SUZENT / 文档
SUZENT 使用手册

Command line

Every suzent command you can run in a terminal, grouped by what it is for, with its most useful options.

此页面目前提供英文内容,中文翻译尚未完成。

Suzent installs a suzent command. Everything the desktop app does can also be started, checked, or changed from a terminal. Add --help to any command to see all of its options, for example suzent cron add --help.

OptionWhat it does
--version, -VShow the installed Suzent version.
--verbose, -vPrint detailed logs while the command runs.
--helpList commands, or the options of one command.

Most commands talk to a running Suzent. If one reports that it can't reach the server, start Suzent first with suzent start or the background service.

Running Suzent

CommandWhat it doesKey options
suzent startOpen the desktop app. It runs in the background, so your terminal is free again once it has started.--port
suzent stopStop a Suzent server running on this computer.--port
suzent restartStop Suzent, then start it again.--port
suzent serveRun the Suzent server in this terminal without the desktop window. Press Ctrl+C to stop it.--host, --port
suzent webOpen Suzent in your web browser. Uses the background service, and offers to install it if it isn't installed yet.--no-open, --install / --no-install, --foreground
suzent uiOpen only the desktop window, connecting to a server that is already running.--port, -p
suzent logsShow the log of a Suzent process started from the terminal.--desktop, --follow / -f, --lines / -n (default 200)
suzent doctorCheck that the tools Suzent needs are installed.

The default port is 25314. Set the SUZENT_PORT environment variable to change it for every command.

suzent web --foreground runs a one-off server in the terminal instead of the background service. Only then do --port and --host apply. Binding to anything other than 127.0.0.1 exposes Suzent to your network.

suzent logs --desktop shows the desktop app's log. Without an option, suzent logs shows the log of a server started in development mode. The background service keeps its own log; see suzent service logs below.

Background service

The background service keeps Suzent running after you quit, so scheduled tasks and chat apps keep working. The same switch is in Settings → Background Service. See Keep Suzent running in the background.

CommandWhat it doesKey options
suzent service installInstall the service, start it at sign-in, and start it now.--no-start to install without starting
suzent service uninstallStop and remove the service. Your data is kept.
suzent service startStart the installed service.
suzent service stopStop the service.
suzent service restartRestart the service.
suzent service statusShow whether it is installed, running, and ready, and how much memory it uses.--json
suzent service doctorDiagnose a service that won't start.
suzent service logsPrint where the service log file is.

Updating

See Updating Suzent for details.

CommandWhat it doesKey options
suzent check-updateCheck whether a newer release is available.--json, --cached
suzent updateUpdate Suzent and the desktop app to the latest release.--headless to update in the terminal without a window; --prefetch to only download it; --apply-staged to install a downloaded release silently
suzent auto-updateTurn silent background updates on or off.on, off, status
suzent upgradeSame as suzent update.--headless
suzent repairReinstall the current release, for example after an update was interrupted.--headless
suzent shortcutsCreate or repair the app's menu entry and shortcuts.--desktop / --no-desktop, --menu / --no-menu, --remove, --json

Chatting from the terminal

CommandWhat it doesKey options
suzent agent chat [message]Chat with your agent in the terminal. It continues your last terminal conversation.--new to start a new conversation
suzent agent currentShow which conversation the terminal is using.
suzent agent clearDetach the terminal from its conversation. The next chat starts a new one.
suzent agent statusCheck that the server is running, and show how many tools and connected devices it has.
suzent agent approve <id>Approve a pending tool request.
suzent agent deny <id>Deny a pending tool request.

Inside suzent agent chat, type / to see the slash commands available in the terminal. When the agent asks for permission, you are asked to allow it right there. Type exit or press Ctrl+C to leave.

Running one task without a terminal session

suzent run "<task>" sends one task, prints the reply, and exits. It never opens a chat prompt and never asks a question, so it suits scripts and scheduled jobs. If Suzent is not running, the command starts it and stops it again when the task is done.

