cargo-context

Cargo CLI — コンテキスト

コンテキストは、ワークスペースのGTMナレッジ（企業のナラティブ、ICP、ペルソナ、プレイブック、実績、異議など）を記録した、Gitで管理される型付きMarkdown／MDXファイルのリポジトリです。人間とエージェントの両方が読み書きします。cargo-ai contextドメインには、次の2つのサブドメインがあります。

• runtime — ワークスペースのランタイムサンドボックス（コンテキストリポジトリをチェックアウトしたコピー）を参照、読み取り、書き込み、編集し、その環境でコマンドを実行します。write／editはデフォルトブランチにプッシュされ、executeはコマンドの実行後に作業ツリーに残った追跡対象の変更を自動でコミットしてプッシュします。
• graph — コンテキストリポジトリ内のすべてのMarkdown／MDXファイルからナレッジグラフを構築／読み込みます。

コンテキストリポジトリの標準的な例はgetcargohq/cargo-workspacesです。新しいエントリーを書く前に、そのドメイン構成とファイル規約を理解するため、README.mdをお読みください。 バッチ実行で使用するランタイムに依存しないファイル（CSV、PDF）をアップロードするには、cargo-workspace-management（cargo-ai workspaceManagement file upload）を使用してください。 エージェントにRAGファイルを添付するには、cargo-ai（cargo-ai content file upload）を使用してください。

コンテキストリポジトリの全体構成とドメインごとのテンプレートについては、references/conventions.mdを参照してください。 各cargo-ai contextコマンドが返すJSONの形式については、references/response-shapes.mdを参照してください。 よくあるエラーとその解決方法については、references/troubleshooting.mdを参照してください。 最初から最後までの追加／編集／削除手順については、references/examples/authoring.mdを参照してください。 初期設定と通話データからの更新の手順については、references/examples/lifecycle.mdを参照してください。 ナレッジグラフの調査については、references/examples/graph-queries.mdを参照してください。

初期設定

すでにサインイン済みで（cargo-ai whoamiがワークスペースを返す場合）、次のセクションに進んでください。

