Signal Foundry CLI

Agent-first CLI for Signal Foundry.

sf は Signal Foundry の agent 実行面です。skills が自然文の依頼を route し、CLI が job artifact、source row、evidence、run を stable command / structured error / JSON contract として返します。

Signal Foundry は会社リスト作成CLIではなく agent-native data workspace です。v0 は company-first ですが、操作単位は source -> row -> column -> evidence -> run です。会社リスト作成は重要な導線の1つで、全体像は job -> artifact -> evidence/run -> list/source/enrich/export です。

Release notes are tracked in CHANGELOG.md.

Choose the right entrypoint

| User intent | Start here | Output | | --- | --- | --- | | 何を調べるべきか、前提が曖昧 | sf job business-understanding <query> --execute --json | business_understanding_brief artifact, open gaps, safe / blocked commands | | 1社を深掘りしたい | sf job company-research <company> --execute --json | company_research_note artifact with profile / observations / optional filings | | 条件に合う会社群を作りたい | sf list plan -> estimate -> discovery materialize | discovery run, candidates preview, saved List | | CSV / 外部sourceを持ち込みたい | sf source import -> inspect -> map -> resolve | source rows resolved to company master | | 検索済みの会社をそのまま保存したい | sf companies search -> sf list create --company-id | explicit company-id saved List | | 保存済みListを強くしたい | sf list enrich <listId> --source website|parallel --estimate | enrichment estimate / preview, then bounded execute | | 保存済みListを見直したい | sf job watchlist-review <listId> --execute --json | watchlist_review_queue artifact |

Parallel は broad search / Find All の入口ではありません。Signal Foundry で絞った saved List に対する bounded enrichment として使います。

job artifact flow

sf data capabilities --json
sf job business-understanding "兵庫県の建設業向けに生成AI研修を売りたい" --buyer 情シス --product 生成AI研修 --pain 業務効率化 --execute --json
sf job business-understanding "兵庫県の建設業向けに生成AI研修を売りたい" --buyer 情シス --product 生成AI研修 --pain 業務効率化 --execute --save --json
sf job artifact ls --job business-understanding --json
sf job artifact show --run-id <runId> --json
sf job company-research 7203 --execute --json

business-understanding は外部調査や list materialize を勝手に実行しません。artifact に targeting_context、evidence_strategy、list_strategy、open gaps、coverage review、credit risk、safe / blocked command contracts を固定します。targeting_context.readiness が needs_clarification の場合は、missing_keys を埋めるまで target list / materialize / external research に進みません。--save を付けると workspace に残り、Research / evidence 画面と sf job artifact show から再開できます。

credit workspace flow

sf data capabilities --json
sf list plan "上場企業で売上100億以上、生成AIに関連" --json
sf list estimate "上場企業のうち、売上100億以上" --json
sf discovery show <runId> --json
sf discovery refine <runId> "神戸市だけ" --json
sf discovery materialize <runId> --name "神戸市の建設業" --execute --max-credits 100 --json
sf list estimate "上場企業" --industry-33-code 7050,7100 --json
sf list candidates --from-estimate <estimateId> --json
sf list materialize --from-estimate <estimateId> --name "売上100億以上の上場企業" --execute --max-credits 100 --json
sf list create --company-id cn_6010001187623 --company-id jpx_7203 --name "確認済み候補" --json
sf list enrich <listId> --source website --estimate --json
sf list enrich <listId> --source website --execute --max-credits 100 --json
sf list enrich <listId> --source parallel --estimate --limit 10 --json
sf list enrich <listId> --source parallel --execute --limit 50 --max-credits 50 --json
sf list show <listId> --json
sf list export <listId> --format csv --output ./exports/listed-revenue-10b.csv --json
sf credits balance --json
sf credits summary --json

会社群や営業候補を保存する導線は capabilities -> plan -> estimate -> discovery run -> materialize -> enrich -> export です。これは Signal Foundry の全体ではなく、会社群を作るときの導線です。data capabilities と list plan は agent が使える source と未対応条件を確認するための無料・local contract です。estimate と candidates は無料、materialize は Basic credit、enrich は source ごとの enrichment credit を使います。list estimate 後に追加条件が出たら、元 query を作り直さず discovery_run.run_id で sf discovery show / refine / materialize に進みます。materialize 後は sf list show で saved row projection の companies[].website_url / companies[].website_domain / companies[].preview_sources / companies[].source_types / companies[].why_now_summary を確認します。持ち込み source を保存するだけでは credit boundary にしません。Signal Foundry が row を正規化・保存したり enrichment column / evidence cell を作ったりする実行が credit 対象です。sf list enrich --estimate は対象件数、既存 enrichment の再利用件数、最大追加 credit、preview rows を返します。website enrichment は found row だけ credit を使い、not_found / no_data は課金対象外です。Parallel は候補生成ではなく、saved List に絞った後の --source parallel --estimate --limit <n> / --source parallel --execute --limit <n> --max-credits <n> として扱います。保存済み List の export は無料です。Parallel enrichment 済みの export CSV には parallel_enrichment_status、parallel_enrichment_summary、parallel_enrichment_query、parallel_enrichment_urls、parallel_enrichment_signals などの列が入ります。

