使用 CLI

安装并登录 Clowld Space CLI，在终端中管理工作区、任务、智能体和运行时。

Clowld Space CLI 既负责连接本机运行时，也可以在终端中管理工作区、任务、智能体和自动化。为兼容上游，安装后的可执行文件仍叫 clowld。这里介绍常用路径；当前版本支持的参数始终以命令自身的 --help 为准。

安装

macOS / Linux

curl -fsSL https://updates.clowld.xyz/cli/install.sh | bash

Clowld Space 目前没有发布独立的 Homebrew Tap。请使用上面的安装器，避免误装 Multica 上游官方版本。

Windows PowerShell

irm https://updates.clowld.xyz/cli/install.ps1 | iex

确认安装成功：

clowld version

已经安装 Desktop 时，不需要再运行独立安装器。Desktop 会管理 ~/.clowld-space/bin/ 中的官方 CLI、用户 PATH 和版本更新；来源未知、自编译或版本更高的 CLI 不会被覆盖。命名 profile 始终保持独立。

第一次连接

连接 Clowld Space：

clowld setup self-host --server-url https://api.clowld.com --app-url https://space.clowld.com

连接自托管实例：

clowld setup self-host \
  --server-url https://api.example.com \
  --app-url https://app.example.com

独立 CLI 的 setup 会保存服务地址、打开浏览器完成登录，并启动守护进程。Desktop 托管的默认 CLI 不会再创建第二个 daemon，而是使用 Desktop 的登录和守护进程。完成后检查：

clowld auth status
clowld daemon status

如果只需要重新登录，不想覆盖其他配置，运行 clowld login。没有浏览器的环境可以先在 Web 设置中创建个人访问凭证，再输入：

clowld login --token

命令会在终端中提示粘贴访问凭证，避免把完整值留在 shell history 中。

选择工作区

列出并切换默认工作区：

clowld workspace list
clowld workspace switch <slug>

之后的命令会使用这个工作区。单次命令可以通过 --workspace-id 临时覆盖，也可以设置 CLOWLD_WORKSPACE_ID。

邀请成员：

clowld workspace member invite teammate@example.com
clowld workspace member invite admin@example.com --role admin

常用任务操作

# 查看和搜索
clowld issue list
clowld issue get CS-123
clowld issue search "登录失败"

# 创建和修改
clowld issue create --title "修复登录失败"
clowld issue status CS-123 in_progress
clowld issue assign CS-123 --to "Backend Agent"

# 评论和执行记录
clowld issue comment list CS-123
clowld issue comment add CS-123 --content "请先检查回归测试"
clowld issue comment update <comment-id> --expected-revision 2 --content "请检查回归测试和发布说明"
clowld issue runs CS-123

长描述或评论从 stdin 读取，避免处理换行和引号：

clowld issue create --title "升级说明" --description-stdin < notes.md
clowld issue comment add CS-123 --content-stdin < review.md
clowld issue comment update <comment-id> --expected-revision 2 --content-file revised-review.md

查看某次执行的消息，或停止执行：

clowld issue run-messages <task-id> --issue CS-123
clowld issue cancel-task <task-id> --issue CS-123

智能体和 skill

clowld agent list
clowld agent get <agent-id>
clowld agent create --help
clowld agent update <agent-id> --help

clowld skill list
clowld skill get <skill-id>
clowld skill import --url <skill-url>
clowld agent skills add <agent-id> --skill-ids <skill-id>

导入时遇到同名 skill，默认会停止且不修改现有内容。按意图选择：

clowld skill import --url <skill-url> --on-conflict overwrite
clowld skill import --url <skill-url> --on-conflict rename
clowld skill import --url <skill-url> --on-conflict skip

overwrite 只允许 skill 的创建者使用，并保留原来的 ID 与智能体绑定关系。

守护进程和运行时

clowld daemon start
clowld daemon stop
clowld daemon restart
clowld daemon status --output json
clowld daemon logs --follow

clowld runtime list
clowld runtime rename <runtime-id> "Office Mac"
clowld runtime usage <runtime-id>
clowld runtime activity <runtime-id>

删除仍绑定活跃智能体的运行时时，命令默认拒绝。clowld runtime delete <id> --cascade 会解绑这些智能体、保留其配置与历史记录，并取消它们的活动执行。

运行机制和自定义 profile 见守护进程与运行时。

