CLI 使用

DimAgent 只有一个 CLI 入口：dim。当前 npm 版本为 dimcode@0.3.16。

帮助

dim --help

概要

Usage: dim [command] [options]

Run without a command to open the interactive TUI.

Commands:
  acp                          Run ACP server over stdio
  exec [--trace[=/abs/path]] [--image <path>] [prompt] Run a one-shot prompt
  exec resume <id|--last>       Resume a session
  image <command>               Generate, edit, or enhance images
  video <command>               Generate, edit, or enhance videos
  speech <command>              Synthesize or transcribe speech
  music generate                Generate music
  audio generate                Generate audio
  asset generate                Generate 3D assets
  motion generate               Generate motion data
  realtime connect              Create a realtime connection
  ocr recognize <input>         Recognize text in images or PDFs
  modality <command>            Manage modality defaults and tasks
  session <command>             Manage sessions
  provider <command>            Manage providers
  model <command>               Manage models and subagent model preference
  remote <command>              Manage Remote host daemon
  auth <command>                Manage auth
  mcp <command>                 Manage MCP servers
  hooks <command>               Review and trust command hooks
  usage [--json]                Show DimAgent plan usage
  upgrade                       Upgrade to the latest version
  update                        Alias for upgrade
  version                       Print version
  help                          Print usage

Interactive TUI

dim

工具审批在 TUI 内通过 /approvals 或 Settings 设置。模型、MCP、插件分别用 /models、/mcp、/plugins 配置。

权限、审批与 Sandbox

这三项控制不同的边界：

入口	控制内容	可选值或位置
`/approvals`	当前 session 遇到待审批工具时由谁决定	`auto`：全部自动放行；`approve-for-me`：Agent 自动审核，无法安全判断时询问用户；`normal`：读取类工具自动执行，写入和命令类工具询问用户
`/settings` → Sandbox	工具进程的文件系统边界；CLI 的网络访问默认保持 unrestricted	`workspace-write`、`read-only`、`off`
`/settings` → Exec command 权限	具体 shell command 的默认动作与 matcher 规则	`ask`、`allow`、`deny`；保存到 `~/.dimcode/v2/permissions.json`

/approvals 不接收命令参数，它会打开选择器。审批模式、Sandbox 和 Exec command 规则独立生效；Sandbox 拒绝的访问不会因为审批模式是 auto 而放行。

One-shot Prompt (`dim exec`)

dim exec 面向脚本和 CI，输出写到 stdout。one-shot 默认使用 --policy full-access。

# Basic usage
dim exec "Summarize this repo and propose next steps"

# Full access (default for one-shot)
dim exec --policy full-access "hello"

# Safer policies
dim exec --policy workspace-write "Run a focused code review"
dim exec --policy read-only "Review this repo without making changes"

# With verification and one repair pass
dim exec --verify "pnpm test" --repair-attempts 1 "Find the bug and fix it"

# With trace output
dim exec --trace "Find the bug and fix it"
dim exec --trace=/abs/path/to/traces "Find the bug and fix it"

# With image input
dim exec --image screenshot.png "Describe this UI"

# Read from stdin
echo "Review this code" | dim exec --stdin

# JSONL event stream
dim exec --json "Summarize this repo"

# Resume a session
dim exec resume <session-id> "Continue the work"
dim exec resume --last "Continue the work"

Notes:

--policy 的可用值是 read-only、workspace-write、full-access。
新建的 one-shot session 会自动处理 ask 权限请求；read-only 与显式 deny 仍会阻止对应动作。Resume 保留原 session 的权限设置。
--allowed-tools <a,b> 追加 allow 规则；--disallowed-tools <a,b> 追加 deny 规则，并优先于 allow。
--mode agent|plan|goal 选择运行模式，默认是 agent。
--provider <id> 与 --model <id> 为本次 run 指定模型。
--tools <a,b> 限制可用工具；--mcp-server <id> 暴露指定 MCP server。
--reasoning-effort <effort> 在当前模型支持时设置本次 run 的 reasoning。
--session-id <id> 载入一个已存在的 session；不存在时返回错误。

Headless 权限参数

当前 CLI 没有 --permission 参数。dim exec 使用 --policy 选择权限预设，再用 tool 规则覆盖预设：

预设	文件系统	网络 / 进程	默认 tool 规则
`read-only`	只读	deny / deny	允许 `read`；写入和命令执行被能力边界阻止
`workspace-write`	工作区可写	ask / ask	允许 `read`、`write`、`edit`、`exec(git *)`；其他 `exec` 为 ask
`full-access`	完全访问	allow / allow	one-shot 默认值；不等待人工审批

