cargo-workspace-management

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cargo CLI — Workspace

Cargo CLI — 工作区

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.

工作区管理：管理用户、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
。

Prerequisites

前提条件

bash

npm install -g @cargo-ai/cli
cargo-ai login --oauth                                  # browser sign-in (recommended)

bash

npm install -g @cargo-ai/cli
cargo-ai login --oauth                                  # 浏览器登录（推荐）

or: cargo-ai login --token <your-api-token> # workspace-scoped API token (non-interactive)

或：cargo-ai login --token <your-api-token> # 工作区范围的API令牌（非交互式）

Pin a default workspace at login (with --oauth)

登录时固定默认工作区（使用--oauth）

cargo-ai login --oauth --workspace-uuid <uuid>


Verify with `cargo-ai whoami`. All commands output JSON to stdout. Without a global install, prefix every command with `npx @cargo-ai/cli` instead of `cargo-ai`.

Failed commands exit non-zero and return `{"errorMessage": "..."}`.

**Note:** Most workspace management commands require a token with admin access.

cargo-ai login --oauth --workspace-uuid <uuid>


使用`cargo-ai whoami`验证。所有命令都会向标准输出（stdout）输出JSON。如果未全局安装，请在每个命令前添加`npx @cargo-ai/cli`替代`cargo-ai`。

执行失败的命令会返回非零退出码，并返回`{"errorMessage": "..."}`。

**注意：** 大多数工作区管理命令需要拥有管理员权限的令牌。

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

bash

cargo-ai whoami                        # 当前用户与活跃工作区
cargo-ai workspaceManagement user list           # 所有工作区成员
cargo-ai workspaceManagement role list           # 可用角色
cargo-ai workspaceManagement token list          # 所有API令牌
cargo-ai workspaceManagement folder list         # 所有文件夹

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>

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>

Current user and workspace

当前用户与工作区

bash

undefined

bash

undefined

Get your current user and workspace context

获取当前用户与工作区上下文

cargo-ai whoami

→ Returns your user UUID, email, and active workspace UUID

→ 返回你的用户UUID、邮箱以及活跃工作区UUID

undefined

undefined

Users

用户管理

bash

undefined

bash

undefined

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>

undefined

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

undefined

Roles

角色管理

Roles define what users can do in the workspace.

bash

undefined

角色定义了用户在工作区中的操作权限。

bash

undefined

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.

cargo-ai workspaceManagement role list


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

API tokens

API令牌管理

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

undefined

每个令牌都有一个可读的

name

和

permissions

字段。通过CLI创建的令牌默认

permissions: null

，这意味着该令牌会继承创建者（执行

token create

命令的用户）的权限——因此令牌的实际访问权限受限于该用户在工作区中的权限。细粒度权限范围（显式允许/拒绝列表）需通过API或Cargo应用配置。

bash

undefined

List all API tokens (includes name and permissions of each token)

列出所有API令牌（包含每个令牌的名称和权限）

cargo-ai workspaceManagement token list

Create a new token — --name is required

创建新令牌——--name为必填项

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).

cargo-ai workspaceManagement token remove <token-uuid>


**命名建议：** 选择能明确体现令牌用途的`--name`，以便后续在`token list`中区分（例如`"GitHub Actions — production"`、`"Local dev — alice"`、`"Zapier integration"`）。名称是列表中区分令牌的唯一方式。

**安全提示：** 令牌值仅在创建时显示一次。请将其存储在密钥管理器中（如GitHub Secrets、AWS Secrets Manager）。

Folders

文件夹管理

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

bash

undefined

文件夹用于在Cargo应用中组织资源（plays、tools、agents）。

bash

undefined

List all folders

列出所有文件夹

cargo-ai workspaceManagement folder list

Create a folder (kind: "tool", "play", "agent", or "file")

创建文件夹（kind可选值："tool"、"play"、"agent"或"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>

undefined

cargo-ai workspaceManagement folder remove <folder-uuid>

undefined

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

undefined

向工作区管理提交报告。每当CLI出现故障、行为异常、缺少所需功能，或者你（用户或Agent）在使用CLI完成任务时遇到困难，都可以使用该功能。 这是官方反馈渠道——每一份报告都会被Cargo团队审阅，并用于改进CLI、相关技能及底层API。

bash

undefined

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

cargo-ai workspaceManagement report create
--title "<简短摘要>"
--description "<详细描述，包含尝试的命令及遇到的错误>"


**提交报告的场景（非 exhaustive）：**

- 命令返回非零退出码，且你无法通过`--help`或`references/troubleshooting.md`解决`errorMessage`中的问题。
- CLI被误用或语法不明确（例如你无法确定应传递哪个标志，或者`--filter`/`--nodes`/`--action`的JSON模式模糊不清）。
- 用户或AI Agent重复执行同一命令却无进展（同一任务失败≥2次）。
- 文档中描述的命令行为与实际不符，或者响应结构与`references/response-shapes.md`中的文档不一致。
- 完全缺少某项功能（没有对应命令实现你的需求）。
- 异步操作从未进入终端状态，或者多次运行返回不一致的结果。

**报告内容建议：**

- `--title`: 问题的一行摘要（例如`"批量创建在工具工作流中因'playNotCompatible'失败"`）。
- `--description`: 包含执行的精确命令（敏感信息已脱敏）、JSON格式的`errorMessage`、你的预期结果、尝试过的解决方法，以及任何相关UUID（运行、批量、工作流、模型）。提供的上下文越多，问题处理速度越快。

```bash

Example: report a CLI struggle after multiple failed attempts

示例：多次尝试失败后提交CLI问题报告

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.

cargo-ai workspaceManagement report create
--title "分段查询返回空结果，但UI中存在匹配记录"
--description "执行命令：cargo-ai segmentation segment fetch --model-uuid <uuid> --filter '{"conjunction":"and","groups":[...]}'。返回0条记录。但在应用UI中使用相同筛选条件显示有1200条匹配记录。尝试了--filter和--segment-uuid两种方式，均返回空结果。预期：获取与UI中一致的记录。"


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

Workspace files

工作区文件管理

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

bash

undefined

工作区文件是指为批量运行上传的CSV或其他数据文件。

bash

undefined

Upload a file

上传文件

cargo-ai workspaceManagement file upload --file-path <path-to-file>

→ Returns s3Filename

→ 返回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/tools.md` for the full file upload and batch run workflow.


`s3-filename`会在通过`cargo-ai workspaceManagement file upload`上传文件时返回。完整的文件上传与批量运行流程请查看`cargo-orchestration`技能的`references/tools.md`。

Help

帮助信息

Every command supports

--help

bash

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

每个命令都支持

--help

参数：

bash

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