cargo-workspace-management

Cargo CLI — 工作区

工作区管理：管理用户、API 令牌、文件夹、角色、工作区级文件，以及向工作区管理部门提交报告。

完整的 JSON 响应结构请参见 references/response-shapes.md。 常见错误及其修复方法请参见 references/troubleshooting.md。 用户邀请和管理示例请参见 references/examples/users.md。 API 令牌创建和轮换示例请参见 references/examples/tokens.md。 将资源整理到文件夹中的示例请参见 references/examples/folders.md。 提交工作区管理报告的示例请参见 references/examples/reports.md。 会话跟踪请参见 references/examples/sessions.md — Cargo 安装程序会自动搭建 Claude Code 的 SessionStart + Stop + SessionEnd 钩子。

初始化

已登录（cargo-ai whoami 返回工作区）？请跳至下一节。

npm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`
cargo-ai login --email [email protected]  # 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

每条命令都会向 stdout 输出 JSON；失败时会以非零状态退出，并向 stderr 输出 {"error": "...", "status": ..., "body": ...}。任何会创建运行或批次的操作都是异步的 — 传入 --wait-until-finished，或轮询对应的 get 命令。**仅限管理员：**用户、角色和 envVar 写操作需要工作区管理写入（管理员）权限。任何用户都可以创建、列出和删除自己的令牌；管理员权限还可管理服务用户令牌。文件夹写操作会检查文件夹写入权限，而 report create 和 session upsert 不需要权限。安装完整的技能包后，../cargo/references/prerequisites.md 会补充 CLI 版本固定、令牌范围和仅限管理员的功能说明。

先发现资源

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

快速参考

cargo-ai whoami
cargo-ai workspaceManagement user list
cargo-ai workspaceManagement user create --email <email> --role-slug <slug>
cargo-ai workspaceManagement role create --name <name> --slug <slug> --permissions '<json>'
cargo-ai workspaceManagement workspaces list
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]
cargo-ai workspaceManagement envVar list
cargo-ai workspaceManagement envVar create --key <KEY> [--value <v>] [--secret]

当前用户和工作区

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

# Workspaces this user can reach, and the one selected now
cargo-ai workspaceManagement workspaces list
cargo-ai workspaceManagement workspaces get-current      # honors CARGO_WORKSPACE_UUID

# Create another workspace (it is not selected for you — sign in to it or set CARGO_WORKSPACE_UUID)
cargo-ai workspaceManagement workspaces create --name "Acme GTM"

# Update the selected workspace — pass the literal "null" to clear a nullable field
cargo-ai workspaceManagement workspaces update --name "Acme GTM (prod)"
cargo-ai workspaceManagement workspaces update --allowed-email-domains acme.com,acme.io
cargo-ai workspaceManagement workspaces update --default-role-uuid <role-uuid>   # role new members get

workspaces update 还接受 --openai-api-key、--logo-base64、--metadata、--syncs 和 Chrome 扩展 Agent 字段；这是管理员写操作，而 --openai-api-key 是机密 — 请通过环境变量传入，不要直接写在命令中。

用户

# List all workspace members
cargo-ai workspaceManagement user list

# Invite a new user (requires their email and a role)
cargo-ai workspaceManagement user create \
  --email [email protected] \
  --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>

# Grant one user access to one resource (a workflow, folder, agent, app, …)
cargo-ai workspaceManagement user upsert-permission \
  --user-uuids <uuid> --action orchestration:workflow:read --resource-uuid <workflow-uuid> --effect allow

# Take a grant back
cargo-ai workspaceManagement user remove-permission --user-uuid <uuid> --resource-uuid <workflow-uuid> --effect allow

关于 upsert-permission，有两点需要注意：

• **--action 是权限操作，而不是 read / write。**它必须是 角色 中列出的操作之一 — 按资源限定的操作包括 orchestration:workflow:*|read|write、ai:agent:…、ai:mcpServer:…、hosting:app:…、hosting:worker:…、content:file:… 和 workspaceManagement:folder:…。（在 CLI 1.0.128 之前，帮助信息中的 --action read 示例无效。）
• --effect deny 仅适用于现有成员，因此需要传入 --user-uuids；与 --emails 一起使用时会被拒绝，因为该路径用于邀请。在 cargo#6369（CLI 1.0.128）之前，API 会忽略 effect，始终写入 allow — 如果工作区仍有此行为，请在角色中设置 deny（role create|update --permissions）。remove-permission 无论如何都会遵循 --effect。

--emails 会邀请尚未成为成员的地址，因此请先检查 user list。

每位成员的月度额度上限。PUT /v1/workspaceManagement/users/<user-uuid> 接受 {"monthlyCreditsLimit": <n> | null}：限制成员在每个 UTC 自然月内，因其触发的运行、批次和 Agent 消息而消耗的额度。设为 null 可移除此限制。管理员也可在 Web 应用中设置此项（Settings → Users → 成员的额度上限）；user list 会返回该字段，但没有对应的 CLI 标志。成员达到上限后，在下个月开始前，其新的额度消耗型工作将被拒绝，与工作区余额耗尽时的处理方式相同。该检查会在工作开始前进行，并读取最多缓存一分钟的消费记录，因此成员的实际消耗可能略微超过上限。此检查采用故障放行策略：如果无法读取上限或账本，工作仍会运行。此限制机制随 cargo#6379 一同发布，此前设置的上限虽已存储，但不会强制执行。可通过 cargo-billing 查看每位成员的消费情况（usage get-metrics --group-by user_uuid）。

服务用户

服务用户是一种具有自身角色的非人类身份——托管工作进程、编码 Agent 的沙箱或已连接的 GitHub 仓库均以此身份运行，这样自动化任务就无需借用任何人的访问权限。它没有收件箱，也无法登录；只能通过自己的 API 令牌进行身份验证（其地址为 su-<uuid>@service-users.getcargo.io，此域名不接受个人邀请）。

CLI 无法创建服务用户——user create 仅接受 --email 和 --role-slug。请使用 Web 应用、项目的 defineUser（参见 ../cargo-project/references/resources.md）， 或 API（需要工作区管理写入权限）：

# POST /v1/workspaceManagement/users
{"kind":"service","firstName":"Enrichment","lastName":"Worker","roleSlug":"<role-slug>"}
# → 201 {user}; 404 roleNotFound / workspaceNotFound
# A token for it: POST /v1/workspaceManagement/tokens {"name":"…","userUuid":"<service-user-uuid>"}
#   (403 unless the caller has workspace-management write and the target is kind "service")

firstName / lastName 为可选项（1–255 个字符）。CLI 的 token create 只能为调用者创建令牌，因此服务用户自己的令牌也需要通过 API 或 Web 应用创建。

以服务用户身份运行。 工作进程（hosting worker update --run-as-user-uuid、defineWorker({ runAs })）、Agent 的编码仓库（repository.runAsUserUuid、defineAgent({ repository: { runAs } })）或已连接的仓库可以作为服务用户运行；随后 Cargo 会为其绑定临时的 CARGO_API_TOKEN。分配时会检查以下两项：

原因	时机	状态
runAsUserNotFound	用户不存在或不是 kind: "service"——个人用户永远不能作为运行身份	hosting / state 路由返回 404，ai 聊天、消息和发布路由返回 403
runAsUserNotPermitted	服务用户的某项权限（包括其自身权限和角色权限，含拒绝项）未被你的允许项涵盖	403

因此，你只能向自动化任务授予自己已有的访问权限；如果服务用户的角色权限比你的更广，你就不能将其指定为运行身份。

角色

角色定义用户在工作区中可以执行的操作。

# List available roles
cargo-ai workspaceManagement role list

# Create a custom role: a slug, a colour, and a list of permission statements
cargo-ai workspaceManagement role create \
  --name "Run operator" --slug run-operator --color green \
  --description "Starts and reads runs and batches; cannot edit workflows" \
  --permissions '[
    {"effect":"allow","resources":null,"actions":["orchestration:read","orchestration:run:*","orchestration:batch:*","storage:read","segmentation:read"]}
  ]'

# Update or remove a custom role (built-in roles can't be changed)
cargo-ai workspaceManagement role update --uuid <role-uuid> --permissions '[...]'
cargo-ai workspaceManagement role remove <role-uuid>

邀请用户前，请务必检查可用角色——创建或更新用户时，请使用 role list 返回的 slug。

权限声明的格式为 {"effect": "allow" | "deny", "resources": [<uuid>, …] | null, "actions": [...]}——resources: null 表示该声明适用于整个工作区。role update 中的 --permissions 会替换整个权限列表。操作遵循 <domain>:*|read|write 格式，适用于 ai、billing、connection、content、context、domainManagement、hosting、mailboxManagement、observability、orchestration、revenueOrganization、segmentation、storage、systemOfRecordIntegration 和 workspaceManagement，并支持资源级子操作（orchestration:workflow:…、ai:agent:…、hosting:app:…、workspaceManagement:folder:… 等）。

在编排中，运行权限与编辑权限相互独立。orchestration:run:*|read|write 涵盖运行，orchestration:batch:*|read|write 涵盖批次；两者互不包含，也都不允许持有者编辑工作流、play 或工具（这需要 orchestration:write / orchestration:workflow:write）。orchestration:read / :write / :* 仍同时包含两者。这样，角色就可以启动和查看运行，却不能更改其执行内容。

role create 遇到 slugAlreadyExists 或 slugReserved（内置 slug）时会失败；只要仍有成员持有该角色，或该角色是工作区的默认角色，role remove 就会因 roleInUse 而失败——请先为他们重新分配角色。

API 令牌

每个令牌都有一个易读的 name 和一个 permissions 字段。通过 CLI 创建的令牌会以 permissions: null 签发，这意味着令牌会沿用其所属用户（运行 token create 的用户）的权限，因此令牌的实际访问权限不会超出该用户在工作区中可执行的操作范围。细粒度权限范围（显式允许/拒绝列表）需通过 API 或 Cargo 应用配置。

# List your API tokens (includes name, permissions, and the token value of each)
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

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

命名： 选择一个用途一目了然的 --name，方便之后在 token list 中识别（例如 "GitHub Actions — production"、"Local dev — alice"、"Zapier integration"）。名称是在列表中区分令牌的唯一方式。

安全性： 令牌值会在创建时以及通过 token list（你自己的令牌，以及管理员可见的服务用户令牌）返回。请将这两处输出都视为机密，并将令牌值存储在机密管理器中（例如 GitHub Secrets、AWS Secrets Manager）。

文件夹

文件夹用于在 Cargo 应用中整理资源（plays、工具、Agent）。

# List all folders
cargo-ai workspaceManagement folder list

# Create a folder (kind: tool, play, agent, file, mcpServer, model, app, worker, alert, or mailbox)
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 (rename, move under a parent, or reorder among its siblings)
cargo-ai workspaceManagement folder update --uuid <folder-uuid> --name "Q1 2025 Campaigns"
cargo-ai workspaceManagement folder update --uuid <folder-uuid> --parent-uuid <parent-folder-uuid> --order 0

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

报告

向工作区管理团队提交报告。每当 CLI 运行失败、行为异常、缺少你需要的功能，或你（用户或 Agent）难以通过 CLI 完成任务时，都请提交报告。 这是官方反馈渠道——Cargo 团队会审核每份报告，并据此改进 CLI、相关技能及底层 API。

# 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>"

适合提交报告的情况（不限于以下情形）：

• 命令以非零状态退出，且你无法通过 --help 或 references/troubleshooting.md 解决其中的 errorMessage。
• CLI 被误用或语法不清楚（例如，你不清楚该传入哪个标志，或 --filter / --nodes / --action 的 JSON 架构存在歧义）。
• 用户或 AI Agent 反复重试同一命令但毫无进展（在同一任务中失败 ≥ 2 次）。
• 已记录的命令行为与技能描述不符，或响应结构与 references/response-shapes.md 中的说明不同。
• 某项功能似乎完全缺失（没有可用于所需操作的命令）。
• 异步操作始终无法达到终止状态，或多次运行返回的结果不一致。

报告中应包含的内容：

• --title：用一行概述问题（例如 "batch create fails with 'playNotCompatible' on tool workflow"）。
• --description：包含实际执行的确切命令（请对敏感值脱敏）、JSON errorMessage、预期结果、尝试过的解决方法，以及相关 UUID（运行、批次、工作流、模型）。提供的上下文越充分，问题排查就越快。

# 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 '{\"conjonction\":\"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."

不要在 CLI 任务失败时默默放弃。请提交报告。 这能形成反馈闭环，帮助改进 CLI 和这些技能。

会话

在 workspace_management.sessions 中记录 Claude Code 会话。每个 (workspaceUuid, sessionId) 对应一行。Cargo 路由器的 Claude Code SessionStart + Stop + SessionEnd 钩子配方会用到此记录——有关如何接入这些钩子，请参阅 ../cargo/SKILL.md。

# 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。title 和 summary 在架构中为 NOT NULL——开始时请传入占位内容，并在结束时覆盖。
• --finished 会将 finished_at 设为当前时间。若要指定时间戳，请改用 --finished-at <iso>。
• 使用相同的 --session-id 两次调用 upsert 会更新同一行——title 和 summary 会被覆盖；只有传入 --finished 或 --finished-at 时才会更新 finished_at。

命令会以 JSON 格式返回 upsert 后的会话。Cargo 安装程序会接入 SessionStart + Stop + SessionEnd 钩子，并自动调用此命令：SessionStart 会写入占位内容；每轮的 Stop 钩子会检查点式更新该行（不传入 --finished）；SessionEnd 会写入根据转录生成的 AI 摘要并传入 --finished——请参阅 references/examples/sessions.md。

环境变量

工作区环境变量会注入工作区中的每个 worker、应用和 Agent，而 worker 或应用级别中键相同的条目会覆盖它们。它们位于同一目录中，但读取时机取决于使用方：

• Agent 以及项目的 workspaceEnv("NAME") 指针，每次使用时都会在服务端读取值，因此轮换值后无需重新部署即可生效。
• 托管 worker 和应用会在部署时捕获值。 worker 的绑定会在部署晋升时附加，非机密值会编译到其包中。应用只会接收带有公开前缀（VITE_、NEXT_PUBLIC_ 等）的非机密条目，并将其烘焙到构建产物中。更改后，再次运行 hosting deployment create + promote。参见 ../cargo-hosting/SKILL.md → Worker 环境变量和机密。

cargo-ai workspaceManagement envVar list

# Create. Omit --value to read it from the environment variable of the same name.
cargo-ai workspaceManagement envVar create \
  --key OPENAI_API_KEY \
  --value sk-... \
  --secret \
  --description "Used by the enrichment worker"

# Update. Omit --value to keep the stored one.
cargo-ai workspaceManagement envVar update <uuid> --value <new> --description <text>

cargo-ai workspaceManagement envVar remove <uuid>

• --secret 会在静态存储时加密该值，且之后不会再返回该值——list 和 update 都不会回显该值。凭据请使用此选项；要将变量恢复为纯文本，请在 update 时使用 --no-secret（这样该值会重新显示在 list 中）。
• create 中的 --value 是可选的。 如果省略，CLI 会从 shell 中读取同名环境变量，因此 export OPENAI_API_KEY=… && cargo-ai workspaceManagement envVar create --key OPENAI_API_KEY --secret 可让该值既不进入 shell 历史记录，也不出现在此命令行中。
• update 接受的是 uuid，而不是键名。 可通过 envVar list 获取。

在项目中，请使用 workspaceEnv("NAME") 引用条目，而不要将值复制到代码中——这是一个每次使用时都在服务端解析的指针。另一种选择是 secret("NAME")，但其含义不同（在部署时从你自己的环境中读取）。参见 ../cargo-project/SKILL.md → 关键规则。

工作区文件

工作区文件是上传后供批量运行使用的 CSV 或其他数据文件。

# 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

通过 cargo-ai workspaceManagement file upload 上传文件时会返回 s3-filename。有关完整的文件上传和批量运行工作流，请参阅 cargo-orchestration 技能中的 references/examples/tools.md。

帮助

每个命令都支持 --help：

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