CLI

コマンドとフラグ

`sf` CLI の主要 command family と、エージェントが必ず守る flag の扱いをまとめます。

このページの内容7項目

このページはリファレンスです。初回実行はクイックスタートと基本コマンドから始めてください。

Command families

Family	役割	代表コマンド
`version`	version と更新確認	`sf version --json --check-update`
`login` / `auth`	CLI ログインと接続状態確認	`sf login`, `sf auth show`
`search`	会社 resolver / signal search の標準入口	`sf search 7203 --json`
`query`	エージェントが生成した `company_query.v1` の実行	`sf query --file company-query.json --json`
`company`	1 社の Company Card 標準入口	`sf company jpx_7203 --json`
`signals`	会社別 Signals の標準入口	`sf signals jpx_7203 --json`
`usage`	Search / Company Card / Signals の利用量確認	`sf usage --json`
`job search`	求人行検索	`sf job search "大阪勤務のAI求人" --json`
`construction search`	建設業許可と営業所明細検索	`sf construction search "大阪の建設業許可" --json`
`credits`	クレジット balance / summary	`sf credits balance --json`

Coverage / warning の読み方

通常の最初の実行は sf search から始めます。返却 JSON の coverage / warning を見て、低ヒットを市場不在として扱ってよいか判断します。

見る key:

companies[].company.company_id
companies[].query_match
companies[].source_coverage
meta.returned_companies
meta.source_coverage
warnings[]
gaps[]

weak / unsupported / needs_human の場合は、0 件成功にせず、人間に制約を返します。現行機能は各コマンドの --help で確認します。

財務閾値など、自然文のまま q に残すと誤読しやすい条件は、エージェントが company_query.v1 JSON を作ってから sf query --file <path> --json で実行します。sf query に自然文を直接渡さないでください。

運用者向け release / eval コマンドは公開 CLI の通常ワークフローでは使いません。公開モードでは unavailable として返します。

エージェントが必ず使う flag

Flag	使う場面	理由
`--json`	ほぼ全コマンド	エージェントが shape を検証し、error recovery できる
`--check-update`	`sf version`	CLI が古いことに気づける
`--limit <n>`	search / signals / jobs / construction	bounded execution にする
`--aggregate company-count`	filter-only の会社数集計	pagination の下限値ではなく aggregate contract を読む
`--group-by industry-33`	上場企業の業種別会社数	`aggregate.groups[]` と従業員数欠損内訳を同時に読む
`--ai-jobs`, `--job-location`, `--prefecture`	job search	求人行の条件を構造化する

エージェントが原則避ける flag / パターン

Flag / pattern	避ける理由
API key をコマンドラインに直接渡す	shell history と transcript に残る。通常は `sf login` を使う
credit 消費 Signal read を残高確認なしで繰り返す	無料枠を食い潰しやすい
unsupported 条件を 0 件成功にする	silent failure になる
preview URL を API base URL にする	deploy preview と production data の境界が崩れる
list flag を空白区切りで渡す	`--include hiring,cases` のようにカンマ区切りにするか、flag を複数回指定する

失敗時の復旧

失敗時はまず JSON error を見ます。error envelope、exit code、復旧コマンドの正本はヘルプとエラーです。

Agent surface の確認

エージェントが自然文を実行前に分解する場合は、通常の help に加えて capability surface を読みます。

sf data capabilities --agent-surface --json

公開ワークフローでは、次のような境界を満たしているかを確認します。

境界	期待する動き
財務しきい値 / ranking	`company_query.v1` に構造化し、`sf search` の `q` に残さない
ROE / ROA	`return_on_equity` / `return_on_assets` として実行し、営業利益率や純利益率で代用しない
free cash flow / EBITDA	`financial_metric` として `company_query.v1` に構造化し、営業CF単独・売上・粗利などで代用しない
trend、四半期、OR / NOT、cash runway、short/long debt	`unsupported_predicate` として止める
個人連絡先、未公開情報、リアルタイム株価、SNS firehose	top-level `unsupported.source` として止める
年収しきい値つき求人会社	`structured_job_salary` として止め、salary sort に逃がさない

Reference の正本

細かい option は CLI 自身が正本です。各コマンドに --help --json を付けて確認します。help コマンドの一覧と読み方はヘルプとエラーを見てください。

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

CLI