Skip to content

Output & errors ​

JSON-first by design ​

rimo prints JSON to stdout by default — and it does not matter whether you are in a terminal, in a pipe, or inside CI. The output of a command is the same everywhere, which is what makes it safe to script and safe for an AI agent to parse. Nothing about your environment changes the format; only a flag does.

When you want to read the output rather than parse it, add --pretty — see Human-readable output below.

A few human-facing commands print plain text on success instead, because a JSON wrapper would just get in the way:

  • rimo version and rimo upgrade
  • rimo note ask (the streamed answer)
  • rimo note get with --transcript, --document, --full, --meeting-chat, or --document-id

Even for these, errors are always JSON, so failures stay machine-readable.

Whichever the format, stdout carries the data and stderr carries everything else — progress spinners, update notices, and the Fetch a note: / pagination hints — so piping stdout into jq is always safe.

For what each command returns, field by field, see the Response reference.

Human-readable output (--pretty) ​

--pretty renders the same data as a table (for lists) or an aligned key/value block (for a single record) instead of JSON.

bash
rimo note list --pretty
ID                    TITLE                            HELD AT           DURATION  STATE
J9yyjDQLJWqhiSTH0sAT  週次定例 プロダクトチーム        2026-09-05 14:30  58m       ASR_DONE
aK2mLp0QQzXcVbNm1234  Rimo CLI design review — outpu…  2026-09-04 10:00  1h 05m    ASR_DONE

2 of 137 notes
Next page: --page-token next-page-2

It is opt-in and never automatic. rimo note list gives JSON whether or not a terminal is attached, so a script that worked yesterday keeps working; and rimo note list --pretty | grep 定例 gives you exactly what you saw on screen.

What it does with long values and narrow terminals ​

The layout adapts to your terminal width (taken from COLUMNS if you set it, otherwise from the terminal itself, otherwise 100 columns when piped):

  • IDs and timestamps are never shortened. An ID you cannot paste back into rimo note get would defeat the point, so long titles give up room instead.
  • When space runs out, whole columns are dropped, least important first, rather than every column being shaved down to ellipses. Resize your terminal and re-run to see more.
  • Very long text fields (a document's markdown, a search snippet, a memo) are never shown as columns — they would fill the row with a single …. Ask for them explicitly with --fields if you want them.
  • Multi-line values are flattened to one line so a memo cannot break the table. To read one in full, fetch the single record: rimo note get <id> --pretty wraps long values instead of truncating them.

Choosing columns ​

--fields picks the columns and their order; --excludes removes them:

bash
rimo note list --pretty --fields id,title,held_at
rimo team list --pretty --excludes description

Columns you name with --fields are never dropped, even on a narrow terminal.

When not to use it ​

  • In scripts and pipelines — parse the JSON. The table's spacing and column set are a presentation detail and may change between releases.
  • For AI agents — JSON is smaller, unambiguous, and combines with --fields to keep responses cheap.
  • --fields=compact is a JSON-only mode (it swaps long values for "[omitted]"); with --pretty it is ignored, since the layout already fits values to your terminal.

Errors are always JSON, with or without --pretty, so failure handling never depends on how the successful output is rendered.

Field filtering ​

--fields and --excludes apply to any command whose output is JSON. They filter the records inside the response envelope — the scalar metadata siblings such as next_page_token and total_count are always preserved.

--fields ​

ValueBehavior
"" (default)All fields, full values
"compact"All fields; long string values replaced with "[omitted]"
"f1,f2,f3"Only these fields
bash
rimo note list --fields compact
rimo note list --fields id,title,created_at

A field can be missing from some records, so names that do not appear are not an error. When none of the names you pass appears in the response, a warning: line on stderr lists the fields its records do have; stdout and the exit code are unchanged.

--excludes ​

Comma-separated field names to remove from output. Applied after --fields.

bash
rimo note list --excludes transcript,document_markdown

Field filtering is especially useful for AI agents — request only the fields you need (--fields id,title) to keep responses small and cheap to parse.

Dry runs ​

--dry-run works in one of two ways, depending on the command:

  • note create and note append send no request and return a placeholder example of the response shape with "dry_run": true added.
  • appointment link create, update, enable, disable and delete, and appointment cancel, ask the server, which runs the same checks as a real request and returns the real result ("dry_run": true) without saving, deleting or cancelling anything. A dry run that fails a check returns the same error and exit code as the real command would. One exception: the appointment cancel dry run does not contact the calendar, so it can pass and the real cancel still fail with calendar_event_delete_failed.

See Dry-run output.

Exit codes ​

CodeMeaning
0Success
1General error — including conflicts (409), rate limits, server errors (5xx) and network errors
2Not authenticated, or not allowed (401, 403) — log in, or use a token with the required scope
3Not found (404)
4The command or its input is wrong — an unknown command or flag, a wrong argument, a bad flag combination, or a request the API rejected as invalid (400)

Zero vs non-zero is the reliable signal of success vs failure — check it in scripts rather than parsing output. The non-zero value tells you what kind of failure it was; for the exact reason, read code in the error JSON.

Error format ​

Any error is written as JSON to stdout, and the process exits with one of the codes above:

json
{
  "code": "validation_error",
  "message": "unknown flag: --bogus"
}
FieldDescription
codeMachine-readable error code — branch on this, not on message. See below.
messageHuman-readable description of the failure. Errors from the API start with API error <HTTP status>:.
detailsOptional. Structured information about the failure; its shape depends on code. Omitted when there is none.

Error codes ​

When the API returns an error, code is the API's own error type when it gives one — for example unknown_field for a request key the API does not accept. Otherwise it follows the HTTP status:

codeWhenExit
validation_errorThe command line is wrong (unknown flag, wrong number of arguments, flags that cannot be combined, a bad value, an input file that cannot be read), or the API rejected the request as invalid (400, 422)4
unknown_commandA mistyped command; details.suggestion names the closest one when there is one4
auth_errorNo usable credentials (not logged in, an expired session, a malformed RIMO_API_KEY, no saved account matching the one you named), or the API rejected the credentials (401)2
permission_deniedThe API refused the request (403). When the token lacks a scope, details.required_scopes lists the scopes it needs2
not_foundThe resource does not exist or you cannot see it (404)3
conflictThe request conflicts with the resource's current state (409), e.g. the note is locked1
rate_limit_exceededThe daily cap on reading note contents (rimo note get with a content flag) is reached (429). It resets at the time given in message (00:00 UTC); retrying before then fails again1
rate_limitedToo many requests (429) when the API gives no error type of its own1
server_errorThe API failed (5xx); retrying later may help1
api_errorAny other HTTP error status1
network_errorThe API could not be reached or did not answer (connection, DNS, TLS, timeout)1
errorAny other failure, such as a response the CLI cannot read1

An API error type keeps the exit code of its HTTP status: unknown_field (400) exits 4, and a 409 with its own error type exits 1. New API error types can appear as the API grows, so treat an unrecognised code by its exit code.

When the API sends structured details with the error, they are passed through unchanged in details — for example, every unknown key with a suggestion:

json
{
  "code": "unknown_field",
  "details": [
    {
      "allowed_fields": ["title", "description", "duration_minutes"],
      "field": "duration",
      "suggestion": "duration_minutes"
    }
  ],
  "message": "API error 400: Unknown fields: duration. Did you mean duration_minutes?"
}

A token without the scope a command needs:

json
{
  "code": "permission_denied",
  "details": {
    "required_scopes": ["appointments:read"]
  },
  "message": "API error 403: insufficient_scope (requires appointments:read)"
}