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

# CLI Reference

> The full RemoteMux CLI surface — commands, groups, and common flows.

## Top-Level Commands

| Command          | What it does                                                        |
| ---------------- | ------------------------------------------------------------------- |
| `rmux login`     | Authenticate with the RemoteMux control plane.                      |
| `rmux auth`      | Inspect, switch, or clear stored hosted auth.                       |
| `rmux whoami`    | Show the current authenticated identity.                            |
| `rmux configure` | Write or inspect resolved config.                                   |
| `rmux aws-check` | Validate AWS BYOC setup.                                            |
| `rmux gcp-check` | Validate GCP BYOC setup.                                            |
| `rmux env new`   | Create an environment for the current directory.                    |
| `rmux env`       | Manage environments, secrets, and ports.                            |
| `rmux workspace` | Manage workspaces inside the current environment.                   |
| `rmux claude`    | Inspect, login, or sync Claude Code auth.                           |
| `rmux token`     | Create and manage service tokens.                                   |
| `rmux provider`  | Manage hosted provider connections.                                 |
| `rmux usage`     | Show usage for the active org/project scope on the current backend. |
| `rmux admin`     | Manage API keys and subscriptions (admin only).                     |
| `rmux update`    | Install the latest CLI release.                                     |
| `rmux version`   | Print the installed CLI version.                                    |

## Command Groups

### `auth`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
rmux auth status
rmux auth use oauth
rmux auth use api-key --token <api-key>
rmux auth clear
```

Stored hosted auth is explicit and single-mode: either an OAuth session or an API key. `RMUX_API_KEY` overrides the stored selection until you unset it. Project config is not a hosted auth source.

### `env`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
rmux env list               # list environments for current backend
rmux env status             # current environment details
rmux env sync               # resync local directory into environment
rmux env down               # stop compute, preserve state
rmux env destroy            # remove environment entirely
rmux env secrets ls         # list secrets
rmux env secrets set KEY    # set a secret (reads from stdin)
rmux env secrets rm KEY     # remove a secret
rmux env expose 3000        # expose a port, returns URL
rmux env ports              # list exposed ports
rmux env share 3000         # create a private preview share (Managed/E2B only)
rmux env shares 3000        # list preview shares for a port
rmux env unshare share_123  # revoke a preview share
```

### `workspace`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
rmux workspace attach                    # attach to main
rmux workspace attach server             # attach to named workspace
rmux workspace ls                        # list workspaces
rmux workspace new server                # create workspace
rmux workspace run bun test              # run command in main
rmux workspace run -w server bun dev     # run command in named workspace
rmux workspace logs server --follow      # tail workspace output
rmux workspace rm server                 # remove workspace
rmux workspace prune --prefix ci- --stale 2h --force
```

Editor commands (AWS and GCP only):

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
rmux workspace code main                 # open in VS Code
rmux workspace cursor server             # open in Cursor
rmux workspace editor main --vscode      # explicit editor flag
```

All workspace subcommands accept `--env <name-or-id>` to target an environment by name or ID instead of using the directory binding. The `RMUX_ENVIRONMENT` environment variable serves as a fallback.

### `claude`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
rmux claude status    # check local and remote Claude auth state
rmux claude login     # run Claude login, then sync to environment
rmux claude sync      # force sync from current local auth state
```

### `token`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
rmux token ls --org-id org_123
rmux token create --label "github-actions" --org-id org_123
rmux token create --label "github-actions" --project-id proj_123
```

Service tokens inherit the active hosted scope from config by default, and `--org-id` / `--project-id` let you override it per command.

### `admin`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
rmux admin keys ls
rmux admin keys create --label "Customer A" --plan starter
rmux admin subscription --key-id <key-id> --status active
```

Admin commands require a key with admin permissions.

## Common Flows

### First setup

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
rmux auth use oauth
rmux configure
rmux aws-check        # or rmux gcp-check
rmux env new
rmux workspace new main
```

### Daily work

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
rmux workspace attach
rmux workspace run bun test
rmux workspace code main       # AWS/GCP only
rmux env status
```

### Cleanup

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
rmux env down
rmux env destroy
```

## Terminal UX

`rmux env new` and `rmux workspace new main` show step-by-step progress during provisioning and sync. In an interactive terminal, press `d` to toggle low-level command details.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
rmux --help
rmux help workspace run
rmux env --help
```