CLI

Commands & Flags

`sf` CLI の主要 command family と、agent が必ず守る flag の扱いをまとめます。

このページの内容6項目

このページは reference です。初回実行は Quick Start と Essential Commands から始めてください。

Command families

Family	役割	代表コマンド
`version`	version と更新確認	`sf version --json --check-update`
`auth`	base URL と API key 設定	`sf auth setup`, `sf auth show`
`agent`	Codex / Claude Code skill 配置	`sf agent install --target codex --force`
`data`	capability map	`sf data capabilities --json`
`list plan`	自然文を実行可能な条件に落とす	`sf list plan "<query>" --json`
`list estimate`	保存前の件数 / credit 見積もり	`sf list estimate "<query>" --json`
`list candidates`	preview rows	`sf list candidates --from-estimate <id> --json`
`list materialize`	saved List 作成	`sf list materialize --from-estimate <id> --execute --max-credits <n> --json`
`list enrich`	enrichment column 追加	`sf list enrich <listId> --source website --estimate --json`
`list enrich --source parallel`	narrowed saved List の外部補完	`sf list enrich <listId> --source parallel --estimate --limit 10 --json`
`list ls / show / preview`	saved List の確認	`sf list show <listId> --json`
`list publish / refresh / diff`	snapshot、再評価、差分確認	`sf list refresh <listId> --execute --max-credits <n> --json`
`list create`	空 List、source 由来 List、明示 company List 作成	`sf list create --company-id jpx_7203 --name "<name>" --json`
`list export`	saved List export	`sf list export <listId> --format csv --output ./exports/list.csv --json`
`source`	ユーザー持ち込み CSV の import / map / resolve	`sf source import ./companies.csv --name "<name>" --json`
`source review / select`	ambiguous source row の人間確認と明示選択	`sf source select <sourceId> --row <rowId> --company <companyId> --max-credits 1 --json`
`list create --from-source`	resolved source rows から saved List 作成	`sf list create --from-source <sourceId> --name "<name>" --json`
`discovery`	estimate 後の run 復元、refine、materialize	`sf discovery show <runId> --json`
`job`	agent-ready workflow	`sf job business-understanding "<query>" --execute --json`
`job artifact`	job artifact の一覧・再開	`sf job artifact ls --job business-understanding --json`
`companies`	company identity / resolver	`sf companies identity KEYENCE --json`
`company`	profile / observations / filings	`sf company profile jpx_7203 --json`
`filing`	filing detail / compare	`sf filing show jpx_7203 edinet_fil_<id> --json` / `sf filing compare jpx_7203 edinet_fil_<id> --json`
`observations`	cross-company evidence search	`sf observations search "生成AI" --source edinet --json`
`research`	external research item の保存・一覧	`sf research add jpx_7203 --content-file ./note.md --json`
`credits`	credit balance	`sf credits balance --json`
`feedback`	要望 / 不具合送信	`sf feedback create "<title>" --details "<body>" --json`

Capability contract

sf data capabilities --json は、agent が保存や外部調査に進む前の正本です。

見る key:

contract_version
capabilities[].source_id
capabilities[].status
capabilities[].filters[]
capabilities[].entrypoints[]
capabilities[].pricing
capabilities[].limitations[]
deferred_surfaces[]

capabilities[].status が weak / unsupported / needs_human の場合は、0 件成功にせず、人間に制約を返します。現行 surface の一覧は Data Capability Map を見てください。

Flags agent must use

Flag	使う場面	理由
`--json`	ほぼ全コマンド	agent が shape を検証し、error recovery できる
`--check-update`	`sf version`	CLI が古いことに気づける
`--execute`	保存 / 消費系	dry-run と実行を明確に分ける
`--max-credits <n>`	materialize / enrich	credit 上限なし実行を防ぐ
`--estimate`	enrichment 前	追加 credit 見積もりを先に出す
`--from-estimate <id>`	candidates / materialize	同じ定義で preview と保存をつなぐ
`--from-source <id>`	resolved source rows から list 作成	ユーザー持ち込みsourceを saved List につなぐ
`--company-id <id>`	確認済み company を明示保存する	broad discovery と区別する
`--column <field=header>`	source map	CSV header を company identifier に対応付ける
`--source <id>`	observations / enrich	source coverage を明示する
`--limit <n>`	`parallel` enrichment や preview	bounded execution にする
`--output <path>`	export	agent が成果物の置き場所を制御する

Flags agent should avoid by default

Flag / pattern	避ける理由
API key を command line に直接渡す	shell history と transcript に残る
`--execute` without `--max-credits`	credit boundary が曖昧になる
preview result の export	preview は無料確認であり、保存済み成果物ではない
unsupported 条件のまま materialize	silent 0 件や誤保存につながる
preview URL を API base URL にする	deploy preview と production data の境界が崩れる
list flag を空白区切りで渡す	`--section-key business_risks,strategy` または flag を複数回指定する

Recovery contract

失敗時はまず JSON error を見ます。

{
  "ok": false,
  "error": {
    "code": "usage_error",
    "hint": "先に `sf companies search <query> --json` で company_id を解決してください。",
    "suggested_next_commands": ["sf companies search <query> --json"]
  }
}

agent は error.suggested_next_commands[0] を次の候補にします。ただし、credit 消費や保存を伴う場合は人間に確認してください。

max_credits_exceeded が返る場合は type: "budget_limit" です。retry/backoff ではなく、--max-credits <n> を上げるか条件を絞ってください。

Reference の正本

細かい option は CLI 自身が正本です。

sf --help
sf list --help
sf list materialize --help
sf list enrich --help
sf source --help
sf source map --help
sf feedback create --help

この docs は「どこを見るか」を固定するための索引です。option の完全一覧は CLI help に寄せます。

CLI