The CLI is designed for automation and scripting (CI/CD pipelines, batch processing,
programmatic control). For interactive terminal experiences, consider tools like Claude
Code or similar TUIs.
xum run normally executes a single request to completion and exits. Goals are the exception: --goal starts a CLI Goal Run, and a run whose agent creates a goal with set_goal adopts that goal. Both perform automatic continuations until the goal is complete or a limit is reached.
GitHub Actions Guide
Learn how to use
xum run in CI/CD pipelinesExisting automation can continue invoking
mux; the legacy package and binary forward to the same
Xum CLI. New scripts should use xum.Installation
The CLI is available via npm and can be run directly withnpx:
npx @coder/xum is especially convenient for CI/CD pipelines where you don’t want to manage a global installation.
xum run
Execute a one-off agent task:
Options
CLI Goal Runs
Use--goal when a task should keep going across automatic continuations until the agent marks the persisted goal complete:
/goal. It is ephemeral to the xum run process, does not apply interactive goal defaults, bypasses the interactive continuation cooldown, and exits successfully only when the persisted goal status is complete. If neither --goal-budget nor --goal-turns is provided, Xum warns that the goal is uncapped.
--budget remains the hard session spending limit in USD. --goal-budget is goal accounting, accepts forms like $5, 5.00, and 500c, and may allow a final budget-limit wrap-up turn. If the session --budget is exceeded, the run stops immediately.
Goals the agent creates
A plainxum run (without --goal) whose agent calls set_goal adopts that goal when the first turn ends. With --mode plan, it also adopts a goal that the agent sets in the execution turn that follows the auto-approved plan. From then on the run behaves like a CLI Goal Run: it drives the goal to completion and uses the exit codes below. The goal’s own budget and turn cap bound the extra spend, because set_goal requires at least one of them. A run whose agent never sets a goal still executes a single request.
With --json, adoption emits a goal-adopted event (goalId, objective, status, budgetCents, turnCap), followed by the same goal-continuing, goal-completed, or goal-incomplete events as --goal. The goal-not-continued event that earlier versions emitted no longer exists.
Exit codes for CLI Goal Runs:
Runtimes
local(default): Runs directly in the specified directory. Best for one-off tasks.worktree: Creates an isolated git worktree under~/.xum/src. Useful for parallel work.ssh <host>: Runs on a remote machine via SSH. Example:--runtime "ssh user@myserver.com"docker <image>: Runs in a Docker container. Example:--runtime "docker node:20"
Output Modes
- Default (TTY): Human-readable streaming with tool call formatting
--json: NDJSON streaming - each line is a JSON object with event data--quiet: Suppresses streaming output, only shows final assistant response
Examples
xum workflow
Run a durable workflow JavaScript file from the command line without opening the desktop app. Workflows are addressed by explicit script_path values; there is no workflow discovery, list, or show command. Skill-packaged workflows use skill://<skill-name>/<file.js>, and local workflow files use an explicit workspace-contained .js path. xum wf is a shorthand alias for xum workflow.
The CLI workflow runner supports the
local runtime only; worktree, SSH, Docker, and
devcontainer workflow execution are blocked until their workflow isolation and cleanup semantics
are implemented.skill:// paths run the packaged workflow they reference, which may require AI credentials or model budget.
Workflow commands
Workflow options
Workflow arguments
Workflows receive structured args. Positional prose is rejected; pass JSON, a JSON file/stdin payload, or explicit--arg key=value pairs instead.
Only one argument mode can be used per run:
Workspace-file workflow scripts are executable only after the project is trusted. If an explicit local
.js script path points into an untrusted project, xum workflow run fails before executing repo-controlled workflow code. Linked git worktrees inherit trust from the main repository path. Grant trust headlessly with xum trust.
xum trust
Trust gates all repo-controlled automation: project workflows, hooks, and .mux configuration. The desktop app records trust via Settings → Project trust; xum trust writes the same entry in ~/.xum/config.json headlessly — no desktop app or server required, registering the project if it was never added to Xum. A running desktop instance picks the change up automatically.
xum server
Start the HTTP/WebSocket server for remote access (for example, from a phone or another machine):
--host <host>- Host/interface to bind to (default:localhost)--port <port>- Port to bind to (default:3000)--auth-token <token>- Bearer token for HTTP/WS auth--no-auth- Disable authentication entirely--print-auth-token- Always print the auth token on startup--allow-http-origin- Accept HTTPS browser origins when a TLS-terminating proxy forwardsX-Forwarded-Proto=http--unix-socket <path>- Also listen on a Unix socket. The path must be absolute and at most 107 bytes on Linux (103 on macOS). Its folder is created with mode0700and must be owned by you, and no other user may be able to rename it (every folder above it must be yours or root’s, and not writable by others unless sticky like/tmp), so no other user can create the socket’s name. A stale socket from a crashed run is removed, under a lock (<path>.lockin the same folder), so two servers started at once on one path cannot remove each other’s socket. A socket that a running server still holds is not removed: the server refuses to start.make dev-serveruses it for the Vite proxy--ssh-host <host>- SSH hostname/alias used for editor deep links in browser mode--add-project <path>- Add and open project at the specified path
--allow-http-origin only when HTTPS is terminated by an upstream reverse proxy and Xum receives rewritten X-Forwarded-Proto=http headers. This compatibility mode is disabled by default. For non-CLI server starts (for example desktop/browser mode), set XUM_SERVER_ALLOW_HTTP_ORIGIN=1 to opt in.
Auth token precedence:
--no-auth--auth-tokenXUM_SERVER_AUTH_TOKEN- Auto-generated token
XUM_SERVER_AUTH_GITHUB_OWNER or serverAuthGithubOwner in ~/.xum/config.json. See Server Access.
xum acp
Start the ACP (Agent-Client Protocol) stdio bridge used by editor integrations:
For editor-specific setup (Zed, Neovim, JetBrains), see the
ACP Editor Integrations guide.
xum desktop
Launch the desktop app. This is automatically invoked when running the packaged app or via electron .:
xum with no arguments under Electron, the desktop app launches automatically.
xum --version
Print the version and git commit:
Debug Environment Variables
These environment variables help diagnose issues with LLM requests and responses.
Example usage:
systemMessage: The full system prompt sent to the modelmessages: All conversation messages in the requesttools: Tool definitions with descriptions and input schemasproviderOptions: Provider-specific options (thinking level, etc.)mode,thinkingLevel,maxOutputTokens,toolPolicy