登录时自启动

只有人类在本机明确执行以下命令，才会为当前 profile 注册登录自启动：

clowld daemon autostart enable
clowld daemon autostart status --output json
clowld daemon autostart disable

独立 profile 加上 --profile <name>。daemon start 不会自动注册，只刷新已启用且由 Clowld Space 创建的条目；Desktop 和外部 supervisor 继续管理各自的守护进程。Windows 使用用户 Run key，macOS 使用 LaunchAgent，Linux 使用 systemd 用户单元或 XDG 自启动条目。

登录环境只保存 PATH；其他设置应放在 profile 或用户环境中。disable 阻止下次登录启动，当前守护进程继续运行；Linux 会保留已停用的单元文件，以维持当前服务的自更新重启策略。用户自行创建的条目不会被覆盖或删除。

命令概览

命令	用途
`issue`	创建、更新、分配和搜索任务；管理评论、订阅、标签、属性与执行记录
`topic`	管理主题及其资源
`label`、`property`	管理工作区标签和自定义属性
`agent`、`skill`、`squad`	管理智能体、skill 和小队
`autopilot`	管理自动化、触发器和运行历史
`workspace`	创建、查看、切换工作区和邀请成员
`repo`	管理工作区仓库，并把仓库检出到本机
`daemon`、`runtime`	启停本机守护进程，查看和管理运行时
`attachment`	上传或下载附件
`user profile`	查看或更新当前用户资料
`auth`、`login`、`setup`	登录、查看认证状态和初始化连接
`config`	查看或修改当前 CLI profile 的本地配置
`update`、`version`	更新 CLI 或查看版本

clowld chat 读取的是智能体当前正在处理的外部聊天会话，主要供聊天集成中的智能体使用；它不是用于浏览任意工作区对话的通用命令。

ID 和输出格式

任务使用 CS-123 这样的 key 或完整 UUID，不接受 UUID 短前缀。

其他资源的 list 命令通常显示可复制的短 ID，并支持 --full-id 输出完整 UUID。短 ID 不唯一时，CLI 会要求增加字符或改用完整 UUID。执行 ID 还需要通过 --issue 指明所属任务。

许多命令支持结构化输出：

clowld issue list --output json
clowld agent list --output json

脚本使用 JSON 输出，不解析面向终端的表格。各命令支持的输出格式和分页参数以 clowld <command> --help 为准。

Profile 与配置

默认配置保存在 ~/.clowld-space/cli/config.json。使用 --profile <name> 可以隔离另一套服务地址、访问凭证、默认工作区和守护进程状态：

clowld setup self-host --profile staging \
  --server-url https://api.staging.example.com \
  --app-url https://app.staging.example.com

clowld issue list --profile staging

命名 profile 保存在 ~/.clowld-space/cli/profiles/<name>/config.json。首选健康端口不可用时，守护进程会绑定另一个 loopback 端口，并把实际端口和 PID 写入同目录的 daemon.port。CLI 生命周期命令和 Desktop 使用前会验证存活进程的 profile 与 PID；该文件只是发现线索，不是端口配置。查看当前值：

clowld config show
clowld config show --profile staging

CLI 配置文件包含可代表你访问 Clowld Space 的访问凭证。不要提交到仓库、上传到日志或与他人共享。

命令参考

下表覆盖当前全部顶层命令，按 CLI 自身的分组排列。所有命令都接受全局 flag --server-url、--workspace-id、--profile 和 --debug。--output 是逐命令注册的 flag，默认格式因命令而异：list 类默认表格，get、create 类多默认 JSON。完整参数以 clowld <command> --help 为准。

Core