companies search で既に company_id が分かっている場合は、sf list create --company-id <companyId> --name "<name>" --json で saved List にできます。この導線は自然文の universe discovery ではなく、agent/user が確認済みの会社を明示保存するためのものです。

source import flow

ユーザーが CSV や外部sourceを持ち込む場合は、保存だけでは credit を使いません。Signal Foundry の company master に解決できた row だけが Basic credit の対象です。

sf source import ./companies.csv --name "展示会リード" --json
sf source inspect <sourceId> --json
sf source map <sourceId> --entity company --column company_id=company_id --column corporate_number=法人番号 --column name=会社名 --column domain=URL --json
sf source resolve <sourceId> --execute --max-credits 100 --json
sf source review <sourceId> --status multiple_candidates --json
sf source review <sourceId> --status not_found --json
sf source select <sourceId> --row <sourceRowId> --company <companyId> --max-credits 1 --json
sf list create --from-source <sourceId> --name "展示会リード" --json
sf list enrich <listId> --source website --estimate --json
sf list enrich <listId> --source website --execute --max-credits 100 --json
sf list export <listId> --format csv --output ./exports/imported-leads.csv --json

source inspect は headers、sample rows、detected identifier candidates、mapping warnings を返します。source resolve は matched / multiple_candidates / not_found / invalid を返します。Signal Foundry の ID だと明確な sf_company_id などは自動検出され、汎用 company_id 列は CRM 側 ID の可能性があるため --column company_id=<header> で明示した場合だけ company master に直結します。multiple_candidates は source review で候補を確認し、ユーザーが明示したものだけ source select で matched にします。not_found / unresolved / invalid row でも、companies search などで確認済みの company_id があれば source select --company <companyId> で明示接続できます。source select は新規選択時に 1 Basic credit を使い、同じ row/company の再試行は二重消費しません。list create --from-source は matched rows だけを saved List にします。export CSV には標準の会社情報・enrichment列に加えて、source:<original_header> として元CSV列も残ります。

job flow

sf job business-understanding "HULFT Square の競合調査" --json
sf job business-understanding "兵庫県の建設業向けに生成AI研修を売りたい" --buyer 情シス --product 生成AI研修 --pain 業務効率化 --execute --json
sf job business-understanding "HULFT Square の競合調査" --execute --save --json
sf job artifact ls --job business-understanding --json
sf job artifact show <artifactId> --json
sf job company-research 7203 --json
sf job company-research 7203 --execute --json
sf job sales-list "生成AI CRM に反応している上場SaaS" --json
sf job sales-list "生成AI CRM に反応している上場SaaS" --execute --json
sf job sales-list "生成AI CRM に反応している上場SaaS" --execute --save --account-id <uuid> --json
sf job watchlist-review <listId> --json
sf job watchlist-review <listId> --execute --json
sf job watchlist-review <listId> --execute --refresh --account-id <uuid> --json

sf job business-understanding は BIZ-870 の orchestration 入口です。business_understanding_brief artifact に company context、product、buyer、user job、current alternative、pain/signal、targeting_context、evidence_strategy、list_strategy、known facts、open gaps、coverage review、research insertion plan、credit explanation、handoff readiness、safe / blocked command contracts を固定します。--execute でも外部調査を勝手に実行せず、local Signal Foundry route で足りない gap が明確になり、--allow-external-research、--max-credits、対象 list_id が揃うまで estimate / suggested command に留めます。target list に進む前に targeting_context.readiness と targeting_context.missing_keys を確認します。list_strategy.export_goal は、saved List row が company identity、why_now、evidence、website、enrichment、targeting context を持った表になることを確認するための handoff です。--save を付けると workspace に artifact を保存し、sf job artifact show <artifactId> --json または sf job artifact show --run-id <runId> --json で再開できます。

