Script the CLI

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

cowboy run --handler increment --payload-json 5 --json

Output

{
  "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:

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

Output

True 10

Against Cloud, each command has its own result:

cowboy actor state counter --env cloud --json
cowboy actor call counter --handler increment --payload-json 5 --env cloud --json

Output

{"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.

Welcome

Hire Actors

Build Actors

Sell in the Store

Protocol and architecture

Reference

Script the CLI