Command Line Interface
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.
mux run
Execute a one-off agent task:
1
# Basic usage - run in current directory
2
mux run "Fix the failing tests"
3
4
# Specify a directory
5
mux run --dir /path/to/project "Add authentication"
6
7
# Use SSH runtime
8
mux run --runtime "ssh user@myserver" "Deploy changes"
9
10
# Pipe instructions via stdin
11
echo "Add logging to all API endpoints" | mux run
12
13
# JSON output for scripts
14
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, or ssh <host> | local |
--mode <mode> | Agent mode: plan or exec | exec | |
--thinking <level> | -t | Thinking level: off, low, medium, high | medium |
--timeout <duration> | Timeout (e.g., 5m, 300s, 300000) | No timeout | |
--json | Output NDJSON for programmatic use | Off | |
--quiet | -q | Only output final result | Off |
--workspace-id <id> | Explicit workspace ID | Auto-generated | |
--config-root <path> | Mux config directory | ~/.mux |
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"
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
1
# Quick fix in current directory
2
mux run "Fix the TypeScript errors"
3
4
# Use a specific model with extended thinking
5
mux run -m anthropic:claude-sonnet-4-5 -t high "Optimize database queries"
6
7
# Run on remote server
8
mux run -r "ssh dev@staging.example.com" -d /app "Update dependencies"
9
10
# Scripted usage with timeout
11
mux run --json --timeout 5m "Generate API documentation" > output.jsonl
mux server
Start the HTTP/WebSocket server for remote access (e.g., from mobile devices):
1
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 .:
1
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:
1
mux --version
2
# v0.8.4 (abc123)