Cargo Content

Cargo CLI — Content

Workspace knowledge management: upload and organize files (PDFs, CSVs, text) and group or sync them into libraries. These are the binary/grouped knowledge resources that ground agent responses (retrieval-augmented generation, RAG).

New top-level domain (CLI ≥ 1.0.19). Files and libraries moved out of the ai domain into the content domain — cargo-ai content file … and cargo-ai content library …. The old cargo-ai ai file … commands no longer exist; an unknown command error means you're on the old path.

For attaching a file or library to an agent (via the release resources array), use `cargo-ai`.

For folders that organize files, use `cargo-workspace-management` (cargo-ai workspaceManagement folder …).

For batch-run input files (CSVs uploaded to drive a batch), that's a different surface — cargo-ai workspaceManagement file upload — documented in `cargo-workspace-management`.

See references/examples/files.md for end-to-end file, library, and attach-to-agent examples.

See references/response-shapes.md for full JSON response structures.

See references/troubleshooting.md for common errors and how to fix them.

Prerequisites

See `../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.

Discover resources first

cargo-ai content file list                 # all uploaded files (uuid, name, contentType, size)
cargo-ai content library list              # knowledge libraries (native or connector-backed)

Files

Upload files (PDFs, CSVs, text) so an agent can ground its responses in specific knowledge. The upload response includes the uuid you reference when attaching the file to an agent release (see `cargo-ai`).

# List all files
cargo-ai content file list

# Get a single file
cargo-ai content file get <file-uuid>

# Upload a file (optionally straight into a folder)
cargo-ai content file upload --file-path ./knowledge-base.pdf
cargo-ai content file upload --file-path ./knowledge-base.pdf --folder-uuid <folder-uuid>

# Update a file's name or folder
cargo-ai content file update --uuid <file-uuid> --name "Q1 Research Notes"
cargo-ai content file update --uuid <file-uuid> --folder-uuid <folder-uuid>

# Remove a file
cargo-ai content file remove <file-uuid>

Reading content files from the context sandbox. Uploaded content files are also available read-only under .files/ in the context runtime sandbox, so a command run there can consume them — e.g. cargo-ai context runtime execute --command ls --args '["-1",".files"]'. The directory sits outside the committed context tree (never pushed, not writable); to add or change files use content file here. See `cargo-context`.

Libraries

A library groups files into one resource an agent can reference. There are two kinds:

• `native` — workspace-managed collections of uploaded files.
• `connector` — synced from an external source (e.g. a help center or knowledge base) through an unstructured-data extractor (--extractor-slug). Get the connectorUuid from `cargo-connection`.

# List libraries (filter by kind or connector)
cargo-ai content library list
cargo-ai content library list --kind native
cargo-ai content library list --kind connector --connector-uuid <connector-uuid>

# Get a single library
cargo-ai content library get <library-uuid>

# Create a connector-backed library
cargo-ai content library create \
  --name "Help Center" \
  --connector-uuid <connector-uuid> \
  --extractor-slug <extractor-slug> \
  --folder-uuid <folder-uuid> \
  --config '{}'

# Update / remove
cargo-ai content library update --uuid <library-uuid> --name "Updated Name"
cargo-ai content library remove <library-uuid>

Attaching to an agent

Files and libraries are knowledge resources — they do nothing until attached to an agent via that agent's draft release resources array, then deployed. That wiring lives in `cargo-ai` (ai release update-draft --resources … → ai release deploy-draft). See references/examples/files.md for the upload → attach → deploy sequence.

Help

Every command supports --help:

cargo-ai content file upload --help
cargo-ai content library create --help

File & library examples

CLI ≥ 1.0.19: files and libraries live in the top-level `content` domain (cargo-ai content file …, cargo-ai content library …). The old cargo-ai ai file … commands no longer exist.

Files

List all files

cargo-ai content file list

Upload a file

cargo-ai content file upload --file-path ./knowledge-base.pdf

Supported content types include PDFs, CSVs, plain text, and other common document formats. The response includes the uuid and s3Filename needed to reference the file.

Upload and attach to an agent

# 1. Upload the file
cargo-ai content file upload --file-path ./product-docs.pdf
# → file.uuid

# 2. Add the file as a resource on the agent's draft release
cargo-ai ai release update-draft --agent-uuid <agent-uuid> \
  --resources '[{"kind":"file","slug":"product_docs","name":"Product Docs","description":null,"prompt":null,"items":[{"kind":"file","fileUuid":"<file-uuid>"}]}]'

# 3. Deploy
cargo-ai ai release deploy-draft --agent-uuid <agent-uuid> \
  --language-model-slug gpt-4o \
  --integration-slug openai

Upload to a folder

Folders are managed by the `cargo-workspace-management` skill — see its references/examples/folders.md for create/list/update.

# 1. Find the folder (kind: "file")
cargo-ai workspaceManagement folder list

# 2a. Upload straight into the folder…
cargo-ai content file upload --file-path ./notes.pdf --folder-uuid <folder-uuid>

# 2b. …or move an existing file afterwards
cargo-ai content file update --uuid <file-uuid> --folder-uuid <folder-uuid>

Rename a file

cargo-ai content file update --uuid <file-uuid> --name "Q1 Research Notes"

Remove a file

cargo-ai content file remove <file-uuid>

Audit files by size

cargo-ai content file list
# → Check the "size" field (in bytes) for each file
# → 1048576 bytes = 1 MB

Libraries

A library groups files into one resource an agent can reference. native libraries are workspace-managed; connector-backed libraries sync documents from an external source through an unstructured-data extractor.

# List libraries, optionally filtered
cargo-ai content library list
cargo-ai content library list --kind native
cargo-ai content library list --kind connector --connector-uuid <connector-uuid>

# Get one
cargo-ai content library get <library-uuid>

# Create a connector-backed library
cargo-ai content library create \
  --name "Help Center" \
  --connector-uuid <connector-uuid> \
  --extractor-slug <extractor-slug> \
  --folder-uuid <folder-uuid> \
  --config '{}'

# Update / remove
cargo-ai content library update --uuid <library-uuid> --name "Updated Name"
cargo-ai content library remove <library-uuid>

Content response shapes

Full JSON response structures for the content domain. All commands output JSON to stdout; failures exit non-zero with {"errorMessage": "..."}.

cargo-ai content file list

{
  "files": [
    {
      "uuid": "file-uuid",
      "workspaceUuid": "...",
      "libraryUuid": "library-uuid",
      "userUuid": null,
      "name": "knowledge-base.pdf",
      "isTemporary": false,
      "folderUuid": null,
      "s3Filename": "...",
      "openAiFileId": "...",
      "contentType": "application/pdf",
      "size": 1048576,
      "isIndexedInOpenAiVectorStore": true,
      "externalId": null,
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-15T00:00:00Z",
      "deletedAt": null,
      "kind": "native"
    }
  ]
}

Each file is a discriminated union on kind: "native" (as above) or "connector", which adds a connectorUuid: string.

Key fields: uuid (used to reference in agent release resources — see `cargo-ai`), libraryUuid (the library the file belongs to), name, contentType, size (in bytes), folderUuid (null unless filed into a folder), isIndexedInOpenAiVectorStore (whether it's retrievable for RAG yet), kind (native or connector; the latter carries connectorUuid).

cargo-ai content library list

The exact JSON envelope isn't pinned here (capture it from a live cargo-ai content library list when you need field-level certainty). Each library carries at least: uuid (referenced in agent release resources), name, kind (native or connector), and — for connector-backed libraries — the connectorUuid and the extractor it syncs through. Filter the list with --kind native|connector and --connector-uuid <uuid>.

Content troubleshooting

Common errors in the content domain and how to fix them.

unknown command 'file' / unknown command 'library'

File and library commands moved from the ai domain to the new top-level `content` domain in CLI ≥ 1.0.19. Use cargo-ai content file … / cargo-ai content library … — the old cargo-ai ai file … path no longer exists. If you still hit this on the new path, bump the CLI: npm install -g @cargo-ai/cli@latest.

fileNotFound

The file UUID does not exist or has been deleted. Run cargo-ai content file list to get the current list.

folderNotFound

The folder UUID passed to --folder-uuid does not exist. Folders are managed by the `cargo-workspace-management` skill — run cargo-ai workspaceManagement folder list to find valid folder UUIDs, or cargo-ai workspaceManagement folder create --kind file ... to create one.

Upload fails or times out

Large files may take longer to upload. Ensure the file path is correct and the file is not locked by another process.

Library created but the agent doesn't use it

A file or library is inert until it's attached to an agent's deployed release. Add it to the draft release resources array and deploy — see `cargo-ai` and examples/files.md.