sf job company-research は agent-ready job surface の最小入口です。sf job company-research 7203 --json は shared job response envelope で plan を返し、company_research_note artifact と planned steps を先に固定できます。--execute は 1 社に解決できたら profile / observations / optional filings を読み、stable company_research_note artifact を返します。0 件 / 複数候補なら needs_human を返します。observations / filings / compare の非 fatal failure は evidence_gaps に寄せ、profile failure は fatal のまま扱います。

sf job sales-list は plan に加えて discovery execute と save execute を持ちます。--execute は criteria を deterministic な short query と market filter に落とし、POST /api/signal-foundry/observations/search から candidate を返します。candidate には reason, evidence, confidence, evidence_gap が入り、0 件なら fallback guidance を返します。--execute --save は discovered candidates の company_id を saved List に materialize し、candidate rationale を list-scoped research/items に保存し、free refresh で latest diff に反映したうえで list_id と sf job watchlist-review <listId> --execute --json を返します。

テーマ語だけの候補発見は sales-list / observations search、保存前の credit 見積もりは list estimate です。list estimate は bounded なEDINET本文テーマ検索も見ますが、保存目的なら先に observations search --source edinet で evidence を確認し、list estimate -> discovery show/refine -> discovery materialize に進みます。

sf job watchlist-review は plan に加えて review execute を持ちます。--execute は GET /api/signal-foundry/lists/:listId/diffs/latest を読み、diff summary を残しつつ row を high / medium / low / ignore の 今日見る順番 に整形した watchlist_review_queue artifact を返します。high / medium は why_now, evidence, next_action を持ち、low / ignore は suppress reason を返します。--execute --refresh は先に POST /api/signal-foundry/lists/:listId/refresh を呼んでから latest diff を読みます。

Data Capability Map

| Surface | 向いていること | 現時点で期待しないこと | | --- | --- | --- | | data capabilities | 現在の source / filter / pricing / evidence / limitation を machine-readable に確認する | remote data fetch や課金見積もり | | list plan | 自然文 list query を supported / weak / unsupported conditions に分解する | 保存、課金、remote API 実行 | | companies identity | 会社名、ブランド名、証券コード、domain stem から identity_status 付きの identity card を返す | ambiguous / generic_name / not_found を agent が勝手に確定すること | | companies search | 証券コード、社名、domain、識別子、--industry-33-code から company_id 候補を解決する | 長い自然文の会社群検索 | | company_registry | 何百万社規模の日本企業 universe から地域、業種キーワード、Webサイト有無、非上場などを高速に見積もる | source of truth として扱うこと。必要なら materialize / enrichment / evidence lookup に進む | | list estimate | 上場状態、JPX公式の新規上場日、market segment、JPX 33業種コード、会社名/識別子、EDINET 財務指標しきい値、bounded なEDINET本文テーマ検索で会社群と credit を見積もる | list plan で unsupported と出た条件の強行保存 | | discovery show / refine / materialize | estimate 後の run_id から会話状態を復元し、追加条件で絞り、run_id のまま保存する | agent 側で query を雑に連結し直すこと | | list create --company-id | companies search や source review で確認済みの company_id を saved List に固定する | 未解決の自然文条件から広く候補生成すること | | observations search | 生成AI LLM 人工知能 などのテーマ語の横断 evidence を探す。--technology generative_ai|genai|llm|ai_agent は EDINET theme alias として扱う | saved List 作成や credit 見積もり | | job business-understanding | 会社・事業理解から target list / watchlist review へ進む前の artifact と open gaps を固定する | 外部調査や target list 生成を勝手に実行すること | | job sales-list | テーマから候補 discovery と evidence review をする | 保存の正規導線として使うこと。保存は list estimate -> materialize を優先 | | list enrich --source parallel | narrowed saved List の公式サイト確認や最新情報補完を Parallel Search で高速に実行する | Signal Foundry route / estimate / preview 前の broad search や Find All | | company profile / observations / filings / compare | v0 の entity type である company を深掘りする | unresolved な社名を直接渡すこと |

list plan が needs_human を返した場合や、plan.confidence が low、plan.weak_conditions / plan.unsupported_conditions がある場合は、そのまま materialize せず、query を対応済み条件に分解してください。list estimate 後は resolved_definition.warnings や date / temporal filter の扱いも確認します。

list plan が company_name_identity / website_domain_identity を返した場合は list estimate へ進まず、safe_next_commands の sf companies identity ... --json を先に実行します。identity_status: ambiguous | generic_name | not_found は質問で止め、法人番号・証券コード・所在地・URLなどで再解決してください。トヨタグループ のような group scope は entity_scope を確認してから進めます。

