Skip to content

Repository files navigation

Mux CLI

A command-line interface for interacting with the Mux API, designed to provide a first-class development experience for working with Mux services locally.

Table of Contents

Installation

Homebrew (macOS)

brew install muxinc/tap/mux

Install via npm

npm install -g @mux/cli

Or run directly with npx:

npx @mux/cli

Shell installer

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

Download the binary

Download the latest binary for your platform from GitHub Releases:

# macOS (Apple Silicon)
curl -L https://github.com/muxinc/cli/releases/latest/download/mux-darwin-arm64 -o mux
chmod +x mux
sudo mv mux /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/muxinc/cli/releases/latest/download/mux-darwin-x64 -o mux
chmod +x mux
sudo mv mux /usr/local/bin/

# Linux (x64)
curl -L https://github.com/muxinc/cli/releases/latest/download/mux-linux-x64 -o mux
chmod +x mux
sudo mv mux /usr/local/bin/

# Linux (arm64)
curl -L https://github.com/muxinc/cli/releases/latest/download/mux-linux-arm64 -o mux
chmod +x mux
sudo mv mux /usr/local/bin/

The binary is self-contained and has no dependencies.

Shell Completions

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

mux completions install

This detects your shell and adds the appropriate source line to your config file (e.g. ~/.zshrc). Restart your shell or source the file to activate completions.

Manual setup

If you prefer to configure completions yourself, add the appropriate line to your shell's config file:

Bash: Add the following line to ~/.bashrc:

source <(mux completions bash)

Zsh: Add the following line to ~/.zshrc:

source <(mux completions zsh)

Fish: Add the following line to ~/.config/fish/config.fish:

source (mux completions fish | psub)

After saving the file, restart your shell or source it (e.g. source ~/.zshrc) to activate completions.

Getting Started

Authentication

The CLI supports two ways to sign in, and both are fully supported:

  • Browser sign-in (default). mux login opens the Mux Dashboard, where you pick an organization and environment. The CLI receives the result on a local loopback address and manages token refresh for you. Best for local development.
  • Mux API access token. A Token ID and Secret from the Mux Dashboard. Best for CI, service accounts, and scripting, where no browser is available.
# Browser sign-in: pick an organization and environment in the dashboard
mux login

# Sign in to more environments by running it again — each one is saved separately
mux login

# Mux API access token, entered manually
mux login --interactive

# Access token from a .env file (expects MUX_TOKEN_ID and MUX_TOKEN_SECRET)
mux login --env-file .env

# Save the MUX_TOKEN_ID / MUX_TOKEN_SECRET already set in this shell
mux login --from-env

# Named environments for multi-environment workflows
mux login --name production
mux login --name staging --env-file .env.staging

Important

When MUX_TOKEN_ID and MUX_TOKEN_SECRET are set in your shell, mux login with no flags stops and asks which method you meant, rather than silently saving them. Those variables already work on their own — no login needed — and they take precedence over any saved login, so a config entry written from them has no effect until they are unset. Pass --from-env to save them deliberately, or --oauth for a browser sign-in.

Browser sign-in names each environment after the organization and environment you selected (for example acme-inc-production); pass --name to choose your own. Signing in again to the same environment refreshes its credentials in place and keeps its signing keys and forward URL; signing in to a different environment adds a new entry and never overwrites an existing one. An entry saved by a version that did not yet record environment ids is recognized by asking Mux which environment its access token pair belongs to, so the first browser sign-in updates it in place rather than leaving its signing keys behind on a second entry.

The first environment you add becomes the default, and a new browser sign-in becomes the active environment unless you pass --keep-current. Run mux auth status at any time to see every credential the CLI can find and which one is active. See Authentication & Environment Management for more details.

Credential sources and precedence

The CLI resolves credentials from two sources, in order:

  1. Environment variablesMUX_TOKEN_ID and MUX_TOKEN_SECRET. Used only when both are set and non-empty; a lone variable is ignored.
  2. Stored login — the active environment saved by mux login, whether it holds a browser sign-in or an access token pair.

Environment variables take precedence over the stored login, matching the convention of tools like the GitHub, Stripe, and Vercel CLIs. When they shadow a stored login, the CLI prints a one-line notice on stderr naming the shadowed environment (suppressed in agent mode). mux auth status lays out every source and marks the active one.

Because environment variables win, mux login with MUX_TOKEN_ID and MUX_TOKEN_SECRET already set refuses to guess: it prints the four explicit methods and exits without writing anything. Pass --from-env to save the shell credentials, or --oauth for a browser sign-in. If a login is saved while those variables are set, the CLI says so — the saved login will not take effect until they are unset.

One environment, two ways in

A single environment can hold both credential kinds at once: an access token pair saved for CI and a browser sign-in saved by mux login. Both are kept, and OAuth is preferred when present — OAuth credentials go stale unless they are exercised and refreshed, so the CLI does not quietly live on the token pair.

If an OAuth login stops working for good (its refresh token was revoked or expired), the CLI records the failure on that credential, surfaces it in mux auth status and mux env list, and falls back to the access token pair on the same environment if there is one. Nothing is deleted automatically: run mux login to replace the dead login, or mux logout <name> to remove the environment entirely.

