使用 CLI

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

Multica CLI 既负责连接本机运行时，也可以在终端中管理工作区、任务、智能体和自动化。这里介绍常用路径；当前版本支持的参数始终以命令自身的 --help 为准。

安装

curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash

安装了 Homebrew 时也可以运行：

brew install multica-ai/tap/multica

确认安装成功：

multica version

选择工作区

列出并切换默认工作区：

multica workspace list
multica workspace switch <slug>

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

邀请成员：

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

常用任务操作

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

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

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

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

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

查看某次运行的消息、停止运行或重试：

multica issue run-messages <task-id> --issue MUL-123
multica issue cancel-task <task-id> --issue MUL-123
multica issue rerun-task <run-id> --issue MUL-123
multica issue rerun-task <run-id> --issue MUL-123 --fresh

同一项目、同一父任务下已有标题相同（不区分大小写，忽略多余空格）且未关闭的任务时，issue create 会拒绝创建并给出那个任务。确实要再建一个，加 --allow-duplicate；要把一个任务标为另一个的重复，用 multica issue status MUL-124 cancelled --duplicate-of MUL-123。

时间线

issue get 给出任务现在的状态；issue timeline 按时间顺序列出状态、优先级、负责人、标题、日期的改动和运行结果，并混排评论，用来回答"什么时候进入 in_review""卡在当前状态多久了"：

multica issue timeline MUL-123 --action status_changed
multica issue timeline MUL-123 --activity-only --output json
multica issue timeline MUL-123 --since 2026-08-19T00:00:00Z

--activity-only 去掉评论，保留全部活动记录；--action 只返回指定的动作，可重复，并隐含 --activity-only。服务器读取的历史有上限，被截断时 stderr 会打印警告，这时不要据此推算停留时长。

读长评论线程

评论多的任务，智能体逐条读取很费 token。先扫一遍线程，再展开需要的那一个：

multica issue comment list MUL-123 --roots-only --summary --output json --compact
multica issue comment list MUL-123 --thread <comment-id> --tail 5 --output json --compact

--roots-only 只返回顶层评论，每条附带回复数和最近活动时间。
--summary 把每条内容截成预览。
--compact 只作用于 JSON 输出，去掉不带信息的字段（例如重复的 issue_id、空数组）。
--recent N 返回最近活跃的 N 个线程，每个线程带上全部回复，回复多时输出可能很长。
已解决的线程默认折叠成首条评论和结论，需要原文时加 --full。

列表也可以只取需要的字段：multica issue list --output json --fields id,identifier,title,status。筛选在 CLI 本地完成，减少的是输出和上下文，不是请求量。

唤醒

唤醒让智能体在某个事件发生、某个条件成立或到点时开始一次普通运行。完整规则见任务唤醒。

multica issue wakeup events
multica issue wakeup create MUL-123 --agent-id <agent-id> \
  --event comment.created --filter-actor-type member --filter-actor-id <user-id> \
  --instruction "对方回复后，按回复内容更新报价单"
multica issue wakeup create MUL-123 --agent-id <agent-id> \
  --kind every --every 1h --expires-in 72h \
  --instruction "检查供应商是否回信"
multica issue wakeup list MUL-123
multica issue wakeup runs MUL-123 <wakeup-id>

在终端里以成员身份创建时需要 --agent-id；智能体在自己的运行中创建时默认唤醒它自己。

智能体和 skill

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

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

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

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

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

环境变量和 MCP 配置常带有 token。命令行里直接写值会留在 shell 历史和 ps 输出中，用 -file 或 -stdin 形式传入：

multica agent create --name "运营助手" --runtime-id <runtime-id> \
  --custom-env-file ./agent-env.json \
  --mcp-config-file ./mcp.json \
  --custom-args '["--max-turns", "40"]'

multica agent env set <agent-id> --custom-env-stdin < agent-env.json
multica agent update <agent-id> --mcp-config-file ./mcp.json

--custom-env 系列只在 agent create 中可用。之后修改用 agent env set，它整体替换原有变量，值写成 **** 的键保留原值。
agent update --mcp-config null 清除 MCP 配置。
--custom-args 是 JSON 数组，排在启动参数的最后。选模型用 --model，部分工具会拒绝出现在自定义参数里的 --model。
谁能调用智能体用 --permission-mode：private 只有所有者，public_to 配合 --public-to-workspace 或 --public-to-member <user-id>。--visibility private|workspace 是旧写法，会映射到 --permission-mode；两者同时给出时以 --permission-mode 为准。

守护进程和运行时

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

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

multica daemon autostart enable
multica runtime usage <runtime-id> --days 30
multica runtime update <runtime-id> --target-version <version> --wait
multica runtime profile create --display-name "内部 Claude 封装" \
  --command-name ccms --runtime-type claude

