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.
mux provides a CLI for running one-off agent tasks without the desktop app. Unlike the interactive desktop experience, mux run executes a single request to completion and exits.

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

OptionShortDescriptionDefault
--dir <path>-dProject directoryCurrent directory
--model <model>-mModel to use (e.g., anthropic:claude-sonnet-4-5)Default model
--runtime <runtime>-rRuntime: local, worktree, ssh <host>, or docker <image>local
--mode <mode>Agent mode: plan or execexec
--thinking <level>-tThinking level: off, low, medium, highmedium
--budget <usd>-bStop when session cost exceeds budget (USD)No limit
--experiment <id>-eEnable experiment (repeatable)None
--jsonOutput NDJSON for programmatic useOff
--quiet-qOnly output final resultOff

​
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 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

# 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 dev@staging.example.com" -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 server

Start the HTTP/WebSocket server for remote access (e.g., from mobile devices): 
mux server --port 3000 --host 0.0.0.0
Options:
  • --host <host> - Host to bind to (default: localhost)
  • --port <port> - Port to bind to (default: 3000)
  • --auth-token <token> - Optional bearer token for authentication
  • --add-project <path> - Add and open project at the specified path

​
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.
VariablePurpose
MUX_DEBUG_LLM_REQUESTSet 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