> ## Documentation Index
> Fetch the complete documentation index at: https://shux.coder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

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

<Note>
  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.
</Note>

Shux provides a CLI for running one-off agent tasks without the desktop app. Unlike the interactive desktop experience, `shux 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.

<Card title="GitHub Actions Guide" icon="github" href="/guides/github-actions">
  Learn how to use `shux run` in CI/CD pipelines
</Card>

<Note>
  Existing automation can continue invoking `mux`; the legacy package and binary forward to the same
  Shux CLI. New scripts should use `shux`.
</Note>

## Installation

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

```bash theme={null}
# Run without installing
npx @coder/shux run "Fix the failing tests"

# Or install globally
npm install -g @coder/shux
shux run "Fix the failing tests"
```

Using `npx @coder/shux` is especially convenient for CI/CD pipelines where you don't want to manage a global installation.

## `shux run`

Execute a one-off agent task:

```bash theme={null}
# Basic usage - run in current directory
npx @coder/shux run "Fix the failing tests"

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

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

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

# JSON output for scripts
shux 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](/config/models#thinking-levels)) | `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:

```bash theme={null}
# Goal text is also used as the initial message when no message/stdin is provided
shux run --goal "Fix the failing tests and verify the suite passes"

# Provide separate kickoff instructions while keeping the objective active
shux 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
shux 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 `shux 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, Shux 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 `~/.shux/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

```bash theme={null}
# Goal run with automatic continuations
shux run --goal "Update dependencies, fix resulting tests, and verify the suite passes"

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

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

# Run on remote server
shux run -r "ssh dev@staging.example.com" -d /app "Update dependencies"

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

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

## `shux 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. `shux wf` is a shorthand alias for `shux workflow`.

<Note>
  `shux workflow` is experimental. Invoking the command implicitly enables the `dynamic-workflows`
  experiment for that invocation only. The initial CLI runner supports the `local` runtime only;
  `worktree`, SSH, Docker, and devcontainer workflow execution are blocked until their workflow
  isolation and cleanup semantics are implemented.
</Note>

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.

```bash theme={null}
# Run a trusted local workflow file with explicit JSON args
shux workflow run ./workflows/research.js --args-json '{"topic":"workflow runners"}'

# Same as above, using the alias and machine-readable output
shux wf run ./workflows/research.js --args-json '{"topic":"workflow runners"}' --json
```

### Workflow commands

| Command                           | Description                                       |
| --------------------------------- | ------------------------------------------------- |
| `shux workflow run <script_path>` | Run an explicit workflow script in the foreground |

### Workflow options

| Option                       | Description                                                                  |
| ---------------------------- | ---------------------------------------------------------------------------- |
| `--dir <path>` / `-d`        | Project directory. When omitted, Shux 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 additional experiment for workflow-owned child agents.             |
| `--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

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:

| Input mode                      | Workflow args value                       |
| ------------------------------- | ----------------------------------------- |
| No args                         | `{}`                                      |
| `--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          |

Workspace-file workflow scripts are executable only after the project is trusted. If an explicit local `.js` script path points into an untrusted project, `shux workflow run` fails before executing repo-controlled workflow code. Linked git worktrees inherit trust from the main repository path. Grant trust headlessly with [`shux trust`](#shux-trust).

## `shux trust`

Trust gates all repo-controlled automation: project workflows, hooks, and `.mux` configuration. The desktop app records trust via Settings → Security; `shux trust` writes the same entry in `~/.shux/config.json` headlessly — no desktop app or server required, registering the project if it was never added to Shux. A running desktop instance picks the change up automatically.

```bash theme={null}
# Trust the project containing the current directory (git toplevel)
shux trust

# Trust an explicit directory
shux trust --dir /path/to/repo

# Revoke trust
shux trust --revoke

# Machine-readable output
shux trust --json
```

Run from a linked git worktree (for example a Shux 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.

## `shux server`

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

```bash theme={null}
shux 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 Shux 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 `SHUX_SERVER_ALLOW_HTTP_ORIGIN=1` to opt in.

Auth token precedence:

1. `--no-auth`
2. `--auth-token`
3. `SHUX_SERVER_AUTH_TOKEN`
4. Auto-generated token

GitHub owner login for browser sessions is configured separately via `SHUX_SERVER_AUTH_GITHUB_OWNER` or `serverAuthGithubOwner` in `~/.shux/config.json`. See [Server Access](/config/server-access).

## `shux acp`

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

```bash theme={null}
shux acp
```

| Option                 | Description                                       |
| ---------------------- | ------------------------------------------------- |
| `--server-url <url>`   | URL of a running shux 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](/integrations/acp) guide.

## `shux desktop`

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

```bash theme={null}
shux desktop
```

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

## `shux --version`

Print the version and git commit:

```bash theme={null}
shux --version
# v0.8.4 (abc123)
```

## Debug Environment Variables

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

| Variable                 | Purpose                                                                                                                                                                 |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SHUX_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}
SHUX_DEBUG_LLM_REQUEST=1 shux 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`