> ## Documentation Index > Fetch the complete documentation index at: https://mux.coder.com/llms.txt > Use this file to discover all available pages before exploring further. # CLI > Run one-off agent tasks from the command line with `mux run` The CLI is designed for **automation and scripting** (CI/CD pipelines, batch processing, programmatic control). For interactive terminal experiences, consider tools like [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) 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. Learn how to use `mux run` in CI/CD pipelines ## Installation The CLI is available via npm and can be run directly with `npx`: ```bash theme={null} # 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: ```bash theme={null} # 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 ` | `-d` | Project directory | Current directory | | `--model ` | `-m` | Model to use (e.g., `anthropic:claude-sonnet-4-5`) | Default model | | `--runtime ` | `-r` | Runtime: `local`, `worktree`, `ssh `, or `docker ` | `local` | | `--mode ` | | Agent mode: `plan` or `exec` | `exec` | | `--thinking ` | `-t` | Thinking level: `OFF`, `LOW`, `MED`, `HIGH`, `MAX` | `MED` | | `--budget ` | `-b` | Stop when session cost exceeds budget (USD) | No limit | | `--experiment ` | `-e` | Enable experiment (repeatable) | None | | `--json` | | Output NDJSON for programmatic use | Off | | `--quiet` | `-q` | Only output final result | Off | ### 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 `**: Runs on a remote machine via SSH. Example: `--runtime "ssh user@myserver.com"` * **`docker `**: 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 ```bash theme={null} # 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): ```bash theme={null} mux server --port 3000 --host 0.0.0.0 ``` Options: * `--host ` - Host to bind to (default: `localhost`) * `--port ` - Port to bind to (default: `3000`) * `--auth-token ` - Optional bearer token for authentication * `--add-project ` - 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 .`: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} 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`