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.
The Mux CLI can be installed via Homebrew, npm, a shell installer, or by downloading pre-built binaries.
brew install muxinc/tap/muxInstall globally to use the mux command anywhere:
npm install -g @mux/cliOr run directly without installing using npx:
npx @mux/cliRun the install script to automatically download and set up the CLI:
curl -fsSL https://raw.githubusercontent.com/muxinc/cli/main/install.sh | bashPlatform-specific binaries are available for macOS (Apple Silicon and Intel) and Linux (x64 and arm64) from the GitHub Releases page. These are self-contained executables with no external dependencies.
Enable tab completion for commands, subcommands, and options in your shell:
Bash (add to ~/.bashrc):
source <(mux completions bash)Zsh (add to ~/.zshrc):
source <(mux completions zsh)Fish (add to ~/.config/fish/config.fish):
source (mux completions fish | psub)Restart your shell or source the config file to activate completions.
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.
Run mux login to authenticate interactively:
mux loginYou'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.
The CLI can read credentials from a .env file or environment variables:
MUX_TOKEN_ID=your-token-id
MUX_TOKEN_SECRET=your-token-secretLogin from a .env file:
mux login --env-file .envFor managing multiple Mux accounts (production, staging, development), you can configure named environments:
mux login --name production
mux login --name staging --env-file .env.stagingThe first environment you add becomes the default. Switch between environments:
mux env switch staging
mux env listRemove an environment:
mux logout stagingThese 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. |
Create, list, update, and delete video assets.
# 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:
mux assets manageCreate and manage live streams for broadcasting via RTMP.
# 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://global-live.mux.com/appCreate direct upload URLs for client-side video uploading.
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) |
For assets with signed playback policies, the CLI can generate secure URLs.
mux signing-keys createThe private key is only returned once during creation. The CLI automatically stores it in your current environment configuration.
mux signing-keys list
mux signing-keys get <key-id>
mux signing-keys delete <key-id># 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 |
Look up which asset or live stream a playback ID belongs to:
mux playback-ids <playback-id>
mux playback-ids <playback-id> --expand # fetch the full asset or live stream objectControl where and how your content can be played.
# 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 falseManage custom vocabularies to improve automatic speech recognition accuracy for domain-specific terms.
# 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>List delivery usage reports for video assets and live streams.
mux delivery-usage list
mux delivery-usage list --asset-id <id>
mux delivery-usage list --live-stream-id <id>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>Commands for video analytics, monitoring, and incident tracking via the Mux Data API.
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># 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 95thCommon options for metric commands: --measurement <95th|median|avg|count|sum>, --filters, --metric-filters, --timeframe
Real-time monitoring data from Mux Data.
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>mux incidents list
mux incidents list --status open --severity alert
mux incidents get <incident-id>
mux incidents related <incident-id>Mark significant events (deployments, config changes) on your analytics timeline.
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># 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 listView available commands:
mux --helpGet help for a specific command:
mux assets --help
mux assets create --helpFor more information, see the Mux CLI repository on GitHub.