All OAuth endpoints live on the Mux API host, so they are derived from one base — MUX_BASE_URL moves the API calls, discovery, and the sign-in flow together, and the token endpoint can never end up on a different host than the authorization endpoint. A login made against a non-default host stores that host with the environment, so its API calls, token refresh, and revocation keep going there in shells where MUX_BASE_URL is not set. On top of that, the CLI discovers the authorization server's endpoints at runtime (RFC 8414 / OIDC discovery, cached for a day in ~/.cache/mux/), so Mux can move them without breaking installed versions. Discovery is never required: if it is unreachable the CLI falls back to built-in defaults, and MUX_OAUTH_AUTHORIZE_URL / MUX_OAUTH_TOKEN_URL / MUX_OAUTH_REVOKE_URL always win when set. It is consulted only on login, refresh, and logout (to revoke), never on ordinary commands.

Requests carry Authorization: Basic for access token credentials and Authorization: Bearer for browser sign-ins. Access tokens for a browser sign-in are refreshed automatically: shortly before they expire, and once on an unexpected 401 before the request is retried. Concurrent mux processes coordinate through a lock file so a refresh token is never spent twice. When a refresh token is finally rejected, the CLI names the environment and tells you to run mux login again.

All values in a credential bundle come from the same source — the CLI never mixes sources:

Variable Purpose
MUX_TOKEN_ID / MUX_TOKEN_SECRET API credentials (both required to take effect)
MUX_BASE_URL API host override (applies to either source). Also moves the OAuth endpoints and endpoint discovery, so one variable points the whole CLI at another environment
MUX_SIGNING_KEY / MUX_PRIVATE_KEY Signing key pair for mux sign (setting only one of the pair is an error; used alongside API credentials, not instead of them)
MUX_OAUTH_CLIENT_ID OAuth client identifier. Needed when pointing at a non-production authorization server
MUX_OAUTH_SCOPES Narrow the scopes requested at sign-in (space or comma separated). Defaults to what the CLI's commands need
MUX_OAUTH_AUTHORIZE_URL / MUX_OAUTH_TOKEN_URL / MUX_OAUTH_REVOKE_URL Override a single OAuth endpoint. Takes precedence over both discovery and MUX_BASE_URL

When credentials come from environment variables, the API host is MUX_BASE_URL or the default https://api.mux.com — never a stored environment's custom host. Similarly, mux sign only falls back to a stored environment's signing keys when that environment matches the active credentials, so tokens for one environment cannot mint tokens with another environment's key.

Common Options

These options are available on most commands and are not repeated in individual command docs below.

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. Required for delete commands with --json or in agent mode.
--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.

Caution

These CLI commands are for local development only and provide no delivery guarantees. In production, you must configure a webhook endpoint in the Mux Dashboard that points to your server webhook endpoint URL.

mux webhooks listen

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

Options:

  • --forward-to <url> - POST received events to a local URL in real-time
  • --json - Output raw JSON per event
# Listen and print events
mux webhooks listen

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

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 using the Mux Node SDK:

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.

Options:

  • --limit <n> - Maximum number of events to show (default: 25)
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.

Options:

  • --forward-to <url> - POST event(s) to a local URL
  • --all - Replay all stored events
  • --json - Output JSON instead of pretty format
# 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

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. This is useful for testing your webhook handler without creating real resources.

Options:

  • --forward-to <url> - Local URL to POST the example event to (required)
  • --json - Output JSON instead of pretty format
# 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

# See the generated payload
mux webhooks trigger video.asset.created --forward-to http://localhost:3000/api/webhooks/mux --json

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

Webhook Management

Configure the webhooks that Mux delivers events to for the current environment.

mux webhooks create --address https://example.com/api/webhooks/mux
mux webhooks list
mux webhooks get <webhook-id>
mux webhooks update <webhook-id> [--address <url>] [--enable | --disable]
mux webhooks delete <webhook-id> [--force]

The signing secret is printed when a webhook is created; store it securely and use it to verify webhook signatures.

Commands

Assets

mux assets create

Create a new Mux video asset from a URL, local file, or JSON configuration.

Options:

  • --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

Examples:

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

