CLI

Run one-off agent tasks and durable workflows from the command line

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.

Mux provides a CLI for running one-off agent tasks without the desktop app. Unlike the interactive desktop experience, mux run normally executes a single request to completion and exits. The --goal option is an explicit exception: it starts a CLI Goal Run that may perform automatic continuations until the goal is complete or a limit is reached.

GitHub Actions Guide

Learn how to use mux run in CI/CD pipelines

Installation

The CLI is available via npm and can be run directly with npx:

# Run without installing
npx mux run "Fix the failing tests"

# Or install globally
npm install -g mux
mux run "Fix the failing tests"

Using npx mux is especially convenient for CI/CD pipelines where you don’t want to manage a global installation.

mux run

Execute a one-off agent task:

# Basic usage - run in current directory
npx mux run "Fix the failing tests"

# Specify a directory
mux run --dir /path/to/project "Add authentication"

# Use SSH runtime
mux run --runtime "ssh user@myserver" "Deploy changes"

# Pipe instructions via stdin
echo "Add logging to all API endpoints" | mux run

# JSON output for scripts
mux run --json "List all TypeScript files" | jq '.type'

Options

Option	Short	Description	Default
--dir <path>	-d	Project directory	Current directory
--model <model>	-m	Model to use (e.g., anthropic:claude-sonnet-4-5)	Default model
--runtime <runtime>	-r	Runtime: local, worktree, ssh <host>, or docker <image>	local
--mode <mode>		Agent mode: plan or exec	exec
--thinking <level>	-t	Thinking level: OFF, LOW, MED, HIGH, MAX, or 0–9 (model-relative, see Models)	MED
--budget <usd>	-b	Stop when session cost exceeds budget (USD)	No limit
--goal <objective>		Start a CLI Goal Run and continue until the persisted goal is complete or a limit stops it	Off
--goal-budget <n>		Goal budget ($5, 5.00, or 500c); separate from --budget	No limit
--goal-turns <n>		Maximum automatic goal continuation turns	No limit
--experiment <id>	-e	Enable experiment (repeatable)	None
--json		Output NDJSON for programmatic use	Off
--quiet	-q	Only output final result	Off

CLI Goal Runs

Use --goal when a task should keep going across automatic continuations until the agent marks the persisted goal complete:

# Goal text is also used as the initial message when no message/stdin is provided
mux run --goal "Fix the failing tests and verify the suite passes"

# Provide separate kickoff instructions while keeping the objective active
mux run --goal "Ship the migration safely" "Start by inspecting the schema and propose a plan"

# Bound automatic continuations with a goal-specific budget and turn cap
mux run --goal "Complete the refactor" --goal-budget 5.00 --goal-turns 10

A CLI Goal Run is intentionally not a strict alias for interactive /goal. It is ephemeral to the mux 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, Mux 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.

Exit codes for CLI Goal Runs:

Code	Meaning
0	Goal completed (unless the agent set a nonzero exit code)
1	Operational, model, or tool error
2	Session --budget exceeded
3	Goal stopped incomplete, including goal budget/turn limits
130	User interrupt

Runtimes

• local (default): Runs directly in the specified directory. Best for one-off tasks.
• worktree: Creates an isolated git worktree under ~/.mux/src. Useful for parallel work.
• ssh <host>: Runs on a remote machine via SSH. Example: --runtime "ssh [e-mail]"
• 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

# Goal run with automatic continuations
mux run --goal "Update dependencies, fix resulting tests, and verify the suite passes"

# Quick fix in current directory
mux run "Fix the TypeScript errors"

# Use a specific model with extended thinking
mux run -m anthropic:claude-sonnet-4-5 -t high "Optimize database queries"

# Run on remote server
mux run -r "ssh [e-mail]" -d /app "Update dependencies"

# Scripted usage with JSON output
mux run --json "Generate API documentation" > output.jsonl

# Limit spending to $2.00
mux run --budget 2.00 "Refactor the authentication module"

mux workflow

