CLI Usage

After startup, you enter the interactive CLI and can directly enter natural-language tasks. The prompt displays the current status in the form [模式][agent名] > , such as [plan][code] > .

Built-in Commands

Command	Description
/plan	Switch to plan mode (read-only exploration + plan proposal)
/interactive	Switch to interactive approval mode (default)
/auto	Switch to auto mode (no approval required, high risk)
/discuss	Switch to discuss mode (read-only conversation)
/mode	Show the current mode
/connect	Connect to LLM (select provider → key → refresh model list → reasoning effort)
/connect rm	Clear connection configuration (fall back to environment variables)
/providers	List configured LLM providers (▶ marks the active one)
/use <序号|id>	Switch the active provider
/rm <序号|id>	Delete the specified provider
/link	Enter the account onboarding wizard (Hub URL + email/phone number + password or SMS verification code)
/link <接入码> [Hub地址]	Use a one-time access code to connect the local node to the user center
/sessions	List saved sessions and select one to resume (after switching, echo the most recent messages)
/history	List user instructions in the current session
/model <id>	Switch the LLM model
/agent <name>	Switch agent (Prompt + optional model synchronization)
/agents	List all agents (current one highlighted)
/agent add <name> <prompt...>	Add a custom agent
/agent edit <name> <prompt...>	Modify the agent Prompt (the current agent hot-updates immediately)
/agent rm <name>	Delete an agent
/agent show [name]	Show agent details
/mcp	List MCP servers and connection status
/mcp add <name> stdio <cmd...>|http <url>	Add and connect an MCP server (tools are automatically injected)
/mcp rm|enable|disable|refresh [name]	Remove / enable / disable / refresh the tool list
/tools	List all tools (source, risk, disabled status)
/tool add <name> <cmd...>	Add a command tool (executes shell commands)
/tool rm|disable|enable <name>	Remove / disable / enable a tool
/clear	Clear the current session
quit / exit	Exit
reset	Reset the session
Type directly + press Enter during execution	Provide steering input for the current task (takes effect in the next iteration)
Press ESC twice during execution	Interrupt the current task

Common Task Examples

Simply enter natural language, for example:

> 帮我在当前目录初始化一个 TypeScript 项目
> 读一下 src/ 下的代码，指出潜在问题
> 把 logs/ 里所有 .json 文件重命名为 .json.bak
> 运行测试并修复失败的用例

When files need to be modified or commands executed, an approval card appears in interactive mode for you to confirm.

Run Modes

Mode	Behavior
discuss	Read-only; all writes and execution are prohibited
plan	Read-only; all writes and execution are prohibited; intended for plan proposals
interactive	Operations with side effects require user approval each time (default)
auto	All operations with side effects are allowed through (high risk; you bear the consequences yourself)

Approval Cards

In interactive mode, approval cards support:

• Y Allow once
• A Always allow this tool
• D Deny
• run_shell additionally supports C to always allow this command (per-command allowlist, safer than allowing the entire tool)

Steering During Execution (Supplemental Input)

During task execution, you can append instructions without waiting for completion: type text directly and press Enter. The message will be injected into the current task as a user message at the next iteration gap, and the agent will automatically incorporate this steering input when it continues execution.

To start a new task, first wait for the current task to finish or press ESC twice to interrupt it. (When an approval or question is pending (suspended), input still takes precedence as the approval response or question answer.)

Session Management

• /sessions lists saved sessions and lets you choose one to resume; after switching, recent messages are echoed, making it convenient to continue from a breakpoint.
• /clear clears the current session; reset resets the session state.
• /history lists user instructions in the current session for quickly reviewing context.

Multi-Provider Management

You can save multiple LLM connections (different vendors or different keys) and switch at any time:

/providers           # 列出全部供应商，▶ 为当前生效
/use 2               # 按序号切换（也可用 /use <id>）
/rm 3                # 删除某个供应商

Use /connect to add a new provider. Switching takes effect immediately without restarting.

CLI Subcommands

In addition to entering an interactive session directly with zqagent, the CLI has four subcommands:

zqagent serve [--port <n>] [--host <addr>] [--data-dir <dir>]   # 无界面常驻服务
zqagent link --hub <url> --username <邮箱/手机号> --password '<密码>'  # 账号接入（免重启）
zqagent link --hub <url> --code <接入码>                         # 一次性接入码接入（免重启）
zqagent rename <名称>                                            # 修改节点在 Hub 显示的名称
zqagent update [--status|--check|--now|--rollback]               # 查看/触发节点自动更新、回滚