job command で足りないときだけ、次の low-level surface に降ります。

sf companies identity KEYENCE --json
sf companies search 7203 --json
sf company profile jpx_7203 --json
sf company observations jpx_7203 --limit 5 --json

前提

• Node.js 20+
• base URL
• API key

通常の production 利用では、まず https://signal-foundry.app/auth/sign-up でアカウントを作成し、/home/settings/api-keys で API key を発行します。招待リンクはチーム参加用の補助導線であり、CLI 利用開始には不要です。

install

最短の確認:

npx -y @signal-foundry/cli@latest version --check-update

継続利用:

npm install -g @signal-foundry/cli
sf version --check-update

更新:

npm install -g @signal-foundry/cli@latest
sf version --check-update

特定 version に固定して更新する場合:

npm install -g @signal-foundry/[email protected]
sf version --check-update

通常は @latest を使います。固定 version は検証再現や一時的な rollback が必要なときだけ使います。

interactive terminal では、1 日に 1 回だけ npm の latest version を確認し、古い場合は stderr に更新コマンドを表示します。agent / automation は sf version --json --check-update を最初に実行し、JSON の update.update_available を見ます。通常の --json 出力には notice を混ぜません。不要な場合は SIGNAL_FOUNDRY_CLI_UPDATE_CHECK=0 で止められます。

npm の @signal-foundry/cli が取得できない場合は、まず registry / network / npm login の問題として切り分けます。internal fallback が必要な社内検証では、repo access か tarball handoff を使います。

この CLI は proprietary client です。利用条件の正本は tooling/signal-foundry-cli/LICENSE と https://signal-foundry.app/terms-of-service を参照してください。

auth

sf auth setup --base-url https://signal-foundry.app
sf auth show --json

sf auth setup は、初回接続を人間向けに短くするための導線です。API キー設定画面を開き、API キーはターミナルの隠し入力で保存します。Claude Code / Codex の chat には貼り付けないでください。

社内/初期ユーザーに渡す最短コマンド:

npm install -g @signal-foundry/cli@latest
sf version --check-update
sf auth setup --base-url https://signal-foundry.app
sf auth show --json

agent skill install

Codex / Claude Code に自然文で渡したい場合は、CLI に同梱された skill bundle を 1 回だけ配置します。

sf agent install --target codex
sf agent install --target claude

インストール先:

• Codex: ~/.codex/skills/signal-foundry-agent
• Claude Code: ~/.claude/skills/signal-foundry-agent

上書きするとき:

sf agent install --target codex --force
sf agent install --target claude-code --force

配置後は、対象 agent を再起動してください。

旧式の手動保存 loop まで確認するなら、次を足します。

sf list create "AI Targets" --json
sf list create --company-id cn_6010001187623 --name "確認済み候補" --json
sf research add jpx_7203 --content "補助的な外部調査メモ" --json
sf list preview <listId> --json
sf list publish <listId> --json
sf list refresh <listId> --json
sf list diff <listId> --json
sf credits balance --json

新しい会社リスト作成は sf list plan で条件分解してから sf list estimate に進みます。list create -> research add -> preview -> publish -> refresh -> diff は手動メモや既存 watchlist の fallback です。

feedback

ユーザーが明示した要望・不具合だけを、Signal Foundry API 経由で Canny-backed feedback intake に送れます。Canny API key はサーバー側にだけ置き、CLI には保存しません。

sf feedback create "list estimate の条件指定を増やしたい" --details "Codex から使っていて、業種と地域を別々に指定したいです。" --source codex --surface list.estimate --json
sf feedback create "company search が 0 件になる" --kind bug --details-file ./feedback.md --source claude --surface companies.search --json

Claude Code / Codex から送る場合も、raw transcript、API key、顧客の秘密情報は送らず、要約済みの title/details だけを送ってください。

運用ルール

• --help は subcommand ごとの usage / examples / next commands を返す
• agent 実行では --json を基本にする
• 会社群や営業候補は sf data capabilities と sf list plan で route を確認してから sf list estimate に進む
• materialize と enrich は必ず estimate 後に --execute --max-credits で実行する
• 失敗時は ok: false と error.code / error.hint / error.suggested_next_commands を見る
• profile や filings の前に、必ず companies search で company_id を解決する

詳細は repo docs を参照:

• docs/signal-foundry-agent-quickstart.md
• docs/signal-foundry-cli.md
• docs/signal-foundry-private-distribution.md