> ## Documentation Index > Fetch the complete documentation index at: https://docs.cowboy.inc/llms.txt > Use this file to discover all available pages before exploring further. # cowboy run > Run one handler locally against the simulated PVM and report the result ## Synopsis ```bash theme={null} cowboy run [] [--handler ] [--payload | --payload-text | --payload-json ] [--expect ] [--cycles-limit ] [--initial-state | --state [--reset]] [--strict] [--sender
] [--block-height ] [--timestamp ] [--stub FUNCTION=JSON]... [--stub-error FUNCTION=TYPE:MESSAGE]... [--stub-exit FUNCTION=CODE]... [--stub-llm ]... [--stub-llm-failure ]... [--json] [--verbose] cowboy run --code [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 1. 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`). 2. 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. 3. 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. 4. Print the decoded output, then `State:`, `Off-chain calls:`, `Events:`, `Messages:`, `Timers:`, and `Deferred transactions:` sections when non-empty, then `Gas used: `. 5. With `--expect`, compare the raw returned bytes: print `Output matches --expect.` or fail with `does not match --expect`. 6. 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 | | - | - | - | | `` | 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 ```bash theme={null} $ 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 ``` ```bash theme={null} $ 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.