OptionWhat it does
--cwd <folder>The folder the agent works in. Defaults to the folder you run the command from.
--model, -mThe model to use. It must be one of your enabled models. Defaults to your default model.
--permission-mode <mode>The permission mode for this run. Defaults to your saved mode.
--tools <names>A comma-separated list of the tools the agent may use for this run, for example ReadFileTool,RunCommandTool. Defaults to your saved tools. The agent gets exactly these tools and no others, so include the file tools (ReadFileTool, GlobTool, GrepTool) if it should read files.
--code-mode / --no-code-modeTurn code mode on or off for this run. Defaults to your saved setting.
--jsonPrint one JSON object when the task is done, with the reply, the token usage, and the conversation ID.
--keep-background-processesLeave commands the agent started in the background running after the run ends, for example a server the task asks for. Without it they stop with the run. Only applies when the command starts Suzent itself.
--startup-timeout <seconds>How long to wait for Suzent to start when the command has to start it.

Leave out the task to read it from standard input, for example cat task.md | suzent run.

Each run is saved as a conversation named [run] followed by the start of the task. Suzent does not rename it, so a run makes no extra model call for a title.

Nobody is there to approve tool requests during a run. A tool that would ask for permission is denied, and the command lists what it denied when it finishes. Pass --permission-mode full_access to let the agent use every tool without asking. Only do that in a folder and on a machine where you accept whatever the agent does.

The command exits with 0 when the task finished, 1 when the run failed, and 2 when the command was given a bad option.

Configuration

CommandWhat it does
suzent config showPrint the settings the running server reports.
suzent config get <key>Print one of those settings, for example suzent config get defaultModel.
suzent config set <key> <value>Change a saved preference, for example suzent config set sandbox_enabled true.

config set accepts the preferences the app saves: model, tools, memory_enabled, thinking, sandbox_enabled, sandbox_volumes, embedding_model, and extraction_model. Values such as true, 42, or a JSON list are converted automatically. For everything else, see Configuration files.

Skills

CommandWhat it does
suzent skill listList every skill Suzent found, with where it came from and whether it is on.
suzent skill toggle <name>Switch a skill on or off.
suzent skill reloadRescan the skill folders after adding or editing skills.

To install or write a skill, ask the agent. See Skills.

MCP servers

CommandWhat it doesKey options
suzent mcp listList MCP servers and whether each is enabled.
suzent mcp add <name>Add a server, either by URL or by the command that starts it.--url with --header / -H, or --command with --args and --env / -e
suzent mcp test <name>Check that a server answers, and list its tools.
suzent mcp enable <name>Enable a server.
suzent mcp disable <name>Disable a server.
suzent mcp remove <name>Remove a server.

For example:

suzent mcp add sqlite --command npx --args "-y,@modelcontextprotocol/server-sqlite,/db"
suzent mcp add docs --url https://example.com/mcp --header "Authorization: Bearer <token>"

--args takes a comma-separated list. --header and --env can be repeated. See MCP servers.

Scheduled tasks

The same tasks as in Settings → Automation. See Automation.

CommandWhat it doesKey options
suzent cron listList your scheduled tasks.--verbose / -v
suzent cron addCreate a task.See below
suzent cron edit <id>Change a task.--name, --cron, --prompt, --delivery, --model (none clears it)
suzent cron trigger <id>Run a task now.
suzent cron toggle <id>Switch a task on or off.
suzent cron remove <id>Delete a task.
suzent cron history <id>Show a task's recent runs.--limit / -l (default 10)
suzent cron statusShow whether the scheduler is running and how many tasks there are.
suzent cron webhook-url <id>Issue a new URL for a webhook task. The old URL stops working.
suzent cron install-presetsAdd or update the built-in notebook upkeep tasks.--activate-existing

suzent cron add needs a --name, a --prompt, and exactly one schedule:

OptionWhat it does
--cron, -cRun on a cron expression, such as "0 9 * * 1-5".
--everyRun every N minutes.
--atRun once at a time, such as "2026-01-02T09:00".
--webhookRun whenever the task's webhook URL is called. The URL is printed once.
--chatRun inside an existing conversation instead of the task's own chat.
--quietWith --chat, leave the conversation untouched when there is nothing to report.
--timezoneTime zone for a cron schedule, such as Asia/Shanghai.
--jitterSpread the start time over up to N random seconds.
--catch-upAfter downtime, skip missed runs (default) or run_once to make one up.
--delivery, -dannounce (default) shows the result in the app's status bar; none only keeps it in the task's history.
--model, -mUse a specific model for this task.
--inactiveCreate the task switched off.

