| name | mux-cli |
| description | Use when running or scripting the `mux` CLI — managing Mux video assets, live streams, direct uploads, playback IDs, signed URLs, playback restrictions, DRM, webhooks, Mux Data analytics queries, or Mux Robots AI jobs (summarize, moderate, chapters, key moments, caption translation) from the command line. Triggers on `mux <command>`, "Mux CLI", or "Mux Robots". |
Mux CLI
The mux CLI is the fastest way to act on a Mux account — prefer it over hand-writing REST calls when it is installed. Check with mux --version; if missing, install via brew install muxinc/tap/mux, npm install -g @mux/cli, or https://github.com/muxinc/cli.
Always pass --agent on every command. It enables agent mode: JSON output (parseable) and an agent-identifying User-Agent.
Run mux <command> --help for exact flags — never guess flag names. The installed version may lag the docs (e.g. mux robots ships in versions newer than 1.0.0); if a command in this skill is missing from mux --help, suggest upgrading the CLI or fall back to the REST API using current docs (see the mux-docs skill).
Auth and environments
mux login — interactive auth (the user runs this themselves).- Non-interactive: set
MUX_TOKEN_ID and MUX_TOKEN_SECRET. Never print or commit these values.
mux whoami --agent — confirm identity and environment before mutating anything.mux env list --agent / mux env switch <name> — inspect or change the active environment. Assets, streams, and keys are environment-scoped; a "missing" asset is usually the wrong environment.mux logout <name> — remove stored credentials for an environment.
Command groups
Video
| Task | Command |
|---|
| Create asset (from URL, local file, or JSON) | mux assets create --agent |
| List / inspect / update / delete assets | mux assets list|get|update|delete --agent |
| Input file details and tracks | mux assets input-info <asset-id> --agent |
| Playback IDs on an asset | mux assets playback-ids list|create|delete --agent |
| Downloadable MP4s (static renditions) | mux assets static-renditions list|create|delete --agent |
| Subtitle/audio tracks, ASR subtitles | mux assets tracks create|delete|generate-subtitles --agent |
| Direct uploads for client-side uploading | mux uploads create|list|get|cancel --agent |
| Look up what a playback ID points to | mux playback-ids <playback-id> --agent |
| Custom ASR vocabularies | mux transcription-vocabularies … --agent |
Live streaming
| Task | Command |
|---|
| Create / list / inspect / update / delete streams | mux live create|list|get|update|delete --agent |
| Enable, disable, complete a stream | mux live enable|disable|complete <stream-id> --agent |
| Rotate a leaked stream key | mux live reset-stream-key <stream-id> --agent |
| Restream to other platforms | mux live simulcast-targets create|get|delete --agent |
| Live captions (embedded or ASR) | mux live update-embedded-subtitles|update-generated-subtitles --agent |
| Playback IDs on a stream | mux live playback-ids list|create|delete --agent |
Secure playback
| Task | Command |
|---|
| Signing keys for signed playback policies | mux signing-keys create|list|get|delete --agent |
| Mint a signed playback/thumbnail/GIF/storyboard URL | mux sign <playback-id> --agent |
| Referrer / user-agent playback restrictions | mux playback-restrictions … --agent |
| DRM configurations | mux drm-configurations list|get --agent |
Webhooks (no tunnel needed for local dev)
| Task | Command |
|---|
| Stream events to a local endpoint | mux webhooks listen --forward-to http://localhost:3000/api/webhooks --agent |
| Send a synthetic test event | mux webhooks trigger video.asset.ready --agent |
| Browse / replay stored events | mux webhooks events list|replay --agent |
Mux Data (analytics)
| Task | Command |
|---|
| Individual playback sessions | mux video-views list|get --agent |
| Aggregate metrics: breakdown, timeseries, insights | mux metrics list|breakdown|overall|timeseries|insights --agent |
| Real-time monitoring | mux monitoring metrics|breakdown|timeseries … --agent |
| Auto-detected quality incidents | mux incidents list|get|related --agent |
| Deploy/release markers on charts | mux annotations … --agent |
| Filterable attributes and their values | mux dimensions list|values --agent |
| Playback errors | mux errors list --agent |
| Raw view-data CSV exports | mux exports list --agent |
| Delivery/billing usage | mux delivery-usage list --agent |
Agent docs
mux docs path --agent prints the installed paths to the CLI's embedded agent skill, bundled docs, and AGENTS.md — useful for offline docs access.
Mux Robots (AI jobs)
Robots run AI workflows on video assets: point a robot at an asset ID, it runs as an asynchronous job, collect the result.
mux robots summarize <asset-id> --agent
mux robots generate-chapters <asset-id> --agent
mux robots moderate <asset-id> --agent
mux robots ask-questions <asset-id> --agent
mux robots find-key-moments <asset-id> --agent
mux robots translate-captions <asset-id> --agent
mux robots list --agent
mux robots get <job-id> --agent
mux robots cancel <job-id> --agent
Each robot has its own flags (e.g. summarize takes --description-length, --tag-count) — check mux robots <robot> --help.
The robot catalog grows over time (find-scenes, best thumbnails, premium captions, audio translation, engagement insights are documented). If a robot exists in the docs but not in the installed CLI, use the REST API (/robots/v0/jobs/...) per the docs, or suggest upgrading the CLI.
Robots-specific pitfalls:
- The asset must be ready (
video.asset.ready) before starting a job.
- Jobs are asynchronous. Store the job ID and check status, or handle the completion webhook — don't block synchronously in an app.
- Robots directives steer behavior (tone, format, constraints) — fetch the directives doc before hand-rolling prompt-like options.
- Results may need human review before publishing (especially
moderate and generated metadata) — surface as suggestions, not silent writes.
Conventions and pitfalls
- Deletes are permanent (assets, live streams, signing keys). Confirm with the user before any delete.
- Playback ID ≠ asset ID. Playback and image URLs use playback IDs; management commands use asset/stream IDs.
- Environment scoping is the first thing to check when something "doesn't exist" — run
mux env list --agent.
- Don't poll asset status in scripts; use
mux webhooks listen or the --wait flag where a command supports it.
Docs
| Topic | URL |
|---|
| CLI repo / install | https://github.com/muxinc/cli |
| Robots overview | https://www.mux.com/docs/guides/robots.md |
| Robots directives | https://www.mux.com/docs/guides/robots-directives.md |
| Robot task guides | https://www.mux.com/docs/guides/robots-<task>.md (summarize, moderate, generate-chapters, ask-questions, find-key-moments, find-scenes, find-best-thumbnails, translate-captions, translate-audio, generate-premium-captions, edit-captions, generate-engagement-insights) |
For any other Mux docs page, use the mux-docs skill. If a URL 404s, search https://www.mux.com/llms.txt for the current location.
