data follows the operation: a saved record, a page of summaries, a provider
action receipt and a public-web result are different things.
The envelope
Exit codes:
0 success, 1 failure, 2 invalid arguments, 130 interrupted.
Help is a result too: almanac help COMMAND and COMMAND --help put the help
text in data.text. --markdown prints prose for a person at a terminal
instead of the envelope, and read --body prints only the Markdown body.
--json is accepted and changes nothing. Login prompts go to stderr; stdout
carries only the document.
Large results
Stdout stays under 40,000 characters. A larger envelope is written to a file, stdout keepsdisplay, page and saved without data, and a notice says if
display itself was trimmed. Read the complete result from saved.path:
SESSION_ID is a returned ID. A partial display is not the complete
conversation. Inspect the saved file, follow its continuation, and state the
scope actually reviewed. Conversation history explains
current versus earlier messages. Only web read and web download take a saved
path with --from; web result files explains that handoff.
Carry state deliberately
For saved record edits, retain the full record and its revision. CLI field input is a flat object, such as{"description":"..."}; an HTTP schema’s enclosing
set object is not another layer to add to --input. Arrays and maps replace
the supplied field, so preserve entries that should remain. See
editing records.
Every list continues the same way: pass page.next_cursor to --cursor, with
the same filters. A cursor is an opaque continuation, not an item ID. Listings
across several connected accounts return one page per account in data; continue
one account with --account and that page’s own next_cursor.
Interpret failure before retrying
A nonzero exit status is a failure signal. Preserve
error.request_id when
reporting a failure you cannot resolve. Missing content is not equivalent to a
successful empty result. A failure can still carry data for what did happen:
email send that created its draft but could not send it returns the draft
beside the error. An action receipt read can itself succeed while reporting an
unknown or failed action inside it.
Writes report request_key. Without --request-key, the CLI derives one; inside
a managed agent session, re-running the same terminal call derives the same keys
and replays its writes instead of repeating them. An identical retry reuses the
reported key and input. A revised decision uses a new key after reading current
state. For external effects, inspect the saved action receipt and current original
where possible before repeating work; uncertain actions
explains why a new key can duplicate a send or event. Do not apply a generic
retry loop to all failures.