cowboy run

Synopsis

cowboy run [<target>] [--handler <name>] [--payload <hex|@file> | --payload-text <text> | --payload-json <json>]
           [--expect <hex>] [--cycles-limit <n>] [--initial-state <json> | --state <file> [--reset]] [--strict]
           [--sender <address>] [--block-height <n>] [--timestamp <ms>]
           [--stub FUNCTION=JSON]... [--stub-error FUNCTION=TYPE:MESSAGE]... [--stub-exit FUNCTION=CODE]...
           [--stub-llm <json>]... [--stub-llm-failure <code>]... [--json] [--verbose]
cowboy run --code <path> [flags]

cowboy run is the inner loop: one local invocation of one handler, with no chain involved. The default output is the decoded return value, the decoded state writes, the off-chain calls, and the gas.

Behavior

Resolve the payload: --payload as hex (0x optional) or @path for raw bytes; --payload-text as UTF-8 bytes; --payload-json as CBOR-encoded JSON. With none, the payload is empty (0x).
Prepare the actor: compile the named target (or the project’s only actor), or the standalone file given by --code (- reads stdin). Off-chain calls are answered by the --stub* flags or by a local container when none is given.
Run the handler through the cowboy-dev-runner simulator with the cycles limit and any --initial-state or --state file. With --state, a successful run saves the state it leaves back to that file.
Print the decoded output, then State:, Off-chain calls:, Events:, Messages:, Timers:, and Deferred transactions: sections when non-empty, then Gas used: <n>.
With --expect, compare the raw returned bytes: print Output matches --expect. or fail with does not match --expect.
A handler that raises prints the exception type and message, the Actor line in the developer’s source when the build’s source map covers it, and the traceback; the process exits 1.

Under --json stdout carries one envelope with the simulator’s own fields (output, state, gas_used, events, messages, timers, deferred_transactions) plus decoded_output, decoded_state, offchain_calls, the error fields, actor_location, and the expected/matched pair when --expect was given. A reverted run still reports the state, events, and gas it produced.

The dev runner

The simulator is a separate cowboy-dev-runner binary. It is located by, in order: the COWBOY_DEV_RUNNER environment variable when set and non-empty; a cowboy-dev-runner file next to the cowboy executable; then cowboy-dev-runner on PATH. A world-writable runner binary is refused. A runner built from a different revision than cowboy is refused with a dev_runner_mismatch diagnostic that names both paths and suggests cargo build -p cowboy-dev-runner or pointing COWBOY_DEV_RUNNER at a matching build.

Flags

Flag	Default	Description
`<target>`	Inferred when the project has one actor	Actor target name; conflicts with `--code`
`--code`	None	Python source file to run instead of a project target
`--handler`	`main`	Handler function name
`--payload`	`0x`	Hex (`0x` optional) or `@path/to/file` for raw bytes; conflicts with the other payload flags
`--payload-text`	None	UTF-8 text passed as raw bytes
`--payload-json`	None	JSON string encoded to CBOR
`--expect`	None	Expected output bytes (hex); the run passes only if the handler succeeds and returns exactly these
`--cycles-limit`	`10000000`	Cycles (gas) limit
`--initial-state`	None	Initial state as a JSON object of `"hex_key": "hex_value"`
`--state`	None	Start from the state in this file and, when the handler succeeds, save the state it leaves back to it, so calls follow one another like transactions. A missing file is an empty state. Conflicts with `--initial-state`
`--reset`	`false`	With `--state`, start from an empty state instead of the file; requires `--state`
`--sender`	Fixed simulation sender	Caller address seen by the handler (20-byte hex, `0x` optional)
`--block-height`	`1`	Simulated block height
`--timestamp`	`1700000000000`	Simulated block time in milliseconds since the Unix epoch
`--strict`	`false`	Apply chain source checks and deterministic SDK import aliases; time and randomness still use local fixtures
`--stub-llm`	None (repeatable)	Answer the next `runner.llm` call with JSON; structured values are checked against their schema
`--stub-llm-failure`	None (repeatable)	Return a structured LLM failure code. Both LLM stub flags are consumed in command-line order
`--stub`	None (repeatable)	Answer an off-chain function: `FUNCTION=JSON`
`--stub-error`	None (repeatable)	Make an off-chain function raise: `FUNCTION=TYPE:MESSAGE`
`--stub-exit`	None (repeatable)	Make an off-chain container crash: `FUNCTION=CODE` (nonzero)
`--json`	`false`	Emit one versioned JSON result object
`--verbose`	`false`	Also report the build identity, the simulator path, the raw result bytes, and the messages the runtime sends itself

Example

$ cowboy run --handler score --stub 'score_report={"mean":2.0,"count":3}'
State:
  last_mean: 2.0
Off-chain calls:
  score_report -> stub ok
Gas used: 1320091

$ cowboy run --handler score --payload 0x --expect 0xf5
...
✓ Output matches --expect.

Edge Cases

--payload, --payload-text, and --payload-json are mutually exclusive.
With no target, no --code, and no single project actor, the run is refused with the candidate targets listed.
A failed run exits 1 after printing its result; under --json the envelope’s ok is false and the diagnostics carry the reason.
Internal simulator failures name the runner binary; they are not reported as a handler failure.

Start Here

Build

How Cowboy Works

Reference

Synopsis

Behavior

The dev runner

Flags

Example

Edge Cases

​Synopsis

​Behavior

​The dev runner

​Flags

​Example

​Edge Cases

Synopsis

Behavior

The dev runner

Flags

Example

Edge Cases