Heartbeat

A heartbeat is a regular check-in inside one conversation. See Heartbeat.

CommandWhat it does
suzent heartbeat statusShow whether the heartbeat is on.
suzent heartbeat enableTurn it on.
suzent heartbeat disableTurn it off.
suzent heartbeat runRun a check-in now.
suzent heartbeat interval <minutes>Change how often it runs.

Each takes --chat <id> (or -c) to choose the conversation. Without it, the conversation your terminal is using is picked.

Memory

Check your memory files and draft fixes for them. See Memory.

CommandWhat it does
suzent memory lintList problems in MEMORY.md, user.md, persona.md, heartbeat.md and oversized notebook pages.
suzent memory cleanupWrite suggested fixes to a dated folder under the notebook's .state/cleanup/, with a README.md and a diff to review. Your files are not changed.

Chat app pairing

Handle requests from people asking to use your bot. See Access control & pairing.

CommandWhat it does
suzent pair listList pending requests, with their codes.
suzent pair approve <code>Approve a request.
suzent pair deny <code>Deny a request.

Devices

Pair other computers and phones, and let devices use each other. See Devices & other agents.

CommandWhat it doesKey options
suzent nodes discoverFind Suzent devices on your network and your Tailscale network.--timeout / -t (seconds, default 2)
suzent nodes listList everything this computer is linked to.
suzent nodes statusShow a summary of connected devices.
suzent nodes describe <device>Show what a device can do.
suzent nodes invoke <device> <command> [key=value ...]Run one of a device's commands, such as speaker.speak text="Hello".--params / -p (JSON), --timeout / -t
suzent nodes trigger <peer> <prompt>Ask another Suzent's agent to do something, and show its reply.--chat-id, --file (repeatable)
suzent nodes pendingList devices waiting for your approval.
suzent nodes approve <code>Approve a waiting device.
suzent nodes deny <code>Refuse a waiting device.
suzent nodes devicesList approved devices.
suzent nodes revoke <device_id>Remove an approved device. It must pair again to reconnect.
suzent nodes connect <url>Join another Suzent as a device, for example from a headless server.--name / -n
suzent nodes connectionsList the connections this computer started.
suzent nodes disconnect <url>Stop one of those connections.
suzent nodes hostOffer this computer's speaker and camera to Suzent, until you press Ctrl+C. The camera needs the Camera plugin (suzent plugin install camera).--name / -n, --capabilities / -c, --url

Editors (ACP)

CommandWhat it doesKey options
suzent acpLet an editor that supports the Agent Client Protocol, such as Zed, use Suzent as its agent. Your editor runs this command; you don't run it yourself.--permission-mode (defaults to auto, with default accepted as an alias. full_access skips classification.)
suzent acp --loginRequest editor access, approve the matching code under Settings → ACP Agents → Editor connections, then reconnect your editor.--client-name, --server-url

Editor pairing is required by default. Use --client-name matching your editor's reported name when signing in manually. --server-url selects a local backend; Suzent must already be running. --no-require-auth disables pairing and chat isolation for trusted local integrations. See editor setup.

See Use Suzent from your editor.

For developers

suzent start --dev and suzent restart --dev run Suzent from a source checkout in development mode, and suzent update --dev updates that checkout to the latest development version. suzent logs --frontend reads the development window's log, and suzent setup-build-tools installs the Windows build tools needed to compile the desktop app. See the development guide.

suzent chats read <chat_id> --offset 0 --limit 20 reads a page of visible messages without assistant reasoning traces. Use the returned next_offset to continue; null means there are no more messages.

suzent chats show <chat_id> prints a conversation from its file in ~/.suzent/chats/. suzent chats verify checks that the index in chats.db matches every conversation file in ~/.suzent/chats/, and lists any that do not. suzent chats rebuild-index rewrites every conversation in chats.db from those files; quit Suzent before running it. See chat storage.

在 GitHub 上编辑此页 ↗

本页内容