anona without parsing prose: one JSON
document on stdout, a stable exit code, and errors on stderr.
JSON output
Every data command takes--json, and then prints one JSON document on
stdout and nothing else there. Each command page shows its document; the
short form is also printed by anona guide.
- On success, stdout is the document, usually the API’s response as it came.
Where the API answers with no body (a delete, a settings reset), the CLI
writes a small document of its own, such as
{"deleted": true, "memory_id": ..., "space_id": ...}. - An empty result is still a document with exit
0:{"results": []},{"items": [], ...}. - On failure, stdout is empty and a one-line error is on stderr, so
anona retrieve ... --json | jqnever receives half a document. - The one exception is
recordthat stored nothing: exit3, and its document (withstatus: "nothing_extracted") is still on stdout. - Non-ASCII and control characters are escaped (
é,\u001b), so the output is safe to print to a terminal and decodes to exactly what was stored.
--quiet turns them off.
Exit codes
A script branches on the exit code rather than on the message. Each code means the same thing on every command.Codes
5 to 8 are new. pip anona 0.24.0 and the npm CLI report every
refused or failed request as 1, and a 403 as 1 rather than 4. The table
above is the next pip release; the npm CLI follows when its port lands. A script
that must run on both can treat 1 and 5-7 alike.start, login, logout, status) use only 0 and
1, plus 2 for a wrong command line.
Errors
Errors go to stderr, one line, in the API’s own terms:anona: is the error code, which
is the stable thing to match on. A failure to reach the server is reported as
exactly that, never as an HTTP status, because no server answered. Quote the
request_id when you contact support.
Retries and timeouts
A write is never re-sent after a
5xx or a timeout. The server may already
have stored it, and a second send would store it twice. So after exit 7 from
record, documents upload or any other write, check before you run it again:
anona retrieve or anona memories list --q for a record, anona documents list for an upload. Reads are retried, and so is a 429 on anything, because a
rate-limited request was not processed.
Each retry says so on stderr while it waits
(anona: rate limited, retrying in 3 s (1/2)), so a slow command can be told
from a hung one. An expired anona login is renewed and the request sent once
more; that is separate from --retries.
Waiting on background work
record --async, record --batch and documents upload queue work and return
job ids. Add --wait to poll until the jobs finish, and the exit code reports
the outcome instead of the submission:
Polling is free and backs off from 1 s to 5 s.
--wait-timeout 0 is a single
status check. With --json the document is
{"submitted": <what the submit returned>, "jobs": [<one jobs get document per job>]}.
Batch files
record --batch FILE takes JSON Lines, at most 100
items, one per line: a JSON string, or an object with content and any of
context, timestamp, metadata, tags, user_id, agent_id,
session_id. The file is validated in full before anything is sent; a bad line
exits 2 and names the line number. Details and examples:
Batch ingest.
Global options
These go before or after the command.
Environment:
ANONA_API_KEY, ANONA_SPACE_ID, ANONA_BASE_URL,
ANONA_PROFILE.
In CI
Use an API key from your CI’s secret store, neveranona login, which needs a
person at a browser:
anona doctor --json is a cheap first step that fails the job early, with exit
4 or 7, when the key or the network is wrong.