规则合并顺序是 preset → --allowed-tools → --disallowed-tools，因此 deny 最终生效。Tool allow 规则不能越过 preset 的文件、网络或进程能力边界。

# Read-only review
dim exec --policy read-only "Review this repository"

# Workspace writes, but block shell execution explicitly
dim exec --policy workspace-write --disallowed-tools exec "Update the docs"

# Only expose selected tools; this controls availability, not approval
dim exec --policy read-only --tools read,glob,grep "Audit the code"

`dim exec` 参数参考

输入与输出：

参数	适用范围	行为
`<prompt>`	one-shot	位置参数；多个 token 会以空格连接
`--stdin`	one-shot	从 stdin 读取输入；同时传 prompt 时会把 stdin 追加到 prompt
`-`	one-shot	把 stdin 作为完整 prompt
`--image <path>`	one-shot、resume	附加一个本地 `png`、`jpg`、`jpeg`、`webp` 或 `gif` 文件
`--json`	one-shot、resume	stdout 输出 JSONL event stream
`--trace[=/absolute/path]`	所有 `exec` 模式	写入 trace；自定义目录必须用绝对路径和 `=` 形式
`--no-hooks`	所有 `exec` 模式	当前 CLI 进程不加载 command hooks

Session 与执行：

参数	适用范围	行为
`--mode <agent	plan	goal>`
`--session-id <id>`	one-shot 入口	载入已有 session 后执行 prompt；保留该 session 的权限与模型
`exec resume <id> <prompt>`	resume	恢复指定 session
`exec resume --last <prompt>`	resume	恢复最近更新的 session
`--reasoning-effort <effort>`	one-shot、resume	可用值：`none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`；仅在模型支持时生效
`--rpc`	RPC	启动 stdin/stdout JSONL RPC；默认 policy 是 `read-only`，权限请求由 `permission_response` 回复

模型、prompt 与工具：

参数	适用范围	行为
`--provider <id>`	新 one-shot session	指定 provider
`--model <id>`	新 one-shot session	指定 model
`--system-prompt <text>`	one-shot	替换完整 system prompt
`--append-system-prompt <text>`	one-shot	在默认 system prompt 后追加文本
`--mcp-server <a,b>`	one-shot	只向 run 暴露指定 MCP server
`--tools <a,b>`	one-shot	只向 run 暴露指定工具；未知工具直接报错

权限与验收：

参数	适用范围	行为
`--policy <preset>`	新 one-shot session、RPC	选择 `read-only`、`workspace-write` 或 `full-access`；one-shot 默认 `full-access`，RPC 默认 `read-only`
`--allowed-tools <a,b>`	新 one-shot session、RPC	在 preset 上追加 allow tool 规则
`--disallowed-tools <a,b>`	新 one-shot session、RPC	追加 deny tool 规则，并覆盖同名 allow
`--verify <command>`	one-shot、resume	Agent 完成后运行验收命令；可重复，按声明顺序执行
`--repair-attempts <count>`	one-shot、resume	验收失败后的最大自动修复轮数，默认 `0`

exec resume 和 --session-id 都使用已有 session 的权限。传入 --policy、--allowed-tools、--disallowed-tools、--provider 或 --model 不会改写已有 session；需要新权限时请创建新的 one-shot session。

`dim auth`

管理认证。

dim auth login [--provider dimcode-api-oauth|openai-codex] [--email <email>]
dim auth login --device-login [--provider dimcode-api-oauth] [--email <email>]
dim auth login --provider <id> --api-key <key>
dim auth logout [--provider <id>]
dim auth refresh
dim auth status

子命令：

login：通过浏览器 OAuth、设备 OAuth 或 API key 认证。
logout：删除已保存的凭据。
refresh：刷新保存的 OAuth token。
status：检查认证状态。

`dim session`

管理会话。

dim session list [--all]
dim session show <id>
dim session delete <id>
dim session export <id>
dim session rename <id> <name>
dim session clean [--older-than <days>] [--keep-last <n>] [--dry-run]

子命令：

list：列出会话（默认当前 cwd，--all 列出全部）。
show：显示会话详情。
delete：删除会话。
export：导出会话为 JSON。
rename：重命名会话。
clean：清理旧会话（--dry-run 预览）。

`dim provider`

管理提供方。

dim provider list [--json]
dim provider get <id> [--json]
dim provider add <id> [--api-key <key>] [--base-url <url>] [--model <model>] [--name <name>] [--adapter <adapter>] [--user-agent <value>] [--enabled|--disabled]
dim provider update <id> [--api-key <key>] [--base-url <url>] [--model <model>] [--name <name>] [--adapter <adapter>] [--user-agent <value>|--clear-user-agent] [--enabled|--disabled]
dim provider remove <id>
dim provider enable <id>
dim provider disable <id>
dim provider disconnect <id>
dim provider test <id> [--json]
dim provider switch <id> [--model <model>]

