Name: cargo-workspace-management
Author: getcargohq

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 acce

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. Every command prints JSON to stdout; failures exit non zero and print {"error": "...", "status": ..., "body": ...} to stderr. Anything that creates a run or a batch is async — pass wait until finished or poll the matching get . Admin only: user, role, and envVar writes require workspace management write (admin) access. Any user can create, list, and remove their own tokens; admin access adds service user tokens. Folder writes check folder write permission, and report create and session upsert need none. 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 Quick reference Current user and workspace workspaces update also takes openai api key , logo base64 , metadata , syncs and the Chrome extension agent fields; it is an admin write, and openai api key is a secret — pass it from the environment, not inline. Users Two things to know about upsert permission : action is a permission action, not read / write . It must be one of the actions listed under [Roles]( roles) — the resource scoped ones are orchestration:workflow: read write , ai:agent:… , ai:mcpServer:… , hosting:app:… , hosting:worker:… , content:file:… and workspaceManagement:folder:… . (The help's own action read example was invalid before CLI 1.0.128.) effect deny applies to existing members only , so it takes user uuids ; with emails it is refused, because that path invites. Before cargo 6369 (CLI 1.0.128) the API ignored the effect and always wrote an allow — on a workspace still doing so, put the deny in a role ( role create update permissions ). remove permission honors effect either way. emails invites any address that isn't a member yet, so check user list first. Per member monthly credit cap. PUT /v1/workspaceManagement/users/<user uuid accepts {"monthlyCreditsLimit": <n null} : the credits a member may consume per UTC calendar month across the runs, batches and agent messages they trigger. null removes it. Admins also set it in the web app (Settings → Users → the member's credits limit), user list returns the field, and there is no CLI flag for it. Once the member reaches the cap, their new credit consuming work is refused until the next month, the same way an empty workspace balance refuses it. The check gates work before it starts and reads spend cached for up to a minute, so a member can land slightly past the cap. It fails open: if the limit or the ledger can't be read, the work runs. Enforcement shipped with cargo 6379, and caps set before then were stored but not enforced. Per member spend is readable in cargo billing ( usage get metrics group by user uuid ). Service users A service user is a non human identity with its own role — what a hosted worker, a coding agent's sandbox or a connected GitHub repo acts as, so automation never borrows a person's access. It has no inbox and no login; it authenticates only through its own API tokens (its address is su <uuid @service users.getcargo.io , a domain refused for person invites). The CLI cannot create one — user create takes only email and role slug . Use the web app, a project's defineUser (see [ ../cargo project/references/resources.md ](../cargo project/references/resources.md)), or the API (workspace management write access): firstName / lastName are optional (1–255 chars). The CLI's token create mints only for the caller, so a service user's own token also goes through the API or the web app. Run as. A worker ( hosting worker update run as user uuid , defineWorker({ runAs }) ), an agent's coding repository ( repository.runAsUserUuid , defineAgent({ repository: { runAs } }) ) or a connected repo can run as a service user; Cargo then binds a temporary CARGO API TOKEN for it. Two checks guard the assignment: Reason When Status runAsUserNotFound The user is missing or not kind: "service" — a person can never be run as 404 on hosting / state routes, 403 on ai chat, message and release routes runAsUserNotPermitted One of the service user's permissions (its own and its role's, deny entries included) is not covered by your allow entries 403 So you can only hand automation access you already hold, and a service user with a broader role than yours can't be assigned by you. Roles Roles define what users can do in the workspace. Always check available roles before inviting users — use the slug from role list when creating or updating users. Permission statements are {"effect": "allow" "deny", "resources": [<uuid , …] null, "actions": [...]} — resources: null applies the statement workspace wide. permissions on role update replaces the whole list. Actions follow <domain : read write for ai , billing , connection , content , context , domainManagement , hosting , mailboxManagement , observability , orchestration , revenueOrganization , segmentation , storage , systemOfRecordIntegration and workspaceManagement , plus resource level sub actions ( orchestration:workflow:… , ai:agent:… , hosting:app:… , workspaceManagement:folder:… , …). Running is separate from editing in orchestration. orchestration:run: read write covers runs and orchestration:batch: read write covers batches; neither includes the other, and neither lets the holder edit a workflow, play or tool (that is orchestration:write / orchestration:workflow:write ). orchestration:read / :write / : still include both. That is how a role can start and watch runs without being able to change what they do. role create fails with slugAlreadyExists or slugReserved (a built in slug); role remove fails with roleInUse while any member holds the role or it is the workspace's default role — reassign them first. 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. 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 returned at creation and again by token list (your own tokens, plus service user tokens for admins). Treat both outputs as secrets and store the value in a secrets manager (e.g. GitHub Secrets, AWS Secrets Manager). Folders Folders organize resources (plays, tools, agents) in the Cargo app. 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. 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. 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. 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 and summary are overwritten; finished at only when finished or finished at is passed. 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). Environment variables Workspace environment variables are injected into every worker, app and agent in the workspace, and a worker or app level entry with the same key overrides them. One catalog, but when it is read depends on the consumer: Agents, and a project's workspaceEnv("NAME") pointers , read the value server side on each use, so rotating it takes effect with no redeploy. Hosted workers and apps capture values at deploy time. A worker's bindings are attached when a deployment is promoted, and non secret values are compiled into its bundle. An app receives only non secret entries with a public prefix ( VITE , NEXT PUBLIC , …), baked into its build. After a change, run hosting deployment create + promote again . See [ ../cargo hosting/SKILL.md ](../cargo hosting/SKILL.md) → Worker env vars and secrets. secret encrypts the value at rest and it is never returned again — list and update will not echo it back. Use it for credentials; use no secret on update to turn a variable back into plain text (which re exposes it to list ). value is optional on create . Omitted, the CLI reads the environment variable of