CLI

ヘルプとエラー対応

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

このページの内容7項目

Claude Code / Codex で sf を使うときは、失敗を prose で推測せず、CLI が返す構造化 error を次の行動に使います。

Help の読み方

sf --help --json
sf search --help --json
sf company --help --json
sf signals --help --json
sf company observations --help --json
sf credits balance --help --json

help では次を確認します。

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

エージェントは、help を読んだあとも deep signal / bulk などのクレジット消費を伴う実行には --max-credits <n> を付けます。

Error envelope

usage error の例です。

{
  "ok": false,
  "error": {
    "code": "usage_error",
    "exit_code": 2,
    "hint": "先に `sf company search <query> --json` で company_id を解決してください。",
    "message": "companyId is required",
    "retryable": false,
    "suggested_next_commands": [
      "sf search <query> --json",
      "sf company jpx_7203 --card --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 --base-url https://signal-foundry.app --json"
    ],
    "type": "network_error"
  }
}

まず見る key:

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

error.suggested_next_commands[0] は次の候補です。ただし、候補が deep signal / bulk などのクレジット消費 command なら、対象と --max-credits を確認してから実行します。

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 解決 command
`6`	rate limit	`Retry-After` と待機
`7`	remote/server error	`error.hint` と再試行可否

よくある復旧

Error	次に打つ command	Notes
`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 --base-url https://signal-foundry.app --json`
`company_not_found`	`sf search <query> --json`	自由入力を profile / filings に渡さない
`max_credits_required`	`sf <command> --help --json`	usage estimate と上限を確認する
`max_credits_exceeded`	`sf credits balance --json`	上限を上げるか検索条件を絞る
`credit_balance_insufficient`	`sf credits balance --json`	付与の残高を確認
`feedback_not_configured`	`sf feedback create --help`	現行 server では通常 durable inbox に `queued` される。発生時は CLI 側で Canny key を設定せず、時間を置くか support に連絡

Idempotency

課金を伴う HTTP 書き込みは idempotency key を使います。CLI で同じ操作を再実行する場合も、error が retryable: true か、API 側の suggested_next_commands が再試行を指示しているかを見ます。

再試行の例:

sf <command> ... --max-credits 100 --idempotency-key <same-key> --json

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

やってはいけないこと

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

次に読むページ

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

CLI