子命令：

list：列出已配置的提供方。
get：显示提供方详情。
add：添加提供方。
update：更新提供方设置。
remove：删除提供方。
enable / disable：切换提供方可用状态，保留其配置。
disconnect：删除已保存的凭据并禁用提供方。
test：测试提供方连接。
switch：切换活跃提供方，并可同时指定默认模型。

`dim model`

管理模型与 subagent 模型偏好。

dim model list [--provider <id>] [--json]
dim model refresh <provider> [--json]
dim model subagent get [--json]
dim model subagent list [--json]
dim model subagent set --provider <providerId> --model <modelId> [--json]
dim model subagent clear [--json]

使用 dim provider switch <providerId> --model <modelId> 设置父 session 默认模型。dim model subagent set 只设置固定的 subagent 模型偏好；clear 会恢复跟随父 session。

`dim mcp`

管理 MCP 服务器。

dim mcp list [--json]
dim mcp get <name> [--json]
dim mcp add <name> [--scope user|project] [--force] -- <command> [args...]
dim mcp add <name> --command <cmd> [--args <comma-separated-args>] [--env <KEY=VALUE>] [--scope user|project] [--force]
dim mcp add --transport http <name> <url> [--header <KEY: VALUE>] [--scope user|project] [--force]
dim mcp add-json <name> '<json>' [--scope user|project] [--force]
dim mcp auth list [--json]
dim mcp auth <name> [--json]
dim mcp logout <name> [--json]
dim mcp remove <name> [--scope user|project] [--json]
dim mcp test <name> [--json]
dim mcp toggle <name> --enabled <true|false> [--scope user|project] [--json]

子命令：

list：列出合并后的 MCP 服务器、状态、scope、transport 和 warnings。
get：显示 MCP 服务器详情。
add：添加 stdio 或 HTTP MCP server，默认写入 user scope。
add-json：从单个 server JSON object 添加 MCP server。
auth / logout：管理 HTTP MCP server 的 OAuth 凭据。
remove：删除 MCP server；省略 --scope 时删除当前生效 scope。
test：临时连接 MCP server，发现工具后断开。
toggle：启用或禁用 MCP server；禁用后保留配置并从运行时工具集中移除。

示例：

dim mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .
dim mcp add --transport http remote https://example.com/mcp
dim mcp add --transport http remote https://example.com/mcp \
  --header 'Authorization: Bearer ${MCP_TOKEN}'
dim mcp add-json remote '{"type":"http","url":"https://example.com/mcp"}'

MCP 配置文件位于 ~/.dimcode/v2/mcp.json，项目级配置位于 <project>/.mcp.json。项目级同名 server 覆盖用户级 server。

其他 CLI 命令

dim image generate [--provider <provider> --model <model>] --prompt <prompt> (--out <path>|--out-dir <dir>)
dim image edit [--provider <provider> --model <model>] --prompt <prompt> --image <path> [--image <path> ...] (--out <path>|--out-dir <dir>)
dim image enhance [--provider <provider> --model <model>] --image <path> --operation <operation> (--out <path>|--out-dir <dir>)
dim video generate [--provider <provider> --model <model>] --prompt <prompt> (--out <path>|--out-dir <dir>)
dim video edit [--provider <provider> --model <model>] --video <path> --operation <operation> (--out <path>|--out-dir <dir>)
dim video enhance [--provider <provider> --model <model>] --video <path> --operation <operation> (--out <path>|--out-dir <dir>)
dim speech synthesize [--provider <provider> --model <model>] --text <text> (--out <path>|--out-dir <dir>)
dim speech transcribe [--provider <provider> --model <model>] --audio <path> (--out <path>|--out-dir <dir>)
dim music generate [--provider <provider> --model <model>] --prompt <prompt> (--out <path>|--out-dir <dir>)
dim audio generate [--provider <provider> --model <model>] --operation <video-to-audio|sound-effect> (--out <path>|--out-dir <dir>)
dim asset generate [--provider <provider> --model <model>] (--prompt <prompt>|--image <path>|--asset <path>) (--out <path>|--out-dir <dir>)
dim motion generate [--provider <provider> --model <model>] (--prompt <prompt>|--video <path>|--image <path>|--asset <path>) (--out <path>|--out-dir <dir>)
dim realtime connect --category <category> --input <audio|text|image|video> --output <audio|text|image|video|event>
dim ocr recognize <input> [--provider <provider> --model <model>] [--out-dir <dir>] [--timeout <ms>] [--output-mode <text|layout>] --json
dim modality list [--json]
dim modality get <capability> [--json]
dim modality set <capability> --provider <id> --model <id> [--json]
dim modality unset <capability> [--json]
dim modality task <list|status|wait|cancel> [task-id] [--json]
dim remote daemon [--socket <path>] [--state <path>] [--device-name <name>]
dim remote status [--socket <path>] [--json]
dim remote enable [--socket <path>] [--json]
dim remote disable [--socket <path>] [--json]
dim hooks [list] [--json]
dim hooks disable <index|hash-prefix> [--json]
dim hooks disable --all [--json]
dim hooks enable <index|hash-prefix> [--json]
dim hooks enable --all [--json]
dim export <session_id> [--json|--md] [--compacted] [--format <openai-chat|openai-responses|anthropic|gemini>] [--no-thinking] [--no-tools]

