基本コマンド

このページは CLI の最小正本です。エージェントは目的を選び、このページで Search / Company Card / Signals / Usage の実行順を確認します。

原則は 4 つです。

• エージェント向けコマンドは --json を付けます
• まず sf search で company_id を解決します
• sf company <companyId> で要点を読み、必要な Signals だけ深掘ります
• リストや CSV はローカルで作れます。確定した会社群は sf list で Saved List に保存できます

主要コマンドの credit は次のとおりです。

操作ごとの無料 / 有料境界は クレジット表 を 見ます。取得元と根拠の出所は データの出所 を見ます。母集団、coverage、semantic tag の読み方は データカバレッジと semantic tag を見ます。

0. 起動前の確認

sf version --json --check-update
sf auth show --json
sf search 7203 --json

見る key:

• version
• update.current_version
• update.latest_version
• update.update_available
• effectiveBaseUrl
• authMode
• oauth.tokenAvailable
• companies[].company.company_id
• companies[].company.display_name
• meta.returned_companies

CLI が古い場合の更新手順は sf CLI のインストール を見ます。

1. 会社を探す

識別子で特定する:

sf search 7203 --json
sf search KEYENCE --json
sf search global.toyota --json

条件検索:

sf search "生成AI" --listing-status listed --json
sf search "AI求人" --prefecture 大阪府 --has-jobs true --json
sf search --prefecture 東京都 --industry-33-code 5250 --ai-jobs true --json

structured filter を 1 つ以上指定する場合、query は省略できます。query も structured filter もない入力は usage error です。

Search は入力された query と structured filter を決定的に実行します。 会社名、証券コード、法人番号、domain、または 2〜5 語の短い検索語を渡してください。 所在地、業種、上場区分、従業員数は option で明示します。 エージェントは依頼文から検索語と option を組み立てます。サーバーは長い依頼文を分解しません。

sf search "AI求人" --prefecture 東京都 --industry-33-code 5250 --ai-jobs true --json

planner.mode は compatibility field として deterministic を返します。 0件の場合は gaps[] の query_not_interpreted / no_rows / search_temporarily_unavailable を確認してください。

見る key:

• companies[].company.company_id
• companies[].company.display_name
• companies[].card
• companies[].source_context
• companies[].query_match
• planner
• meta.returned_companies
• meta.matched_companies
• meta.total_kind
• meta.pagination_supported
• meta.more_results_exist
• meta.results_truncated

Search で meta.more_results_exist=true の場合は、条件を explicit filters に分けて再実行します。 offset が必要な既存連携だけ、HTTP /companies または MCP company_search の互換入力を使います。

meta.matched_companies は meta.total_kind と組で読みます。exact は確定値、lower_bound は現在ページまでに確認できた下限、estimate は scan / truncation を含み得る推定です。lower_bound と estimate を母集団の確定分母にしないでください。総数を返さない場合は matched_companies: null と total_kind: "unknown" の組になります。

候補が競合する場合は companies[] を見て、勝手に確定せず人間に確認します。

財務閾値を決定的に扱う場合は、自然文を q に残さず、エージェントが company_query.v1 JSON を作ってから実行します。詳細は コマンドとフラグ を見ます。

sf query --file company-query.json --json

見る key:

• query.status
• query.executors.financial_gold.status
• query.executors.financial_gold.result.matched_count
• query.executors.financial_gold.result.matched_financial_facts[]
• search.meta.returned_companies
• search.meta.coverage_warnings

MBO / TOB / 上場廃止 / 合併の候補は event executor で確認します。

sf event search "MBO TOB" --limit 100 --json

--limit は既定 20、最大 100 です。見る key:

• query.executors.company_events.result.matched_count
• query.executors.company_events.result.truncated
• query.gaps[]
• search.meta.returned_companies

truncated=true の場合、返却会社を event 母集団の全件として扱いません。 company_event_result_truncated gap の pagination_supported=false と suggested_actions[] を読み、--event-type、--since、--until で絞ります。 event result の offset / cursor pagination は未対応です。

会社検索だけを細かく確認する場合は Company Search を見ます。

2. Company Card を読む

sf company <companyId> --json

見る key:

• company.company_id
• company.display_name
• card
• card.insured_persons
• source_coverage
• suggested_next_commands[]

被保険者数(card.insured_persons)

会社規模の一次指標です。日本年金機構の月次集計で、人間向け出力では Insured persons (social insurance): <人数> (as of YYYY-MM) の 1 行で出ます。

読み方:

• 頭数の従業員数ではありません。上場法人の適用事業所単位の集計で、持株会社では連結従業員数よりずっと小さく出ます。caveat に同じ注意が入ります。
• key が無い場合は「未観測」です。0 人とは扱わないでください。meta.source_coverage.insured_persons が found / no_data / error を示します。
• signals.insured_person_count と freshness.insured_persons_observed_month にも同じ値が入ります。JSON の card.scale.employee_number は互換のため残っていますが、観測時点が不明なため規模判断には被保険者数を使ってください。

足りない場合だけ Signals を読みます。

3. Signals を読む

まず標準の signal envelope を読みます。

sf signals <companyId> --json

絞り込みは --include hiring,cases,technology,ir,web と --limit <n> だけです。 signal 種別を絞る前に、sf signals --help --json の topic.options[] で現行の option を確認します。ここにない入力を渡すと invalid_query になります。

見る key:

• signals.hiring
• signals.cases
• signals.technology
• signals.ir
• signals.web
• gaps[]
• actions[]
• usage

求人や建設許可の行レベル detail が必要な場合:

sf job search "<query>" --json
sf construction search "<query>" --json

4. リストを作る・複数会社を扱う

ユーザーが「リスト」「CSV」「表」を求める場合は、Signal Foundry の返却 JSON からエージェント側でローカル出力を作れます。後で共有・再利用する場合は Saved List に保存します。複数会社も同じ確認手順です。

1. sf search "<criteria>" --json を実行します。
2. companies[] と card を読みます。
3. 必要な会社だけ Company Card または Signals を読みます。
4. Markdown / JSON / CSV をローカルで生成するか、確定した会社だけを Saved List に保存します。

sf list create "<list-name>" --json
sf list add <list-id> --company <company-id> --json
sf list show <list-id> --json
sf list export <list-id> --csv

複数の確定 ID は、JSON array を sf list add <list-id> --stdin-json --json へ渡せます。already_present[] と unknown_company_ids[] を分けて確認してください。持ち込み CSV の判定手順は 営業リストの名寄せ を見ます。

5. Usage を確認する

sf usage --json

見る key:

• usage.search
• usage.card
• usage.signals
• usage_limits.plan
• usage_limits.remaining
• summary.usage_key_totals
• representative_estimates[]

credit_balance_insufficient や rate_limit_exceeded が出た場合は、先に残高、 usage、対象件数を見直します。

失敗した場合

ok: false が返ったら次を見ます。

• error.code
• error.hint
• error.retryable
• error.suggested_next_commands[]

invalid_query が返る場合:

1. sf signals --help --json など、失敗した surface の help を確認します。
2. topic.arguments[] と topic.options[] にない入力を渡していないか確認します。
3. Signals が薄い場合は sf search に戻って候補条件を見直します。

help の読み方、error envelope、exit code、復旧コマンドの正本は ヘルプとエラー です。

weak、unsupported、needs_human、credit error を 0 件成功として扱わないで ください。

次に読むページ

• 目的から選ぶ: ユースケース
• 会社検索の詳細: Company Search
• 1 社調査: 1社調査
• error shape: ヘルプとエラー