zqagent also supports --resume <会话ID> to resume the previous session, and --debug to output startup diagnostic logs.

serve can also connect directly at startup: --hub <url> --enroll-code <码> --label <名称>, or using account mode --hub <url> --username <邮箱/手机号> --password <密码>.

For the Windows single-file executable, replace zqagent with zqagent.exe (use .\zqagent.exe if it is not in PATH):

zqagent.exe serve --port 8787 --data-dir "%APPDATA%\zqagent"
zqagent.exe link --hub https://hub.cd-zq.com --username you@example.com --password <密码>
zqagent.exe link --hub https://hub.cd-zq.com --code <接入码>

Running zqagent link without credential arguments enters the interactive wizard; the password can also be provided via ZQAGENT_HUB_PASSWORD.

On Windows, link also automatically discovers the node service installed by the desktop client, so --data-dir is generally not needed; you only need to specify it explicitly when a scheduled task has been manually configured and the data directory is not in the default location.

See Starting a Node for details.

Startup Diagnostics (--debug)

When encountering issues such as “exits immediately on startup with no console output,” enable diagnostics with --debug:

zqagent --debug              # 单文件可执行程序（macOS / Linux）
node bin/zqagent --debug     # npm 安装的入口

zqagent.exe --debug          :: Windows 单文件
set ZQAGENT_DEBUG=1          :: Windows cmd，等价写法

export ZQAGENT_DEBUG=1       # bash/zsh

Diagnostic logs are synchronously written to disk (bypassing stdout buffering, so they will not be lost even if the process crashes or exits immediately) and are also echoed to stderr. The log path is resolved in the following order:

Environment Variable	Meaning
ZQAGENT_DEBUG_LOG	Full path to the log file (preferred)
ZQAGENT_DEBUG_DIR	Log directory; the file name is fixed as zqagent-debug.log
Neither set	zqagent-debug.log under the system temporary directory (os.tmpdir())

Logs include an environment snapshot, each startup stage, and crash stacks (for credentials such as OPENAI_API_KEY, only “whether set + length” is recorded; plaintext is not printed). The line where the log stops is the failure point. Disabling --debug turns it off completely: no files are written and no handlers are registered.

Control Probes: Identifying the Failing Layer

A single-file artifact = the official node base + the injected SEA blob + the business code inside it. When it exits immediately on startup, separating the three layers with minimal samples first is much faster than guessing at the business code:

Sample	Generation Method	Meaning if It Fails to Run
_node-base-<ver>-<platform>-<arch>	Official node, zero modifications	Blocked at the OS/security software/loader level; unrelated to packaging
_sea-minimal-probe-<platform>-<arch>	Minimal SEA probe, useCodeCache: false	SEA injection or loading failed (check the exit code, e.g. 0xC0000005)
_sea-cc-probe-<platform>-<arch>	Same as above but useCodeCache: true	Cross-build included the build machine's V8 code cache
zqagent-windows-x64.exe	Real artifact	If the first three all work, the problem is in business code initialization; continue with --debug

pnpm run probes:sea                                   # win32-x64（默认）
pnpm run probes:sea -- --arch arm64                   # win32-arm64
pnpm run probes:sea -- --platform linux --arch x64    # 在 Linux 上生成 linux 探针（本机可跑）
pnpm run probes:sea -- --platform darwin --arch arm64 # 在 macOS 上生成 macos 探针（本机可跑）

In addition to printing to stdout, the probe also writes zqagent-probe.log to the temporary directory—if it happens that “the console shows no output,” the on-disk log can still prove whether the JS actually executed.

The sha256 of the injected artifact changes with every build (the blob records the absolute path of the main script on the build machine), so only the hash of the base _node-base-* is used as evidence of “whether the file is complete/consistent.”

Notes for generating/using on macOS: SEA requires Node ≥ 20; before injecting a darwin artifact, you must first run codesign --remove-signature, and after injection run codesign --sign - --force for ad-hoc signing (the script handles this automatically when generating the macOS probe locally); the arm64 kernel refuses to run unsigned binaries. Generating artifacts for Windows, by contrast, is pure cross-assembly (postject only writes files and does not execute them), so a .exe can be produced directly on macOS/Linux.

On Windows, put the entire set of files in the same directory and run release/cli/diagnose.cmd directly: it executes node -e, the two probes, and zqagent --debug in sequence, prints the exit code of each sample, and outputs the diagnostic log and the probe's on-disk log; copy the full screen of text back to pinpoint the issue.

Next Steps

• Built-in Tools
• Agent Mechanism
• MCP and Tool Management