Merge pull request #48 from muxinc/dk/strings

dylanjha · web-flow · commit 66898098c84f · 2026-02-19T11:29:34.000-08:00
Add TOC and better help strings
diff --git a/README.md b/README.md
@@ -2,6 +2,47 @@
 
 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](#installation)
+  - [Install via npm](#install-via-npm)
+  - [Shell installer](#shell-installer)
+  - [Download the binary](#download-the-binary)
+- [Getting Started](#getting-started)
+  - [Authentication](#authentication)
+- [Commands](#commands)
+  - [Asset Management](#asset-management)
+    - [Create Assets](#mux-assets-create)
+    - [List Assets](#mux-assets-list)
+    - [Get Asset](#mux-assets-get-asset-id)
+    - [Update Asset](#mux-assets-update-asset-id)
+    - [Delete Asset](#mux-assets-delete-asset-id)
+    - [Interactive Management](#mux-assets-manage)
+    - [Playback ID Management](#playback-id-management)
+    - [Static Renditions Management](#static-renditions-management)
+  - [Live Stream Management](#live-stream-management)
+    - [Create Live Stream](#mux-live-create)
+    - [List Live Streams](#mux-live-list)
+    - [Get Live Stream](#mux-live-get-stream-id)
+    - [Delete Live Stream](#mux-live-delete-stream-id)
+    - [Playback ID Management (Live)](#playback-id-management-1)
+  - [Playback ID Lookup](#playback-id-lookup)
+  - [Signing Keys & Secure Playback](#signing-keys--secure-playback)
+    - [Create Signing Key](#mux-signing-keys-create)
+    - [List Signing Keys](#mux-signing-keys-list)
+    - [Get Signing Key](#mux-signing-keys-get-key-id)
+    - [Delete Signing Key](#mux-signing-keys-delete-key-id)
+    - [Sign Playback ID](#mux-sign-playback-id)
+  - [Authentication & Environment Management](#authentication--environment-management)
+- [Configuration](#configuration)
+- [Development](#development)
+  - [Prerequisites](#prerequisites)
+  - [Setup](#setup)
+  - [Testing](#testing)
+  - [Project Structure](#project-structure)
+- [License](#license)
+- [Support](#support)
+
 ## Installation
 
 ### Install via npm
diff --git a/src/commands/assets/create.test.ts b/src/commands/assets/create.test.ts
@@ -255,7 +255,7 @@ describe('mux assets create command', () => {
   describe('Command metadata', () => {
     test('has correct command description', () => {
       expect(createCommand.getDescription()).toBe(
-        'Create a new Mux video asset',
+        'Create a Mux video asset from a URL, local file upload, or JSON config',
       );
     });
 
diff --git a/src/commands/assets/create.ts b/src/commands/assets/create.ts
@@ -238,14 +238,22 @@ async function createFromConfig(
 }
 
 export const createCommand = new Command()
-  .description('Create a new Mux video asset')
-  .option('--url <url:string>', 'Video URL to ingest from the web')
+  .description(
+    'Create a Mux video asset from a URL, local file upload, or JSON config',
+  )
+  .option(
+    '--url <url:string>',
+    'Publicly accessible video URL to ingest (http/https)',
+  )
   .option(
     '--upload <path:string>',
     'Local file(s) to upload (supports glob patterns). Can be specified multiple times.',
     { collect: true },
   )
-  .option('--file, -f <path:string>', 'JSON configuration file')
+  .option(
+    '--file, -f <path:string>',
+    'JSON config file matching Mux Asset API schema (inputs, playback_policies, etc.)',
+  )
   .option(
     '-p, --playback-policy <policy:string>',
     'Playback policy (public or signed). Can be specified multiple times.',
@@ -268,7 +276,7 @@ export const createCommand = new Command()
   )
   .option(
     '--passthrough <string:string>',
-    'User metadata (max 255 characters)',
+    'Arbitrary metadata stored on asset and returned in API responses (max 255 chars)',
     {
       value: (value: string): string => {
         if (value.length > 255) {
@@ -309,7 +317,7 @@ export const createCommand = new Command()
   )
   .option(
     '--video-quality <quality:string>',
-    'Video quality level (basic, plus, or premium)',
+    'Video quality level: basic, plus, or premium (all support up to 4K). See https://mux.com/docs/guides/use-video-quality-levels',
     {
       value: (value: string): string => {
         const validQualities = ['basic', 'plus', 'premium'];
@@ -325,7 +333,10 @@ export const createCommand = new Command()
   .option('--normalize-audio', 'Normalize audio loudness level')
   .option('-y, --yes', 'Skip confirmation prompts')
   .option('--json', 'Output JSON instead of pretty format')
-  .option('--wait', 'Wait for asset processing to complete')
+  .option(
+    '--wait',
+    'Wait for asset processing to complete (polls up to 5 minutes)',
+  )
   .arguments('[files...:string]')
   // biome-ignore lint: Cliffy infers upload as string but collect makes it string[]
   .action(async (options: any, ...args: unknown[]) => {
@@ -450,7 +461,7 @@ export const createCommand = new Command()
         } else {
           if (!opts.json) {
             console.log(
-              'WARNING: Asset is still processing. Check status later.',
+              `WARNING: Asset is still processing. Run 'mux assets get ${asset.id}' to check status.`,
             );
           }
         }
diff --git a/src/commands/assets/delete.ts b/src/commands/assets/delete.ts
@@ -8,7 +8,7 @@ interface DeleteOptions {
 }
 
 export const deleteCommand = new Command()
-  .description('Delete a Mux video asset')
+  .description('Permanently delete a Mux video asset (cannot be undone)')
   .arguments('<asset-id:string>')
   .option('-f, --force', 'Skip confirmation prompt')
   .option('--json', 'Output JSON instead of pretty format')
diff --git a/src/commands/assets/index.ts b/src/commands/assets/index.ts
@@ -9,7 +9,9 @@ import { staticRenditionsCommand } from './static-renditions/index.ts';
 import { updateCommand } from './update.ts';
 
 export const assetsCommand = new Command()
-  .description('Manage Mux video assets')
+  .description(
+    'Manage Mux video assets (uploaded or ingested videos ready for streaming)',
+  )
   .action(function () {
     this.showHelp();
   })
diff --git a/src/commands/assets/list.ts b/src/commands/assets/list.ts
@@ -24,7 +24,10 @@ export const listCommand = new Command()
   .option('--page <number:number>', 'Page number for pagination', {
     default: 1,
   })
-  .option('--upload-id <id:string>', 'Filter by upload ID')
+  .option(
+    '--upload-id <id:string>',
+    'Filter by upload ID (returned from mux assets create --upload)',
+  )
   .option('--live-stream-id <id:string>', 'Filter by live stream ID')
   .option('--json', 'Output JSON instead of pretty format')
   .option('--compact', 'Output one line per asset (grep-friendly)')
diff --git a/src/commands/assets/playback-ids/index.ts b/src/commands/assets/playback-ids/index.ts
@@ -4,7 +4,9 @@ import { deleteCommand } from './delete.ts';
 import { listCommand } from './list.ts';
 
 export const playbackIdsCommand = new Command()
-  .description('Manage playback IDs for Mux video assets')
+  .description(
+    'Manage playback IDs (unique identifiers used in stream.mux.com URLs) for video assets',
+  )
   .action(function () {
     this.showHelp();
   })
diff --git a/src/commands/assets/playback-ids/list.ts b/src/commands/assets/playback-ids/list.ts
@@ -27,7 +27,10 @@ export const listCommand = new Command()
         console.log(JSON.stringify(output, null, 2));
       } else {
         if (playbackIds.length === 0) {
-          console.log(`No playback IDs found for asset ${assetId}`);
+          console.log(`No playback IDs found for asset ${assetId}.`);
+          console.log(
+            `Run 'mux assets playback-ids create ${assetId}' to add one.`,
+          );
           return;
         }
 
diff --git a/src/commands/assets/static-renditions/create.ts b/src/commands/assets/static-renditions/create.ts
@@ -46,11 +46,11 @@ export const createCommand = new Command()
   )
   .option(
     '-p, --passthrough <passthrough:string>',
-    'Custom metadata for the rendition (max 255 characters)',
+    'Arbitrary metadata stored on rendition and returned in API responses (max 255 chars)',
   )
   .option(
     '-w, --wait',
-    'Wait for the rendition to be ready instead of returning immediately',
+    'Wait for the rendition to be ready (polls up to 10 minutes, exits with error on timeout)',
   )
   .option('--json', 'Output JSON instead of pretty format')
   .action(async (options: CreateOptions, assetId: string) => {
diff --git a/src/commands/assets/static-renditions/index.ts b/src/commands/assets/static-renditions/index.ts
@@ -4,7 +4,9 @@ import { deleteCommand } from './delete.ts';
 import { listCommand } from './list.ts';
 
 export const staticRenditionsCommand = new Command()
-  .description('Manage static renditions (MP4s) for Mux video assets')
+  .description(
+    'Manage static renditions (downloadable MP4 files) for Mux video assets',
+  )
   .action(function () {
     this.showHelp();
   })
diff --git a/src/commands/assets/update.ts b/src/commands/assets/update.ts
@@ -11,7 +11,9 @@ interface UpdateOptions {
 }
 
 export const updateCommand = new Command()
-  .description('Update a Mux video asset')
+  .description(
+    'Update metadata fields on a Mux video asset (title, passthrough, etc.)',
+  )
   .arguments('<asset-id:string>')
   .option('--title <title:string>', 'Set meta.title (max 512 characters)')
   .option(
diff --git a/src/commands/env/index.ts b/src/commands/env/index.ts
@@ -3,7 +3,9 @@ import { listCommand } from './list.ts';
 import { switchCommand } from './switch.ts';
 
 export const envCommand = new Command()
-  .description('Manage Mux environments')
+  .description(
+    'Manage Mux environments (isolated containers for assets, streams, and keys within your organization)',
+  )
   .action(function () {
     this.showHelp();
   })
diff --git a/src/commands/env/switch.ts b/src/commands/env/switch.ts
@@ -2,7 +2,9 @@ import { Command } from '@cliffy/command';
 import { getEnvironment, setDefaultEnvironment } from '../../lib/config.ts';
 
 export const switchCommand = new Command()
-  .description('Switch the default environment')
+  .description(
+    'Switch the default environment (used by all subsequent mux commands)',
+  )
   .arguments('<name:string>')
   .action(async (_options, name: string) => {
     // Check if environment exists
diff --git a/src/commands/live/create.ts b/src/commands/live/create.ts
@@ -9,23 +9,25 @@ type LatencyMode = NonNullable<
 type PlaybackPolicy = Mux.PlaybackPolicy;
 
 export const createCommand = new Command()
-  .description('Create a new Mux live stream')
+  .description(
+    'Create a Mux live stream, returning stream key and RTMP URL for broadcasting',
+  )
   .option(
     '-p, --playback-policy <policy:string>',
     'Playback policy (public or signed). Can be specified multiple times.',
     { collect: true },
   )
   .option(
     '--new-asset-settings <mode:string>',
-    'Automatically create an asset from this live stream (none, or JSON string with settings)',
+    'Record live stream to asset: "none" to disable, or JSON with playback_policies, passthrough, etc.',
   )
   .option(
     '--reconnect-window <seconds:number>',
-    'Time in seconds a stream can be disconnected before being considered finished',
+    'Seconds a stream can be disconnected before finishing (0-1800, default: 60)',
   )
   .option(
     '--latency-mode <mode:string>',
-    'Latency mode: low or standard (default: low)',
+    'Latency mode: low, standard, or reduced (default: low)',
   )
   .option('--test', 'Create test live stream (deleted after 24h)')
   .option('--json', 'Output JSON instead of pretty format')
diff --git a/src/commands/live/delete.ts b/src/commands/live/delete.ts
@@ -8,7 +8,7 @@ interface DeleteOptions {
 }
 
 export const deleteCommand = new Command()
-  .description('Delete a Mux live stream')
+  .description('Permanently delete a Mux live stream (cannot be undone)')
   .arguments('<stream-id:string>')
   .option('-f, --force', 'Skip confirmation prompt')
   .option('--json', 'Output JSON instead of pretty format')
diff --git a/src/commands/live/index.ts b/src/commands/live/index.ts
@@ -6,7 +6,9 @@ import { listCommand } from './list.ts';
 import { playbackIdsCommand } from './playback-ids/index.ts';
 
 export const liveCommand = new Command()
-  .description('Manage Mux live streams')
+  .description(
+    'Manage Mux live streams (RTMP/SRT ingest endpoints for broadcasting)',
+  )
   .action(function () {
     this.showHelp();
   })
diff --git a/src/commands/live/playback-ids/index.ts b/src/commands/live/playback-ids/index.ts
@@ -4,7 +4,9 @@ import { deleteCommand } from './delete.ts';
 import { listCommand } from './list.ts';
 
 export const playbackIdsCommand = new Command()
-  .description('Manage playback IDs for Mux live streams')
+  .description(
+    'Manage playback IDs (unique identifiers used in stream.mux.com URLs) for live streams',
+  )
   .action(function () {
     this.showHelp();
   })
diff --git a/src/commands/live/playback-ids/list.ts b/src/commands/live/playback-ids/list.ts
@@ -27,7 +27,10 @@ export const listCommand = new Command()
         console.log(JSON.stringify(output, null, 2));
       } else {
         if (playbackIds.length === 0) {
-          console.log(`No playback IDs found for live stream ${liveStreamId}`);
+          console.log(`No playback IDs found for live stream ${liveStreamId}.`);
+          console.log(
+            `Run 'mux live playback-ids create ${liveStreamId}' to add one.`,
+          );
           return;
         }
 
diff --git a/src/commands/login.ts b/src/commands/login.ts
@@ -55,10 +55,12 @@ export async function parseEnvFile(filePath: string): Promise<EnvVars> {
 }
 
 export const loginCommand = new Command()
-  .description('Login to Mux and save credentials')
+  .description(
+    'Authenticate with Mux API credentials (Token ID and Secret from dashboard.mux.com)',
+  )
   .option(
     '-f, --env-file <path:string>',
-    'Path to .env file containing credentials',
+    'Path to .env file containing MUX_TOKEN_ID, MUX_TOKEN_SECRET, and optionally MUX_SIGNING_KEY and MUX_PRIVATE_KEY for signed URLs',
   )
   .option(
     '-n, --name <name:string>',
@@ -85,15 +87,19 @@ export const loginCommand = new Command()
 
       if (!envVars.MUX_TOKEN_ID || !envVars.MUX_TOKEN_SECRET) {
         throw new Error(
-          'Missing required variables in .env file. Expected: MUX_TOKEN_ID and MUX_TOKEN_SECRET',
+          'Missing required variables in .env file. Expected: MUX_TOKEN_ID and MUX_TOKEN_SECRET.\n' +
+            'Generate API credentials here: https://dashboard.mux.com/settings/access-tokens',
         );
       }
 
       tokenId = envVars.MUX_TOKEN_ID;
       tokenSecret = envVars.MUX_TOKEN_SECRET;
     } else {
       // Interactive prompts
-      console.log('Enter your Mux API credentials:');
+      console.log('Enter your Mux API credentials.');
+      console.log(
+        'Get your Token ID and Secret from https://dashboard.mux.com/settings/access-tokens\n',
+      );
 
       tokenId = await inputPrompt({ message: 'Mux Token ID:' });
       if (!tokenId.trim()) {
diff --git a/src/commands/logout.ts b/src/commands/logout.ts
@@ -6,7 +6,7 @@ import {
 } from '../lib/config.ts';
 
 export const logoutCommand = new Command()
-  .description('Remove credentials for an environment')
+  .description('Remove stored credentials for an environment by name')
   .arguments('<name:string>')
   .action(async (_options, name: string) => {
     // Check if environment exists
diff --git a/src/commands/sign.test.ts b/src/commands/sign.test.ts
@@ -37,7 +37,7 @@ describe('mux sign command', () => {
   describe('Command metadata', () => {
     test('has correct command description', () => {
       expect(signCommand.getDescription()).toBe(
-        'Sign a playback ID for secure video playback',
+        'Sign a playback ID, returning a JWT token and signed playback URL',
       );
     });
 
diff --git a/src/commands/sign.ts b/src/commands/sign.ts
diff --git a/src/commands/signing-keys/create.test.ts b/src/commands/signing-keys/create.test.ts
diff --git a/src/commands/signing-keys/create.ts b/src/commands/signing-keys/create.ts
diff --git a/src/commands/signing-keys/get.test.ts b/src/commands/signing-keys/get.test.ts
diff --git a/src/commands/signing-keys/get.ts b/src/commands/signing-keys/get.ts
diff --git a/src/commands/signing-keys/index.ts b/src/commands/signing-keys/index.ts
diff --git a/src/commands/signing-keys/list.test.ts b/src/commands/signing-keys/list.test.ts
diff --git a/src/commands/signing-keys/list.ts b/src/commands/signing-keys/list.ts
diff --git a/src/lib/mux.ts b/src/lib/mux.ts

Original file line number	Diff line number	Diff line change
`@@ -8,7 +8,7 @@ interface DeleteOptions {`
`8`	`8`	`}`
`9`	`9`
`10`	`10`	`export const deleteCommand = new Command()`
`11`		`- .description('Delete a Mux video asset')`
	`11`	`+ .description('Permanently delete a Mux video asset (cannot be undone)')`
`12`	`12`	`.arguments('<asset-id:string>')`
`13`	`13`	`.option('-f, --force', 'Skip confirmation prompt')`
`14`	`14`	`.option('--json', 'Output JSON instead of pretty format')`
Original file line number	Diff line number	Diff line change
`@@ -46,11 +46,11 @@ export const createCommand = new Command()`
`46`	`46`	`)`
`47`	`47`	`.option(`
`48`	`48`	`'-p, --passthrough <passthrough:string>',`
`49`		`- 'Custom metadata for the rendition (max 255 characters)',`
	`49`	`+ 'Arbitrary metadata stored on rendition and returned in API responses (max 255 chars)',`
`50`	`50`	`)`
`51`	`51`	`.option(`
`52`	`52`	`'-w, --wait',`
`53`		`- 'Wait for the rendition to be ready instead of returning immediately',`
	`53`	`+ 'Wait for the rendition to be ready (polls up to 10 minutes, exits with error on timeout)',`
`54`	`54`	`)`
`55`	`55`	`.option('--json', 'Output JSON instead of pretty format')`
`56`	`56`	`.action(async (options: CreateOptions, assetId: string) => {`