Skip to main content
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 provides a CLI for running one-off agent tasks without the desktop app. Unlike the interactive desktop experience, 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 pipelines
Existing 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 with npx:
Using 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:
A CLI Goal Run is intentionally not a strict alias for interactive /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 plain xum 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.
Use local workflow files for cheap CLI smoke tests. 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.
Run from a linked git worktree (for example a Xum workspace checkout), trust is recorded for the main repository path rather than the ephemeral worktree path. Review a repository before trusting it: trusted projects can execute repo-controlled code.

xum server

Start the HTTP/WebSocket server for remote access (for example, from a phone or another machine):
Options:
  • --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 forwards X-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 mode 0700 and 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>.lock in 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-server uses 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
Use --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:
  1. --no-auth
  2. --auth-token
  3. XUM_SERVER_AUTH_TOKEN
  4. Auto-generated token
GitHub owner login for browser sessions is configured separately via 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 .:
Note: Requires Electron. When running 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:
The output includes:
  • systemMessage: The full system prompt sent to the model
  • messages: All conversation messages in the request
  • tools: Tool definitions with descriptions and input schemas
  • providerOptions: Provider-specific options (thinking level, etc.)
  • mode, thinkingLevel, maxOutputTokens, toolPolicy