CLI 出力契約

このページでは、自動化や運用者が前提にしてよい CLI の観測可能な振る舞いを整理します。

help 出力

help 出力はプレーンテキストです。

help 出力は探索のためのものであり、厳密な機械パース対象ではありません。

呼び出し元が安定した機械可読結果を必要とする場合は、実行系コマンドに --json を付けてください。

成功レスポンスは stdout に書かれ、次の envelope 形を取ります。

json

{
  "success": true,
  "data": {}
}

失敗レスポンスは stderr に書かれ、次の envelope 形を取ります。

json

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "category": "CATEGORY",
    "message": "Human-readable explanation"
  }
}

error.category は安定した機械可読分類です。error.code はより具体的なアプリケーションエラーのまま残ります。

人間向けの可読出力もありますが、自動化では --json を優先してください。

Relqis はアプリケーションエラーを、安定した終了コード分類へ写像します。

終了コード	意味
`0`	成功
`2`	不正な要求または validation error
`3`	not found
`4`	conflict または optimistic concurrency error
`5`	posting policy または master policy の違反
`6`	period または state transition の違反
`7`	persistence、audit、その他の内部失敗
`1`	その他の未分類失敗

2 は、必須 option 不足のような CLI parse failure にも使います。

現在の JSON error.category は次のとおりです。

SQLITE_BUSY と SQLITE_LOCKED は、再試行を促す文脈付きで internal として返ります。呼び出し元は再試行できますが、可能なら並列 writer 自体を避けてください。

特定のコマンド群では、自動化が次の追加フィールドも前提にできます。

posting-request mutation results include attempt_count, and create/validate results also include retried
posting-request detail includes attempt_count and an attempts array
posting-request list/work items include attempt_count
tax-code show/list/create/update results include tax_usage, rate_category, invoice_credit_rule, and business_category
balance-sheet show rows include row_kind and is_synthetic; current-period net income uses row_kind=current_period_net_income