Cargo Workspace Management

Cargo CLI — Workspace

Workspace administration: managing users, API tokens, folders, roles, workspace-level files, and submitting reports to workspace management.

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

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

See references/examples/users.md for user invite and management examples.

See references/examples/tokens.md for API token creation and rotation examples.

See references/examples/folders.md for organizing resources into folders.

See references/examples/reports.md for examples of submitting workspace management reports.

See references/examples/sessions.md for session tracking — the Cargo installer scaffolds the Claude Code SessionStart + Stop + SessionEnd hooks automatically.

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.

Admin-only: user, role, and token writes require a token with admin access on the workspace. Folder writes and report create work with non-admin tokens.

Discover resources first

cargo-ai whoami                        # current user and active workspace
cargo-ai workspaceManagement user list           # all workspace members
cargo-ai workspaceManagement role list           # available roles
cargo-ai workspaceManagement token list          # all API tokens
cargo-ai workspaceManagement folder list         # all folders

Quick reference

cargo-ai whoami
cargo-ai workspaceManagement user list
cargo-ai workspaceManagement user create --user-email <email> --role-slug <slug>
cargo-ai workspaceManagement token list
cargo-ai workspaceManagement token create --name <name>
cargo-ai workspaceManagement token remove <token-uuid>
cargo-ai workspaceManagement folder list
cargo-ai workspaceManagement folder create --name <name> --emoji-slug <slug> --kind <kind>
cargo-ai workspaceManagement report create --title <title> --description <description>
cargo-ai workspaceManagement session upsert --session-id <id> --title <title> --summary <summary> [--finished]

Current user and workspace

# Get your current user and workspace context
cargo-ai whoami
# → Returns your user UUID, email, and active workspace UUID

Users

# List all workspace members
cargo-ai workspaceManagement user list

# Invite a new user (requires their email and a role)
cargo-ai workspaceManagement user create \
  --user-email user@example.com \
  --role-slug <role-slug>

# Update a user's role
cargo-ai workspaceManagement user update --user-uuid <uuid> --role-slug <new-role-slug>

# Remove a user from the workspace
cargo-ai workspaceManagement user remove --user-uuid <uuid>

Roles

Roles define what users can do in the workspace.

# List available roles
cargo-ai workspaceManagement role list

Always check available roles before inviting users — use the slug from role list when creating or updating users.

API tokens

Each token has a human-readable name and a permissions field. Tokens created via the CLI are issued with permissions: null, which means the token mirrors the permissions of its owning user (the user who ran token create) — so a token's effective access is bounded by what that user can do in the workspace. Fine-grained permission scoping (an explicit allow/deny list) is configured via the API or the Cargo app.

# List all API tokens (includes name and permissions of each token)
cargo-ai workspaceManagement token list

# Create a new token — --name is required
cargo-ai workspaceManagement token create --name "CI/CD pipeline"
# → Returns the token value — store it securely, it won't be shown again

# Remove a token
cargo-ai workspaceManagement token remove <token-uuid>

Naming: Pick a --name that makes the token's purpose obvious in token list later (e.g. "GitHub Actions — production", "Local dev — alice", "Zapier integration"). The name is the only way to tell tokens apart in the listing.

Security: Token values are only shown once at creation. Store them in a secrets manager (e.g. GitHub Secrets, AWS Secrets Manager).

Folders

Folders organize resources (plays, tools, agents) in the Cargo app.

# List all folders
cargo-ai workspaceManagement folder list

# Create a folder (kind: "tool", "play", "agent", or "file")
cargo-ai workspaceManagement folder create --name "Q1 Campaigns" --emoji-slug "rocket" --kind "play"

# Get a folder
cargo-ai workspaceManagement folder get <folder-uuid>

# Update a folder
cargo-ai workspaceManagement folder update --uuid <folder-uuid> --name "Q1 2025 Campaigns"

# Remove a folder
cargo-ai workspaceManagement folder remove <folder-uuid>

Reports

Submit a report to workspace management. Use this whenever the CLI is failing, behaving unexpectedly, lacks a capability you need, or whenever you (user or agent) are struggling to accomplish a task with the CLI. This is the official feedback channel — every report is reviewed by the Cargo team and used to improve the CLI, its skills, and the underlying APIs.

