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-workspace-management/SKILL.md) (cargo-ai workspaceManagement file upload) instead. > For RAG file attachments to agents, use [cargo-ai](../cargo-ai/SKILL.md) (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.

Prerequisites

See [../cargo/references/prerequisites.md](../cargo/references/prerequisites.md) for install, login (--oauth / --token), JSON output conventions, and error shapes. Verify the session with cargo-ai whoami before running any of the commands below — runtime write and runtime edit push commits to the workspace's context repo, so confirming workspace.name first is non-negotiable.

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 ]
cargo-ai context runtime read --path  [--start-line ] [--end-line ]
cargo-ai context runtime write --path  --content  [--commit-message ]
cargo-ai context runtime edit --path  --old-string  --new-string  [--commit-message ]
cargo-ai context runtime execute --command  [--args ]

# 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](../cargo-content/SKILL.md)) 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 (or --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 /.md` with `title` + `description` and the body sections filled in.
3. Add cross-refs (`domain/slug`) where useful — keep them bidirectional when it makes sense.
4. Rebuild the knowledge graph to verify the new entry and its links:
   ```bash
   cargo-ai context graph get
   ```

For full per-domain templates and worked examples, see `references/conventions.md` and `references/examples/authoring.md`.

### Workflow: bootstrap and refresh

To stand up a new workspace's context repo from scratch, or to refresh an existing one on a cadence, follow the two-phase lifecycle in `references/examples/lifecycle.md`:

1. **Bootstrap (one-time):** seed `global/`, `persona/`, `client/`, `proof/`, `objection/`, `signal/` from public sources, then open a fresh agent session against the seeded repo. For the prescriptive, automatable version (domain in → files out, idempotent, with credit budget), use `references/examples/bootstrap-from-domain.md`.
2. **Refresh (every 2–4 weeks):** pull the last ~3 months of sales-call transcripts → analyze one at a time, human-in-the-loop → apply a repetition threshold before promoting any claim to context → validate by generating sequence permutations → diff the graph before/after and retire stale entries.

The repetition threshold (how many calls a claim must appear in before it lands in context) is documented in `references/conventions.md`.

## Knowledge graph

`context graph get` builds (or loads from cache) the knowledge graph over every markdown/MDX file in the context repo. Use it to:

- Audit cross-references between domains (e.g. find personas that link to plays with no proof attached).
- Discover what already exists before writing a new entry (avoid duplicates).
- Power downstream agents that need the typed structure of the workspace's context.

```bash
cargo-ai context graph get

The response includes the parsed frontmatter and outbound domain/slug references for each node — pipe it through jq to slice it. See references/examples/graph-queries.md for ready-to-run queries.

Help

Every command supports --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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: getcargohq
• Source: getcargohq/cargo-skills
• License: MIT
• Homepage: https://getcargo.ai

Install and usage instructions live in the source repository linked above.