references/examples/folders.md
# Folder examples
Folders organize resources (plays, tools, agents) in the Cargo app for easier navigation.
## List all folders
```bash
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`.
```bash
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
```bash
cargo-ai workspaceManagement folder get <folder-uuid>
```
## Update a folder
```bash
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
```bash
# 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
```bash
# 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)
```
references/examples/reports.md
# 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.**
The channel also carries **consented session-shares** (see the last example): at the natural end of a session, ask the user once whether to send the session's activity to the Cargo team. Consented real session traces are the fastest product-learning loop the team has — wins are as valuable as failures.
## Submit a report
```bash
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
```bash
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
```bash
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
```bash
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\"}' --data '{...}'. Each fails with a different validation error ('data.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
```bash
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
```bash
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."
```
### Session share (user consented at session end)
Only after the user answered **yes** to "Send this session's activity to the Cargo team so they can improve the experience? (Y/N)":
```bash
cargo-ai workspaceManagement report create \
--title "Session share: TAM build for fintech ICP, 500 companies" \
--description "Goal: 500-company TAM for a fintech ICP + verified emails for top 50. Path: build-tam.md recipe → salesNavigator.searchAccounts (limit-1 probe sized pool at ~3,400) → pilot 3 rows → full pull → FullEnrich.findEmail on 70 (1.4x over-provision) → waterfall.verifyEmail. Worked well: pilot caught a bad industry code before the full pull. Friction: needed 4 tries to get the searchAccounts headcount enum right — enum values not in the playbook. Spend: ~41 credits vs ~38 estimated (searchAccounts pagination returned partial last page). No secrets or record-level data included."
```
Redact secrets and record-level personal data; describe shapes and counts, not rows. If the user answered no, do not file and do not ask again that session.
## 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.
references/examples/sessions.md
# 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
```bash
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
```text
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
```bash
# 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:
```bash
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.
references/examples/tokens.md
# 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
```bash
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"`).
```bash
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)
```bash
# 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
```bash
cargo-ai workspaceManagement token remove <token-uuid>
```
## Find which token is currently in use
```bash
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
```
references/examples/users.md
# User management examples
## List all workspace members
```bash
cargo-ai workspaceManagement user list
```
## Get the current user
```bash
cargo-ai workspaceManagement user get-current
```
## Find available roles before inviting
```bash
cargo-ai workspaceManagement role list
# → Note the "slug" values for the roles you want to assign
```
## Invite a new user
```bash
# 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
```bash
cargo-ai workspaceManagement user update --user-uuid <uuid> --role-slug <new-role-slug>
```
## Remove a user from the workspace
```bash
cargo-ai workspaceManagement user remove --user-uuid <uuid>
```
## Find the current user's details
```bash
cargo-ai whoami
# → Returns your user UUID, email, and active workspace UUID
```
## Audit workspace members
List all users and their roles:
```bash
# 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
```
references/response-shapes.md
# Response shapes
JSON response structures returned by Cargo CLI commands used in the `cargo-workspace-management` skill.
## cargo-ai whoami
```json
{
"user": {
"uuid": "user-uuid",
"email": "user@example.com",
"firstName": "Jane",
"lastName": "Doe"
},
"workspace": {
"uuid": "workspace-uuid",
"name": "Acme Corp"
}
}
```
## cargo-ai workspaceManagement user list
```json
{
"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
```json
{
"roles": [
{
"uuid": "role-uuid",
"slug": "admin"
},
{
"uuid": "role-uuid-2",
"slug": "member"
}
]
}
```
## cargo-ai workspaceManagement token list
```json
{
"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
```json
{
"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:
```json
[
{
"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
```json
{
"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
```json
{
"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.
references/troubleshooting.md
# 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
| Symptom | Cause | Fix |
|---------|-------|-----|
| `{"errorMessage": "..."}` with non-zero exit | Any CLI error | Read the `errorMessage` — it usually says exactly what's wrong |
| `command not found: cargo-ai` | CLI not installed or not in PATH | Run `npm install -g @cargo-ai/cli` or prefix with `npx @cargo-ai/cli` |
| `Unauthorized` or `Forbidden` | Bad or expired credentials, or insufficient permissions | Re-run `cargo-ai login --oauth` (browser sign-in) or `cargo-ai login --token <token>`; verify with `cargo-ai whoami`; use an admin account/token for workspace management |
## Users
| Symptom | Cause | Fix |
|---------|-------|-----|
| `user create` fails with permission error | Token lacks admin access | Use a token belonging to a workspace admin |
| `user create` fails with "role not found" | Wrong role UUID | Run `workspaceManagement role list` to get valid role UUIDs |
| `user remove` fails | Attempting to remove the last admin | Promote another user to admin before removing |
| User can't log in after being created | Email invitation not accepted | Ask the user to check their email for the workspace invitation |
## Tokens
| Symptom | Cause | Fix |
|---------|-------|-----|
| `token create` exits with `error: required option '--name <name>' not specified` | `--name` is required since the named-token migration | Pass `--name "<descriptive label>"` (e.g. `--name "CI/CD pipeline"`) |
| `token create` rejected with `error: unknown option '--from-user'` | Legacy flag — removed when tokens gained `name` and `permissions` | Drop `--from-user`; use `--name <name>` instead. CLI-created tokens already inherit the creating user's permissions (`permissions: null`) |
| Lost the token value after creation | Token value only shown once | Remove the token and create a new one (with the same `--name`); store the new value securely |
| `token remove` fails | Token is currently in use by active processes | Wait for processes to finish, or rotate to a new token first then remove the old one |
| `Unauthorized` errors in CI/CD with a CLI-created token | Token mirrors the creating user's permissions; that user lost access (role downgraded, removed, etc.) | Verify the token still exists with `workspaceManagement token list`; check the role of the user in `userUuid` (`workspaceManagement user list`); restore the user's permissions, or recreate the token under a user with the access you need |
| `Unauthorized` errors in CI/CD with an explicitly scoped token | `permissions` array is too narrow for the action being attempted | Inspect the token's `permissions` field via `workspaceManagement token list`; widen via the API/app, or replace with a `permissions: null` token created by a user that has the required access |
| Two tokens look identical in `token list` | Both were created without a meaningful `--name` | Use `--name` consistently — the name is the only label distinguishing tokens in the listing |
## Folders
| Symptom | Cause | Fix |
|---------|-------|-----|
| `folder remove` fails | Folder still contains resources | Move or remove all resources from the folder before deleting it |
| `folder get` returns not found | Wrong folder UUID | Re-run `folder list` to get the correct UUID |
## Files
| Symptom | Cause | Fix |
|---------|-------|-----|
| `file list-columns` returns empty | Wrong `s3-filename` or file has no headers | Verify the `s3-filename` from the upload response; ensure the CSV has a header row |
| `file upload` fails | File too large or unsupported format | Check file size limits; ensure the file is a CSV or supported format |
## 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:
```bash
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.
skill-metadata.json
{
"$comment": "Generated by .github/scripts/skills-metadata.mjs — do not hand-edit. Regenerate with: node .github/scripts/skills-metadata.mjs --write .",
"name": "cargo-workspace-management",
"version": "1.2.2",
"documents": [
{
"path": "SKILL.md",
"kind": "entrypoint",
"title": "Cargo CLI — Workspace"
},
{
"path": "references/examples/folders.md",
"kind": "example",
"title": "Folder examples"
},
{
"path": "references/examples/reports.md",
"kind": "example",
"title": "Report examples"
},
{
"path": "references/examples/sessions.md",
"kind": "example",
"title": "Session tracking examples"
},
{
"path": "references/examples/tokens.md",
"kind": "example",
"title": "API token examples"
},
{
"path": "references/examples/users.md",
"kind": "example",
"title": "User management examples"
},
{
"path": "references/response-shapes.md",
"kind": "reference",
"title": "Response shapes"
},
{
"path": "references/troubleshooting.md",
"kind": "reference",
"title": "Troubleshooting"
}
],
"contentHash": "802458dbfde95c8c5fb41388e5df4a00cc061cf6cbed1cd912d52b393d21c42c"
}
SKILL.md
---
name: cargo-workspace-management
description: "Administer a Cargo workspace and talk back to the Cargo team — invite and manage members, mint and rotate API tokens, organize plays, tools, and agents into folders, inspect roles, upload batch input files, and file reports. Triggers: \"invite my teammate\", \"create an API token for CI\", \"who has access\", \"organize these into folders\", \"rotate that token\", \"upload this CSV for a batch\" — and for feedback: \"report this bug to Cargo\", \"send feedback to the Cargo team\", \"this CLI command is broken\", \"share this session with Cargo\", \"request a feature\". Most commands need a token with admin access. Skip when: the question is about credits, plans, or invoices — use cargo-billing."
version: "1.2.2"
compatibility: Requires @cargo-ai/cli (npm). Sign in or create an account with `cargo-ai login --email` (emailed code, no browser), `--oauth`, or an API token
homepage: https://github.com/getcargohq/cargo-skills
metadata:
author: getcargo
openclaw:
requires:
bins:
- cargo-ai
install:
- kind: node
package: "@cargo-ai/cli@latest"
bins:
- cargo-ai
homepage: https://github.com/getcargohq/cargo-skills
---
# 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.
## Bootstrap
Already signed in (`cargo-ai whoami` returns a workspace)? Skip to the next section.
```bash
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`. **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. When the full skill bundle is installed, [`../cargo/references/prerequisites.md`](../cargo/references/prerequisites.md) adds the CLI version pin, token scopes, and the admin-only surface.
## Discover resources first
```bash
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
```bash
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
```bash
# Get your current user and workspace context
cargo-ai whoami
# → Returns your user UUID, email, and active workspace UUID
```
## Users
```bash
# 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.
```bash
# 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.
```bash
# 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.
```bash
# 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.
```bash
# 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.
```bash
# 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`](../cargo/SKILL.md) for when to wire them up.
```bash
# 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](https://github.com/getcargohq/cargo-skills#staying-current) 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`](references/examples/sessions.md).
## Workspace files
Workspace files are CSVs or other data files uploaded for use in batch runs.
```bash
# Upload a file
cargo-ai workspaceManagement file upload --file <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`:
```bash
cargo-ai workspaceManagement user create --help
cargo-ai workspaceManagement token create --help
cargo-ai workspaceManagement folder create --help
```