Skip to content

出力とエラー ​

設計としての JSON ファースト ​

rimo はデフォルトで stdout に JSON を出力します。ターミナルで実行しても、 パイプにつないでも、CI の中でも出力は同じです。だからこそスクリプトから安全に 扱え、AI エージェントも安心してパースできます。実行環境によって形式が変わることは なく、変えられるのはフラグだけです。

パースではなく「読む」ことが目的のときは --pretty を付けてください。詳しくは 人間向け出力 を参照してください。

一部の人間向けコマンドは、JSON のラッパーがかえって邪魔になるため、成功時には 代わりにプレーンテキストを出力します:

  • rimo version と rimo upgrade
  • rimo note ask(ストリーミングされる回答)
  • --transcript、--document、--full、--meeting-chat、--document-id を 指定した rimo note get

これらの場合でも、エラーは常に JSON なので、失敗は機械可読のままです。

形式にかかわらず、stdout にはデータが、stderr にはそれ以外のすべて(進捗表示、 更新のお知らせ、Fetch a note: やページネーションのヒント)が出力されます。 そのため stdout をそのまま jq にパイプしても安全です。

各コマンドが返す値をフィールド単位で確認するには レスポンスリファレンス を参照してください。

人間向け出力 (--pretty) ​

--pretty を付けると、同じデータが 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

これは明示的に指定したときだけ有効になり、自動で切り替わることはありません。 rimo note list はターミナルの有無にかかわらず JSON を返すので、昨日動いていた スクリプトは今日も動きます。また rimo note list --pretty | grep 定例 は画面で 見たものとまったく同じ内容を返します。

長い値と狭いターミナルの扱い ​

レイアウトはターミナルの幅に合わせて調整されます(COLUMNS を設定していれば その値、なければターミナルの実際の幅、パイプ時は 100 桁)。

  • ID と日時は決して省略しません。 rimo note get に貼り戻せない ID では 意味がないため、代わりに長いタイトル側が幅を譲ります。
  • 幅が足りなくなったら、列ごと落とします(重要度の低い順)。すべての列を 「…」だらけになるまで削ることはしません。ターミナルを広げて再実行すれば より多くの列が表示されます。
  • 非常に長いテキスト項目(議事録の markdown、検索スニペット、メモ)は 列として表示しません。行全体が「…」で埋まってしまうためです。必要な場合は --fields で明示的に指定してください。
  • 複数行の値は 1 行に畳まれます。メモが表を崩さないようにするためです。 全文を読みたい場合は単一レコードを取得してください。rimo note get <id> --pretty は値を切り詰めずに折り返します。

列の選び方 ​

--fields で列とその順序を指定し、--excludes で除外します。

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

--fields で明示した列は、ターミナルが狭くても落とされません。

使わないほうがよい場面 ​

  • スクリプトやパイプライン — JSON をパースしてください。表の桁揃えや 列の構成は表示上の詳細であり、リリース間で変わる可能性があります。
  • AI エージェント — JSON のほうが小さく曖昧さがなく、--fields と 組み合わせればレスポンスを安く保てます。
  • --fields=compact は JSON 専用のモード(長い値を "[omitted]" に置換)です。 --pretty では無視されます。レイアウトが既に値をターミナル幅に合わせるためです。

--pretty の有無にかかわらず、エラーは常に JSON です。成功時の表示方法に よってエラー処理が変わることはありません。

フィールドのフィルタリング ​

--fields と --excludes は、出力が JSON である任意のコマンドに適用されます。 これらはエンベロープの内側のレコードに適用され、 next_page_token や total_count といったスカラーのメタデータは常に保持されます。

--fields ​

値挙動
""(デフォルト)すべてのフィールド、完全な値
"compact"すべてのフィールド。長い文字列値は "[omitted]" に置換
"f1,f2,f3"これらのフィールドのみ
bash
rimo note list --fields compact
rimo note list --fields id,title,created_at

レコードによっては存在しないフィールドもあるため、見つからない名前があってもエラーには なりません。指定した名前がどれもレスポンスに含まれていない場合は、レコードが持つ フィールドの一覧を warning: として標準エラーに表示します。標準出力と終了コードは 変わりません。

--excludes ​

出力から削除するフィールド名をカンマ区切りで指定します。--fields の後に 適用されます。

bash
rimo note list --excludes transcript,document_markdown

