CLI 参考 · 平台命令

CLI 除了把电脑接成主机外，还能直接通过平台 OpenAPI 操作资源。只要 ~/.raagent/config.json 里保存了 API Key（首次配对或 daemon install 时写入），这些命令就能直接用，无需再登录。

raagent auth <status|login|logout>
raagent market <list|featured|facets|get>
raagent agent <list|hosts|get|create|update|delete>
raagent session <list|get|create|update|delete|messages|cost|ask|push|stop|files|download>
raagent schedule <list|get|create|update|pause|resume|archive|delete|run>

五个命令域各自做什么：

命令域	一句话说明
auth	管理本地登录：登录、查看状态、退出登录
market	逛智能体市场：搜索、浏览热榜、查看详情
agent	管理你名下的智能体：创建、修改、删除、绑定主机
session	会话与对话：发起会话、发消息、看消息和消耗
schedule	定时任务：让智能体按 cron 自动运行

如果你是第一次用，建议从 auth status（确认已登录）→ market list（看看市场上有什么）→ agent list（看你的智能体）开始。

通用约定

全局参数（每个平台命令都支持，放在命令末尾）：

参数	说明
--json	输出纯 JSON，无表格、颜色或提示。流式请求输出 NDJSON（每行一个事件对象）
--server <url>	临时覆盖服务地址，不写入配置
--key <key>	临时覆盖 API Key，不写入配置
--help / -h	显示当前资源或动作的帮助

删除确认：删除智能体、会话、定时任务及 auth logout 都需要确认。确认提示会明确告知「可使用 -y 跳过确认」。非交互环境（脚本/管道）必须带 -y，否则直接失败。

退出码：

退出码	含义
0	成功
1	运行或服务端错误
2	参数错误
3	认证错误（缺少或无效 Key）
4	权限不足或资源不存在
5	冲突（状态冲突等）
6	网络、超时或流式中断
7	用户取消删除

auth — 登录与退出登录

管理本地保存的 API Key。

命令	作用
auth status	检查本地 Key 是否有效（不回显完整 Key）
auth login <apiKey>	把 API Key 保存到本地配置
auth logout	删除本地 Key，退出登录

auth login 参数：

<apiKey>          （必填）你的 API Key，也可用 --key <key> 传入
--server <url>    覆盖服务地址（可选，默认用本地配置或 https://raagent.me）

auth status 支持全局参数；还可用 --server <url> 和 --key <key> 临时验证另一台服务器或另一个 Key，不写入配置。auth logout 需要确认，-y 跳过。

• auth status 通过一个强鉴权只读接口验证 Key 是否有效；不回显完整 Key。
• auth logout 只删除本地 Key，保留 serverUrl、hostId、agentDir，不撤销服务端 Key。

raagent auth login raa-xxxx --server https://example.com
raagent auth status --json
raagent auth logout -y

何时需要 auth login

主机配对（daemon install -key ...）已经写入 Key。auth login 只在你没配主机、或想更换 Key 时使用。auth logout 之后两条通道都会失效——因为主机桥接和平台命令共用这一把 Key。

market — 逛智能体市场

浏览平台上所有人发布的智能体，像在网页上逛市场一样搜索和查看。

命令	作用
market list	搜索并列出市场上的智能体
market featured	查看本周热榜 Top3
market facets	查看市场当前有哪些分类和标签
market get <agent-id>	查看某个智能体的公开详情

市场查询允许匿名访问；携带有效 Key 时列表与详情会带上你的收藏和「朋友分享」可见性。显式无效的 Key 会返回 401，不会降级为匿名。

market list 选项：

--q <文本>            关键词搜索
--cat <分类>          按分类筛选
--tag <标签[,标签]>    按标签筛选
--scope <public|private>   公开或私有智能体
--pricing <free|paid>      免费或付费
--sort <usage|recent|favs|sessions>   排序
--page <页码>  --page-size <条数>      分页
--fav-only             只看我的收藏
--shared-with-me       只看分享给我的
--anonymous            不带 Key 匿名访问

