Essential Commands

このページは CLI の最小正本です。agent は workflow page で job を選び、このページで実行順を確認し、詳細が必要なときだけ個別 CLI / API page に降ります。

原則は 4 つです。

• agent-facing command は --json を付ける
• 保存や enrichment は --execute --max-credits <n> を付ける
• preview は export できない
• 失敗時は error.hint と error.suggested_next_commands から再開する

operation ごとの無料 / 有料境界は Credit Schedule を見ます。source と evidence の出所は Data Provenance を見ます。

0. 起動前の確認

sf version --json --check-update
sf auth show --json
sf data capabilities --json

確認する key:

• version
• update.available
• effectiveBaseUrl
• effectiveApiKeyPreview
• configPath
• contract_version
• capabilities[].source_id
• capabilities[].status
• capabilities[].filters[]
• capabilities[].pricing
• capabilities[].limitations[]

古い CLI なら更新し、agent skill も入れ直します。

npm install -g @signal-foundry/cli@latest
sf agent install --target codex --force
sf agent install --target claude --force

capability.status が weak / unsupported / needs_human の場合は、0 件成功として扱いません。制約を人間に返すか、該当 workflow の復旧手順に進みます。

1. 会社群を保存する

自然文から営業候補や調査対象の List を作るときの正規順です。

sf list plan "上場企業のうち、売上100億以上" --json
sf list estimate "上場企業のうち、売上100億以上" --json
sf list candidates --from-estimate <estimateId> --json
sf list materialize --from-estimate <estimateId> --name "売上100億以上の上場企業" --execute --max-credits 100 --json

確認する key:

• plan.status
• plan.weak_conditions
• plan.unsupported_conditions
• estimate.estimate_id
• resolved_definition
• counts.matched_companies
• billing.materialize.estimated_credits
• companies[].company_id_hint
• companies[].company_hint
• list.list_id
• list.row_count
• billing.credits_used

list plan は無料です。estimate と candidates も保存前の確認です。materialize で saved List が作られ、Basic credit を使います。

2. 追加情報を足して export する

saved List に website enrichment を足す場合は、先に見積もります。

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/list.csv --json

確認する key:

• estimate.estimated_max_credits
• estimate.already_completed_companies
• estimate.reusable_existing_companies
• preview_rows
• run.run_id
• run.found_count
• run.not_found_count
• billing.credits_used
• path
• row_count
• sha256

enrichment は found row / column / evidence の分だけ credit を使います。保存済み List の export は無料です。list candidates の preview は export できません。

3. CSV や外部 source から始める

ユーザーが会社名リストや展示会 CSV を持ち込む場合は、source workflow を先に通します。

sf source import ./companies.csv --name "展示会リード" --json
sf source inspect <sourceId> --json
sf source map <sourceId> --entity company --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 select <sourceId> --row <sourceRowId> --company <companyId> --max-credits 1 --json
sf list create --from-source <sourceId> --name "展示会リード" --json

確認する key:

• source.source_id
• source.row_count
• headers[]
• mapping.status
• run.resolved_count
• run.multiple_candidates_count
• run.not_found_count
• run.review_required_count
• source.resolve_summary.matched
• source.resolve_summary.multiple_candidates
• rows[].resolve_candidates
• billing.credits_used
• list.list_id

resolution.*_count は run.*_count と同じ count contract です。agent は billing から件数を推測せず、run.resolved_count、run.multiple_candidates_count、run.not_found_count、run.review_required_count を読みます。multiple_candidates は agent が勝手に確定しません。source review で候補を見せ、ユーザーが明示した row/company だけ source select します。

4. 会社・事業理解を固定する

会社理解、競合調査、営業ターゲット、pricing targeting の前提が曖昧なら、List に進む前に business understanding artifact を作ります。

sf job business-understanding "HULFT Square の競合調査" --json
sf job business-understanding "兵庫県の建設業向けに生成AI研修を売りたい" --buyer 情シス --product 生成AI研修 --pain 業務効率化 --execute --json

確認する key:

• artifacts[].type = business_understanding_brief
• artifacts[].targeting_context.readiness
• artifacts[].targeting_context.missing_keys
• artifacts[].evidence_strategy.recommended_commands
• artifacts[].list_strategy.entrypoint
• artifacts[].list_strategy.export_goal
• artifacts[].open_gaps[]
• artifacts[].credit_boundary
• artifacts[].handoff.safe_next_commands
• artifacts[].representative_fixture_matrix

open_gaps[].blocks_target_list が true の場合は、target list / materialize / external research へ進まず確認を返します。

5. 1 社を調べる

1 社が主語なら、List ではなく company research から入ります。

sf job company-research 7203 --json
sf job company-research 7203 --execute --json

足りない場合だけ raw 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
sf company filings jpx_7203 --limit 5 --json
sf filing show jpx_7203 <filingId> --json

確認する key:

• identity.company_id
• identity.matched_by
• identity.confidence
• candidates[].candidate_rank_reason
• job
• mode
• status
• steps[].status
• company.company_id
• company_summary
• source_summary
• important_observations
• filings
• filing_detail
• evidence
• evidence_gaps[]
• next_actions[]
• suggested_next_commands[]

sf job company-research は agent がそのまま読める top-level field として company_summary、source_summary、important_observations、filings、filing_detail、evidence、next_actions を返します。artifacts[] は互換 surface です。sf companies identity は短い identity card を返します。候補が競合する場合は candidates[] を見て、勝手に確定せず人間に確認します。profile failure は fatal、observations / filings / compare の一部失敗は evidence_gaps に残します。

6. テーマの根拠を見る

保存より先に市場テーマや競合候補の根拠を見たいときは、cross-company observation search を使います。

sf observations search "生成AI" --source edinet --json
sf observations search --query "生成AI CRM" --industry 情報・通信業 --market-segment prime --json

確認する key:

• results[].company.company_id
• results[].company.display_name
• results[].matched_observations[]
• results[].score.max_relevance
• meta.returned_companies
• meta.matched_observations

テーマ語だけの依頼をそのまま saved List にしないでください。根拠を見てから、保存できる条件に分解して list plan -> estimate に戻ります。

7. Credit を確認する

sf credits balance --json
sf credits summary --json

確認する key:

• balance.available_credits
• balance.grants[]
• balance.consumption_order
• summary.totalQuantity
• summary.meterBreakdown[]
• summary.usageBreakdown[]
• summary.recentEvents[]

credit_balance_insufficient や max_credits_exceeded が出た場合は、先に残高と必要 credit を見直します。

8. Feedback を送る

明示された要望や不具合だけ送ります。raw transcript、API key、顧客秘密情報は送らないでください。

sf feedback create "list estimate の条件指定を増やしたい" \
  --details "業種と地域を別々に指定したいです。" \
  --source codex \
  --surface list.estimate \
  --json

失敗時

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

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

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

credit 消費や保存を伴う suggested_next_commands は、人間に上限と対象を確認してから実行します。

次に読むページ

• job から選ぶ: Workflow overview
• saved List の詳細: Lists / Research / Credits
• theme-first 探索: Observations Search
• error shape: Help と Error Handling