フィールドのフィルタリングは AI エージェントに特に有用です。必要なフィールドのみ (--fields id,title)を要求することで、レスポンスを小さく、パースを安価に保てます。

ドライラン ​

--dry-run の動作はコマンドによって 2 通りです。

  • note create と note append はリクエストを送信せず、レスポンス形状のプレースホルダーの例に "dry_run": true を加えたものを返します。
  • appointment link create・update・enable・disable・delete と appointment cancel はサーバーに問い合わせます。サーバーは実際のリクエストと 同じ検証を行い、保存・削除・キャンセルをせずに実際の結果("dry_run": true)を返します。検証に失敗した場合は、実際のコマンドと 同じエラーと終了コードが返ります。ただし appointment cancel のドライランはカレンダーの予定を確認しないため、ドライランが通っても 実際のキャンセルが calendar_event_delete_failed で失敗することがあります。

ドライランの出力 を参照してください。

終了コード ​

コード意味
0成功
1一般的なエラー — 競合(409)、レート制限、サーバーエラー(5xx)、ネットワークエラーを含む
2未認証、または権限がない(401、403)— ログインするか、必要なスコープを持つトークンを使ってください
3見つからない(404)
4コマンドまたは入力が誤っている — 不明なコマンドやフラグ、引数の誤り、組み合わせられないフラグ、API が不正なリクエストとして拒否した場合(400)

成功か失敗かは 0 か 0 以外かで判断するのが確実です。スクリプトでは出力をパースするのではなく、 終了コードを確認してください。0 以外の値は失敗の種類を表します。具体的な理由はエラー JSON の code を見てください。

エラー形式 ​

エラーは JSON として stdout に出力され、上記のいずれかの終了コードで終了します:

json
{
  "code": "validation_error",
  "message": "unknown flag: --bogus"
}
フィールド説明
code機械可読のエラーコード。分岐には message ではなくこちらを使ってください。下記参照。
message失敗内容を表す人間向けメッセージ。API からのエラーは API error <HTTP ステータス>: で始まります。
details任意。失敗についての構造化された情報で、形は code によって異なります。ない場合は省略されます。

エラーコード ​

API がエラーを返したとき、API 自身がエラー種別を返していれば code はその値になります (例: API が受け付けないリクエストキーに対する unknown_field)。返していなければ HTTP ステータスから決まります:

code発生する場面終了コード
validation_errorコマンドラインの誤り(不明なフラグ、引数の数の誤り、組み合わせられないフラグ、不正な値、読み込めない入力ファイル)、または API が不正なリクエストとして拒否した場合(400、422)4
unknown_commandコマンド名の打ち間違い。近いコマンドがあれば details.suggestion にその名前が入ります4
auth_error使える認証情報がない(未ログイン、セッション切れ、形式が不正な RIMO_API_KEY、指定したアカウントが保存されていない)、または API が認証情報を拒否した場合(401)2
permission_deniedAPI がリクエストを拒否した場合(403)。トークンのスコープが足りないときは details.required_scopes に必要なスコープが入ります2
not_foundリソースが存在しないか、参照できない場合(404)3
conflictリクエストがリソースの現在の状態と競合する場合(409)。例: ノートがロックされている1
rate_limit_exceededノート内容の取得(内容を取得するフラグ付きの rimo note get)が 1 日の上限に達した場合(429)。message に書かれた時刻(00:00 UTC)にリセットされ、それまでは再実行しても失敗します1
rate_limitedリクエストが多すぎる場合(429)で、API が独自のエラー種別を返さないとき1
server_errorAPI 側の失敗(5xx)。時間をおいて再実行すると成功することがあります1
api_errorその他の HTTP エラーステータス1
network_errorAPI に到達できない、または応答がない場合(接続、DNS、TLS、タイムアウト)1
errorその他の失敗(CLI が読み取れない応答など)1

API のエラー種別の終了コードは、その HTTP ステータスに従います。unknown_field(400)は 4 で終了し、独自のエラー種別を持つ 409 は 1 で終了します。API の拡張に伴って新しいエラー 種別が増えることがあるため、知らない code は終了コードで扱ってください。

API がエラーに構造化された詳細を付けている場合、details にそのまま渡されます。例えば、 不明なキーをすべて、候補とともに返す場合:

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?"
}

コマンドに必要なスコープを持たないトークンの場合:

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