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.

FieldDescription
statussuccess, partial (some of the work happened; read next_actions), or failed.
codeWhat happened. Success and partial codes are snake_case, such as credentials_saved. Failure codes are kebab-case, such as confirmation-required.
next_actionsInstructions the reader can follow, such as a command to run. Empty when there is nothing to do.
messageFailures 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:

FieldCommandsDescription
accountlogin, init, whoamiThe account the sign-in acts for: {"id":"acc_..."}.
resource_idAPI key and webhook commandsThe ID of the key or webhook the command acted on.
variablesCommands that write an env fileThe env variables written, by name. Never their values.
keysapi-keys listOne object per key: id, mode, description, last4, and created_at.
message_id, event_typetriggerThe 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 codeMeaning
0Success.
1The command failed, or only partly succeeded. A declined confirmation prompt also exits with 1.
2Invalid 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:

CommandCodes
loginlogged_in, already_logged_in
whoamisigned_in
logoutlogged_out, not_logged_in, logout_revocation_unconfirmed
init, api-keys create, api-keys rollcredentials_saved, credentials_unchanged, credentials_retained, credentials_write_failed, key_creation_unconfirmed, key_roll_unconfirmed, agent_setup_failed
api-keys listkeys_listed, keys_listed_partial
api-keys revokekey_revoked
listenlistener_stopped, listener_superseded, listener_webhook_absent, listener_cleanup_unavailable
triggerexample_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.