CLI

ヘルプとエラー対応

`--help`、構造化 error、exit code、復旧コマンドの読み方をまとめます。

このページの内容7項目

Claude Code / Codex で sf を使うときは、失敗を文章で推測せず、CLI が返す構造化 error を次の行動に使います。このページが error envelope と復旧コマンドの正本です。

Help の読み方

sf --help --json
sf search --help --json
sf company --help --json
sf signals --help --json
sf usage --help --json
sf query --help --json
sf job search --help --json
sf construction search --help --json
sf credits balance --help --json
sf credits summary --help --json

help では次を確認します。

Usage: 必須 argument と option
Examples: --json 付きの実行例
Next: 次に打つコマンド候補

エージェントは、クレジット消費を伴う実行の前に sf credits balance --json で残高を確認し、ユーザーが指定した予算を超える実行はしません。

Error envelope

usage error の例です。

{
  "ok": false,
  "error": {
    "code": "usage_error",
    "exit_code": 2,
    "hint": "先に `sf search <query> --json` で company_id を解決してください。",
    "message": "companyId is required",
    "retryable": false,
    "suggested_next_commands": [
      "sf search <query> --json",
      "sf company jpx_7203 --json"
    ],
    "type": "usage_error"
  }
}

network error の例です。

{
  "ok": false,
  "error": {
    "code": "network_error",
    "exit_code": 3,
    "hint": "接続先を確認してください。",
    "message": "接続できませんでした。",
    "retryable": true,
    "suggested_next_commands": [
      "sf auth show --json",
      "sf login --json"
    ],
    "type": "network_error"
  }
}

まず見る key:

ok
error.code
error.exit_code
error.hint
error.retryable
error.suggested_next_commands[]

error.suggested_next_commands[0] は次の候補です。ただし、候補がクレジット消費コマンドなら、対象と credit 残高を確認してから実行します。

max_credits_exceeded が返る場合は type: "budget_limit" です。retry / backoff で解決するものではありません。検索条件や対象を絞って再実行してください。

Exit code

Exit code	Meaning	最初に見るもの
`2`	usage error	`sf <surface> --help`
`3`	network error	`sf auth show --json`
`4`	auth error	`sf auth show --json` の `authMode` と base URL
`5`	not found	ID 解決コマンド
`6`	rate limit	`Retry-After` と待機
`7`	remote/server error	`error.hint` と再試行可否
`8`	company resolve に一致候補なし	JSON の `status: "not_found"` と `gaps[]`
`9`	条件が未対応(機械可読な拒否)	JSON の `status: "unsupported"` / `"blocked"` と `gaps[].code`

sf company <input> --json は、API 呼び出し自体が成功しても会社候補を解決できない場合に exit 8 を返します。JSON は ok: true / status: "not_found" のままです。sf search の0件は正当な検索結果なので exit 0 のままです。

サーバーが条件を未対応と判定した場合(例: 四半期指定)、CLI は契約 payload(status: "unsupported" と gaps[].code)をそのまま出力し、exit 9 を返します。これは接続エラーではありません。quarter_financial_period のような未対応条件は、同じ条件のまま再試行しても結果は変わらないため、gaps[].code を読み、対応する structured filter または company_query.v1 へ条件を移してください。

よくある復旧

Error	次に打つコマンド	補足
`usage_error`	`sf <surface> --help --json`	必須オプションを確認
`auth_error`	`sf auth show --json`	`effectiveBaseUrl` と credential preview を確認
`authentication_required` / `invalid_oauth_token`	`sf auth show --json`	OAuth token がない、期限切れ、または接続先が違う場合は `sf login --json`
`company_not_found`	`sf search <query> --json`	自由入力を Company Card / Signals に渡さない
`invalid_query`	`sf <surface> --help --json`	`topic.arguments[]` と `topic.options[]` にない入力を渡していないか確認
`max_credits_required`	`sf <command> --help --json`	usage estimate と上限を確認する
`max_credits_exceeded`	`sf credits balance --json`	検索条件や対象を絞って再実行する
`credit_balance_insufficient`	`sf credits balance --json`	付与の残高を確認
`rate_limit_exceeded`	待機して再実行	`error.rate_limit.retryAfterSeconds` または `Retry-After` に従う

Idempotency

credit を消費する HTTP の POST endpoint は、Idempotency-Key header(opt-in)で安全に再試行できます。CLI に idempotency のフラグはありません。CLI で同じ操作を再実行する場合は、error が retryable: true か、error.suggested_next_commands が再試行を指示しているかを見てから、同じコマンドをそのまま再実行します。

同じ会社 / signal を再実行する場合は、二重消費を避けるために同じ意図の再試行として扱います。

やってはいけないこと

unsupported / needs_human を 0 件成功にする
クレジット消費コマンドを上限なしで走らせる
曖昧な会社候補をエージェントが勝手に確定する
API key や顧客秘密情報を support 連絡に入れる

次に読むページ

最小実行順: 基本コマンド
usage / credit の失敗: クレジットと maxCredits の失敗

CLI