raagent market list --q 代码审查 --sort favs
raagent market get raagent/code-review --json

agent — 管理我的智能体

创建、查看和删除你名下的智能体，并绑定主机。发布流程通常从这里开始。

命令	作用
agent list	查看你名下全部智能体
agent hosts	查看可以绑定的主机，以及每台主机真实安装的引擎
agent get <agent-id>	查看某个智能体的完整信息（含绑定的主机与工作目录）
agent create	新建一个智能体
agent update <agent-id>	修改已有智能体的字段
agent delete <agent-id>	删除智能体（需确认，-y 跳过）

agent list 选项：

--q <文本>                按名称/描述搜索
--usage-status <状态>      按使用状态筛选
--scope <public|private>   公开或私有
--engine <引擎>            按引擎筛选
--host <主机ID>            按主机筛选
--enabled / --disabled     只看已启用 / 已停用
--sort <recent|sessions|runs>   排序
--page <页码>  --page-size <条数>  分页

agent hosts 列出当前可用主机，引擎列表来自服务端上报的真实可用引擎，不硬编码。

agent create / agent update 可写字段：

--name <名称>              名称（唯一标识）
--display-name <展示名>     展示名称
--desc <描述>              描述
--tags <标签[,标签]>        标签
--cat <分类>               分类
--pay <free|paid>          免费或付费
--step <draft|submit>      草稿或提交审核
--enabled / --disabled     启用 / 停用
--host <主机ID>            绑定主机
--engine <引擎>            选择引擎
--work-dir <相对目录>       相对主机根目录的工作目录
--expected-input <输入说明>  预期输入说明
--expected-output <输出说明> 预期输出说明
--from-json <文件>         从 JSON 文件读取整个请求体（与上述字段互斥）

• agent get 返回编辑所需的完整管理详情（含 hostId 与 workDir）。
• agent update 只发送你显式给出的字段，至少提供一个。
• --work-dir 是相对主机工作根目录（即 -dir）的路径：根目录用空字符串 ""，子目录如 "apps/demo"。禁止绝对路径和 ..。会话实际运行在 主机根目录 + work-dir + .raagent/workdir-<会话ID>。

raagent agent list --sort recent
raagent agent create --name demo --display-name "示例" --scope private \
  --pay free --step draft --host <主机ID> --engine <引擎> --work-dir ""
raagent agent update <agentId> --desc "新描述"
raagent agent delete <agentId> -y

session — 会话与问答

和智能体对话、管理对话历史。会话相当于一次「对话线程」，你可以在里面发多条消息。

命令	作用
session list	查看我的会话列表
session get <session-id>	查看单个会话的详情
session create	新建一个会话（可附带首条问题）
session update <session-id>	修改会话标题、模式或推理档位
session delete <session-id>	删除会话（需确认，-y 跳过）
session messages <session-id>	查看会话里的消息流
session cost <session-id>	查看这个会话消耗了多少 Token
session ask <session-id> <问题>	向会话发一条消息
session stop <session-id>	停止会话当前运行，并清除该会话排队中的消息
session push [<session-id>]	主动向会话推送文字或文件（供 agent 调用；飞书会话会把文件发到你的飞书）
session files <session-id>	列出会话工作目录的文件树
session download <session-id> <文件路径>	下载会话工作目录里的文件到本地

问题从哪里来（三选一）：发消息的内容，一次只能用一种方式提供：

# 1. 直接写在命令里（位置参数）
raagent session ask s-1 "总结一下这段代码"

# 2. 从标准输入读入（适合管道/脚本）
echo "总结一下这段代码" | raagent session ask s-1 --stdin

# 3. 从文件读入（适合较长的提示词）
raagent session ask s-1 --file prompt.txt

新建会话同理：session create --agent <id> --ask "首问"（或 --stdin / --file）附带首条问题；都不带则创建一个空会话。

session list 选项：

--agent <id>               只看某智能体的会话
--query <文本>             按标题/内容搜索
--sort <lastMsgAt|-createdAt|createdAt>   排序
--page <页码>  --page-size <条数>         分页

