Cargo Context

Cargo CLI — Context

The context is a git-backed repository of typed markdown/MDX files that captures a workspace's GTM knowledge (company narrative, ICPs, personas, plays, proof, objections, etc.) and is read/written by both humans and agents. The cargo-ai context domain has two subdomains you'll use:

• runtime — browse, read, write, edit, and execute against the workspace's runtime sandbox (a checked-out copy of the context repo). write/edit are pushed to the default branch; execute runs are not pushed.
• graph — build/load the knowledge graph derived from every markdown/MDX file in the context repo.

The canonical example of a context repository is `getcargohq/cargo-workspaces`. Read its README.md to understand the domain layout and file conventions before writing new entries. For uploading runtime-independent files (CSVs, PDFs) used in batch runs, use `cargo-workspace-management` (cargo-ai workspaceManagement file upload) instead. For RAG file attachments to agents, use `cargo-ai` (cargo-ai content file upload).

See references/conventions.md for the full context repo structure and per-domain templates. See references/response-shapes.md for the JSON shapes returned by each cargo-ai context command. See references/troubleshooting.md for common errors and how to fix them. See references/examples/authoring.md for end-to-end add / edit / delete recipes. See references/examples/lifecycle.md for the bootstrap + refresh-from-calls playbook. See references/examples/graph-queries.md for inspecting the knowledge graph.

Bootstrap

Already signed in (cargo-ai whoami returns a workspace)? Skip to the next section.

npm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`
cargo-ai login --email you@company.com  # 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

Every command prints JSON to stdout; failures exit non-zero with {"errorMessage": "..."}. Anything that creates a run or a batch is async — pass --wait-until-finished or poll the matching get. runtime write and runtime edit commit and push to the workspace's context repo, so confirming workspace.name first is non-negotiable. When the full skill bundle is installed, `../cargo/references/prerequisites.md` adds the CLI version pin, token scopes, and the admin-only surface.

Discover the context first

Before editing anything, see what's in the context repo:

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

Quick reference

# 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> [--commit-message <message>]
cargo-ai context runtime execute --command <command> [--args <json>]

# Knowledge graph
cargo-ai context graph get

Runtime sandbox

The runtime sandbox is a checked-out, executable copy of the context repository. It's the surface you use to read and modify context files, and to run commands against them.

Two important behaviors to remember:

• `write` and `edit` push to the default branch of the context repo. They are not local-only.
• *`execute` does not push.* Changes made to files by a shell command run via execute stay in the sandbox and are discarded — use execute for builds, tests, or inspection, not for committing edits.

Uploaded content files are available read-only under `.files/`. The workspace's content file uploads (PDFs, CSVs, text — see `cargo-content`) appear in the sandbox under a .files/ directory, so a command run via execute (or read/browse) can consume them — e.g. cargo-ai context runtime execute --command ls --args '["-1",".files"]'. It sits outside the committed context tree: the sandbox's auto-commit skips it, so nothing under .files/ is ever pushed to the context repo, and you can't add or change content files from here (use cargo-ai content file … instead).

Because writes push immediately, confirm the target workspace before the first `write`/`edit`:

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

Read the workspace name back to the user. If the session is for a specific client, make sure workspace.name matches before authoring anything — there is no dry-run mode. If workspace.name is generic or ambiguous (e.g. "Main", "Test", a person's name, an internal codename), don't guess — ask the user for the company name and canonical domain (example.com) and confirm both before the first write. If you logged in without pinning a workspace, re-run cargo-ai login --oauth --workspace-uuid <uuid> (or --token <workspace-scoped-token> for non-interactive use).

Edits derived from sales-call analysis should be applied one at a time with human review, not batched. Looping an agent over many calls tends to overweight the loudest signal and miss nuance — see references/examples/lifecycle.md for the call-refresh playbook.

Browse and read

# 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 a new file

write creates (or overwrites) a file and pushes a commit to the default branch.

Begin every .md/.mdx file with a YAML frontmatter block setting title and description. Frontmatter is not validated — a file with missing, empty, or malformed frontmatter is still written and committed; it just indexes poorly in the graph (a missing title falls back to the filename, the node summary to the first paragraph). write can still fail for other reasons — repositoryNotFound, syncConflict, syncFailed, failedToWrite, or deniedPath (e.g. writing under .files/); see 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 an existing file

edit replaces a single exact substring. --old-string must occur exactly once in the file; pass an empty --new-string to delete the match.