REFERENCE

Output and exit codes

Exit codes, environment variables and JSON your scripts can rely on.

On this page

Branch on the exit code

Use the number to choose your next action. Treat the message as an explanation for a person.

Recala CLI exit codes: the code, its name, what it means and what to do
Code	Name	Meaning	What to do
0	`OK`	Done.	Continue.
1	`ERROR`	Unexpected error, or an answer the CLI could not read.	Stop and report error.message to the person. Do not retry a write.
2	`USAGE`	Bad flags or arguments.	Fix the command. recala schema `--json` lists every flag.
3	`NOT_AUTHENTICATED`	Not signed in, or the credential was refused.	Stop and ask the person to run recala login.
4	`FORBIDDEN`	Your role does not allow it.	Stop and name what is missing. Never look for another way around it.
5	`NOT_FOUND`	Not found.	Check the id with a list command.
6	`CONFLICT`	Not allowed yet: no organization selected, not ready to schedule, or no person linked.	Fix the precondition the message names, or ask the person.
7	`INVALID`	The input was refused.	Read error.message and fix the input.
8	`RATE_LIMITED`	Rate limited.	Wait, then retry once.
9	`UNAVAILABLE`	Server or network trouble.	Retry a read once. After outcome_unknown, never retry: check the state first.
10	`CONFIRMATION_REQUIRED`	Confirmation is missing or was declined.	Nothing was sent. Ask the person to confirm in a terminal or grant this sign-in access.
11	`PAYMENT_REQUIRED`	Not allowed to spend: no credits, a cap reached or a blocked topic.	Stop and tell the person. An agent never buys.

Set defaults for a shell or agent

Variable	What it does	Priority
`RECALA_ORG`	Organization name, slug or id.	Below `--org`; above the saved organization.
`RECALA_JSON`	Set to 1 for JSON output.	Applies across commands in this shell.
`RECALA_API_KEY`	API key credential, where organization-key access is enabled.	Before RECALA_TOKEN and saved login.
`RECALA_TOKEN`	Access-token credential.	Before saved login.
`RECALA_API_URL`	Override the API address for a development environment.	Below `--api-url`.

Terminal

RECALA_ORG=rebeam RECALA_JSON=1 recala topics list

Do not put credentials in copied commands, logs or prompts. The authentication table explains which source is used.

Read one JSON document

On success, stdout contains exactly one JSON document and the process exits 0. On failure, stdout is empty; the last line of stderr is a JSON object with an error key. Earlier stderr lines may be progress messages.

Terminal

recala schema --json

Error field	Meaning
`code`	A stable machine name, such as confirmation_required or outcome_unknown.
`message`	A sentence for a person. Do not parse it.
`status`	The HTTP status the API answered with, or null.
`exit_code`	The process exit code, repeated so a log line carries it.
`retryable`	True only for rate limits and server trouble, and never after outcome_unknown.

Never retry a write with an unknown outcome. Read the resource’s state first. Next, follow the AI agent guide to put these rules into practice.