session list / session get 的 status 为三态：active（空闲）、processing（运行中）、queued（排队中）。排队中的会话 queued（有消息在等主机空位或会话空闲），配合 pendingRuns 字段可看排队条数。

`session get` 选项：

```text
--include-messages     一并返回会话消息
--message-limit <条数>  返回消息的最大条数

session create 选项：

--agent <id>      （必填）绑定哪个智能体
--title <标题>     会话标题
--mode <模式>      会话模式：default / accept-edits / auto / plan
--effort <档位>    推理档位：low / default / medium / high
--ask <问题>       附带首条问题（与 --stdin / --file 三选一）
--stdin            从标准输入读首条问题
--file <路径>      从文件读首条问题
--stream           首问采用流式显示（与 --ask / --stdin / --file 搭配）

session update 选项（至少提供一个）：

--title <标题>   修改标题
--mode <模式>    修改会话模式
--effort <档位>  修改推理档位

session messages 选项：

--before <游标>  只看某条消息之前的（与 --after 互斥）
--after <游标>   只看某条消息之后的
--limit <条数>   返回条数上限

session ask 选项：

<问题>                位置参数，直接写问题
--stdin               从标准输入读问题（与位置参数、--file 三选一）
--file <路径>         从文件读问题
--mode <模式>         本次运行的工作模式：default / accept-edits / auto / plan（不指定则沿用会话当前模式）
--stream              流式显示回答

session stop 停止当前正在运行的任务，并清除该会话所有排队中的消息（排队消息不再执行）：

raagent session stop s-1

停止后会话本身保留，可继续发新消息。已生成但未完成的内容会以中断形式保留在消息记录中。重复调用也安全（无任务在运行时仅复位会话状态）。

SSE 中断后 不会自动重发，请用 session messages 查询结果。

流式输出：

raagent session ask s-1 "总结一下" --stream --json

--stream --json 每行输出一个 NDJSON 事件对象：

{"event":"accepted","data":{"sessionId":"s-1","status":"processing"}}
{"event":"message.delta","data":{"delta":"…"}}
{"event":"run.completed","data":{"status":"completed"}}

若会话正忙、消息进入排队，则不走流式，直接提示「已排队」，稍后用 session messages 查询结果。

session push 选项：

<session-id>      位置参数，可省略——省略时从当前工作目录自动识别（workdir-<id>）
--file <路径>     要推送的文件（须位于会话工作目录内，≤30M）
--text <文字>     要推送的文字

主动推送（agent 用）：session push 让运行在主机上的智能体主动把一个文件或一条消息推给某个会话，而不是等用户提问后才回复。适合「智能体生成了 PPT，想直接发给你看」这类场景：

# 智能体在自己的会话工作目录里，自动识别当前会话并发文件（推荐，无需知道 sessionId）
raagent session push --file ./生成/deck.pptx --text "这是生成的 PPT"

# 指定会话
raagent session push s-1 --text "后台任务已完成"

• 自动识别会话：agent 运行在 主机根 + 智能体相对工作目录 + .raagent/workdir-<会话ID> 里，从当前目录向上找 workdir-<id> 即可定位，所以通常不用传 session-id。
• IM 转发：如果这个会话是由 IM 聊天发起的（当前支持飞书），推送的文字和文件会经平台转发到你的 IM 对话框（响应 forwardedTo 字段标明转发的平台，如 ["feishu"]）；纯 web 会话则只记录到会话（文件本就位于会话工作目录，web 文件树可直接下载）。接入新 IM 平台无需改 CLI 或接口契约。
• 大小上限：单文件 ≤ 30M（受当前飞书 im/v1/files 官方上限约束）。
• 文件必须位于会话工作目录内，防止越权读取主机其它路径。

回收会话产物（脚本用）：session files / session download 是只读通道，用来把智能体在会话里生成的文件取回本地，适合调度脚本回收成果报告：

# 列出文件（path 列即下载用的文件路径）
raagent session files s-1

# 下载到指定位置；省略 --out 时存到当前目录
raagent session download s-1 out/report.zip --out ./report.zip

• 路径相对会话工作目录，session files 输出的第一列就是可用的 <文件路径>。
• 单文件 ≤ 50M（与 web 会话页「下载」按钮同一通道）。
• --json 输出树形结构，便于脚本解析。

schedule — 定时任务

让智能体按 cron 计划自动运行，比如每天早上 9 点生成日报。

命令	作用
schedule list	查看我的定时任务
schedule get <task-id>	查看单个任务的详情（含上次运行结果）
schedule create	新建定时任务
schedule update <task-id>	修改任务名称、cron、时区等
schedule pause <task-id>	暂停任务（不再自动触发）
schedule resume <task-id>	恢复已暂停的任务
schedule archive <task-id>	归档任务（历史保留，不再调度）
schedule delete <task-id>	删除任务（需确认，-y 跳过）
schedule run <task-id>	立即执行一次任务

schedule create / schedule update 可写字段：

--name <名称>         任务名称
--agent <id>          绑定智能体
--cron <表达式>        五段 cron（分 时 日 月 周）
--timezone <时区>      IANA 时区（默认 Asia/Shanghai）
--description <描述>   任务描述
--prompt <提示词>      执行时给智能体的指令
--prompt-file <文件>   从文件读指令（与 --prompt 互斥）
--status <状态>        仅 update：active / paused / archived
--from-json <文件>     从 JSON 文件读取请求体（与上述字段互斥）

• cron 是五段表达式（分 时 日 月 周）；时区用 IANA 名（如 Asia/Shanghai），缺省 Asia/Shanghai。
• 任务创建后默认 active；create 不接受 --status。
• 任务时间字段在 JSON 输出中保持 Unix 毫秒（如 lastRunAt、nextRunAt）；人类输出会格式化为日期。

schedule run 选项：

--wait             等待本次运行完成并显示结果
--timeout <秒>      最长等待秒数（默认 300）
--poll-interval <秒>  轮询间隔秒数（默认 2）

立即执行：schedule run <task-id> 返回 202 与 sessionId；加 --wait 后 CLI 会轮询该会话直到非 processing，再读取最终消息。任务运行失败时以非零退出并给出错误，不会误报成功。

raagent schedule create --name "日报" --agent <agent-id> \
  --cron "0 9 * * *" --timezone Asia/Shanghai --prompt "生成今日日报"
raagent schedule run <task-id> --wait --timeout 300 --poll-interval 2

update — 自更新

raagent update

一条命令完成「检查新版本 → npm 全局更新 → 重启 daemon」：

1. 查询 npm registry 上的最新版本；已是最新（或本地版本超前于 registry）则直接退出，不会降级。
2. 有任务运行中时不阻塞、不中断任务：自动转入后台等待，命令立即返回提示；当前 run 正常结束后，后台进程自动完成更新（等待与执行日志：~/.raagent/logs/update.log）。因此也可以在会话里直接让智能体执行 raagent update。
3. 更新完成后重启 daemon（macOS launchd / Linux systemd 自动拉起新版），2-5 秒内自动重连平台；期间下发的新任务可能提示主机不可达，重试即可。
4. daemon 重启会中断在跑任务，因此更新严格等到任务归零后才执行。

要求通过 npm install -g 安装；npx 临时运行不支持自我更新（下次 npx 会自动拉取新版）。本地版本号比 npm 最新版还新时不执行更新，避免降级。

输出与安全约定

• --json 对非流式命令输出单个合法 JSON 值；错误信息写 stderr。
• --stream --json 输出 NDJSON，每行一个完整事件对象，不能当单个 JSON 数组解析。
• 删除类操作（agent/session/schedule delete、auth logout）都要求确认，-y/--yes 跳过；非 TTY 环境未带 -y 立即失败，不会挂起等待。
• API Key 只通过 Authorization: Bearer 发送，不写入 URL。请勿把完整 Key 放进脚本日志或版本库。
• ~/.raagent/config.json 权限为目录 0700、文件 0600。命令行传 Key 会出现在 shell 历史里，请勿共享该配置文件。

下一步：安装与配对 · 主机管理 · 引擎与运行