Run durable workflow definitions from the command line without opening the desktop app. Workflows are JavaScript files discovered from built-in definitions, global mux workflow directories, and trusted project .mux/workflows directories.

mux workflow is currently gated by the dynamic-workflows experiment. Pass -e dynamic-workflows on each command, or enable the experiment in settings. The initial CLI runner supports the local runtime only; worktree, SSH, Docker, and devcontainer workflow execution are blocked until their workflow/action isolation and cleanup semantics are implemented.

# List discovered workflows
mux workflow list -e dynamic-workflows

# Inspect a workflow and include its source
mux workflow show deep-review-workflow --source -e dynamic-workflows

# Run with positional text, mapped to { "input": "research workflow runners" }
mux workflow run deep-research "research workflow runners" -e dynamic-workflows

# Run with structured JSON args and machine-readable output
mux workflow run deep-review-workflow --args-json '{"base":"main"}' --json -e dynamic-workflows

Workflow commands

Command	Description
mux workflow list	List built-in, global, and trusted workflows
mux workflow show <name>	Show descriptor metadata; add --source for source
mux workflow run <name>	Run a workflow in the foreground

Workflow options

Option	Description
--dir <path> / -d	Project directory. When omitted, Mux uses the Git root for the current cwd.
--runtime <runtime> / -r	Runtime selection. Currently only local is supported for workflow runs.
--model <model> / -m	Model used by workflow-owned child agents.
--thinking <level> / -t	Thinking level used by workflow-owned child agents.
--experiment <id> / -e	Enable an experiment, such as dynamic-workflows.
--json	Emit the final workflow result as a JSON line on stdout.
--quiet / -q	Suppress progress output and print only the final report.
--verbose / -v	Show info-level logs while the workflow command runs.
--log-level <level>	Set log verbosity to error, warn, info, or debug.

Workflow arguments

Only one argument mode can be used per run:

Input mode	Workflow args value
No args	{}
Positional text	{ "input": "..." }
--arg key=value	Object with lightly coerced scalar values
--args-json '{"base":"main"}'	Exact JSON value
--args-file args.json	Exact JSON value read from a file
--args-stdin	Exact JSON value read from stdin

Project-local workflows are executable only after the project is trusted. If a matching .mux/workflows/<name>.js exists in an untrusted project, mux workflow run fails before executing repo-controlled workflow code.

mux server

Start the HTTP/WebSocket server for remote access (for example, from a phone or another machine):

mux server --host 0.0.0.0 --port 3000

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
• --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 mux 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 MUX_SERVER_ALLOW_HTTP_ORIGIN=1 to opt in.

Auth token precedence:

1. --no-auth
2. --auth-token
3. MUX_SERVER_AUTH_TOKEN
4. Auto-generated token

GitHub owner login for browser sessions is configured separately via MUX_SERVER_AUTH_GITHUB_OWNER or serverAuthGithubOwner in ~/.mux/config.json. See Server Access.

mux acp

Start the ACP (Agent-Client Protocol) stdio bridge used by editor integrations:

mux acp

Option	Description
--server-url <url>	URL of a running mux server
--auth-token <token>	Bearer token for authenticated server connections
--log-file <path>	Write ACP logs to a file instead of stderr

For editor-specific setup (Zed, Neovim, JetBrains), see the ACP Editor Integrations guide.

mux desktop

Launch the desktop app. This is automatically invoked when running the packaged app or via electron .:

mux desktop

Note: Requires Electron. When running mux with no arguments under Electron, the desktop app launches automatically.

mux --version

Print the version and git commit:

mux --version
# v0.8.4 (abc123)

Debug Environment Variables

These environment variables help diagnose issues with LLM requests and responses.

Variable	Purpose
MUX_DEBUG_LLM_REQUEST	Set to 1 to log the complete LLM request (system prompt, messages, tools, provider options) as formatted JSON to the debug logs. Useful for diagnosing prompt issues.

Example usage:

MUX_DEBUG_LLM_REQUEST=1 mux run "Hello world"

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