命令	子命令	用途	关键 flag
`issue`	`list`	列出任务	`--status`、`--priority`、`--assignee`、`--topic`、`--metadata`（可重复）、`--property`（可重复，`"名称=值"`；`__none__` 匹配未设置）、`--limit`、`--offset`、`--sort`（支持 `property:名称或 id`）、`--full-id`、`--resolve-properties`（仅 JSON；在保存的 id 旁附上属性、选项和成员名称）
	`get <id>`	查看单个任务	`--resolve-properties`（仅 JSON；在保存的 id 旁附上属性、选项和成员名称）
	`create`	创建任务	`--title`（必填）、`--description` / `--description-stdin` / `--description-file`、`--status`、`--priority`、`--assignee`、`--parent`、`--stage`、`--topic`、`--start-date`、`--due-date`、`--attachment`（可重复）、`--no-start`
	`update <id>`	更新任务字段	与 `create` 同类字段，另有 `--position`
	`assign <id>`	指派或取消指派	`--to`（名称模糊匹配成员、智能体或小队）、`--to-id`、`--unassign`、`--no-start`
	`status <id> <status>`	修改状态	`--no-start`
	`reorder <id>`	在列内移动
	`search <query>`	搜索任务	`--limit`、`--include-closed`
	`children <id>`	按阶段分组列出子任务
	`pull-requests <id>`	列出关联的 PR
	`comment list/add/delete/resolve/unresolve`	管理评论	`add`：`--content` / `--content-stdin` / `--content-file`、`--parent`、`--attachment`；`list`：`--since`、`--thread`、`--tail`
	`subscriber list/add/remove <issue-id>`	管理订阅者	`--user`、`--user-id`（缺省为当前用户）
	`label list/add/remove <issue-id>`	管理任务上的标签
	`metadata list/get/set/delete <issue-id>`	管理任务级键值元数据
	`property list/set/unset <issue-id>`	设置自定义属性值	`set`：`--name`、`--value`（`actor` / `multi_actor` 接受成员的名称、邮箱或 id）
	`runs <issue-id>`	查看执行历史	`--full-id`
	`run-messages <task-id>`	查看单次执行的消息	`--since`、`--issue`
	`usage <issue-id>`	查看聚合 Token 用量
	`rerun <id>`	按当前指派重新入队执行
	`cancel-task <task-id>`	取消运行中或排队中的执行	`--issue`
`topic`	`list/get/create/update/delete`	管理主题
	`status <id> <status>`	修改主题状态
	`resource list/add/update/remove`	管理主题附加资源	`--type`、`--url`、`--local-path`、`--daemon-id`、`--execution-mode`（本地目录的 `in_place` / `worktree`）
`label`	`list/get/create/update/delete`	管理工作区标签	`list`：`--resource-type`（`issue` 或 `skill`）、`--full-id`；`create`：`--name`、`--color`、`--resource-type`（`issue` 或 `skill`）、`--description`
`property`	`list/get/create/update/archive/unarchive`	管理工作区自定义属性	`create`：`--name`、`--type`（`text`、`number`、`select`、`multi_select`、`date`、`checkbox`、`url`、`actor`、`multi_actor`、`multi_text`、`multi_url`）、`--option`（可重复，仅 select 类型）；`list`：`--include-archived`；类型创建后不可修改
`agent`	`list/get/create/update/archive/restore`	管理智能体	`--name`、`--runtime-id`（`create` 必填）、`--instructions`、`--conversation-starters`、`--model`、`--thinking-level`、`--mcp-config`、`--permission-mode`、`--max-concurrent-tasks`
	`copy <agent-id>`	复制为新智能体，原智能体不受影响	`--name`（默认为原名加 `(copy)`）、`--runtime-id`（复制到其他运行时时必须同时指定 `--model`）、`--no-skills`；`custom_env`、`mcp_config`、`runtime_config` 等机密配置不会复制，需用与 `create` 相同的 flag 重新提供
	`tasks <id>`	查看智能体的执行
	`avatar <id>`	上传头像
	`env get/set <agent-id>`	读写自定义环境变量（仅 owner 和 admin）
	`skills list/set/add <agent-id>`	管理绑定的 skill	`--skill-ids`（`set` 全量替换，`add` 增量添加）
	`mcp list/add/enable/disable/remove <agent-id>`	给该 agent 分配工作区 MCP 服务	server id 从 `workspace mcp list` 获取。库里的条目在这里添加之前不会生效；`disable` 只停止下发，保留分配
`autopilot`	`list/get/create/update/delete`	管理自动化	`create`：`--title`、`--agent`、`--mode`（均必填）、`--topic`、`--subscriber`（可重复）
	`trigger <id>`	手动触发一次
	`runs <id>`	查看运行历史
	`trigger-list/trigger-add/trigger-update/trigger-delete/trigger-rotate-url`	列出触发器 ID，并管理定时和 webhook 触发器	`trigger-list`：`--full-id`、`--output`
