Reference
Output and exit codes
The SignatureAPI CLI's --json output contract, result codes, and exit codes, for scripts and coding agents.
The CLI writes for people by default and for programs with --json. Both carry the same events. Neither ever contains an API key, a webhook signing secret, or a sign-in token.
Text output
Text output goes to stderr: a headline marked ✔ (success), ▲ (partial), or ✖ (failure), labeled details, and the next steps to take. Colors turn off when stderr is not a terminal or NO_COLOR is set.
JSON output
Add --json to any command to print newline-delimited JSON on stdout: one event per line.
npx signatureapi api-keys list --json
A command prints any number of authorization_required and progress events, then exactly one result event, last.
agent setup --json prints a single JSON object instead. See Agent setup.
authorization_required
The command needs a sign-in. Show the URL and code to a person, who approves them in a browser. The command waits for the approval.
{"type":"authorization_required","verification_uri":"https://...","user_code":"ABCD-EFGH"}
progress
A step of a longer command, such as listener_ready from listen. Every progress event has a phase and a code. The fields listen adds are described in What the listener shows.
{"type":"progress","phase":"init","code":"credentials_ready"}
result
The outcome of the command. Read status first, then code.
| Field | Description |
|---|---|
status | success, partial (some of the work happened; read next_actions), or failed. |
code | What happened. Success and partial codes are snake_case, such as credentials_saved. Failure codes are kebab-case, such as confirmation-required. |
next_actions | Instructions the reader can follow, such as a command to run. Empty when there is nothing to do. |
message | Failures only, when the CLI has a reason to give, such as the values an option accepts. It never repeats a rejected value. |
Commands add fields that describe what they did:
| Field | Commands | Description |
|---|---|---|
account | login, init, whoami | The account the sign-in acts for: {"id":"acc_..."}. |
resource_id | API key and webhook commands | The ID of the key or webhook the command acted on. |
variables | Commands that write an env file | The env variables written, by name. Never their values. |
keys | api-keys list | One object per key: id, mode, description, last4, and created_at. |
message_id, event_type | trigger | The example event that was sent. |
{"type":"result","status":"success","code":"credentials_saved","next_actions":[],"variables":["SIGNATUREAPI_KEY"],"account":{"id":"acc_..."}}
A failure looks like this:
{"type":"result","status":"failed","code":"confirmation-required","message":"Rolling a live key or revoking a key needs confirmation, and this shell cannot prompt.","next_actions":["Pass --yes to confirm this live API key change in a non-interactive shell."]}
How —json is detected
--json counts only as an option. As the value of another option, such as --description --json, or after --, it does not switch the output.
Exit codes
| Exit code | Meaning |
|---|---|
0 | Success. |
1 | The command failed, or only partly succeeded. A declined confirmation prompt also exits with 1. |
2 | Invalid usage: an unknown command or option, an invalid value, or a missing --yes in a non-interactive shell. Nothing was changed. |
When you stop a command a second time while it is saving a refreshed sign-in, it exits at once with the signal’s status: 130 for Ctrl+C, 143 for SIGTERM, and 129 for SIGHUP.
Result codes
Success and partial codes, by command:
| Command | Codes |
|---|---|
login | logged_in, already_logged_in |
whoami | signed_in |
logout | logged_out, not_logged_in, logout_revocation_unconfirmed |
init, api-keys create, api-keys roll | credentials_saved, credentials_unchanged, credentials_retained, credentials_write_failed, key_creation_unconfirmed, key_roll_unconfirmed, agent_setup_failed |
api-keys list | keys_listed, keys_listed_partial |
api-keys revoke | key_revoked |
listen | listener_stopped, listener_superseded, listener_webhook_absent, listener_cleanup_unavailable |
trigger | example_sent |
A code ending in _unconfirmed means a change may or may not have happened, for example after a timeout. The CLI never retries it on its own; its next steps say how to check.
Failure codes are listed in Troubleshooting.