`dim acp`

启动 ACP server 模式，用于编辑器集成。

dim acp

见 ACP 页面。

`dim version`

输出版本与运行时信息。

dim version
dim --version
dim -v

该命令也会输出 npm 与 standalone binary 安装方式的升级诊断信息。

`dim usage`

查看当前登录 DimAgent 账号的套餐用量。

dim usage
dim usage --json

输出登录账号、可用模型数量、credits 用量进度条、窗口 token 用量与重置时间。
--json 以单行 JSON 输出原始用量数据。
需要先完成 DimAgent OAuth 登录；未登录时命令报错并提示运行 dim auth login。

`dim upgrade`

升级 standalone binary 安装。dim update 是 dim upgrade 的别名。

# Check for updates
dim upgrade --check

# Upgrade to latest
dim upgrade

# Quiet or background mode
dim upgrade --quiet
dim upgrade --background

# Import GoatAgent data
dim upgrade import-goatagent [--source <path>] [--target <path>] [--default-cwd <path>] [--backfill] [--force-reimport] [--json]

参数：

--check：检查更新并退出。
--quiet、--background：抑制输出，适合后台更新。

npm/pnpm/yarn/bun 安装方式使用包管理器升级：

npm install -g dimcode@latest

Auto-update

自动更新检查默认开启。

设置 DIMCODE_DISABLE_AUTOUPDATE=1 可禁用更新检查。
设置 DIMCODE_AUTOUPDATE=0 可禁用后台安装。
Standalone binary 更新元数据存放在 ~/.dimcode/dimcode/bin/binary-upgrade.json。

快捷键

Ctrl+P：命令面板
Enter：发送
Shift+Enter 或 Ctrl+J：换行
Ctrl+O：打开或关闭后台任务面板
Ctrl+C：输入框有内容时清空输入，输入框为空时退出

斜杠命令

命令	作用
`/new`	新建会话
`/sessions`	列出或切换会话
`/timeline`	跳转到某条用户消息
`/resume`	恢复暂停的队列
`/compact`	压缩对话
`/agent`	切换到 agent 模式
`/plan`	切换到 plan 模式
`/goal`	切换到 goal 模式
`/external-agents`	管理外部 agent（别名 `/agents`）
`/skills`	打开 skills 选择器
`/approvals`	工具审批（`auto` / `approve-for-me` / `normal`）
`/connect`	连接提供方，或添加自定义/本地提供方
`/models`	选择提供方与模型
`/mcp`	管理 MCP 连接器与高级设置
`/plugins`	管理 Serper Search 等插件
`/language`	切换界面语言
`/theme`	切换亮/暗主题
`/settings`	打开自定义提供方设置
`/exit`	退出

数据存储位置

DimAgent v2 默认把本地数据存放在 ~/.dimcode/v2/：

dimcode.sqlite：主存储数据库（会话、提供方等）
credentials.json：全局凭据
credentials/<providerId>.json：按提供方存储的凭据
mcp.json：MCP 服务器配置

使用 DIMCODE_HOME=/absolute/path 可迁移基础目录。

CLI 使用

帮助

概要

Interactive TUI

权限、审批与 Sandbox

One-shot Prompt (dim exec)

Headless 权限参数

dim exec 参数参考

dim auth

dim session

dim provider

dim model

dim mcp

其他 CLI 命令

dim acp

dim version

dim usage

dim upgrade

Auto-update

快捷键

斜杠命令

数据存储位置

One-shot Prompt (`dim exec`)

`dim exec` 参数参考

`dim auth`

`dim session`

`dim provider`

`dim model`

`dim mcp`

`dim acp`

`dim version`

`dim usage`

`dim upgrade`