daemon autostart 为当前 profile 登记开机自启，平台差异见开机自启。runtime usage 默认统计 90 天，--days 最多 365。runtime update 让那台电脑上的守护进程把 CLI 更新到指定版本，--wait 会一直等到更新结束。runtime profile create 用 --runtime-type 指定兼容的工具（旧的 --protocol-family 仍可用）；固定参数目前只能在网页端填写。

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

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

项目、工作区和自动化

multica project create --title "618 活动" --lead "李雷" \
  --repo https://github.com/acme/campaign-site
multica project resource add <project-id> --type github_repo \
  --url https://github.com/acme/brand-assets --default-branch-hint main

multica workspace create --name "运营部" --slug ops --issue-prefix OPS
multica workspace update --context-stdin < team-context.md

multica autopilot create --title "每周销售周报" --agent "运营助手" \
  --mode create_issue --issue-title-template "销售周报 {{date}}"
multica autopilot trigger-add <autopilot-id> --cron "0 9 * * 1" --timezone Asia/Shanghai

--lead 接受成员或智能体的名称。--default-branch-hint 只告诉智能体仓库的默认分支，不会切换分支。
工作区的 --context 会提供给工作区里的每个智能体。--slug 创建后不能修改；--issue-prefix 会转成大写，修改它会给所有现有任务重新编号，外部引用里的旧编号随之失效。
--issue-title-template 只替换 {{date}}（UTC，YYYY-MM-DD），其他 {{...}} 会被拒绝。定时触发器的 --timezone 默认 UTC。

命令概览

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

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

ID 和输出格式

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

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

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

multica issue list --output json
multica agent list --output json

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

Profile 与配置

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

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

multica issue list --profile staging

命名 profile 保存在 ~/.multica/profiles/<name>/config.json。查看当前值：

multica config show
multica config show --profile staging

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

命令参考

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

Core

命令	子命令	用途	关键 flag
`issue`	`list`	列出任务	`--status`、`--priority`、`--assignee`、`--project`、`--metadata`（可重复）、`--property`（可重复，`"名称=值"` 或 `"Score>=3"`、`"Due<2026-01-01"`、`"Notes~=text"` 这样的比较；`__none__` 匹配未设置）、`--limit`、`--offset`、`--sort`（支持 `property:<名称或 id>`）、`--full-id`、`--fields`（仅 JSON；逗号分隔，只输出这些字段）、`--resolve-properties`（仅 JSON；在保存的 id 旁附上属性、选项和成员名称）
	`get <id>`	查看单个任务	`--resolve-properties`（仅 JSON；在保存的 id 旁附上属性、选项和成员名称）
	`create`	创建任务	`--title`（必填）、`--description` / `--description-stdin` / `--description-file`、`--status`、`--priority`、`--assignee`、`--parent`、`--stage`、`--project`、`--start-date`、`--due-date`、`--attachment`（可重复）、`--property`（可重复）、`--allow-duplicate`（已有同名未关闭任务时仍创建）
	`update <id>`	更新任务字段	与 `create` 同类字段，另有 `--position`、`--no-start`、`--duplicate-of`
	`assign <id>`	指派或取消指派	`--to`（名称模糊匹配成员、智能体或小队）、`--to-id`、`--unassign`、`--no-start`
	`status <id> <status>`	修改状态	`--no-start`、`--duplicate-of`
	`reorder <id>`	在列内移动
	`search <query>`	搜索任务	`--limit`、`--include-closed`
	`children <id>`	按阶段分组列出子任务
	`pull-requests <id>`	列出关联的 PR
	`comment list/add/update/delete/resolve/unresolve`	管理评论	`add`：`--content` / `--content-stdin` / `--content-file`、`--parent`、`--attachment`；`update`：`--expected-revision`（必填）、`--content` / `--content-stdin` / `--content-file`；`list`：`--since`、`--thread`、`--tail`、`--recent`、`--roots-only`、`--summary`、`--compact`、`--full`
	`timeline <id>`	按时间列出活动记录和评论	`--action`（可重复）、`--activity-only`、`--since`、`--tail`
	`wakeup events/list/get/create/update/disable/trigger/delete/checkin/runs`	管理任务唤醒，详见任务唤醒	`create` / `update`：`--agent-id`、`--kind`（`event`、`at`、`every`、`cron`）、`--event`、`--at` / `--after`、`--every`、`--cron`、`--timezone`、`--until-*` 条件、`--expires-in` / `--expires-at`、`--instruction` / `--instruction-file`；`checkin`：`--note`
	`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-task <run-id>`	沿用原智能体和触发上下文，重跑指定运行	`--issue`, `--fresh`
	`cancel-task <task-id>`	取消进行中或排队中的运行	`--issue`
