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 versionandrimo upgraderimo note ask(the streamed answer)rimo note getwith--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.
rimo note list --prettyID 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-2It 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 getwould 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--fieldsif 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> --prettywraps long values instead of truncating them.
Choosing columns
--fields picks the columns and their order; --excludes removes them:
rimo note list --pretty --fields id,title,held_at
rimo team list --pretty --excludes descriptionColumns 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
--fieldsto keep responses cheap. --fields=compactis a JSON-only mode (it swaps long values for"[omitted]"); with--prettyit 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
| Value | Behavior |
|---|---|
"" (default) | All fields, full values |
"compact" | All fields; long string values replaced with "[omitted]" |
"f1,f2,f3" | Only these fields |
rimo note list --fields compact
rimo note list --fields id,title,created_atA 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.
rimo note list --excludes transcript,document_markdownField 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 createandnote appendsend no request and return a placeholder example of the response shape with"dry_run": trueadded.appointment link create,update,enable,disableanddelete, andappointment 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: theappointment canceldry run does not contact the calendar, so it can pass and the real cancel still fail withcalendar_event_delete_failed.
See Dry-run output.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error — including conflicts (409), rate limits, server errors (5xx) and network errors |
| 2 | Not authenticated, or not allowed (401, 403) — log in, or use a token with the required scope |
| 3 | Not found (404) |
| 4 | The 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:
{
"code": "validation_error",
"message": "unknown flag: --bogus"
}| Field | Description |
|---|---|
code | Machine-readable error code — branch on this, not on message. See below. |
message | Human-readable description of the failure. Errors from the API start with API error <HTTP status>:. |
details | Optional. 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:
code | When | Exit |
|---|---|---|
validation_error | The 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_command | A mistyped command; details.suggestion names the closest one when there is one | 4 |
auth_error | No 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_denied | The API refused the request (403). When the token lacks a scope, details.required_scopes lists the scopes it needs | 2 |
not_found | The resource does not exist or you cannot see it (404) | 3 |
conflict | The request conflicts with the resource's current state (409), e.g. the note is locked | 1 |
rate_limit_exceeded | The 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 again | 1 |
rate_limited | Too many requests (429) when the API gives no error type of its own | 1 |
server_error | The API failed (5xx); retrying later may help | 1 |
api_error | Any other HTTP error status | 1 |
network_error | The API could not be reached or did not answer (connection, DNS, TLS, timeout) | 1 |
error | Any other failure, such as a response the CLI cannot read | 1 |
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:
{
"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:
{
"code": "permission_denied",
"details": {
"required_scopes": ["appointments:read"]
},
"message": "API error 403: insufficient_scope (requires appointments:read)"
}