Headless CLI

zagens 是 Zagens 的无图形界面命令行，与桌面应用共用同一 Agent runtime（桌面嵌入的二进制名为 zagens-runtime，HTTP 契约一致）。适合脚本、CI、远程服务器，以及 macOS / Linux 上暂无桌面包时的主力入口。

安装步骤见官网安装指引的 CLI 安装 区块。

与桌面的关系

	桌面（Tauri）	CLI `zagens`
界面	WebView + 侧栏、diff、回放	终端输出
平台	Windows 10/11 x64	Windows / macOS / Linux
配置	`~/.zagens/config.toml`	同左
引擎	本机 sidecar	进程内直接运行 runtime

二者可并存：桌面负责日常交互，CLI 负责自动化与流水线。

安装与验证

# crates.io（需 Rust stable）
cargo install zagens-cli --bin zagens --locked

# 或从 GitHub Releases 下载预编译包
# https://github.com/didclawapp-ai/zagens/releases
# Windows: zagens-x86_64-pc-windows-msvc.exe

zagens --version
zagens doctor

配置 API Key

任选其一：

zagens login                    # 写入 ~/.zagens/config.toml
export DEEPSEEK_API_KEY=sk-...  # 环境变量（会话级）

在 ~/.zagens/config.toml 中也可直接设置 api_key、base_url、default_text_model 等 — 字段说明见产品仓 config.example.toml。

项目级覆盖：在工作区放置 .zagens/config.toml（默认加载；可用 --no-project-config 跳过）。

快速上手

cd /path/to/your-repo

# 只读问答（无工具）
zagens exec "用三条要点总结 README.md"

# Agent 模式：工具 + shell（自动审批，适合可信 CI）
zagens exec "运行 cargo test -p mycrate" --auto

# 机器可读输出（脚本解析）
zagens exec "列出 src/ 下主要模块" --json

# 指定工作区（默认当前目录）
zagens -w /path/to/repo exec "…"

全局常用标志：

标志	作用
`-w, --workspace`	工作区根目录
`--config`	指定 config.toml
`--profile`	配置 profile 名
`-v, --verbose`	详细日志
`--enable` / `--disable`	临时开关 feature 标志

命令一览

命令	用途
`zagens doctor`	环境与配置诊断（`--json` 跳过实时 API 探测）
`zagens login` / `logout`	保存 / 删除 API Key
`zagens models`	列出当前端点可用模型（`--json`）
`zagens exec`	单次非交互 prompt（`--auto` 启用工具链）
`zagens review`	对 git diff 做代码审查（`--staged` / `--base`）
`zagens apply`	应用 patch 文件或 stdin
`zagens setup`	初始化 MCP / 技能 / 工具目录模板
`zagens mcp …`	管理 MCP 配置（`list`、`tools`、`add` …）
`zagens serve --http`	启动本地 HTTP/SSE runtime API
`zagens sandbox …`	Windows：沙箱 setup / teardown / add-read-dir
`zagens sessions`	列出已保存会话
`zagens resume` / `fork`	恢复或分叉会话（`--last`）
`zagens completions`	生成 shell 补全
`zagens features list`	查看 feature 标志状态
`zagens eval`	离线评测 harness（无网络）

完整子命令以 zagens --help 与 zagens <cmd> --help 为准（随版本演进）。

`zagens exec`

zagens exec "重构 auth 模块并补测试" --auto
zagens exec "解释 config.rs" --model deepseek-v4-flash
zagens exec "生成变更摘要" --json > out.json

标志	说明
`--auto`	Agent 模式：工具 + shell，自动审批（等同全局 `--yolo` 工具面）
`--json`	结构化 JSON 输出，便于 CI 解析
`--model`	覆盖本次运行的文本模型

安全提示： --auto 会在策略允许下执行 shell 与写文件。Windows 上建议先完成 Windows 沙箱 setup；生产 CI 请收紧 sandbox_mode 与执行策略。

`zagens review` 与 `zagens apply`

# 审查相对 origin/main 的 diff
zagens review --base origin/main

# 仅审查已暂存变更
zagens review --staged

# 应用模型生成的 patch
zagens apply fix.patch
git apply -p0 < fix.patch   # 或管道：… | zagens apply

review 使用与桌面相同的模型路由；可用 --max-chars 限制 diff 体积。

`zagens serve --http`

暴露与桌面 sidecar 相同的 HTTP/SSE runtime API（默认 127.0.0.1:7878）：

zagens serve --http --port 7878 --auth-token "$DEEPSEEK_RUNTIME_TOKEN"

要点	说明
当前版本	仅 `--http` 模式可用（`--mcp` / `--acp` 会报错退出）
绑定地址	默认 localhost；绑定 `0.0.0.0` 时务必设置 `--auth-token`
健康检查	启动后输出 `DS_PICK_READY` JSON（含端口），供桌面/测试探测

适合本地集成测试、自建编排器调用 /v1/threads 等接口。契约见产品仓 docs/tech/API_DESIGN.md。

`zagens setup` 与 MCP

zagens setup --all          # MCP 配置 + 技能 + 工具 + 插件模板
zagens setup --mcp          # 仅 ~/.zagens/mcp.json
zagens setup --skills       # ~/.zagens/skills 示例
zagens setup --status       # 只读状态，无网络

zagens mcp list
zagens mcp tools
zagens mcp validate

桌面 设置 → MCP 与 CLI 读写同一份 mcp.json。详见 MCP 服务器。

Windows：`zagens sandbox`

仅 Windows 有意义（与 Windows 沙箱文档对应）：

zagens sandbox setup              # Elevated provisioning（UAC）
zagens sandbox teardown           # 清理沙箱产物
zagens sandbox add-read-dir D:\extra\read\path
zagens sandbox poc deny-read      # 维护者 G0 探测（unelevated）

zagens sandbox run … 在 headless CLI 中尚未开放；日常 Agent shell 由 exec --auto 走 runtime 内沙箱路径。

会话与恢复

zagens sessions --limit 10
zagens resume <session-id>
zagens resume --last
zagens fork --last

与桌面 SQLite 线程存储共用数据目录（由 DEEPSEEK_RUNTIME_DIR / 默认 ~/.zagens 布局决定）。桌面会话恢复 UX 在 CLI 侧对应 resume / fork。

环境变量（常用）

变量	作用
`DEEPSEEK_API_KEY`	Provider API Key
`DEEPSEEK_RUNTIME_TOKEN`	`serve --http` 鉴权
`DEEPSEEK_CONFIG_PATH`	覆盖 config 路径
`DEEPSEEK_RUNTIME_DIR`	Runtime 数据目录

何时用 CLI / 何时用桌面

场景	建议
日常编码、diff、回放、审批 UI	桌面
CI 里跑审查 / 单条自动化任务	`zagens exec` / `review`
无 GUI 的 Linux 服务器	CLI + `serve --http`
Office 文档交付、预览	桌面 Office 模式
定时任务	桌面定时任务或 `serve --http` + 外部调度

限制与诚实边界

桌面包 目前仅 Windows；CLI 是三平台补齐方案。
zagens serve 当前仅 --http；勿依赖 --mcp / --acp 子模式。
全屏 TUI（zagens-tui）仍在开发，不在本页范围。
子命令与标志随版本更新 — 以安装的 zagens --help 为准。

相关：安装指引 · Windows 沙箱 · 执行策略 · MCP · 应用内更新