CLI

Help と Error Handling

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

このページの内容7項目

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

Help の読み方

sf --help
sf list --help
sf list materialize --help
sf source resolve --help
sf observations search --help

help では次を確認します。

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

agent は、help を読んだあとも保存や credit 消費を伴う実行には --execute --max-credits <n> を付けます。

Error envelope

usage error の例です。

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

まず見る key:

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

error.suggested_next_commands[0] は次の候補です。ただし、候補が materialize / enrich / source resolve / source select のような credit 消費 command なら、対象と --max-credits を確認してから実行します。

Exit code

Exit code	Meaning	最初に見るもの
`2`	usage error	`sf <surface> --help`
`3`	network error	`sf auth show --json`
`4`	auth error	API key と 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`	必須 option を確認
`auth_error`	`sf auth show --json`	`effectiveBaseUrl` と key preview を確認
`company_not_found`	`sf companies search <query> --json`	free text を profile / filings に渡さない
`estimate_not_found`	`sf list estimate "<query>" --json`	estimate を作り直す
`max_credits_required`	`sf list materialize --from-estimate <estimateId> --execute --max-credits <n> --json`	上限なし実行をしない
`max_credits_exceeded`	`sf credits balance --json`	上限を上げるか query を絞る
`credit_balance_insufficient`	`sf credits balance --json`	grant の残高を確認
`preview_export_not_allowed`	`sf list materialize --from-estimate <estimateId> --execute --max-credits <n> --json`	saved List にしてから export
`multiple_candidates`	`sf source review <sourceId> --status multiple_candidates --json`	agent が自動確定しない

Idempotency

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

再試行の例:

sf list materialize --from-estimate <estimateId> --execute --max-credits 100 --idempotency-key <same-key> --json

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

やってはいけないこと

unsupported / needs_human を 0 件成功にする
list candidates の preview を export しようとする
--execute だけで credit 消費 command を走らせる
multiple_candidates を agent が確定する
API key や顧客秘密情報を feedback に入れる

次に読むページ

最小実行順: Essential Commands
List 系の失敗: credit と maxCredits の失敗
estimate / materialize の失敗: estimate と materialize の失敗

CLI