`project`	`list/get/create/update/delete`	管理项目	`create`：`--title`（必填）、`--lead`、`--status`、`--icon`、`--start-date`、`--due-date`、`--repo`（可重复）
	`status <id> <status>`	修改项目状态
	`resource list/add/update/remove`	管理项目附加资源	`--type`、`--url`、`--default-branch-hint`、`--ref`、`--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`、`--custom-env` / `--custom-env-file` / `--custom-env-stdin`（仅 `create`）、`--custom-args`、`--mcp-config` / `--mcp-config-file` / `--mcp-config-stdin`、`--permission-mode`、`--visibility`（旧写法）、`--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；每次读取都会记录）	`set`：`--custom-env` / `--custom-env-file` / `--custom-env-stdin`，整体替换，值为 `****` 的键保留原值
	`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`（均必填）、`--description`、`--issue-title-template`、`--project`、`--subscriber`（可重复）
	`trigger <id>`	手动触发一次
	`runs <id>`	查看运行历史
	`trigger-add/trigger-update/trigger-delete/trigger-rotate-url`	管理定时和 webhook 触发器	`trigger-add`：`--kind`（`schedule` 或 `webhook`）、`--cron`、`--timezone`（默认 UTC）、`--label`
`workspace`	`list/get/create/update/switch`	管理工作区；`switch` 设置当前 profile 的默认工作区	`create`：`--name`、`--slug`（均必填）、`--issue-prefix`、`--description`、`--context` / `--context-stdin`；`update` 可改除 slug 外的同类字段
	`mcp list/add/update/remove`	管理工作区的 MCP 服务库	写操作需要 owner/admin。这里添加的服务不会分配给任何 agent——用 `multica agent mcp add` 分配给某个 agent。`list` 只列出名称与 transport；存储的条目是只写的，任何角色都读不回。`--server-config-file` / `--server-config-stdin` 避免 token 进入 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`；均有对应的 `MULTICA_*` 环境变量
	`stop` / `status` / `restart`	停止、查看状态、重启（`restart` 与 `start` 同一套 flag）
	`logs`	查看守护进程日志	`--follow`、`--lines`
	`disk-usage`	查看本机磁盘占用	`--by-workspace`、`--by-task`、`--top`
	`autostart enable/disable/status`	登记或取消当前 profile 的开机自启	`status`：`--output`
`runtime`	`list/usage/activity/update/rename/delete`	查看和管理运行时	`usage`：`--days`（默认 90，最多 365）；`update`：`--target-version`（必填）、`--wait`；`delete`：`--cascade`（解绑绑定的智能体、保留其数据并取消其运行）
	`profile list/create/update/delete`	管理自定义运行时 profile	`create`：`--display-name`、`--command-name`（均必填）、`--runtime-type`（或旧的 `--protocol-family`）、`--description`；`update`：`--enabled`
	`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`）

在其他编码智能体里操作 Multica

如果你的工作大多发生在 Codex、Claude Code 或 Cursor 里，可以直接在那里操作 Multica，不必切回终端。Multica CLI skill 会教这些智能体安全地使用本页的命令：读任务和评论线程时少耗 token、通过文件写评论，以及正确处理 mention、状态变更和指派带来的副作用。

它完全通过你已认证的 CLI 运行，本身不授予任何权限，权限仍然只来自你的登录、所选 profile 和工作区。要求 CLI 版本不低于 v0.4.26。该仓库的 README 说明了 Claude Code 插件市场、Codex skill 安装器、Cursor 以及其他任何加载 Markdown 指令的工具的安装方式。

接下来

Multica CLI skill — 在 Codex、Claude Code 或 Cursor 里操作 Multica。
认证与令牌 — PAT 的创建、续期和吊销。
故障排查 — 命令报错和运行不开始的排查路径。
创建和配置智能体 — agent create 各字段的完整语义。

安装

第一次连接

选择工作区

常用任务操作

时间线

读长评论线程

唤醒

智能体和 skill

守护进程和运行时

项目、工作区和自动化

命令概览

ID 和输出格式

Profile 与配置

命令参考

Core

Runtime

Additional

在其他编码智能体里操作 Multica

接下来

本页目录

使用 CLI

安装Copy Anchor Link

第一次连接Copy Anchor Link

选择工作区Copy Anchor Link

常用任务操作Copy Anchor Link

时间线Copy Anchor Link

读长评论线程Copy Anchor Link

唤醒Copy Anchor Link

智能体和 skillCopy Anchor Link

守护进程和运行时Copy Anchor Link

项目、工作区和自动化Copy Anchor Link

命令概览Copy Anchor Link

ID 和输出格式Copy Anchor Link

Profile 与配置Copy Anchor Link

命令参考Copy Anchor Link

CoreCopy Anchor Link

RuntimeCopy Anchor Link

AdditionalCopy Anchor Link

在其他编码智能体里操作 MulticaCopy Anchor Link

接下来Copy Anchor Link

本页目录

安装

第一次连接

选择工作区

常用任务操作

时间线

读长评论线程

唤醒

智能体和 skill

守护进程和运行时

项目、工作区和自动化

命令概览

ID 和输出格式

Profile 与配置

命令参考

Core

Runtime

Additional

在其他编码智能体里操作 Multica

接下来