# Submit a report to workspace management
cargo-ai workspaceManagement report create \
  --title "<short summary>" \
  --description "<detailed description, including the command(s) tried and the error(s) seen>"

When to send a report (non-exhaustive):

• A command exits non-zero with an errorMessage you cannot resolve from --help or references/troubleshooting.md.
• The CLI is being misused or the syntax is unclear (e.g. you can't figure out which flag to pass, or the JSON schema for --filter / --nodes / --action is ambiguous).
• A user or AI agent is repeatedly retrying the same command without progress (≥ 2 failed attempts on the same task).
• A documented command does not behave as the skill describes, or a response shape differs from what references/response-shapes.md documents.
• A capability appears to be missing entirely (no command exists for what you need to do).
• An async operation never reaches a terminal status, or returns inconsistent results across runs.

What to put in the report:

• --title: one-line summary of the problem (e.g. "batch create fails with 'playNotCompatible' on tool workflow").
• --description: include the exact command(s) executed (with sensitive values redacted), the JSON errorMessage, what you expected, what you tried, and any relevant UUIDs (run, batch, workflow, model). The more context you provide, the faster it can be triaged.

# Example: report a CLI struggle after multiple failed attempts
cargo-ai workspaceManagement report create \
  --title "segment fetch returns empty results despite matching records in UI" \
  --description "Ran: cargo-ai segmentation segment fetch --model-uuid <uuid> --filter '{\"conjunction\":\"and\",\"groups\":[...]}'. Got 0 records. The same filter shows 1,200 matches in the app UI. Tried both --filter and --segment-uuid; both return empty. Expected: the same records as the UI."

Do not silently give up on a failing CLI task. Send a report. This closes the feedback loop so the CLI and these skills can be improved.

Sessions

Record a Claude Code session in workspace_management.sessions. One row per (workspaceUuid, sessionId). Used by the cargo router's Claude Code SessionStart + Stop + SessionEnd hook recipe — see `../cargo/SKILL.md` for when to wire them up.

# Upsert a session. Idempotent on --session-id within the workspace.
cargo-ai workspaceManagement session upsert \
  --session-id <claude-session-id> \
  --title "<short title>" \
  --summary "<one-or-two sentence summary>"

# Same call, but also stamp finished_at = now
cargo-ai workspaceManagement session upsert \
  --session-id <claude-session-id> \
  --title "<final title>" \
  --summary "<final summary>" \
  --finished

• --session-id, --title, --summary are required on every call. title and summary are NOT NULL in the schema — pass placeholders on the start call and overwrite on the end call.
• --finished stamps finished_at = now. Use --finished-at <iso> for an explicit timestamp instead.
• Calling upsert twice with the same --session-id updates the same row — title, summary, and finished_at are overwritten.

Returns the upserted session as JSON. The Cargo installer (curl -fsSL https://api.getcargo.io/install.sh | sh) wires SessionStart + Stop + SessionEnd hooks that call this command automatically: SessionStart writes a placeholder, the per-turn Stop hook checkpoints the row (no --finished), and SessionEnd writes the transcript-driven AI summary with --finished — see `references/examples/sessions.md`.

Workspace files

Workspace files are CSVs or other data files uploaded for use in batch runs.

# Upload a file
cargo-ai workspaceManagement file upload --file-path <path-to-file>
# → Returns s3Filename

# Inspect a file's columns before running a batch
cargo-ai workspaceManagement file list-columns --s3-filename <s3-filename>
# → Returns column names to use when mapping to workflow inputs

The s3-filename is returned when uploading a file via cargo-ai workspaceManagement file upload. See the cargo-orchestration skill's references/examples/tools.md for the full file upload and batch run workflow.

Help

Every command supports --help:

cargo-ai workspaceManagement user create --help
cargo-ai workspaceManagement token create --help
cargo-ai workspaceManagement folder create --help

Folder examples

Folders organize resources (plays, tools, agents) in the Cargo app for easier navigation.

List all folders

cargo-ai workspaceManagement folder list

Create a folder

Requires --name, --emoji-slug, and --kind. Kind determines what resources the folder can contain: play, tool, agent, or file.

cargo-ai workspaceManagement folder create --name "Q1 Campaigns" --emoji-slug "rocket" --kind "play"
cargo-ai workspaceManagement folder create --name "Outbound - SDR Team" --emoji-slug "briefcase" --kind "tool"
cargo-ai workspaceManagement folder create --name "AI Assistants" --emoji-slug "robot" --kind "agent"

Get a folder

cargo-ai workspaceManagement folder get <folder-uuid>

Update a folder

cargo-ai workspaceManagement folder update --uuid <folder-uuid> --name "Q1 2025 Campaigns"
cargo-ai workspaceManagement folder update --uuid <folder-uuid> --emoji-slug "star"
cargo-ai workspaceManagement folder update --uuid <folder-uuid> --parent-uuid <parent-folder-uuid>

Remove a folder

# Remove all resources from the folder first (via the Cargo app or by updating each resource)
cargo-ai workspaceManagement folder remove <folder-uuid>

Find a folder UUID for assigning resources

# 1. List folders to find the one you want
cargo-ai workspaceManagement folder list
# → Note the "uuid" for the target folder

# 2. When creating or updating a play/tool/agent, pass the folder UUID
# (Folder assignment is typically done via play/tool/agent update commands)

Report examples

cargo-ai workspaceManagement report create submits a report to workspace management — the Cargo team's official feedback channel for the CLI and its skills.

Always send a report when:

• A CLI command fails and the cause is not obvious from --help, references/response-shapes.md, or references/troubleshooting.md.
• The user or the AI agent is struggling to use the CLI: repeated failed attempts (≥ 2) on the same task, ambiguous flags, unclear JSON schemas, or commands that don't behave as documented.
• A capability seems to be missing entirely (no command exists for the operation needed).
• A response shape, error message, or async behavior contradicts what the skills describe.
• The CLI is being used incorrectly and the correct usage is not discoverable from the existing documentation.

Reports are how these skills and the CLI improve. Do not give up silently — file a report.

Submit a report

cargo-ai workspaceManagement report create \
  --title "<one-line summary of the problem>" \
  --description "<exact command, error, expected vs actual, relevant UUIDs>"

Both --title and --description are required. The command returns the created report as JSON.

What to include in the description

Always include, when relevant:

• The exact command(s) you ran, with secrets/tokens redacted.
• The full errorMessage from the JSON output.
• What you expected to happen and what actually happened.
• Any UUIDs referenced (run, batch, workflow, model, segment, agent, connector, …).
• How many times the failure was reproduced and any variations tried.
• The skill / reference page consulted before reporting (so the team knows what was already tried).

Examples

CLI command fails with an unhelpful error

cargo-ai workspaceManagement report create \
  --title "orchestration run create returns 'playNotCompatible' on a tool workflow" \
  --description "Ran: cargo-ai orchestration run create --workflow-uuid abc-123 --data '{\"domain\":\"acme.com\"}'. Got: {\"errorMessage\":\"playNotCompatible\"}. The workflow UUID was returned by 'orchestration tool list', so it should be a tool workflow. Skill consulted: cargo-orchestration/SKILL.md decision flowchart."

Filter syntax is unclear / silently returns empty

cargo-ai workspaceManagement report create \
  --title "segment fetch returns 0 records despite UI showing matches" \
  --description "Ran: cargo-ai segmentation segment fetch --model-uuid <uuid> --filter '{\"conjonction\":\"and\",\"groups\":[{\"conjonction\":\"and\",\"conditions\":[{\"kind\":\"string\",\"columnSlug\":\"country\",\"operator\":\"is\",\"values\":[\"US\"]}]}]}'. Got 0 records. The same filter in the app UI shows 1,200 matches. Tried 'conjunction' and 'conjonction' spellings — both return 0."

Agent is struggling with the CLI after multiple retries

cargo-ai workspaceManagement report create \
  --title "Agent unable to determine correct --action JSON for HubSpot company_create" \
  --description "Tried 4 variants of cargo-ai orchestration action execute --action '{\"kind\":\"connector\",\"integrationSlug\":\"hubspot\",\"actionSlug\":\"company_create\",\"config\":{}}' --data '{...}'. Each fails with a different validation error ('config.portalId required', then 'data.properties required', etc.). The required shape is not documented in cargo-connection or cargo-orchestration. Need a worked example or a schema reference."

Missing capability

cargo-ai workspaceManagement report create \
  --title "No CLI command to bulk re-run failed records from a previous batch" \
  --description "Trying to re-run only the failed records from batch <uuid>. 'analytics run download --statuses error' produces a CSV but there is no documented way to feed that CSV back into 'orchestration batch create' as the input set without manual transformation. A '--from-failed-batch <uuid>' option (or equivalent) appears to be missing."

Documentation contradicts observed behavior

cargo-ai workspaceManagement report create \
  --title "billing usage get-metrics --group-by workflow_uuid returns connector_uuid groupings" \
  --description "Ran: cargo-ai billing usage get-metrics --from 2025-01-01 --to 2025-01-31 --group-by workflow_uuid. Response groups results by connector_uuid instead of workflow_uuid. cargo-billing/SKILL.md says workflow_uuid is a valid --group-by value."

After sending a report

The CLI prints the created report as JSON. Note the returned uuid so it can be referenced in any follow-up communication with the Cargo team. After reporting, fall back to the closest documented workaround (e.g. the Cargo app UI) so the user is unblocked.

Session tracking examples

cargo-ai workspaceManagement session upsert creates or updates a Claude Code session row in workspace_management.sessions. One row per (workspaceUuid, sessionId). Use it to keep a queryable log of every Claude Code session — what was worked on, when it started, and a short AI-generated summary of what happened.

CLI surface

cargo-ai workspaceManagement session upsert \
  --session-id <claude-session-id> \
  --title "<short title>" \
  --summary "<one-or-two-sentence summary>" \
  [--finished | --finished-at <iso-timestamp>]

• --session-id, --title, --summary are required on every call (title and summary are NOT NULL in the schema).
• --finished stamps finished_at = now. Use --finished-at <iso> to set an explicit timestamp.
• Calling upsert twice with the same --session-id updates the same row — title, summary, and finished_at are overwritten.

The command returns the upserted session as JSON.

Schema

workspace_management.sessions
├── uuid              (pk)
├── session_id        (string, UNIQUE with workspace_uuid)
├── user_uuid
├── workspace_uuid
├── title             (NOT NULL)
├── summary           (NOT NULL)
├── created_at        (default now)
└── finished_at       (nullable, stamped by --finished)

Manual upsert

# Record a session start with placeholder text
cargo-ai workspaceManagement session upsert \
  --session-id abc-123 \
  --title "Claude Code session abc-123" \
  --summary "Session in progress."

# Later, overwrite with the real title + summary and mark finished
cargo-ai workspaceManagement session upsert \
  --session-id abc-123 \
  --title "Wire up workspace_management.sessions" \
  --summary "Added the sessions resource end-to-end across migration, repository, service, HTTP, and CLI; updated cargo-skills docs to suggest the hook recipe." \
  --finished

Automate with Claude Code hooks (recommended)

Don't hand-roll the hooks — the Cargo installer scaffolds them for you. Run it once and answer y at the session-hooks prompt:

curl -fsSL https://api.getcargo.io/install.sh | sh

It writes three hooks under ~/.claude/ and merges the matching entries into ~/.claude/settings.json:

• `SessionStart` refreshes @cargo-ai/cli + the skills bundle and creates the session row with placeholders ("Session in progress.").
• `Stop` (runs at the end of each assistant turn) checkpoints the row — it derives a lightweight title/summary from the transcript with jq (latest user request + timestamp, no LLM call) and upserts without --finished, throttled to one update per CARGO_CHECKPOINT_INTERVAL seconds (default 45). This keeps a session that never reaches SessionEnd (crash, timeout, reclaimed container) from being stuck on the bare placeholder.
• `SessionEnd` reads the transcript, asks claude -p to summarize, and writes the real title + summary with --finished.

All hooks swallow errors (|| true), so a missing cargo-ai/claude/jq binary never blocks a session — at worst, the row just keeps its last checkpoint. The SessionEnd hook logs each step to $CARGO_SESSION_LOG (default ~/.claude/cargo-session.log), so a row stuck on "Session ended." can be diagnosed there. Set CARGO_INSTALL_HOOKS=0 to skip the prompt (or =1 to install without prompting).

The hooks are thin wrappers around the session upsert command documented above — read the installer (apps/backend/src/http/routes/install.sh in getcargohq/cargo) if you want to see or customize the exact scripts.

API token examples

Every token has a human-readable name and a permissions field. The CLI's token create always issues a token with permissions: null, which means the token mirrors the permissions of the user who created it — its effective access is whatever that user can do in the workspace. Use the API or the Cargo app to scope a token to a different subset of actions / resources.

List all tokens

cargo-ai workspaceManagement token list
# → Each entry includes `uuid`, `name`, `permissions`, `userUuid`, `workspaceUuid`, `createdAt`, `deletedAt`
# (the actual token value is not shown — it is only returned once, at creation)

Create a new token

--name is required. Pick something that makes the token's purpose obvious from token list later (e.g. "CI/CD pipeline", "GitHub Actions — production", "Local dev — alice").

cargo-ai workspaceManagement token create --name "CI/CD pipeline"

The response includes the token field — this is the only time the token value is shown. Store it immediately in a secrets manager.

The new token inherits the permissions of the user running token create. If you need a token with broader or narrower access than your user, create it under the appropriate user account, or scope it explicitly via the API / Cargo app after creation.

Rotate a token (replace an old one)

# 1. Create the new token first (give it a clear name)
cargo-ai workspaceManagement token create --name "CI/CD pipeline (rotated 2026-01)"
# → Save the new token value

# 2. Update all systems using the old token to use the new value

# 3. Remove the old token
cargo-ai workspaceManagement token remove <old-token-uuid>

Remove a token

cargo-ai workspaceManagement token remove <token-uuid>

Find which token is currently in use

cargo-ai whoami
# → The active token is the one used for authentication in the current session
# Run `workspaceManagement token list` to see all tokens and their names

User management examples

List all workspace members

cargo-ai workspaceManagement user list

Get the current user

cargo-ai workspaceManagement user get-current

Find available roles before inviting

cargo-ai workspaceManagement role list
# → Note the "slug" values for the roles you want to assign

Invite a new user

# 1. Get available roles
cargo-ai workspaceManagement role list

# 2. Invite the user with their email and role
cargo-ai workspaceManagement user create \
  --user-email newuser@example.com \
  --role-slug <role-slug>

Update a user's role

cargo-ai workspaceManagement user update --user-uuid <uuid> --role-slug <new-role-slug>

Remove a user from the workspace

cargo-ai workspaceManagement user remove --user-uuid <uuid>

Find the current user's details

cargo-ai whoami
# → Returns your user UUID, email, and active workspace UUID

Audit workspace members

List all users and their roles:

# 1. List all users
cargo-ai workspaceManagement user list
# → Note roleSlug for each user

# 2. List all roles to map slugs to role names
cargo-ai workspaceManagement role list
# → Cross-reference roleSlug values

Response shapes

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

cargo-ai whoami

{
  "user": {
    "uuid": "user-uuid",
    "email": "user@example.com",
    "firstName": "Jane",
    "lastName": "Doe"
  },
  "workspace": {
    "uuid": "workspace-uuid",
    "name": "Acme Corp"
  }
}

cargo-ai workspaceManagement user list

{
  "users": [
    {
      "uuid": "user-uuid",
      "email": "user@example.com",
      "firstName": "Jane",
      "lastName": "Doe",
      "role": { "uuid": "role-uuid", "slug": "member" },
      "createdAt": "2025-01-01T00:00:00Z"
    }
  ]
}

Key fields: uuid, email, firstName, lastName, role.slug (the assigned role).

cargo-ai workspaceManagement role list

{
  "roles": [
    {
      "uuid": "role-uuid",
      "slug": "admin"
    },
    {
      "uuid": "role-uuid-2",
      "slug": "member"
    }
  ]
}

cargo-ai workspaceManagement token list

{
  "tokens": [
    {
      "uuid": "token-uuid",
      "name": "CI/CD pipeline",
      "permissions": null,
      "workspaceUuid": "workspace-uuid",
      "userUuid": "user-uuid",
      "createdAt": "2025-01-01T00:00:00Z",
      "deletedAt": null
    }
  ]
}

Note: Token values are not returned in token list. The actual token string is only returned once at creation time.

Key fields:

• name: human-readable label assigned at creation (--name flag).
• permissions: null means the token mirrors the permissions of its owning user (the user identified by userUuid) — its effective access is bounded by what that user can do. When non-null, it is an array of permission rules { effect, resources, actions } that scope the token explicitly. CLI-created tokens are always null; explicitly scoped tokens are configured via the API or the Cargo app.
• deletedAt: null for active tokens; an ISO timestamp once the token has been removed.

cargo-ai workspaceManagement token create

{
  "token": {
    "uuid": "token-uuid",
    "token": "<token-value>",
    "name": "CI/CD pipeline",
    "permissions": null,
    "workspaceUuid": "workspace-uuid",
    "userUuid": "user-uuid",
    "createdAt": "2025-01-01T00:00:00Z",
    "deletedAt": null
  }
}

Important: Save the token value immediately — it is shown only once and cannot be retrieved again. The name you pass via --name is echoed back in the response and shown in token list. The userUuid is the user whose permissions the token inherits when permissions is null.

Permission shape (when not null)

When a token has been explicitly scoped (via API or app), permissions is an array of rules:

[
  {
    "effect": "allow",
    "resources": ["<workflow-uuid>", "<folder-uuid>"],
    "actions": ["orchestration:workflow:read", "orchestration:workflow:write"]
  },
  {
    "effect": "deny",
    "resources": null,
    "actions": ["workspaceManagement:write"]
  }
]

• effect: "allow" or "deny".
• resources: array of resource UUIDs (workflow, folder, etc.) that the rule applies to, or null for workspace-wide.
• actions: array of dotted action strings, e.g. "orchestration:*", "orchestration:workflow:read", "workspaceManagement:folder:write", "ai:agent:write". The * wildcard at any level grants every action below it.

When permissions is non-null, the rules are evaluated independently of the owning user — the token's access is exactly what the rules describe, regardless of what userUuid can do.

cargo-ai workspaceManagement folder list

{
  "folders": [
    {
      "uuid": "folder-uuid",
      "workspaceUuid": "...",
      "parentUuid": null,
      "kind": "play",
      "name": "Q1 Campaigns",
      "emojiSlug": "rocket",
      "isReadOnly": false,
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-15T00:00:00Z",
      "deletedAt": null
    }
  ]
}

Key fields: uuid, name, kind (play, tool, agent, or file), emojiSlug, parentUuid (null for root folders).

cargo-ai workspaceManagement file list-columns

{
  "columns": [
    { "type": "string", "name": "name" },
    { "type": "string", "name": "domain" },
    { "type": "string", "name": "employee_count" },
    { "type": "string", "name": "industry" }
  ]
}

Each column has a type (always "string" for CSV files) and a name. Use the name values to map CSV data to workflow input fields when creating a batch.

Troubleshooting

Common errors and recovery steps for cargo-workspace-management commands.

If the table below does not resolve the issue, or you (user or agent) are stuck on any Cargo CLI command after ≥ 2 failed attempts, send a workspace management report:

>

```bash

cargo-ai workspaceManagement report create \

--title "<one-line summary>" \

--description "<command run, error message, what you expected, UUIDs involved>"

```

>

See examples/reports.md for guidance on what to include. Reports are how the Cargo team improves the CLI and these skills.

General

Users

Tokens

Folders

Files

When nothing else works — submit a report

Whenever the CLI is failing in a way none of the tables above explain, the syntax for a flag is unclear, the agent is looping on the same task, or a needed capability appears to be missing — escalate by submitting a workspace management report:

cargo-ai workspaceManagement report create \
  --title "<short summary>" \
  --description "<exact command, errorMessage, expected vs actual, UUIDs>"

Trigger conditions (any one is enough):

• A command failed ≥ 2 times in a row on the same task.
• The user or agent does not know which flag / JSON shape to use, and --help plus the skill references do not resolve it.
• A documented behavior contradicts what you observe.
• A feature seems to be missing entirely.

See examples/reports.md for full templates.