{"id":17908,"plugin_id":"plugins_6a7d29277df08191a68f23401570b188","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:14:27.701Z","digest":"90ffcae9f43f393db1ee11424258e93b9fdda3995ca31d88066def308be5960c","against":null,"payload":{"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.","included_files":[{"relative_path":"references/examples/folders.md","size_in_bytes":1583},{"relative_path":"references/examples/reports.md","size_in_bytes":6122},{"relative_path":"references/examples/sessions.md","size_in_bytes":3664},{"relative_path":"references/examples/tokens.md","size_in_bytes":2032},{"relative_path":"references/examples/users.md","size_in_bytes":1258},{"relative_path":"references/response-shapes.md","size_in_bytes":4525},{"relative_path":"references/troubleshooting.md","size_in_bytes":5031},{"relative_path":"skill-metadata.json","size_in_bytes":1290}],"skill_md_contents":"---\nname: cargo-workspace-management\ndescription: \"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.\"\nversion: \"1.2.2\"\ncompatibility: 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\nhomepage: https://github.com/getcargohq/cargo-skills\n---\n\n# Cargo CLI — Workspace\n\nWorkspace administration: managing users, API tokens, folders, roles, workspace-level files, and submitting reports to workspace management.\n\n> See `references/response-shapes.md` for full JSON response structures.\n> See `references/troubleshooting.md` for common errors and how to fix them.\n> See `references/examples/users.md` for user invite and management examples.\n> See `references/examples/tokens.md` for API token creation and rotation examples.\n> See `references/examples/folders.md` for organizing resources into folders.\n> See `references/examples/reports.md` for examples of submitting workspace management reports.\n> See `references/examples/sessions.md` for session tracking — the Cargo installer scaffolds the Claude Code SessionStart + Stop + SessionEnd hooks automatically.\n\n## Bootstrap\n\nAlready signed in (`cargo-ai whoami` returns a workspace)? Skip to the next section.\n\n```bash\nnpm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`\ncargo-ai login --email you@company.com  # emailed code, no browser; creates the account on first use\n                                        # alternatives: --oauth (browser) · --token <api-token> (CI)\ncargo-ai whoami                         # confirm the active workspace before any write\n```\n\nEvery 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.\n\n## Discover resources first\n\n```bash\ncargo-ai whoami                        # current user and active workspace\ncargo-ai workspaceManagement user list           # all workspace members\ncargo-ai workspaceManagement role list           # available roles\ncargo-ai workspaceManagement token list          # all API tokens\ncargo-ai workspaceManagement folder list         # all folders\n```\n\n## Quick reference\n\n```bash\ncargo-ai whoami\ncargo-ai workspaceManagement user list\ncargo-ai workspaceManagement user create --user-email <email> --role-slug <slug>\ncargo-ai workspaceManagement token list\ncargo-ai workspaceManagement token create --name <name>\ncargo-ai workspaceManagement token remove <token-uuid>\ncargo-ai workspaceManagement folder list\ncargo-ai workspaceManagement folder create --name <name> --emoji-slug <slug> --kind <kind>\ncargo-ai workspaceManagement report create --title <title> --description <description>\ncargo-ai workspaceManagement session upsert --session-id <id> --title <title> --summary <summary> [--finished]\n```\n\n## Current user and workspace\n\n```bash\n# Get your current user and workspace context\ncargo-ai whoami\n# → Returns your user UUID, email, and active workspace UUID\n```\n\n## Users\n\n```bash\n# List all workspace members\ncargo-ai workspaceManagement user list\n\n# Invite a new user (requires their email and a role)\ncargo-ai workspaceManagement user create \\\n  --user-email user@example.com \\\n  --role-slug <role-slug>\n\n# Update a user's role\ncargo-ai workspaceManagement user update --user-uuid <uuid> --role-slug <new-role-slug>\n\n# Remove a user from the workspace\ncargo-ai workspaceManagement user remove --user-uuid <uuid>\n```\n\n## Roles\n\nRoles define what users can do in the workspace.\n\n```bash\n# List available roles\ncargo-ai workspaceManagement role list\n```\n\nAlways check available roles before inviting users — use the `slug` from `role list` when creating or updating users.\n\n## API tokens\n\nEach 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.\n\n```bash\n# List all API tokens (includes name and permissions of each token)\ncargo-ai workspaceManagement token list\n\n# Create a new token — --name is required\ncargo-ai workspaceManagement token create --name \"CI/CD pipeline\"\n# → Returns the token value — store it securely, it won't be shown again\n\n# Remove a token\ncargo-ai workspaceManagement token remove <token-uuid>\n```\n\n**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.\n\n**Security:** Token values are only shown once at creation. Store them in a secrets manager (e.g. GitHub Secrets, AWS Secrets Manager).\n\n## Folders\n\nFolders organize resources (plays, tools, agents) in the Cargo app.\n\n```bash\n# List all folders\ncargo-ai workspaceManagement folder list\n\n# Create a folder (kind: \"tool\", \"play\", \"agent\", or \"file\")\ncargo-ai workspaceManagement folder create --name \"Q1 Campaigns\" --emoji-slug \"rocket\" --kind \"play\"\n\n# Get a folder\ncargo-ai workspaceManagement folder get <folder-uuid>\n\n# Update a folder\ncargo-ai workspaceManagement folder update --uuid <folder-uuid> --name \"Q1 2025 Campaigns\"\n\n# Remove a folder\ncargo-ai workspaceManagement folder remove <folder-uuid>\n```\n\n## Reports\n\nSubmit 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.\n\n```bash\n# Submit a report to workspace management\ncargo-ai workspaceManagement report create \\\n  --title \"<short summary>\" \\\n  --description \"<detailed description, including the command(s) tried and the error(s) seen>\"\n```\n\n**When to send a report (non-exhaustive):**\n\n- A command exits non-zero with an `errorMessage` you cannot resolve from `--help` or `references/troubleshooting.md`.\n- 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).\n- A user or AI agent is repeatedly retrying the same command without progress (≥ 2 failed attempts on the same task).\n- A documented command does not behave as the skill describes, or a response shape differs from what `references/response-shapes.md` documents.\n- A capability appears to be missing entirely (no command exists for what you need to do).\n- An async operation never reaches a terminal status, or returns inconsistent results across runs.\n\n**What to put in the report:**\n\n- `--title`: one-line summary of the problem (e.g. `\"batch create fails with 'playNotCompatible' on tool workflow\"`).\n- `--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.\n\n```bash\n# Example: report a CLI struggle after multiple failed attempts\ncargo-ai workspaceManagement report create \\\n  --title \"segment fetch returns empty results despite matching records in UI\" \\\n  --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.\"\n```\n\n> 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.\n\n## Sessions\n\nRecord 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.\n\n```bash\n# Upsert a session. Idempotent on --session-id within the workspace.\ncargo-ai workspaceManagement session upsert \\\n  --session-id <claude-session-id> \\\n  --title \"<short title>\" \\\n  --summary \"<one-or-two sentence summary>\"\n\n# Same call, but also stamp finished_at = now\ncargo-ai workspaceManagement session upsert \\\n  --session-id <claude-session-id> \\\n  --title \"<final title>\" \\\n  --summary \"<final summary>\" \\\n  --finished\n```\n\n- `--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.\n- `--finished` stamps `finished_at = now`. Use `--finished-at <iso>` for an explicit timestamp instead.\n- Calling `upsert` twice with the same `--session-id` updates the same row — `title`, `summary`, and `finished_at` are overwritten.\n\nReturns 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).\n\n## Workspace files\n\nWorkspace files are CSVs or other data files uploaded for use in batch runs.\n\n```bash\n# Upload a file\ncargo-ai workspaceManagement file upload --file <path-to-file>\n# → Returns s3Filename\n\n# Inspect a file's columns before running a batch\ncargo-ai workspaceManagement file list-columns --s3-filename <s3-filename>\n# → Returns column names to use when mapping to workflow inputs\n```\n\nThe `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.\n\n## Help\n\nEvery command supports `--help`:\n\n```bash\ncargo-ai workspaceManagement user create --help\ncargo-ai workspaceManagement token create --help\ncargo-ai workspaceManagement folder create --help\n```\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}