# Mux CLI
Use the Mux CLI to manage your video assets, live streams, and more directly from the terminal.
The Mux CLI is a command-line interface for interacting with the Mux API, designed to provide a first-class development experience for working with Mux services locally. With the CLI, you can upload videos, manage live streams, generate signed URLs, query analytics data, and access Mux's video infrastructure without leaving your terminal.

## Installation

The Mux CLI can be installed via Homebrew, npm, a shell installer, or by downloading pre-built binaries.

### Homebrew (macOS)

```bash
brew install muxinc/tap/mux
```

### npm

Install globally to use the `mux` command anywhere:

```bash
npm install -g @mux/cli
```

Or run directly without installing using `npx`:

```bash
npx @mux/cli
```

### Shell installer

Run the install script to automatically download and set up the CLI:

```bash
curl -fsSL https://raw.githubusercontent.com/muxinc/cli/main/install.sh | bash
```

### Binary download

Platform-specific binaries are available for macOS (Apple Silicon and Intel) and Linux (x64 and arm64) from the [GitHub Releases page](https://github.com/muxinc/cli/releases). These are self-contained executables with no external dependencies.

## Shell completions

Enable tab completion for commands, subcommands, and options in your shell:

**Bash** (add to `~/.bashrc`):

```bash
source <(mux completions bash)
```

**Zsh** (add to `~/.zshrc`):

```bash
source <(mux completions zsh)
```

**Fish** (add to `~/.config/fish/config.fish`):

```bash
source (mux completions fish | psub)
```

Restart your shell or source the config file to activate completions.

## Authentication

The CLI requires Mux API credentials to interact with your account. You can get your Access Token ID and Secret Key from the [Mux Dashboard](https://dashboard.mux.com/settings/access-tokens).

### Interactive login

Run `mux login` to authenticate interactively:

```bash
mux login
```

You'll be prompted to enter your Access Token ID and Secret Key. Credentials are stored securely in `~/.config/mux/config.json` with owner-only file permissions.

### Using environment variables

The CLI can read credentials from a `.env` file or environment variables:

```bash
MUX_TOKEN_ID=your-token-id
MUX_TOKEN_SECRET=your-token-secret
```

Login from a `.env` file:

```bash
mux login --env-file .env
```

### Named environments

For managing multiple Mux accounts (production, staging, development), you can configure named environments:

```bash
mux login --name production
mux login --name staging --env-file .env.staging
```

The first environment you add becomes the default. Switch between environments:

```bash
mux env switch staging
mux env list
```

Remove an environment:

```bash
mux logout staging
```

## Common options

These options are available on most commands:

| Option | Description |
|--------|-------------|
| `--json` | Output raw JSON instead of pretty-printed format. Useful for scripting and piping to `jq`. |
| `--compact` | One-line-per-item output, grep-friendly. Available on `list` commands. |
| `--limit <n>` | Number of results to return (default: 25). Available on `list` commands. |
| `--page <n>` | Page number for pagination (default: 1). Available on `list` commands. |
| `-f, --force` | Skip confirmation prompts on destructive actions. |
| `--wait` | Poll until the resource is ready before returning. Available on `create` commands. |

## Webhook forwarding

Listen for Mux webhook events in real-time and forward them to your local development server. Events are stored locally for replay during development.

<Callout type="warning">
  CLI webhook commands are for **local development only** and provide **no delivery guarantees**. In production, you must configure a webhook endpoint in the [Mux Dashboard](https://dashboard.mux.com) that points to your server's webhook URL.
</Callout>

### `mux webhooks listen`

Connect to Mux's event stream and optionally forward events to a local URL.

```bash
# Listen and print events
mux webhooks listen

# Forward to local dev server
mux webhooks listen --forward-to http://localhost:3000/api/webhooks/mux
```

| Option | Description |
|--------|-------------|
| `--forward-to <url>` | POST received events to a local URL in real-time |
| `--json` | Output raw JSON per event |

When using `--forward-to`, the CLI displays a webhook signing secret and signs each forwarded request with a `mux-signature` header. Set `MUX_WEBHOOK_SECRET` in your app's environment to [verify these signatures](/docs/core/verify-webhook-signatures):

```typescript
const event = mux.webhooks.unwrap(body, headers, process.env.MUX_WEBHOOK_SECRET);
```

The signing secret is unique per environment and persisted between sessions, so you only need to configure it once.

### `mux webhooks events list`

List locally stored webhook events captured during `listen` sessions. The CLI stores the last 100 events.

```bash
mux webhooks events list
mux webhooks events list --limit 50
```

### `mux webhooks events replay [event-id]`

Replay stored webhook events. Useful for re-testing your webhook handler without creating new resources.

```bash
# Replay a specific event to your local server
mux webhooks events replay abc123-event-id --forward-to http://localhost:3000/api/webhooks/mux

# Replay all stored events
mux webhooks events replay --all --forward-to http://localhost:3000/api/webhooks/mux

# View event payload without forwarding
mux webhooks events replay abc123-event-id
```

| Option | Description |
|--------|-------------|
| `--forward-to <url>` | POST event(s) to a local URL |
| `--all` | Replay all stored events |
| `--json` | Output JSON instead of pretty format |

### `mux webhooks trigger <event-type>`

Send a synthetic webhook event to a local URL for testing. No API call is made — the payload is generated locally and signed with the per-environment signing secret.

```bash
# Send an example video.asset.ready event
mux webhooks trigger video.asset.ready --forward-to http://localhost:3000/api/webhooks/mux

# Send a live stream event
mux webhooks trigger video.live_stream.active --forward-to http://localhost:3000/api/webhooks/mux
```

| Option | Description |
|--------|-------------|
| `--forward-to <url>` | Local URL to POST the example event to (required) |
| `--json` | Output JSON instead of pretty format |

Run `mux webhooks trigger <invalid-type>` to see all supported event types.

## Commands

### Asset management

Create, list, update, and delete video assets.

```bash
# Create from URL
mux assets create --url https://example.com/video.mp4 --playback-policy public

# Upload local files (glob supported)
mux assets create --upload ./videos/*.mp4 --playback-policy public

# Create from JSON config file (for overlays, subtitles, multiple inputs)
mux assets create --file asset-config.json

# Wait for processing to complete
mux assets create --url https://example.com/video.mp4 --playback-policy public --wait

# List, get, update, delete
mux assets list
mux assets get <asset-id>
mux assets update <asset-id> --title "My Video" --passthrough "my-custom-id"
mux assets delete <asset-id>
```

The interactive asset manager opens a terminal UI (TUI) for browsing and managing your video library:

```bash
mux assets manage
```

<details>
  <summary>
    View all asset create options
  </summary>

  | Option | Description |
  |--------|-------------|
  | `--url <url>` | Video URL to ingest from the web |
  | `--upload <path>` | Local file(s) to upload (supports glob patterns like `*.mp4`) |
  | `--file, -f <path>` | JSON configuration file for complex asset creation |
  | `--playback-policy <policy>` | `public` or `signed` (repeatable) |
  | `--test` | Create test asset (watermarked, 10s limit, deleted after 24h) |
  | `--passthrough <string>` | User metadata (max 255 characters) |
  | `--static-renditions <resolution>` | e.g. `1080p`, `720p`, `highest`, `audio-only` (repeatable) |
  | `--video-quality <quality>` | `basic`, `plus`, or `premium` |
  | `--normalize-audio` | Normalize audio loudness level |
  | `-y, --yes` | Skip confirmation prompts |
</details>

<details>
  <summary>
    View all asset update options
  </summary>

  | Option | Description |
  |--------|-------------|
  | `--title <string>` | Set `meta.title` (max 512 characters) |
  | `--creator-id <string>` | Set `meta.creator_id` (max 128 characters) |
  | `--external-id <string>` | Set `meta.external_id` (max 128 characters) |
  | `--passthrough <string>` | Set `passthrough` (max 255 characters) |
</details>

<details>
  <summary>
    Asset sub-resources: playback IDs, static renditions, tracks
  </summary>

  #### Playback IDs

  Manage playback IDs on assets. Each asset can have multiple playback IDs with different policies.

  ```bash
  mux assets playback-ids list <asset-id>
  mux assets playback-ids create <asset-id> --policy signed
  mux assets playback-ids delete <asset-id> <playback-id>
  ```

  #### Static renditions

  Static renditions are downloadable MP4 versions of your video assets at specific resolutions.

  ```bash
  mux assets static-renditions list <asset-id>
  mux assets static-renditions create <asset-id> --resolution 1080p --wait
  mux assets static-renditions delete <asset-id> <rendition-id>
  ```

  Resolution options: `highest`, `audio-only`, `2160p`, `1440p`, `1080p`, `720p`, `540p`, `480p`, `360p`, `270p`

  #### Tracks

  Add text and audio tracks (subtitles, captions, audio) to video assets.

  ```bash
  # Add a subtitle track
  mux assets tracks create <asset-id> \
    --url https://example.com/subs.vtt \
    --type text \
    --language-code en \
    --text-type subtitles

  # Generate subtitles from an audio track
  mux assets tracks generate-subtitles <asset-id> <track-id> \
    --language-code en \
    --name "English (auto)"

  # Delete a track
  mux assets tracks delete <asset-id> <track-id>
  ```

  #### Other asset commands

  ```bash
  mux assets input-info <asset-id>                                      # view input file details
  mux assets update-master-access <asset-id> --master-access temporary  # enable master access
  ```
</details>

### Live stream management

Create and manage live streams for broadcasting via RTMP.

```bash
# Create a live stream
mux live create --playback-policy public

# Create with options
mux live create \
  --playback-policy public \
  --latency-mode low \
  --reconnect-window 60

# List, get, delete
mux live list
mux live get <live-stream-id>
mux live delete <live-stream-id>

# Stream lifecycle
mux live complete <live-stream-id>
mux live enable <live-stream-id>
mux live disable <live-stream-id>

# Reset stream key
mux live reset-stream-key <live-stream-id>
```

Once created, stream using:

* **RTMP URL:** `rtmp://global-live.mux.com/app`
* **Stream Key:** returned in the response

<details>
  <summary>
    View all live stream create options
  </summary>

  | Option | Description |
  |--------|-------------|
  | `--playback-policy <policy>` | `public` or `signed` (repeatable) |
  | `--new-asset-settings <settings>` | Auto-create asset from stream. Use `none` to disable, or JSON string |
  | `--reconnect-window <seconds>` | Reconnect timeout (default: 60) |
  | `--latency-mode <mode>` | `low`, `reduced`, or `standard` (default: `low`) |
  | `--test` | Create test stream (deleted after 24h) |
</details>

<details>
  <summary>
    View all live stream update options
  </summary>

  | Option | Description |
  |--------|-------------|
  | `--latency-mode <mode>` | `low`, `reduced`, or `standard` |
  | `--reconnect-window <seconds>` | Reconnect window (0-1800) |
  | `--max-continuous-duration <seconds>` | Max continuous duration (60-43200) |
  | `--passthrough <string>` | Passthrough metadata (max 255 characters) |
  | `--reconnect-slate-url <url>` | Image to display during reconnect |
  | `--use-slate-for-standard-latency` | Display slate for standard latency streams |
  | `--title <string>` | Title for the live stream |
</details>

<details>
  <summary>
    Live stream sub-resources: simulcast targets, subtitles, playback IDs
  </summary>

  #### Simulcast targets

  Restream a live stream to third-party platforms (e.g., YouTube, Twitch).

  ```bash
  mux live simulcast-targets create <stream-id> --url rtmp://live.twitch.tv/app --stream-key live_xxxxx
  mux live simulcast-targets get <stream-id> <target-id>
  mux live simulcast-targets delete <stream-id> <target-id>
  ```

  #### Embedded subtitles (CEA-608)

  ```bash
  mux live update-embedded-subtitles <stream-id> \
    --language-channel cc1 \
    --language-code en \
    --name "English CC"
  ```

  #### Generated subtitles (ASR)

  ```bash
  mux live update-generated-subtitles <stream-id> \
    --language-code en \
    --name "English (auto)"
  ```

  Use `--clear` on either command to remove subtitle settings.

  #### New asset static renditions

  Configure static renditions for assets automatically created from a live stream.

  ```bash
  mux live update-new-asset-static-renditions <stream-id> --resolution 1080p --resolution 720p
  mux live delete-new-asset-static-renditions <stream-id>
  ```

  #### Playback IDs

  ```bash
  mux live playback-ids list <stream-id>
  mux live playback-ids create <stream-id> --policy signed
  mux live playback-ids delete <stream-id> <playback-id>
  ```
</details>

### Direct uploads

Create direct upload URLs for client-side video uploading.

```bash
mux uploads create --cors-origin "https://example.com" --playback-policy public
mux uploads list
mux uploads get <upload-id>
mux uploads cancel <upload-id>
```

| Option | Description |
|--------|-------------|
| `--cors-origin <origin>` | Allowed CORS origin for the upload (required) |
| `-p, --playback-policy <policy>` | `public` or `signed` |
| `--timeout <seconds>` | Seconds before the upload times out (default: 3600) |
| `--test` | Create a test upload (asset deleted after 24 hours) |

### Signing keys and secure playback

For assets with signed playback policies, the CLI can generate secure URLs.

#### Create a signing key

```bash
mux signing-keys create
```

<Callout type="warning">
  The private key is only returned once during creation. The CLI automatically stores it in your current environment configuration.
</Callout>

```bash
mux signing-keys list
mux signing-keys get <key-id>
mux signing-keys delete <key-id>
```

#### Generate signed URLs

```bash
# Sign for video playback
mux sign <playback-id>

# Sign with custom expiration
mux sign <playback-id> --expiration 24h

# Sign a thumbnail with parameters
mux sign <playback-id> --type thumbnail --param time=14 --param width=100

# Sign a GIF
mux sign <playback-id> --type gif

# Output token only (no URL)
mux sign <playback-id> --token-only

# Pass JWT claims as JSON
mux sign <playback-id> --params-json '{"custom": {"session_id": "xxxx-123"}}'
```

| Option | Description |
|--------|-------------|
| `-e, --expiration <duration>` | Token expiration (default: `7d`). Examples: `7d`, `24h`, `30m` |
| `-t, --type <type>` | `video` (default), `thumbnail`, `gif`, `storyboard` |
| `-p, --param <key=value>` | JWT claim as key=value (repeatable) |
| `--params-json <json>` | JWT claims as JSON object |
| `--token-only` | Output only the JWT token |

<details>
  <summary>
    View thumbnail parameters
  </summary>

  These parameters can be passed via `--param` when using `--type thumbnail`:

  | Parameter | Description |
  |-----------|-------------|
  | `time` | Video timestamp in seconds |
  | `width` | Width in pixels |
  | `height` | Height in pixels |
  | `rotate` | Clockwise rotation: 90, 180, or 270 |
  | `fit_mode` | `preserve`, `stretch`, `crop`, `smartcrop`, `pad` |
  | `flip_v` | Flip vertically |
  | `flip_h` | Flip horizontally |
</details>

### Playback ID lookup

Look up which asset or live stream a playback ID belongs to:

```bash
mux playback-ids <playback-id>
mux playback-ids <playback-id> --expand  # fetch the full asset or live stream object
```

### Playback restrictions

Control where and how your content can be played.

```bash
# Create a restriction
mux playback-restrictions create \
  --allowed-domains "example.com" \
  --allowed-domains "*.example.com"

# List, get, delete
mux playback-restrictions list
mux playback-restrictions get <restriction-id>
mux playback-restrictions delete <restriction-id>

# Update referrer rules
mux playback-restrictions update-referrer <restriction-id> \
  --allowed-domains "example.com" \
  --allow-no-referrer

# Update user agent rules
mux playback-restrictions update-user-agent <restriction-id> \
  --allow-no-user-agent true \
  --allow-high-risk-user-agent false
```

### Transcription vocabularies

Manage custom vocabularies to improve automatic speech recognition accuracy for domain-specific terms.

```bash
# Create a vocabulary
mux transcription-vocabularies create \
  --phrase "Mux" --phrase "HLS" --phrase "RTMP" \
  --name "Streaming Terms"

# List, get, update, delete
mux transcription-vocabularies list
mux transcription-vocabularies get <vocabulary-id>
mux transcription-vocabularies update <vocabulary-id> --phrase "Mux" --phrase "DASH"
mux transcription-vocabularies delete <vocabulary-id>
```

### Delivery usage

List delivery usage reports for video assets and live streams.

```bash
mux delivery-usage list
mux delivery-usage list --asset-id <id>
mux delivery-usage list --live-stream-id <id>
```

### DRM configurations

View DRM configurations for your Mux environment. DRM configurations are provisioned by Mux and are read-only.

```bash
mux drm-configurations list
mux drm-configurations get <drm-configuration-id>
```

### Mux Data

Commands for video analytics, monitoring, and incident tracking via the Mux Data API.

#### Video views

```bash
mux video-views list
mux video-views list --filters "country:US" --timeframe "24:hours"
mux video-views list --viewer-id <id>
mux video-views get <view-id>
```

#### Metrics

```bash
# List available metrics
mux metrics list

# Breakdown by dimension
mux metrics breakdown <metric-id> --group-by country --measurement median

# Overall metric values
mux metrics overall <metric-id> --measurement avg

# Timeseries data
mux metrics timeseries <metric-id> --group-by hour

# Performance insights
mux metrics insights <metric-id> --measurement 95th
```

Common options for metric commands: `--measurement <95th|median|avg|count|sum>`, `--filters`, `--metric-filters`, `--timeframe`

#### Monitoring

Real-time monitoring data from Mux Data.

```bash
mux monitoring dimensions
mux monitoring metrics
mux monitoring breakdown <metric-id> --dimension <d>
mux monitoring breakdown-timeseries <metric-id> --dimension <d>
mux monitoring histogram-timeseries --filters ...
mux monitoring timeseries <metric-id>
```

#### Incidents

```bash
mux incidents list
mux incidents list --status open --severity alert
mux incidents get <incident-id>
mux incidents related <incident-id>
```

#### Annotations

Mark significant events (deployments, config changes) on your analytics timeline.

```bash
mux annotations create --date 1700000000 --note "Deployed v2.1.0"
mux annotations list
mux annotations get <annotation-id>
mux annotations update <annotation-id> --date <timestamp> --note <text>
mux annotations delete <annotation-id>
```

#### Dimensions, errors, and exports

```bash
# List available dimensions and their values
mux dimensions list
mux dimensions values <dimension-id> --timeframe "24:hours"

# List errors
mux errors list --filters ... --timeframe ...

# List video view export files
mux exports list
```

## Getting help

View available commands:

```bash
mux --help
```

Get help for a specific command:

```bash
mux assets --help
mux assets create --help
```

## Full documentation

For more information, see the [Mux CLI repository](https://github.com/muxinc/cli) on GitHub.