npm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`
cargo-ai login --email [email protected]  # emailed code, no browser; creates the account on first use
                                        # alternatives: --oauth (browser) · --token <api-token> (CI)
cargo-ai whoami                         # confirm the active workspace before any write

すべてのコマンドはJSONを標準出力に出力します。失敗した場合はゼロ以外で終了し、エラーを標準エラーに出力します（パイプ経由の場合：{"error": "...", "status": <http>, "body": {"reason": "..."}}。body.reasonは機械可読な原因です）。実行やバッチを作成するコマンドはすべて非同期です。--wait-until-finishedを渡すか、対応するgetをポーリングしてください。runtime writeとruntime editはワークスペースのコンテキストリポジトリにコミットしてプッシュするため、事前にworkspace.nameを確認することが必須です。スキル一式がインストールされている場合は、../cargo/references/prerequisites.mdにCLIのバージョン固定、トークンのスコープ、管理者専用の機能が記載されています。

まずコンテキストを確認する

編集を始める前に、コンテキストリポジトリの内容を確認してください。

cargo-ai context runtime browse                 # list entries at the runtime sandbox root
cargo-ai context graph get                      # full knowledge graph derived from the repo's md/mdx files

クイックリファレンス

# Runtime sandbox (checked-out copy of the context repo)
cargo-ai context runtime browse [--path <path>]
cargo-ai context runtime read --path <path> [--start-line <n>] [--end-line <n>]
cargo-ai context runtime write --path <path> --content <content> [--commit-message <message>]
cargo-ai context runtime edit --path <path> --old-string <old> --new-string <new> [--replace-all] [--commit-message <message>]
cargo-ai context runtime execute --command <command> [--args <json>] [--commit-message <message>]

# Knowledge graph
cargo-ai context graph get

ランタイムサンドボックス

ランタイムサンドボックスは、チェックアウト済みで実行可能なコンテキストリポジトリのコピーです。コンテキストファイルの読み取りや変更、ファイルに対するコマンドの実行に使用します。

覚えておくべき重要な動作が 2 つあります。

• write と edit はコンテキストリポジトリのデフォルトブランチにプッシュします。 ローカルだけに反映されるわけではありません。
• execute もプッシュします。 コマンドの実行後に追跡対象ファイルが追加、変更、削除、または名前変更されている場合、それらの変更は自動的にコミット（メッセージは context(runtime): execute <command>、または --commit-message）され、デフォルトブランチにプッシュされます。Git で無視されるパスはスキップされます。execute 経由で実行した sed -i や rm も Git に反映されます。

ミラーされたコンテンツファイルは .files/ の下に読み取り専用で保存されます。 mirrorToContext: true で保存されたコンテンツファイル（content file upload、ウェブアプリからのアップロード、defineFile ではデフォルト。詳細は cargo-content を参照）は、コンテキストリポジトリの .files/<folder path>/<name> にコミットされ、プッシュされます（コミットメッセージは content(mirror): upsert <name>、… move …、… remove …。10 MB を超えるファイルは、バイトデータではなく JSON メタデータのサイドカーとして保存されます）。execute（または read／browse）経由で実行するコマンドから利用できます。例：cargo-ai context runtime execute --command ls --args '["-1",".files"]'。パスを指定して書き込むファイル（content file put、objects API、ワーカー、writeFile ノード、エージェントによる書き込み）は、デフォルトで mirrorToContext: false のため、ここには保存されません。ランタイムから .files/ の内容を追加または変更することはできません（deniedPath）。cargo-ai content file … を使用してください。コンテキストリポジトリを読み取れるユーザーは、ミラーされたすべてのファイルを読み取れます。

書き込みはすぐにプッシュされるため、最初に write／edit を使う前に、対象のワークスペースを確認してください。

cargo-ai whoami   # → workspace.uuid, workspace.name

ワークスペース名をユーザーに読み上げて確認してください。セッションが特定のクライアント向けの場合、何かを作成する前に workspace.name が一致していることを確認してください。ドライランモードはありません。workspace.name が一般的、または曖昧（例：「Main」、「Test」、個人名、社内コードネーム）な場合は、推測せず、会社名と正式なドメイン（example.com）をユーザーに尋ね、最初の書き込み前に両方を確認してください。ワークスペースを指定せずにログインした場合は、cargo-ai login --oauth --workspace-uuid <uuid>（対話なしで使用する場合は --token <workspace-scoped-token>）を再実行してください。

営業通話の分析から導き出した編集は、まとめて適用せず、人による確認を挟んで 1 件ずつ適用してください。複数の通話にわたってエージェントを繰り返し実行すると、最も声の大きい意見を重視しすぎて微妙なニュアンスを見落としがちです。通話内容を反映する手順については、references/examples/lifecycle.md を参照してください。

参照と読み取り

# List entries at the root of the runtime sandbox
cargo-ai context runtime browse

# List entries under a subpath (e.g. a domain folder like persona/ or play/)
cargo-ai context runtime browse --path persona

# Read a full file
cargo-ai context runtime read --path persona/vp-sales-mid-market.md

# Read only a line range (1-indexed, inclusive on both ends)
cargo-ai context runtime read --path play/inbound-trial-to-paid.md --start-line 1 --end-line 40

新しいファイルの作成

write はファイルを作成（または上書き）し、デフォルトブランチにコミットをプッシュします。

.md／.mdx ファイルはすべて、title と description を設定した YAML フロントマターから始めてください。フロントマターは write では検証されません（プロジェクトの defineContext では検証されます。詳細はファイル規約を参照してください）。フロントマターがない、空である、または形式が正しくないファイルも書き込まれ、コミットされますが、グラフでのインデックス作成の精度が低下します（title がない場合はファイル名が使われ、ノードの概要には最初の段落が使われます）。その他の理由で write が失敗することもあります。たとえば、repositoryNotFound、failedToWrite（プッシュが反映されなかった場合を含む）、deniedPath（例：.files/ の下への書き込み）です。詳細は references/response-shapes.md を参照してください。

cargo-ai context runtime write \
  --path persona/vp-sales-mid-market.md \
  --content "$(cat <<'EOF'
---
title: VP of Sales, mid-market
description: Owns pipeline, quota, and rep productivity at a 200–2,000-person company.
---

## Role
- Title: VP of Sales
- Seniority: Executive
- Function: Revenue
- Reports to: CRO or CEO

## KPIs
- New ARR, win rate, pipeline coverage, rep ramp time

## Pains
- Pipeline gaps, slow ramp, low rep activity, forecasting drift

## Motivations
- Hit the number, build a repeatable motion, get visibility

## Day-to-day
Forecast calls, deal reviews, pipeline reviews, 1:1s with frontline managers.

## Preferred channels
- medium/linkedin-outbound
- medium/exec-warm-intro

## Common objections
- objection/we-already-have-an-ai-sdr

## How we land
Lead with pipeline-coverage math, not features.
EOF
)" \
  --commit-message "Add VP of Sales mid-market persona"

既存のファイルを編集する

edit は、完全に一致する部分文字列を1つ置き換えます。--replace-all を指定しない限り、--old-string はファイル内にちょうど1回だけ出現する必要があります。一致した文字列を削除するには、空の --new-string を渡します。文字列はそのまま解釈されます。通常の二重引用符内の \n は改行ではなく、バックスラッシュと n です。そのため、複数行に一致させるには bash の $'...' クォートを使用してください。

edit はフロントマターを検証しません。title／description を削除したり空にしたりする編集も適用されるため、ノードを見つけられる状態にしておくには、ブロック全体を維持してください。ただし、ほかの理由で失敗する場合もあります。stringNotFound／stringNotUnique（--old-string の一致に関するエラー）、fileNotFound、noOp（新しい文字列が古い文字列と同じ）、failedToEdit（反映されなかったプッシュを含む）、または deniedPath です。

# Replace one specific sentence
cargo-ai context runtime edit \
  --path global/positioning.md \
  --old-string "We help RevOps automate workflows." \
  --new-string "We help RevOps run AI-native GTM motions." \
  --commit-message "Refresh positioning one-liner"

# Delete a line (pass empty --new-string)
cargo-ai context runtime edit \
  --path persona/vp-sales-mid-market.md \
  --old-string $'\n- Outdated stat: 4.2x pipeline\n' \
  --new-string ""

大規模な再構成では、edit を何度も続けて呼び出すよりも、write（ファイル全体の上書き）を優先してください。

サンドボックスでコマンドを実行する

execute は、サンドボックス内でシェルコマンドを実行します（タイムアウトは90秒です）。構造の調査やチェックの実行に便利ですが、変更された追跡対象ファイルはコミットされ、プッシュされるため、調査コマンドは読み取り専用にしてください。

# Find every file that cross-references a specific slug
cargo-ai context runtime execute \
  --command grep \
  --args '["-r","-l","persona/vp-sales-mid-market","."]'

# Count entries per domain
cargo-ai context runtime execute --command ls --args '["-1","persona"]'

# Run a one-shot script (no quotes/escaping needed inside --command beyond JSON for args)
cargo-ai context runtime execute --command pwd

--args は、文字列引数の JSON 配列です。引数を取らないコマンドでは省略してください。

コンテキストリポジトリの構造と規約

Cargo のコンテキストリポジトリは、型付きナレッジベースです。規約の基準となる唯一の例は getcargohq/cargo-workspaces です。新しい項目を作成する前に、各ドメインの README.md と _template.md を読んでください。ドメインのリファレンス全体については、references/conventions.md を参照してください。

ドメイン

ドメイン	目的
global/	会社レベルのコンテキスト：ミッション、語り口、ポジショニング、ナラティブ、価格設定
icp/	理想的な顧客プロファイルのセグメント
persona/	購買担当者のペルソナ（ICP 内の役割）
jtbd/	ジョブ理論に基づく枠組み
alternative/	競合他社、代替手段、現状維持
client/	顧客プロフィール、導入事例、リファレンス顧客
insight/	市場に関する洞察と所見
medium/	チャネル別のプレイブック（メール、LinkedIn、電話営業など）
objection/	反論、その応答、裏付けとなる証拠
play/	GTM のプレイ（シグナル → オーディエンス → チャネル → シーケンス → 成果）
proof/	個別の証拠ポイント（指標、引用、顧客データ）
signal/	購買シグナルと購入意欲のきっかけ

ファイル規約

• ファイル名： kebab-case.md（例：vp-sales-mid-market.md）。
• フロントマター： すべての .md／.mdx ファイルは、title と description を設定した YAML フロントマターで始めてください。これは強く推奨される規約ですが、強制ではありません。フロントマターがない、空である、または形式が不正な状態で write しても、ファイルは作成され、コミットされます。ただし、インデックスの精度は低下します。グラフは title（フォールバック：ファイル名）と summary（フォールバック：description、次にファイルの最初の段落）を読み取ります。ノードの概要を description と異なるものにしたい場合に限り、summary: を追加してください。ソース参照とグラフエッジを参照してください。例外として、プロジェクトで宣言されたコンテキスト（defineContext、../cargo-project/SKILL.md を参照）では、フロントマターを解析できない場合や、files で宣言されているファイルのいずれにも一致しない references: エントリ、[[wikilink]]、相対 .md リンクがある場合、project check／plan／deploy は失敗します。ワークスペースリポジトリには存在していても、コード内に存在しないファイルも対象です。title／description がなくても、チェックは通過します。
• 相互参照： .md 拡張子を付けず、domain/slug 形式を使用してください（例：persona/vp-sales-mid-market）。グラフのエッジとして登録するには、参照を以下の3種類のリンク形式のいずれかで記述する必要があります。通常の文章内に domain/slug（またはファイルパス）をそのまま記述しても、エッジは作成されません。
• テンプレート： 各ドメインには _template.md があります。新しい項目を作成する前に、読み込んでください（cargo-ai context runtime read --path persona/_template.md）。_template.* ファイルはグラフの対象外です。参照しないでください。

ソース参照とグラフのエッジ

ナレッジグラフは、リポジトリ内のすべての .md、.mdx、.yaml、.yml ファイル（任意のフォルダーが対象で、.git/ のみ除外）から構築されます。各ファイルがノードになりますが、エッジが作成されるのは次の3つの形式のみです。それ以外はグラフには認識されません。

1. Frontmatter の references: リスト（ソースの引用にはこちらを推奨します。本文をすっきり保てます）：

   ---
   title: AgoraPulse expansion thesis
   description: Why AgoraPulse is ready for a multi-thread expansion play.
   references:
     - outputs/sales-notes/2026-06-05-agorapulse-build-session-1-outcomes.md
   ---
   

2. 本文中の Markdown リンク — 標準的な [label] の直後に (path) が続く構文です。ターゲットにはファイルパスを指定します。たとえば、outputs/sales-notes/2026-06-05-agorapulse-build-session-1-outcomes.md へのアンカーリンクです。
3. 本文中のウィキリンク（拡張子は省略可能）：[[outputs/sales-notes/2026-06-05-agorapulse-build-session-1-outcomes]]。

重要な制約：

• ソースを本文中に単なるパスとして記載しないでください（例：outputs/sales-notes/foo.md というテキストだけを記載する Source: 行）。これは解析されず、エッジも作成されません。
• リポジトリルートからの相対パスを推奨します（まずリポジトリルートから解決し、次に引用元ファイルからの相対パスとして解決されます）。これにより、ドキュメントの場所にかかわらずリンクが機能します。
• ウィキリンクと Frontmatter の references: では拡張子を省略できます。リゾルバーは .md、.mdx、.yaml、.yml の順に自動で試します。Markdown リンクは、ターゲットの末尾が .md、.mdx、.yaml、.yml の場合にのみエッジとして扱われるため、拡張子を付けてください。
• ターゲットが存在している必要があります。存在しない場合、エッジはリンク切れとなり、グラフ UI にデッドリンクが表示されます。引用する前に runtime browse で確認してください。
• Source／Evidence セクションがあるドキュメントでは、ファイルを Frontmatter の references: に記載してください。引用に前後の文章が必要な場合は、インライン Markdown リンクを使用してください。詳細なルールは references/conventions.md を参照してください。

ワークフロー：新しいエントリーを追加する

1. 対象のドメインを確認し、そのテンプレートをコピーします：

   cargo-ai context runtime read --path persona/_template.md
   

2. write を使って <domain>/<slug>.md に新しいファイルを作成し、title と description を設定して、本文の各セクションを記入します。
3. 役立つ場合は相互参照（domain/slug）を追加します。適切な場合は双方向にしてください。
4. ナレッジグラフを再構築して、新しいエントリーとリンクを確認します：

   cargo-ai context graph get
   

ドメインごとのテンプレートと作成例については、references/conventions.md および references/examples/authoring.md を参照してください。

ワークフロー：初期構築と更新

新しいワークスペースのコンテキストリポジトリを一から立ち上げる場合や、定期的に既存のリポジトリを更新する場合は、references/examples/lifecycle.md に記載されている2段階のライフサイクルに従ってください。

1. 初期構築（1回のみ）： 公開ソースをもとに global/、persona/、client/、proof/、objection/、signal/ を用意し、シード済みのリポジトリに対して新しいエージェントセッションを開始します。手順を規定し、自動化できる方法（ドメインを入力し、ファイルを出力する冪等な処理で、クレジット予算を含む）については、references/examples/bootstrap-from-domain.md を参照してください。
2. 更新（2～4週間ごと）： 過去約3か月分の営業通話の文字起こしを取得し、1件ずつ、人間が確認しながら分析します。コンテキストに反映する前に繰り返し出現する閾値を適用し、シーケンスの順列を生成して検証します。更新前後のグラフを比較し、古くなったエントリーを整理します。

主張がコンテキストに反映されるまでに何件の通話で出現する必要があるかを示す繰り返し出現の閾値については、references/conventions.md に記載されています。

ナレッジグラフ

context graph get は、コンテキストリポジトリ内のすべての Markdown／MDX ファイルを対象に、ナレッジグラフを構築（またはキャッシュから読み込み）ます。次の用途に利用できます。

• ドメイン間の相互参照を監査します（例：根拠が添付されていないプレイにリンクしているペルソナを見つけます）。
• 新しいエントリを作成する前に、既存の内容を確認します（重複を避けます）。
• ワークスペースのコンテキストの型付き構造を必要とする後続のエージェントを強化します。

cargo-ai context graph get

レスポンスは {"graph": {"nodes", "edges", "broken", "computedAt"}} です。各ノードには id（拡張子を含むファイルパス）、title、summary、cluster（最上位フォルダー）が含まれ、各エッジには source、target、origin（frontmatter、wikilink、mdlink のいずれか）が含まれます。broken には、ターゲットが存在しないエッジが列挙されます。jq に渡して絞り込んでください。すぐに実行できるクエリについては、references/examples/graph-queries.md を参照してください。

ヘルプ

すべてのコマンドで --help を利用できます。

cargo-ai context --help
cargo-ai context runtime browse --help
cargo-ai context runtime read --help
cargo-ai context runtime write --help
cargo-ai context runtime edit --help
cargo-ai context runtime execute --help
cargo-ai context graph get --help