`workspace`	`list/get/create/update/switch`	管理工作区；`switch` 设置当前 profile 的默认工作区
	`mcp list/add/update/remove`	管理工作区的 MCP 服务库	写操作需要 owner/admin。这里添加的服务不会分配给任何 agent——用 `clowld agent mcp add` 分配给某个 agent。`list` 只列出名称与 transport；存储的条目是只写的，任何角色都读不回。`--server-config-file` / `--server-config-stdin` 避免访问凭证进入 shell 历史
	`member list/invite <email>`	查看成员、发出邀请	`invite`：`--role`（member 或 admin，默认 member）
`repo`	`list/add/remove/checkout`	管理工作区仓库并检出到本机	`--url`（可重复）；`checkout`：`--ref`
`skill`	`list/get/create/update/delete`	管理 skill
	`import`	从 URL 或本地文件导入 skill	`--url` / `--file`、`--on-conflict`（`fail`、`overwrite`、`rename`、`skip`，默认 `fail`）
	`search <query>`	搜索 skill
	`files list/upsert/delete <skill-id>`	管理 skill 内的文件
	`label list/add/remove <skill-id>`	管理 skill 上的标签	`add` / `remove`：`<label-id>` 可使用完整 UUID 或短前缀
`squad`	`list/get/create/update/delete`	管理小队（`delete` 为归档）
	`member list/add/set-role/remove`	管理小队成员
	`activity <issue-id> <outcome>`	记录队长评价
`chat`	`history`、`thread [id]`	读取智能体当前正在处理的外部聊天会话	`--limit`、`--before`

Runtime

命令	子命令	用途	关键 flag
`daemon`	`start`	启动本机守护进程	`--foreground`、`--device-name`、`--runtime-name`、`--workspaces-root`、`--poll-interval`、`--heartbeat-interval`、`--agent-timeout`（`0` 表示不设上限）、`--max-concurrent-tasks`、`--no-auto-update`；均有对应的 `CLOWLD_*` 环境变量
	`stop` / `status` / `restart`	停止、查看状态、重启（`restart` 与 `start` 同一套 flag）
	`logs`	查看守护进程日志	`--follow`、`--lines`
	`disk-usage`	查看本机磁盘占用	`--by-workspace`、`--by-task`、`--top`
`runtime`	`list/usage/activity/update/rename/delete`	查看和管理运行时	`delete`：`--cascade`（解绑绑定的智能体、保留其数据并取消其执行）
	`profile list/create/update/delete`	管理自定义运行时 profile
	`profile set-path/unset-path <profile-id>`	固定本机可执行文件路径（仅本地生效，不上传服务器）

Additional

命令	子命令	用途	关键 flag
`auth`	`status` / `logout`	查看认证状态；`logout` 只删除本地保存的访问凭证，不吊销服务端访问凭证
`user`	`profile get/update`	查看或更新当前用户资料
`login`	—	浏览器登录并自动配置全部工作区	`--token`（不带值时在终端交互式输入）
`setup`	`cloud`（默认）、`self-host`	保存服务地址、完成登录并启动守护进程	`self-host`：`--server-url`、`--app-url`、`--port`、`--frontend-port`
`attachment`	`download <attachment-id>`、`upload <path>`	下载或上传附件	`download`：`--output-dir`；`upload`：`--task`
`config`	`show`、`set <key> <value>`	查看或修改当前 profile 的本地配置	优先级：命令行 flag > 环境变量 > `config.json` > 内置默认；设为空串可清除
`update`	—	更新 CLI 到最新版本
`version`	—	查看版本信息	`--output`（`text` 或 `json`）

在其他编码智能体里操作 Clowld Space

Clowld Space 通过 Codex、Claude Code、Cursor 等运行时启动智能体时，会自动注入内置 skill，教它们使用本页的 clowld 命令，包括低成本读取任务和评论线程、通过文件写评论，以及正确处理 mention、状态变更和指派带来的副作用。

这些 skill 使用 Clowld Space 为任务注入的专用 CLI 凭据，本身不会增加任何权限。权限仍由任务发起成员、工作区和智能体范围共同决定，不需要额外维护一套 CLI skill 登录。

接下来

Skill — 了解 Clowld Space 如何向智能体提供可复用指令。
认证与访问凭证 — PAT 的创建、续期和吊销。
故障排查 — 命令报错和任务不开始的排查路径。
创建和配置智能体 — agent create 各字段的完整语义。

本页目录