# Upload local files (glob supported, each file becomes a separate asset)
mux assets create --upload ./videos/*.mp4 --playback-policy public

# Complex config from JSON file (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

JSON Configuration File:

For complex asset creation (overlays, subtitles, multiple input tracks), use a JSON configuration file:

{
  "input": [
    {
      "url": "https://example.com/video.mp4",
      "overlay_settings": {
        "url": "https://example.com/logo.png",
        "vertical_align": "bottom",
        "horizontal_align": "right",
        "vertical_margin": "5%",
        "horizontal_margin": "5%",
        "opacity": "80%"
      },
      "generated_subtitles": [
        { "language_code": "en", "name": "English" }
      ]
    }
  ],
  "playback_policies": ["signed"],
  "video_quality": "plus",
  "static_renditions": [{ "resolution": "1080p" }],
  "normalize_audio": true,
  "passthrough": "my-video-123"
}
mux assets create --file asset-config.json

mux assets list

List all video assets with pagination and filtering.

Unique options:

  • --upload-id <id> - Filter by upload ID
  • --live-stream-id <id> - Filter by live stream ID
mux assets list
mux assets list --limit 10 --page 2
mux assets list --live-stream-id abc123

mux assets get <asset-id>

Get detailed information about a specific video asset.

mux assets get abc123xyz

mux assets update <asset-id>

Update metadata fields on a video asset. At least one field flag must be provided.

Options:

  • --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)
  • --thumbnail-time <seconds> - Set the asset's default thumbnail time
  • --clear-thumbnail-time - Reset the default thumbnail time
mux assets update abc123xyz --title "My Video" --creator-id "user-42"
mux assets update abc123xyz --title ""  # clear a field
mux assets update abc123xyz --thumbnail-time 12.5
mux assets update abc123xyz --clear-thumbnail-time

mux assets delete <asset-id>

Delete a video asset permanently.

mux assets delete abc123xyz          # with confirmation prompt
mux assets delete abc123xyz --force  # skip confirmation

mux assets manage

Interactive terminal UI (TUI) to browse assets, view details, manage playback IDs, and copy URLs. Navigate with arrow keys, Enter, and q to quit.

mux assets manage

Note: Requires an interactive terminal (TTY). For scripting, use mux assets list, mux assets get, etc.

mux assets input-info <asset-id>

Retrieve input info for an asset, including file details, tracks, and encoding settings.

mux assets input-info abc123xyz

mux assets update-master-access <asset-id>

Update master access settings for an asset (temporary or none).

mux assets update-master-access abc123xyz --master-access temporary

Playback ID Management

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

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> [--force]

Static Renditions Management

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

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> [--force]

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

Shots Management

Shot detection data segments a video into its individual shots. Generated data is reused by Robots jobs.

mux assets shots get <asset-id>
mux assets shots generate <asset-id>
mux assets shots delete <asset-id> [--force]

Track Management

Manage text and audio tracks (subtitles, captions, audio) on video assets.

mux assets tracks create <asset-id>

Add a text or audio track to an asset.

Options:

  • --url <url> - URL of the track file (required)
  • --type <type> - Track type: text or audio (required)
  • --language-code <code> - BCP 47 language code, e.g., en-US (required)
  • --name <name> - Human-readable name for the track
  • --text-type <type> - Text track type: subtitles or captions
  • --closed-captions - Indicates the track provides SDH
  • --passthrough <string> - Passthrough metadata (max 255 characters)
mux assets tracks create abc123xyz --url https://example.com/subs.vtt --type text --language-code en --text-type subtitles
mux assets tracks update <asset-id> <track-id>

Update a text track (subtitles/captions) on an asset. At least one field flag must be provided. The API rejects non-text tracks.

Options: --name <name>, --language-code <code>, --closed-captions <true|false>, --passthrough <string>

mux assets tracks update abc123xyz track456 --name "English (SDH)" --closed-captions true
mux assets tracks delete <asset-id> <track-id>

Delete a track from an asset. Supports --force.

mux assets tracks generate-subtitles <asset-id> <track-id>

Generate subtitles for an audio track using automatic speech recognition.

Options: --language-code <code>, --name <name>, --passthrough <string>

mux assets tracks generate-subtitles abc123xyz track456 --language-code en --name "English (auto)"

Live Streams

mux live create

Create a new Mux live stream for broadcasting.

Options:

  • --playback-policy <policy> - public or signed (repeatable)
  • --new-asset-settings <settings> - Auto-create asset from stream. Use none to disable, or JSON string (e.g., '{"playback_policies": ["public"]}')
  • --reconnect-window <seconds> - Reconnect timeout (default: 60)
  • --latency-mode <mode> - low, reduced, or standard (default: low)
  • --test - Create test stream (deleted after 24h)
mux live create --playback-policy public
mux live create --playback-policy public --latency-mode low --test
mux live create --playback-policy public --new-asset-settings '{"playback_policies": ["public"]}'

Once created, stream using:

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

mux live list

List all live streams with pagination.

mux live list
mux live list --limit 10 --compact

mux live get <stream-id>

Get detailed information about a specific live stream.

mux live get abc123xyz

mux live update <stream-id>

Update configuration on a live stream. At least one option must be provided.

Options:

  • --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
mux live update abc123xyz --latency-mode standard
mux live update abc123xyz --reconnect-window 300 --title "My Stream"

mux live delete <stream-id>

Delete a live stream permanently.

mux live delete abc123xyz          # with confirmation
mux live delete abc123xyz --force  # skip confirmation

mux live complete <stream-id>

Signal that a live stream has ended and Mux should complete the recording.

mux live enable <stream-id>

Enable a disabled live stream, allowing it to accept new connections.

mux live disable <stream-id>

Disable a live stream, preventing it from accepting new connections.

mux live complete abc123xyz
mux live enable abc123xyz
mux live disable abc123xyz

mux live reset-stream-key <stream-id>

Reset the stream key for a live stream. This invalidates the current key.

mux live reset-stream-key abc123xyz          # with confirmation
mux live reset-stream-key abc123xyz --force  # skip confirmation

Simulcast Targets

Manage simulcast targets to restream a live stream to third-party platforms (e.g., YouTube, Twitch).

# Create a simulcast target
mux live simulcast-targets create <stream-id> --url rtmp://live.twitch.tv/app --stream-key live_xxxxx

# Get details about a simulcast target
mux live simulcast-targets get <stream-id> <target-id>

# Delete a simulcast target
mux live simulcast-targets delete <stream-id> <target-id> [--force]

Embedded & Generated Subtitles

mux live update-embedded-subtitles <stream-id>

Update embedded subtitle (CEA-608) configuration.

Options: --language-channel <cc1|cc2|cc3|cc4>, --language-code <code>, --name <name>, --passthrough <string>, --clear

mux live update-embedded-subtitles abc123xyz --language-channel cc1 --language-code en --name "English CC"
mux live update-generated-subtitles <stream-id>

Update generated subtitle (ASR) configuration.

Options: --language-code <code>, --name <name>, --passthrough <string>, --transcription-vocabulary-ids <id> (repeatable), --clear

mux live update-generated-subtitles abc123xyz --language-code en --name "English (auto)"

New Asset Static Renditions

Configure static rendition settings for assets automatically created from a live stream.

# Set rendition resolutions
mux live update-new-asset-static-renditions <stream-id> --resolution 1080p --resolution 720p

# Delete rendition settings
mux live delete-new-asset-static-renditions <stream-id> [--force]

Playback ID Management (Live)

Manage playback IDs on live streams, same interface as asset playback IDs.

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> [--force]

Uploads

Manage direct uploads for client-side video uploading. Direct uploads provide a URL that clients can use to upload video files directly to Mux.

mux uploads create

Create a new direct upload URL.

Options:

  • --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)
mux uploads create --cors-origin "https://example.com" --playback-policy public

mux uploads list

List direct uploads with pagination. Supports --limit, --page, --compact.

mux uploads get <upload-id>

Get details about a specific direct upload.

mux uploads cancel <upload-id>

Cancel a waiting direct upload. Supports --force.

mux uploads cancel abc123xyz --force

Playback ID Lookup

mux playback-ids <playback-id>

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

Options:

  • --expand - Fetch the full asset or live stream object instead of just the reference
mux playback-ids abc123playbackid
mux playback-ids abc123playbackid --expand

Note: The nested playback-ids commands under assets and live are for managing playback IDs on known resources. This top-level command is for discovering what resource a playback ID belongs to.

Playback Restrictions

Manage playback restrictions to control where and how your content can be played.

mux playback-restrictions create

Create a new playback restriction.

Options:

  • --allowed-domains <domain> - Allowed referrer domains (required, repeatable)
  • --allow-no-referrer - Allow playback when no referrer is sent
  • --allow-no-user-agent - Allow playback when no user agent is sent
  • --allow-high-risk-user-agent - Allow playback from high-risk user agents
mux playback-restrictions create --allowed-domains "example.com" --allowed-domains "*.example.com"

mux playback-restrictions list

List playback restrictions. Supports --limit, --page, --compact.

mux playback-restrictions get <restriction-id>

Get details about a playback restriction.

mux playback-restrictions delete <restriction-id>

Delete a playback restriction. Supports --force.

mux playback-restrictions update-referrer <restriction-id>

Update the referrer restriction.

Options: --allowed-domains <domain> (required, repeatable), --allow-no-referrer

mux playback-restrictions update-user-agent <restriction-id>

Update the user agent restriction.

Options: --allow-no-user-agent <boolean> (required), --allow-high-risk-user-agent <boolean> (required)

Signing Keys & Secure Playback

Signing Key Management

mux signing-keys create              # creates key and saves to current environment
mux signing-keys list                # lists keys with environment indicators
mux signing-keys get <key-id>
mux signing-keys delete <key-id> [--force]

The private key is only returned once during creation. The CLI automatically stores it in your current environment configuration.

Deleting a signing key invalidates all tokens and signed URLs created with it and removes it from any local environment configurations.

mux sign <playback-id>

Sign a playback ID to generate a secure URL for video playback, thumbnails, GIFs, or storyboards. Used with assets or live streams that have a signed playback policy.

Options:

  • -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 (no URL)

When both --param and --params-json are provided, --params-json is applied first and --param values override on top.

Examples:

mux sign abc123playbackid
mux sign abc123playbackid --expiration 24h
mux sign abc123playbackid --type thumbnail --param time=14 --param width=100
mux sign abc123playbackid --type gif
mux sign abc123playbackid --params-json '{"custom": {"session_id": "xxxx-123"}}'
mux sign abc123playbackid --token-only

Output URLs by type:

Type Domain Example path
video stream.mux.com /{id}.m3u8?token=...
thumbnail image.mux.com /{id}/thumbnail.png?token=...
gif image.mux.com /{id}/animated.gif?token=...
storyboard image.mux.com /{id}/storyboard.vtt?token=...

Thumbnail parameters (embedded in JWT via --param):

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

Prerequisite: You must have a signing key in your current environment. Run mux signing-keys create to set one up.

Transcription Vocabularies

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

mux transcription-vocabularies create

Options:

  • --phrase <phrase> - Phrase to include (required, repeatable)
  • --name <name> - Name for the vocabulary
  • --passthrough <string> - Passthrough metadata (max 255 characters)
mux transcription-vocabularies create --phrase "Mux" --phrase "HLS" --phrase "RTMP" --name "Streaming Terms"

mux transcription-vocabularies list

List vocabularies. Supports --limit, --page, --compact.

mux transcription-vocabularies get <vocabulary-id>

Get details about a vocabulary.

mux transcription-vocabularies update <vocabulary-id>

Update a vocabulary. This replaces all existing phrases.

Options: --phrase <phrase> (required, repeatable), --name <name>, --passthrough <string>

mux transcription-vocabularies delete <vocabulary-id>

Delete a vocabulary. Supports --force.

Delivery Usage

mux delivery-usage list

List delivery usage reports for video assets and live streams.

Options:

  • --asset-id <id> - Filter by asset ID
  • --live-stream-id <id> - Filter by live stream ID
  • --timeframe <timeframe> - Timeframe as Unix epoch timestamps (specify twice for start and end)
mux delivery-usage list
mux delivery-usage list --asset-id abc123xyz

Supports --limit, --page, --compact.

DRM Configurations

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

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

Robots

Run AI-powered workflows on your video assets using Mux Robots. Requires accepting the Robots terms of service in the Mux Dashboard and a token with robots:read and robots:write permissions.

Job Management

# List all jobs (with optional filters)
mux robots list [--workflow summarize] [--status completed] [--asset-id <id>]

# Get full details about a specific job
mux robots get <job-id> --workflow <type>

# Cancel a running job
mux robots cancel <job-id>

List options: --workflow, --status, --asset-id, --limit, --page, --compact

Workflow values: summarize, moderate, generate-chapters, ask-questions, find-key-moments, translate-captions, edit-captions, find-best-thumbnails, find-scenes, generate-engagement-insights, generate-premium-captions, translate-audio

mux robots summarize <asset-id>

Generate a title, description, and tags for a video.

Options:

  • --tone <tone> - neutral, playful, or professional
  • --language-code <code> - BCP 47 code of the caption track to analyze
  • --output-language-code <code> - BCP 47 code for the generated output
  • --title-length <n> - Maximum title length in words
  • --description-length <n> - Maximum description length in words
  • --tag-count <n> - Maximum number of tags (default: 10)
  • --passthrough <string> - Arbitrary metadata (max 255 chars)
mux robots summarize abc123 --tone playful

mux robots moderate <asset-id>

Analyze video content for policy violations.

Options:

  • --language-code <code> - BCP 47 code for transcript analysis (audio-only assets)
  • --sampling-interval <seconds> - Interval between sampled thumbnails (min 5)
  • --max-samples <n> - Maximum number of thumbnails to sample
  • --threshold-sexual <n> - Score threshold (0.0-1.0) for sexual content (default: 0.7)
  • --threshold-violence <n> - Score threshold (0.0-1.0) for violent content (default: 0.8)
  • --passthrough <string> - Arbitrary metadata (max 255 chars)
mux robots moderate abc123 --threshold-sexual 0.5 --threshold-violence 0.9

mux robots generate-chapters <asset-id>

Automatically generate chapters for a video.

Options:

  • --language-code <code> - BCP 47 code of the caption track to analyze
  • --output-language-code <code> - BCP 47 code for output chapter titles
  • --passthrough <string> - Arbitrary metadata (max 255 chars)
mux robots generate-chapters abc123

mux robots ask-questions <asset-id>

Ask questions about a video and get answers.

Options:

  • --question <question> - Question to ask (required, repeatable)
  • --language-code <code> - BCP 47 code of the caption track to analyze
  • --passthrough <string> - Arbitrary metadata (max 255 chars)
mux robots ask-questions abc123 --question "What is this video about?" --question "Are there children?"

mux robots find-key-moments <asset-id>

Find key moments and highlights in a video.

Options:

  • --max-moments <n> - Maximum number of key moments to extract (default: 5)
  • --target-duration-min-ms <ms> - Preferred minimum highlight duration in milliseconds (must be paired with max)
  • --target-duration-max-ms <ms> - Preferred maximum highlight duration in milliseconds (must be paired with min)
  • --passthrough <string> - Arbitrary metadata (max 255 chars)
mux robots find-key-moments abc123 --max-moments 3 --target-duration-min-ms 15000 --target-duration-max-ms 45000

mux robots translate-captions <asset-id>

Translate captions on a video to another language.

Options:

  • --track-id <id> - Source caption track ID to translate (required)
  • --to-language-code <code> - BCP 47 code for translated output (required)
  • --no-upload - Do not upload the translated VTT to Mux
  • --passthrough <string> - Arbitrary metadata (max 255 chars)
mux robots translate-captions abc123 --track-id track456 --to-language-code es

mux robots translate-audio <asset-id>

Translate a video's audio track to another language.

Options:

  • --to-language-code <code> - BCP 47 code for the translated audio (required)
  • --no-upload - Do not upload the translated audio track to Mux
  • --passthrough <string> - Arbitrary metadata (max 255 chars)
mux robots translate-audio abc123 --to-language-code es

mux robots edit-captions <asset-id>

Edit a caption track with find/replace rules or automatic profanity censoring.

Options:

  • --track-id <id> - Caption track ID to edit (required)
  • --replace <find=replace> - Find/replace rule (repeatable)
  • --case-sensitive - Make --replace rules match case-sensitively
  • --censor-profanity - Automatically censor profanity
  • --censor-mode <mode> - blank, remove, or mask (implies --censor-profanity)
  • --delete-original-track - Delete the original track after editing
  • --track-name-suffix <suffix> - Suffix appended to the edited track name
  • --no-upload - Do not upload the edited VTT to Mux
  • --passthrough <string> - Arbitrary metadata (max 255 chars)
mux robots edit-captions abc123 --track-id track456 --replace "Muks=Mux" --censor-profanity

mux robots generate-premium-captions <asset-id>

Generate high-accuracy premium captions for a video.

Options:

  • --language-code <code> - BCP 47 code of the spoken audio (auto-detected when omitted)
  • --include-speakers - Include speaker labels
  • --include-words - Include word-level timing
  • --phrase <phrase> - Domain-specific phrase to boost recognition (repeatable)
  • --replace-existing - Replace an existing generated caption track in the same language
  • --track-name <name> - Name for the generated caption track
  • --no-upload - Do not upload the generated captions to Mux
  • --passthrough <string> - Arbitrary metadata (max 255 chars)
mux robots generate-premium-captions abc123 --language-code en --include-speakers

mux robots find-best-thumbnails <asset-id>

Find the best thumbnail candidates for a video.

Options:

  • --max-thumbnails <n> - Maximum number of candidates to return
  • --update-asset-thumbnail - Set the asset's default thumbnail time to the top candidate
  • --audience <text> - Intended audience used as scoring guidance
  • --campaign-style <text> - Campaign/channel thumbnail style to prefer
  • --looking-for <text> - What to look for in candidate thumbnails
  • --start-time <seconds> / --end-time <seconds> - Execution window on the asset timeline
  • --passthrough <string> - Arbitrary metadata (max 255 chars)
mux robots find-best-thumbnails abc123 --max-thumbnails 3 --update-asset-thumbnail

mux robots find-scenes <asset-id>

Detect and describe the scenes in a video.

Options:

  • --language-code <code> - BCP 47 code of the caption track to analyze
  • --min-scene-duration-ms <ms> - Minimum scene duration
  • --min-scenes <n> - Minimum number of scenes
  • --audience <text> - Intended audience used as model guidance
  • --brand-term <term> - Preferred brand or domain term (repeatable)
  • --narration-detail <detail> - concise, balanced, or detailed
  • --start-time <seconds> / --end-time <seconds> - Execution window on the asset timeline
  • --passthrough <string> - Arbitrary metadata (max 255 chars)
mux robots find-scenes abc123 --min-scenes 5 --narration-detail detailed

mux robots generate-engagement-insights <asset-id>

Analyze a video's engagement data and generate insights.

Options:

  • --passthrough <string> - Arbitrary metadata (max 255 chars)
mux robots generate-engagement-insights abc123 --wait

All job creation commands also support --file <path> (JSON config with the full parameters object), --wait (poll until the job completes), and --json.

Mux Data

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

Video Views

mux video-views list [--filters "country:US"] [--timeframe "24:hours"] [--viewer-id <id>] [--error-id <id>]
mux video-views get <view-id>

List options: --filters, --metric-filters, --timeframe, --viewer-id, --error-id, --order-direction, --limit, --page, --compact

Metrics

# List available metrics
mux metrics list [--dimension <dimension>] [--value <value>]

# 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: --measurement <95th|median|avg|count|sum>, --filters, --metric-filters, --timeframe

Breakdown/timeseries also support: --group-by, --order-by, --order-direction, --limit, --page, --compact

Monitoring

Real-time monitoring data from Mux Data.

mux monitoring dimensions                              # list available dimensions
mux monitoring metrics                                  # list available metrics
mux monitoring breakdown <metric-id> [--dimension <d>] [--timestamp <ts>]
mux monitoring breakdown-timeseries <metric-id> [--dimension <d>]
mux monitoring histogram-timeseries [--filters ...]
mux monitoring timeseries <metric-id> [--timestamp <ts>]

Incidents

mux incidents list [--status open] [--severity alert]
mux incidents get <incident-id>
mux incidents related <incident-id>

List options: --status <open|closed|expired>, --severity <warning|alert>, --order-by, --order-direction, --limit, --page, --compact

Annotations

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

# Create annotation
mux annotations create --date 1700000000 --note "Deployed v2.1.0" [--sub-property-id <id>]

# List, get, update, delete
mux annotations list [--timeframe ...]
mux annotations get <annotation-id>
mux annotations update <annotation-id> --date <timestamp> --note <text>
mux annotations delete <annotation-id> [--force]

Dimensions

mux dimensions list                                    # list available dimensions
mux dimensions values <dimension-id> [--timeframe "24:hours"]

Engagement

Engagement analytics for a specific video, addressed by exactly one of --asset-id, --playback-id, or --video-id.

# Viewership across the video timeline
mux engagement heatmap --asset-id <id> [--timeframe "7:days"]

# Most-watched moments
mux engagement hotspots --asset-id <id> [--limit 5] [--order-direction desc]

Errors

mux errors list [--filters ...] [--timeframe ...]

Exports

mux exports list                                       # list video view export files

Authentication & Environment Management

mux login

Sign in to Mux and save credentials. With no flags, opens your browser to select an organization and environment; the CLI then manages token refresh for you.

The four authentication methods are mutually exclusive; passing more than one is an error.

Options:

  • --oauth - Sign in with a browser (the default when no shell credentials are set)
  • --interactive - Enter a Mux API access token (Token ID and Secret) manually
  • -f, --env-file <path> - Path to .env file containing MUX_TOKEN_ID and MUX_TOKEN_SECRET, and optionally MUX_SIGNING_KEY and MUX_PRIVATE_KEY (saved for mux sign when both are present)
  • --from-env - Save the MUX_TOKEN_ID and MUX_TOKEN_SECRET already set in this shell
  • -n, --name <name> - Name for this environment (default: derived from the organization and environment for browser sign-in, or default otherwise)
  • --print-url - Print the authorization URL instead of opening a browser
  • --port <port> - Local port to receive the login redirect on
  • --timeout <seconds> - How long to wait for the browser authorization before giving up (default: 300)
  • --keep-current - Save the login without making it the active environment
mux login                                         # browser sign-in
mux login --interactive                           # prompts for Token ID and Secret
mux login --env-file .env                         # from .env file
mux login --from-env                              # save this shell's credentials
mux login --name production --env-file .env.prod  # named environment
mux login --print-url                             # no browser available

--interactive needs a real terminal to prompt on: it fails immediately with instructions under --json, in agent mode, or when stdin is not a TTY (CI, piped input), rather than hanging. A bare mux login without a TTY and without --json or agent mode also fails fast. Use --env-file, --from-env, or the environment variables for unattended automation.

Browser sign-in from a coding agent: with --json or in agent mode, mux login runs the browser flow without a terminal. The moment the authorization URL is known it is emitted as a single JSON line on stderr:

{"event":"authorization_url","url":"https://...","browserOpened":true,"expiresInSeconds":300}

The command then blocks until the browser redirect arrives (bounded by --timeout), and prints the final result as one JSON document on stdout (name, identity, activated, replacedExisting, dropped). The CLI still attempts to open a browser directly; pass --print-url to suppress that. Agent harnesses that only surface output when a command exits should run mux login in the background and poll its output so the URL can be relayed to the user while the command waits. This works only when the agent and the user's browser share a machine (or the user forwards the port — see below).

Signing in from a remote or SSH session: the redirect goes to a loopback address on the machine running the CLI, which your browser cannot reach from elsewhere. Either forward the port (ssh -L 51372:127.0.0.1:51372 …, then mux login --port 51372) or use mux login --interactive.

mux auth status

Show every credential source the CLI can find, which one is active, and how to change it. Reads only local state — no network calls — and never prints token material.

Options:

  • --json - Output JSON instead of pretty format
mux auth status
Active:       acme-inc-production
Sign-in:      browser sign-in
Environment:  Acme Inc / Production

Other environments (1):
  ci-token  access token  env_01H9

Switch with 'mux env switch <name>'.

When MUX_TOKEN_ID and MUX_TOKEN_SECRET are set they outrank every saved login, so no saved login is active and all of them are listed — including the one that would take over if you unset the variables:

Active:       MUX_TOKEN_ID / MUX_TOKEN_SECRET
Source:       environment variables
Note:         takes precedence over the saved login acme-inc-production
              unset both variables to use that instead

Saved logins (2):
  acme-inc-production  browser sign-in  Acme Inc / Production  (selected)
  ci-token             access token     env_01H9

Switch with 'mux env switch <name>'.

An environment reachable both ways reads browser sign-in (also has access token), naming the one requests actually use. Access token expiry is deliberately not shown: it is refreshed automatically, so there is nothing to act on. --json carries expires_at for callers that want it.

mux auth login and mux auth logout are aliases of the top-level commands.

mux logout [name]

Remove credentials for a specific environment. When you remove the default environment, the CLI automatically selects another as the new default. For a browser sign-in, the refresh token is also revoked server-side; if that call fails, the local credentials are still removed and a warning is printed.

Options:

  • --all - Remove stored credentials for every environment
mux logout default
mux logout staging
mux logout --all

mux env list

Display all configured environments, with the credential kind and the organization and environment they point at. An environment holding both credentials shows oauth+token, and a credential that has failed shows a warning line beneath it.

Options:

  • --json - Output JSON instead of pretty format
mux env list
Configured environments:

* acme-inc-production (current)  oauth  Acme Inc / Production
  ci-token                       token  env_01H9

2 environments total

mux env switch [name]

Change the default environment. Works for both credential kinds. Run it without a name in an interactive terminal to pick from a list.

mux env switch staging
mux env switch            # interactive picker

Configuration

Credentials are stored securely in ~/.config/mux/config.json with restrictive file permissions (readable/writable only by the owner).

Each environment holds its identity and settings, plus one or both credential blocks. Entries written by earlier versions are flat (tokenId / tokenSecret at the top level) and are read as a token block automatically — there is no migration step and no config version to track.

{
  "environments": {
    "acme-inc-production": {
      "environmentId": "env_…",
      "environmentName": "Production",
      "organizationId": "org_…",
      "organizationName": "Acme Inc",
      "oauth": {
        "accessToken": "",
        "refreshToken": "",
        "expiresAt": 1799999999,
        "scope": "video:read video:write"
      },
      "token": {
        "tokenId": "your_token_id",
        "tokenSecret": "your_token_secret"
      }
    },
    "staging": {
      "tokenId": "your_staging_token_id",
      "tokenSecret": "your_staging_token_secret"
    }
  },
  "defaultEnvironment": "acme-inc-production"
}

acme-inc-production above is reachable both ways; requests use the oauth block. staging is a flat entry from an older version, read as an access token login. A credential that has failed terminally gains a lastError field, which is what mux auth status reports.

Upgrading from 2.x

Nothing to do beyond signing in again. Two things are worth knowing:

  • Run mux login after upgrading. The first command that writes the config converts every entry to the layout above, including entries it wasn't asked about. Version 2.x looks for tokenId at the top level, so if you go back to it afterwards it will report that you are not logged in.
  • Your access token secret is not lost. It is still in ~/.config/mux/config.json, just nested under token. Mux only displays a token secret once, at creation, so don't mint a replacement — signing in again, or moving the two fields back up a level, restores it.

In CI, mux login now fails when MUX_TOKEN_ID and MUX_TOKEN_SECRET are set, because those variables already work without a login and take precedence over anything saved. Use mux login --from-env if you specifically want them written to the config.

Writes are atomic (written to a temporary file in the same directory, then renamed), so a config read during a token refresh never sees a partial file.

Development

This project uses Bun as the JavaScript runtime and is written in TypeScript.

Prerequisites

  • Bun runtime installed
  • pnpm for package management

Setup

# Install dependencies
pnpm install

# Run tests
bun test

# Build the project
pnpm run build

Testing

# Run all tests
bun test

# Run tests in watch mode
bun test --watch

Project Structure

src/
├── commands/                          # CLI command definitions
│   ├── assets/                       # Asset management
│   │   ├── manage/                   # Interactive TUI
│   │   ├── playback-ids/             # Playback ID sub-resource
│   │   ├── static-renditions/        # Static rendition sub-resource
│   │   ├── tracks/                   # Track management (subtitles, audio)
│   │   ├── create.ts, list.ts, get.ts, update.ts, delete.ts
│   │   ├── input-info.ts             # Retrieve input info
│   │   └── update-master-access.ts   # Update master access settings
│   ├── live/                         # Live stream management
│   │   ├── playback-ids/             # Playback ID sub-resource
│   │   ├── simulcast-targets/        # Simulcast target sub-resource
│   │   ├── create.ts, list.ts, get.ts, update.ts, delete.ts
│   │   ├── complete.ts, enable.ts, disable.ts
│   │   ├── reset-stream-key.ts
│   │   ├── update-embedded-subtitles.ts
│   │   ├── update-generated-subtitles.ts
│   │   ├── update-new-asset-static-renditions.ts
│   │   └── delete-new-asset-static-renditions.ts
│   ├── uploads/                      # Direct upload management
│   ├── playback-restrictions/        # Playback restriction management
│   ├── transcription-vocabularies/   # Transcription vocabulary management
│   ├── delivery-usage/               # Delivery usage reports
│   ├── drm-configurations/          # DRM configuration management
│   ├── robots/                       # Mux Robots AI workflows
│   ├── signing-keys/                 # Signing key management
│   ├── video-views/                  # Mux Data: video view analytics
│   ├── metrics/                      # Mux Data: metric analytics
│   ├── monitoring/                   # Mux Data: real-time monitoring
│   ├── incidents/                    # Mux Data: incident tracking
│   ├── annotations/                  # Mux Data: annotation management
│   ├── dimensions/                   # Mux Data: dimension queries
│   ├── engagement/                   # Mux Data: engagement analytics
│   ├── errors/                       # Mux Data: error analytics
│   ├── exports/                      # Mux Data: export files
│   ├── webhooks/                     # Webhook config, listening & replay
│   │   ├── events/                  # Event storage & replay
│   │   └── listen.ts                # Real-time SSE listener
│   ├── env/                          # Environment management
│   ├── login.ts, logout.ts, sign.ts  # Auth & signing commands
│   └── playback-ids.ts               # Playback ID lookup
├── lib/                              # Shared libraries
│   ├── tui/                          # Reusable TUI components
│   ├── config.ts                     # Configuration management
│   ├── formatters.ts                 # Output formatting
│   ├── data-filters.ts               # Mux Data filter utilities
│   ├── mux.ts                        # Mux API client
│   ├── urls.ts                       # URL generation
│   ├── signing.ts                    # JWT signing
│   ├── webhook-signing.ts            # Webhook signature generation
│   ├── events-store.ts               # Local webhook event storage
│   ├── sse.ts                        # Server-Sent Events parser
│   └── ...                           # Other utilities
└── index.ts                          # CLI entry point

License

Apache-2.0. See LICENSE for details.

Support

For issues and questions:

About

Command Mux from the command line like a boss.

Resources

Stars

19 stars

Watchers

37 watching

Forks

Releases

Packages

Used by

Contributors

Languages