A command-line interface for interacting with the Mux API, designed to provide a first-class development experience for working with Mux services locally.
- Installation
- Shell Completions
- Getting Started
- Common Options
- Commands
- Configuration
- Development
- License
- Support
brew install muxinc/tap/muxnpm install -g @mux/cliOr run directly with npx:
npx @mux/clicurl -fsSL https://raw.githubusercontent.com/muxinc/cli/main/install.sh | bashDownload 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.
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.
Before using the Mux CLI, you need to authenticate with your Mux API credentials. You can obtain these from the Mux Dashboard.
# Interactive login (prompts for Token ID and Secret)
mux login
# Login with .env file (expects MUX_TOKEN_ID and MUX_TOKEN_SECRET)
mux login --env-file .env
# Named environments for multi-environment workflows
mux login --name production
mux login --name staging --env-file .env.stagingThe first environment you add becomes the default. See Authentication & Environment Management for more details.
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 when combining --json with delete commands. |
--wait |
Poll until the resource is ready before returning. Available on create commands. |
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>-publicorsigned(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, orpremium--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 --waitJSON 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.jsonList 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 abc123Get detailed information about a specific video asset.
mux assets get abc123xyzUpdate metadata fields on a video asset. At least one field flag must be provided.
Options:
--title <string>- Setmeta.title(max 512 characters)--creator-id <string>- Setmeta.creator_id(max 128 characters)--external-id <string>- Setmeta.external_id(max 128 characters)--passthrough <string>- Setpassthrough(max 255 characters)
mux assets update abc123xyz --title "My Video" --creator-id "user-42"
mux assets update abc123xyz --title "" # clear a fieldDelete a video asset permanently.
mux assets delete abc123xyz # with confirmation prompt
mux assets delete abc123xyz --force # skip confirmationInteractive 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 manageNote: Requires an interactive terminal (TTY). For scripting, use mux assets list, mux assets get, etc.
Retrieve input info for an asset, including file details, tracks, and encoding settings.
mux assets input-info abc123xyzUpdate master access settings for an asset (temporary or none).
mux assets update-master-access abc123xyz --master-access temporaryManage 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 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
Manage text and audio tracks (subtitles, captions, audio) on video assets.
Add a text or audio track to an asset.
Options:
--url <url>- URL of the track file (required)--type <type>- Track type:textoraudio(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:subtitlesorcaptions--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 subtitlesDelete a track from an asset. Supports --force.
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)"Create a new Mux live stream for broadcasting.
Options:
--playback-policy <policy>-publicorsigned(repeatable)--new-asset-settings <settings>- Auto-create asset from stream. Usenoneto disable, or JSON string (e.g.,'{"playback_policies": ["public"]}')--reconnect-window <seconds>- Reconnect timeout (default: 60)--latency-mode <mode>-low,reduced, orstandard(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
List all live streams with pagination.
mux live list
mux live list --limit 10 --compactGet detailed information about a specific live stream.
mux live get abc123xyzUpdate configuration on a live stream. At least one option must be provided.
Options:
--latency-mode <mode>-low,reduced, orstandard--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"Delete a live stream permanently.
mux live delete abc123xyz # with confirmation
mux live delete abc123xyz --force # skip confirmationSignal that a live stream has ended and Mux should complete the recording.
Enable a disabled live stream, allowing it to accept new connections.
Disable a live stream, preventing it from accepting new connections.
mux live complete abc123xyz
mux live enable abc123xyz
mux live disable abc123xyzReset 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 confirmationManage 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]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"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)"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]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]Manage direct uploads for client-side video uploading. Direct uploads provide a URL that clients can use to upload video files directly to Mux.
Create a new direct upload URL.
Options:
--cors-origin <origin>- Allowed CORS origin for the upload (required)-p, --playback-policy <policy>-publicorsigned--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 publicList direct uploads with pagination. Supports --limit, --page, --compact.
Get details about a specific direct upload.
Cancel a waiting direct upload. Supports --force.
mux uploads cancel abc123xyz --forceLook 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 --expandNote: 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.
Manage playback restrictions to control where and how your content can be played.
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"List playback restrictions. Supports --limit, --page, --compact.
Get details about a playback restriction.
Delete a playback restriction. Supports --force.
Update the referrer restriction.
Options: --allowed-domains <domain> (required, repeatable), --allow-no-referrer
Update the user agent restriction.
Options: --allow-no-user-agent <boolean> (required), --allow-high-risk-user-agent <boolean> (required)
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.
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-onlyOutput 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.
Manage custom transcription vocabularies to improve automatic speech recognition accuracy for domain-specific terms.
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"List vocabularies. Supports --limit, --page, --compact.
Get details about a vocabulary.
Update a vocabulary. This replaces all existing phrases.
Options: --phrase <phrase> (required, repeatable), --name <name>, --passthrough <string>
Delete a vocabulary. Supports --force.
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 abc123xyzSupports --limit, --page, --compact.
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 [--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
# 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
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>]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
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]mux dimensions list # list available dimensions
mux dimensions values <dimension-id> [--timeframe "24:hours"]mux errors list [--filters ...] [--timeframe ...]mux exports list # list video view export filesAuthenticate with Mux and save credentials.
Options:
-f, --env-file <path>- Path to .env file containingMUX_TOKEN_IDandMUX_TOKEN_SECRET-n, --name <name>- Name for this environment (default:default)
mux login # interactive
mux login --env-file .env # from .env file
mux login --name production --env-file .env.prod # named environmentRemove credentials for a specific environment. When you remove the default environment, the CLI automatically selects another as the new default.
mux logout default
mux logout stagingDisplay all configured environments.
mux env listChange the default environment.
mux env switch stagingCredentials are stored securely in ~/.config/mux/config.json with restrictive file permissions (readable/writable only by the owner).
The configuration file structure:
{
"environments": {
"production": {
"tokenId": "your_token_id",
"tokenSecret": "your_token_secret"
},
"staging": {
"tokenId": "your_staging_token_id",
"tokenSecret": "your_staging_token_secret"
}
},
"defaultEnvironment": "production"
}This project uses Bun as the JavaScript runtime and is written in TypeScript.
- Bun runtime installed
- pnpm for package management
# Install dependencies
pnpm install
# Run tests
bun test
# Build the project
pnpm run build# Run all tests
bun test
# Run tests in watch mode
bun test --watchsrc/
├── 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
│ ├── 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
│ ├── errors/ # Mux Data: error analytics
│ ├── exports/ # Mux Data: export files
│ ├── 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
│ └── ... # Other utilities
└── index.ts # CLI entry point
Apache-2.0. See LICENSE for details.
For issues and questions:
- File an issue on GitHub
- Visit Mux Documentation
- Contact Mux Support