> ## 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.

# Script the CLI

> The JSON output and exit codes of cowboy commands

With `--json`, most commands print one JSON object on standard output. `cowboy version --json` lists them. For example:

```bash theme={"system"}
cowboy run --handler increment --payload-json 5 --json
```

```text Output theme={"system"}
{
  "schema": "cowboy-command/v2",
  "command": "run",
  "ok": true,
  "result": {
    "handler": "increment",
    "ok": true,
    "output": "0a",
    "decoded_output": 10,
    "decoded_state": {
      "__INITIALIZED__": 1,
      "count": 10,
      …
    },
    "events": [
      { "data": "0xa165636f756e740a", "topic": "counter.changed" }
    ],
    …
  },
  "diagnostics": []
}
```

* `ok` says whether the command did what it was asked. `result` holds what it produced.
* `diagnostics` lists problems, each with a `code`, a `message`, a `hint`, and `retryable`.

The exit status says what to do next:

| Exit | Meaning | What to do |
| - | - | - |
| 0 | Success | Read the result |
| 1 | Failed, with no more specific class, such as a handler that raised | Read `diagnostics` |
| 2 | Wrong command, flags or target | Fix the command |
| 3 | Bad input or configuration, such as an invalid payload | Fix the input or the project |
| 4 | Key or sign-in problem | Supply a working key or sign in |
| 5 | Refused, such as too low a balance | Fix the cause |
| 6 | Temporary failure, such as no connection | Safe to run the same command again |
| 7 | Outcome unknown | Don't send it again yet: check with `cowboy transaction status --hash <hash> --json` |
| 128+n | Stopped by signal n | Check what finished before you retry |

A script reads the result like this:

```bash theme={"system"}
cowboy run --handler count --json > count.json
python3 -c 'import json; r = json.load(open("count.json")); print(r["ok"], r["result"]["decoded_output"])'
```

```text Output theme={"system"}
True 10
```

Against Cloud, each command has its own `result`:

```bash theme={"system"}
cowboy actor state counter --env cloud --json
cowboy actor call counter --handler increment --payload-json 5 --env cloud --json
```

```text Output theme={"system"}
{"schema":"cowboy-command/v2","command":"actor.state","ok":true,"result":{…},…}
{"schema":"cowboy-command/v2","command":"actor.call","ok":true,"result":{…},…}
```

`actor state` puts the values under `result.storage`. `actor call` returns the call's `status` and `receipt`, with no return value: to get what a handler returned, use the [Python client](https://docs.cowboy.inc/build/call-from-apps.md#call-a-handler-and-wait-for-the-result).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.