getcargohq__cargo-skills/cargo-context/references/response-shapes.md

Response shapes

JSON response structures returned by Cargo CLI commands used in the cargo-context skill.

Unlike the workspace storage / orchestration skills, the context CLI commands return shapes that depend on the underlying file content and on the graph derived from it. Field names below are the ones used throughout this skill's examples (nodes, slug, frontmatter, links, etc.); for a given workspace, confirm the exact shape with --help and a one-shot invocation before scripting against it.

Error shape (every command)

Failed commands exit non-zero and return:

{
  "errorMessage": "..."
}

cargo-ai context runtime edit fails with this shape when --old-string matches zero or multiple times in the target file. See references/troubleshooting.md.

cargo-ai context runtime browse

Lists entries at the sandbox root (or under --path). Returns the directory listing — file and folder names under the requested path. Combine with cargo-ai context runtime read --path <file> to inspect any entry.

cargo-ai context runtime browse
cargo-ai context runtime browse --path persona

Run once at the top of a session to confirm the exact JSON shape for your workspace.

cargo-ai context runtime read

Returns the file content at --path, optionally restricted to --start-line/--end-line (1-indexed, inclusive). Use this to read frontmatter + body before editing.

cargo-ai context runtime read --path persona/vp-sales-mid-market.md
cargo-ai context runtime read --path play/inbound-trial-to-paid.md --start-line 1 --end-line 40

cargo-ai context runtime write

Creates (or overwrites) the file at --path and pushes a commit to the default branch. Returns the commit metadata. The --commit-message flag controls the commit subject.

cargo-ai context runtime write \
  --path persona/vp-sales-mid-market.md \
  --content "<file body with frontmatter>" \
  --commit-message "Add VP of Sales mid-market persona"

On failure it returns the generic error shape (see Error shape); the context-specific case to know is a denied write under .files/ (update those via Content instead). Frontmatter is not validated — a file missing title/description or with malformed frontmatter is written, not rejected. Failure reasons are enumerated in references/troubleshooting.md.

cargo-ai context runtime edit

Replaces a single exact substring in the file at --path and pushes a commit. --old-string must match exactly once — read the file with runtime read first and copy the substring verbatim, whitespace included. Pass an empty --new-string to delete the match. Returns the commit metadata on success.

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"

On failure it returns the generic error shape — most often because --old-string matched zero or multiple times. Frontmatter is not validated, so an edit that strips title/description still applies. Failure reasons are enumerated in references/troubleshooting.md.

cargo-ai context runtime execute

Runs a shell command in the sandbox and returns its stdout / stderr / exit code. Does not push any file changes — use only for inspection (grep, ls, pwd, find). --args is a JSON array of string arguments; omit for a no-arg command.

cargo-ai context runtime execute --command grep --args '["-r","-l","persona/vp-sales-mid-market","."]'
cargo-ai context runtime execute --command ls --args '["-1","persona"]'
cargo-ai context runtime execute --command pwd

cargo-ai context graph get

Returns the typed knowledge graph derived from every markdown/MDX file in the context repo. Shape used throughout references/examples/graph-queries.md:

{
  "nodes": [
    {
      "slug": "persona/vp-sales-mid-market",
      "frontmatter": {
        "title": "VP of Sales, mid-market",
        "description": "Owns pipeline, quota, and rep productivity at a 200–2,000-person company."
      },
      "links": [
        "medium/linkedin-outbound",
        "medium/exec-warm-intro",
        "objection/we-already-have-an-ai-sdr"
      ]
    }
  ]
}

Key fields:

• nodes[].slug — domain/slug (no .md extension), the canonical identifier used in cross-references.
• nodes[].frontmatter — parsed YAML frontmatter. title and description are required on every file.
• nodes[].links — outbound domain/slug references found in the body. Missing or empty when the file links nowhere.

For ready-to-run queries (count per domain, dangling references, plays missing proof, inbound references to a node), see references/examples/graph-queries.md.