blitzreels 0.1.2 → 0.1.3

package/dist/index.js

@@ -9,13 +9,465 @@ const KEYCHAIN_SERVICE = "BlitzReels CLI";
 const KEYCHAIN_ACCOUNT = "api-key";
 const DEFAULT_WAIT_INTERVAL_MS = 3000;
 const DEFAULT_WAIT_TIMEOUT_MS = 20 * 60 * 1000;
+const GLOBAL_FLAGS = ["api-key", "base-url", "json", "help"];
+const TEXT_STYLE_FLAGS = [
+    "spec-json",
+    "font-family",
+    "font-size",
+    "font-weight",
+    "color",
+    "background-color",
+    "padding-x",
+    "padding-y",
+    "border-radius",
+    "top",
+    "left",
+    "text-align",
+    "text-shadow",
+    "no-background",
+];
+const CAPTION_WORD_SELECTOR_FLAGS = [
+    "word-id",
+    "word-ids",
+    "timeline-item-id",
+    "match-text",
+    "match-pattern",
+];
+const CAPTION_WORD_STYLE_FLAGS = [
+    "style-json",
+    "font-family",
+    "font-weight",
+    "font-style",
+    "color",
+    "active-color",
+    "background-color",
+    "active-animation",
+    "text-transform",
+    "text-shadow",
+    "glow-color",
+    "glow-blur-px",
+    "scale",
+    "offset-x",
+    "offset-y",
+    "rotation-deg",
+    "letter-spacing",
+    "opacity",
+    "clear-existing",
+];
+function commandSpec({ command, usage, flags = [], }) {
+    return { command, usage, flags };
+}
+const COMMAND_SPECS = [
+    commandSpec({
+        command: ["auth", "login"],
+        usage: "blitzreels auth login [--no-browser] [--timeout-ms 120000]",
+        flags: ["no-browser", "timeout-ms"],
+    }),
+    commandSpec({
+        command: ["auth", "set-key"],
+        usage: "blitzreels auth set-key --api-key KEY [--base-url URL]",
+    }),
+    commandSpec({
+        command: ["auth", "whoami"],
+        usage: "blitzreels auth whoami [--json]",
+    }),
+    commandSpec({
+        command: ["workspace", "settings", "get"],
+        usage: "blitzreels workspace settings get [--json]",
+    }),
+    commandSpec({
+        command: ["workspace", "settings", "update"],
+        usage: "blitzreels workspace settings update [--name NAME] [--description TEXT|null] [--protected-words foo,bar] [--icon-storage-key KEY|null] [--aspect-ratio 9:16] [--orientation portrait] [--resolution 1080p] [--frame-rate 30] [--auto-manage-broll true] [--caption-theme-id ID|null]",
+        flags: [
+            "name",
+            "description",
+            "protected-words",
+            "icon-storage-key",
+            "aspect-ratio",
+            "orientation",
+            "resolution",
+            "frame-rate",
+            "auto-manage-broll",
+            "caption-theme-id",
+        ],
+    }),
+    commandSpec({
+        command: ["projects", "list"],
+        usage: "blitzreels projects list [--search QUERY] [--status active|archived|all] [--limit 50] [--offset 0] [--cursor CURSOR] [--json]",
+        flags: ["search", "status", "limit", "offset", "cursor"],
+    }),
+    commandSpec({
+        command: ["projects", "create"],
+        usage: "blitzreels projects create --name NAME [--description TEXT] [--aspect-ratio 9:16] [--project-type video|carousel] [--carousel-settings-json JSON]",
+        flags: [
+            "name",
+            "description",
+            "aspect-ratio",
+            "project-type",
+            "carousel-settings-json",
+        ],
+    }),
+    commandSpec({
+        command: ["projects", "get"],
+        usage: "blitzreels projects get --project-id ID [--json]",
+        flags: ["project-id"],
+    }),
+    commandSpec({
+        command: ["projects", "rename"],
+        usage: "blitzreels projects rename --project-id ID --name NAME",
+        flags: ["project-id", "name"],
+    }),
+    commandSpec({
+        command: ["projects", "update"],
+        usage: "blitzreels projects update --project-id ID [--name NAME] [--description TEXT|null]",
+        flags: ["project-id", "name", "description"],
+    }),
+    commandSpec({
+        command: ["projects", "delete"],
+        usage: "blitzreels projects delete --project-id ID --confirm-delete",
+        flags: ["project-id", "confirm-delete"],
+    }),
+    commandSpec({
+        command: ["media", "list"],
+        usage: "blitzreels media list [--folder-id ID] [--asset-type video|audio|image|document] [--search QUERY] [--limit 100] [--offset 0] [--json]",
+        flags: ["folder-id", "asset-type", "search", "limit", "offset"],
+    }),
+    commandSpec({
+        command: ["media", "get"],
+        usage: "blitzreels media get --asset-id ID [--json]",
+        flags: ["asset-id"],
+    }),
+    commandSpec({
+        command: ["media", "delete"],
+        usage: "blitzreels media delete --asset-id ID --confirm-delete",
+        flags: ["asset-id", "confirm-delete"],
+    }),
+    commandSpec({
+        command: ["media", "upload"],
+        usage: "blitzreels media upload --file ./video.mp4 [--name NAME] [--content-type video/mp4] [--auto-process true] [--auto-transcribe true] [--auto-describe true] [--auto-suggest-shorts true]",
+        flags: [
+            "file",
+            "name",
+            "content-type",
+            "auto-process",
+            "auto-transcribe",
+            "auto-describe",
+            "auto-suggest-shorts",
+        ],
+    }),
+    commandSpec({
+        command: ["media", "import-youtube"],
+        usage: "blitzreels media import-youtube --url URL [--folder-id ID|root] [--quality 1080p] [--fps 30] [--audio-language fr|null]",
+        flags: ["url", "folder-id", "quality", "fps", "audio-language"],
+    }),
+    commandSpec({
+        command: ["media", "rename"],
+        usage: "blitzreels media rename --asset-id ID --name NAME",
+        flags: ["asset-id", "name"],
+    }),
+    commandSpec({
+        command: ["media", "update"],
+        usage: "blitzreels media update --asset-id ID [--name NAME] [--description TEXT|null] [--folder-id ID|root] [--allow-broll true]",
+        flags: ["asset-id", "name", "description", "folder-id", "allow-broll"],
+    }),
+    commandSpec({
+        command: ["media", "move"],
+        usage: "blitzreels media move --asset-id ID|--asset-ids ID1,ID2 --target-folder-id ID|root",
+        flags: ["asset-id", "asset-ids", "target-folder-id"],
+    }),
+    commandSpec({
+        command: ["media", "attach"],
+        usage: "blitzreels media attach --project-id ID --asset-id ID [--at 0] [--duration 4] [--layer-index 2] [--allow-duplicate true] [--position-preset center] [--position-x 0] [--position-y 0] [--width-px 320] [--height-px 180] [--scale 1.2] [--opacity 0.9] [--animation-preset popIn]",
+        flags: [
+            "project-id",
+            "asset-id",
+            "at",
+            "duration",
+            "layer-index",
+            "allow-duplicate",
+            "position-preset",
+            "position-x",
+            "position-y",
+            "width-px",
+            "height-px",
+            "scale",
+            "opacity",
+            "animation-preset",
+        ],
+    }),
+    commandSpec({
+        command: ["media", "folders", "list"],
+        usage: "blitzreels media folders list [--parent-folder-id ID] [--json]",
+        flags: ["parent-folder-id"],
+    }),
+    commandSpec({
+        command: ["media", "folders", "create"],
+        usage: "blitzreels media folders create --name NAME [--parent-folder-id ID] [--description TEXT|null] [--icon-type video]",
+        flags: ["name", "parent-folder-id", "description", "icon-type"],
+    }),
+    commandSpec({
+        command: ["media", "folders", "rename"],
+        usage: "blitzreels media folders rename --folder-id ID --name NAME",
+        flags: ["folder-id", "name"],
+    }),
+    commandSpec({
+        command: ["media", "folders", "update"],
+        usage: "blitzreels media folders update --folder-id ID [--name NAME] [--parent-folder-id ID|root] [--description TEXT|null] [--icon-type video]",
+        flags: [
+            "folder-id",
+            "name",
+            "parent-folder-id",
+            "description",
+            "icon-type",
+        ],
+    }),
+    commandSpec({
+        command: ["media", "folders", "delete"],
+        usage: "blitzreels media folders delete --folder-id ID --confirm-delete [--cascade true]",
+        flags: ["folder-id", "confirm-delete", "cascade"],
+    }),
+    commandSpec({
+        command: ["project", "inspect"],
+        usage: "blitzreels project inspect --project-id ID [--mode full] [--json]",
+        flags: ["project-id", "mode"],
+    }),
+    commandSpec({
+        command: ["project", "timeline"],
+        usage: "blitzreels project timeline --project-id ID [--json]",
+        flags: ["project-id"],
+    }),
+    commandSpec({
+        command: ["project", "snapshot"],
+        usage: "blitzreels project snapshot --project-id ID --at 00:03 [--target-width 608] [--image-format jpeg|png|webp] [--json]",
+        flags: ["project-id", "at", "target-width", "image-format"],
+    }),
+    commandSpec({
+        command: ["project", "snapshots"],
+        usage: "blitzreels project snapshots --project-id ID --at 00:01,00:03 [--target-width 608] [--image-format jpeg|png|webp] [--json]",
+        flags: ["project-id", "at", "target-width", "image-format"],
+    }),
+    commandSpec({
+        command: ["timeline", "transform"],
+        usage: "blitzreels timeline transform --project-id ID --timeline-item-id ID [--position-x 0] [--position-y 0] [--width-px 320|null] [--height-px 180|null] [--keep-aspect-ratio true]",
+        flags: [
+            "project-id",
+            "timeline-item-id",
+            "position-x",
+            "position-y",
+            "width-px",
+            "height-px",
+            "keep-aspect-ratio",
+        ],
+    }),
+    commandSpec({
+        command: ["timeline", "move"],
+        usage: "blitzreels timeline move --project-id ID --timeline-item-id ID --at 00:03 [--layer-index 2]",
+        flags: ["project-id", "timeline-item-id", "at", "layer-index"],
+    }),
+    commandSpec({
+        command: ["timeline", "delete"],
+        usage: "blitzreels timeline delete --project-id ID --timeline-item-id ID|--timeline-item-ids ID1,ID2 [--auto-pack true]",
+        flags: ["project-id", "timeline-item-id", "timeline-item-ids", "auto-pack"],
+    }),
+    commandSpec({
+        command: ["text", "add"],
+        usage: "blitzreels text add --project-id ID --text \"Hook\" [--name NAME] [--at 0] [--duration 4] [--layer-index 2] [--spec-json JSON] [--font-family Inter] [--font-size 64] [--font-weight 700] [--color '#fff'] [--background-color '#000'] [--padding-x 32] [--padding-y 16] [--border-radius 24] [--top '18%'] [--left '50%'] [--text-align center] [--text-shadow '0 6px 18px #000'] [--no-background]",
+        flags: [
+            "project-id",
+            "text",
+            "name",
+            "at",
+            "duration",
+            "layer-index",
+            ...TEXT_STYLE_FLAGS,
+        ],
+    }),
+    commandSpec({
+        command: ["text", "list"],
+        usage: "blitzreels text list --project-id ID [--json]",
+        flags: ["project-id"],
+    }),
+    commandSpec({
+        command: ["text", "update"],
+        usage: "blitzreels text update --project-id ID --content-item-id ID [--text \"New hook\"] [--name NAME] [--spec-json JSON] [--font-family Pacifico] [--font-size 82] [--font-weight 700] [--color '#17FFA6'] [--background-color '#051914'] [--padding-x 32] [--padding-y 16] [--border-radius 24] [--top '18%'] [--left '50%'] [--text-align center] [--text-shadow '0 6px 18px #000'] [--no-background]",
+        flags: [
+            "project-id",
+            "content-item-id",
+            "text",
+            "name",
+            ...TEXT_STYLE_FLAGS,
+        ],
+    }),
+    commandSpec({
+        command: ["text", "remove"],
+        usage: "blitzreels text remove --project-id ID --content-item-id ID",
+        flags: ["project-id", "content-item-id"],
+    }),
+    commandSpec({
+        command: ["audio", "add"],
+        usage: "blitzreels audio add --project-id ID --asset-id ID [--at 0] [--duration 30] [--volume 0.6] [--fade-in 0.5] [--fade-out 0.5] [--loop true]",
+        flags: [
+            "project-id",
+            "asset-id",
+            "at",
+            "duration",
+            "volume",
+            "fade-in",
+            "fade-out",
+            "loop",
+        ],
+    }),
+    commandSpec({
+        command: ["silence", "plan"],
+        usage: "blitzreels silence plan --project-id ID --timeline-item-id ID [--padding-ms 120] [--silence-threshold-db -35] [--min-silence-duration 0.25] [--remove-blips-max-duration 0.12] [--use-caption-validation true] [--json]",
+        flags: [
+            "project-id",
+            "timeline-item-id",
+            "padding-ms",
+            "silence-threshold-db",
+            "min-silence-duration",
+            "remove-blips-max-duration",
+            "use-caption-validation",
+        ],
+    }),
+    commandSpec({
+        command: ["silence", "apply"],
+        usage: "blitzreels silence apply --project-id ID --timeline-item-id ID --confirm-preview [--padding-ms 120] [--silence-threshold-db -35] [--min-silence-duration 0.25] [--remove-blips-max-duration 0.12] [--use-caption-validation true] [--delete-silent-clips true] [--manual-segment-overrides-json JSON]",
+        flags: [
+            "project-id",
+            "timeline-item-id",
+            "confirm-preview",
+            "padding-ms",
+            "silence-threshold-db",
+            "min-silence-duration",
+            "remove-blips-max-duration",
+            "use-caption-validation",
+            "delete-silent-clips",
+            "manual-segment-overrides-json",
+        ],
+    }),
+    commandSpec({
+        command: ["mistakes", "plan"],
+        usage: "blitzreels mistakes plan --project-id ID --timeline-item-id ID [--json]",
+        flags: ["project-id", "timeline-item-id"],
+    }),
+    commandSpec({
+        command: ["mistakes", "apply"],
+        usage: "blitzreels mistakes apply --project-id ID --timeline-item-id ID --confirm-preview [--plan-json JSON] [--manual-verdicts-json JSON] [--delete-mistakes true]",
+        flags: [
+            "project-id",
+            "timeline-item-id",
+            "confirm-preview",
+            "plan-json",
+            "manual-verdicts-json",
+            "delete-mistakes",
+        ],
+    }),
+    commandSpec({
+        command: ["captions", "words", "list"],
+        usage: "blitzreels captions words list --project-id ID [--timeline-item-id ID] [--match-text TEXT] [--limit 100] [--offset 0]",
+        flags: ["project-id", "timeline-item-id", "match-text", "limit", "offset"],
+    }),
+    commandSpec({
+        command: ["captions", "words", "text"],
+        usage: 'blitzreels captions words text --project-id ID --word-id ID --text "Fix"|--new-text "Fix"',
+        flags: ["project-id", "word-id", "text", "new-text"],
+    }),
+    commandSpec({
+        command: ["captions", "words", "batch-text"],
+        usage: 'blitzreels captions words batch-text --project-id ID --updates-json \'[{"word_id":"...","new_text":"..."}]\'',
+        flags: ["project-id", "updates-json"],
+    }),
+    commandSpec({
+        command: ["captions", "words", "style"],
+        usage: "blitzreels captions words style --project-id ID [--word-id ID|--word-ids IDs|--timeline-item-id ID|--match-text TEXT|--match-pattern numbers|caps|exclamations] [--style-json JSON|null] [--font-family Pacifico] [--font-weight 700] [--font-style italic] [--color '#17FFA6'] [--active-color '#fff'] [--background-color '#051914'] [--active-animation pop] [--text-transform uppercase] [--text-shadow '0 6px 18px #000'] [--glow-color '#17FFA6'] [--glow-blur-px 18] [--scale 1.45] [--offset-x 0] [--offset-y -8] [--rotation-deg -2] [--letter-spacing 1] [--opacity 1] [--clear-existing true]",
+        flags: [
+            "project-id",
+            ...CAPTION_WORD_SELECTOR_FLAGS,
+            ...CAPTION_WORD_STYLE_FLAGS,
+        ],
+    }),
+    commandSpec({
+        command: ["captions", "words", "emphasis"],
+        usage: "blitzreels captions words emphasis --project-id ID [--word-id ID|--word-ids IDs|--timeline-item-id ID|--match-text TEXT|--match-pattern numbers|caps|exclamations] [--emphasis true]",
+        flags: ["project-id", ...CAPTION_WORD_SELECTOR_FLAGS, "emphasis"],
+    }),
+    commandSpec({
+        command: ["captions", "words", "delete"],
+        usage: "blitzreels captions words delete --project-id ID --word-id ID|--word-ids ID1,ID2",
+        flags: ["project-id", "word-id", "word-ids"],
+    }),
+    commandSpec({
+        command: ["captions", "words", "merge"],
+        usage: 'blitzreels captions words merge --project-id ID --word-ids ID1,ID2 [--text "Merged"]',
+        flags: ["project-id", "word-ids", "text"],
+    }),
+    commandSpec({
+        command: ["captions", "words", "split"],
+        usage: 'blitzreels captions words split --project-id ID --word-id ID --words "foo,bar"',
+        flags: ["project-id", "word-id", "words"],
+    }),
+    commandSpec({
+        command: ["captions", "themes", "list"],
+        usage: "blitzreels captions themes list [--json]",
+    }),
+    commandSpec({
+        command: ["captions", "theme", "set"],
+        usage: "blitzreels captions theme set --project-id ID --theme-id ID",
+        flags: ["project-id", "theme-id"],
+    }),
+    commandSpec({
+        command: ["captions", "theme", "set-default"],
+        usage: "blitzreels captions theme set-default --theme-id ID",
+        flags: ["theme-id"],
+    }),
+    commandSpec({
+        command: ["exports", "start"],
+        usage: "blitzreels exports start --project-id ID [--resolution 1080p] [--format mp4] [--include-captions true]",
+        flags: ["project-id", "resolution", "format", "include-captions"],
+    }),
+    commandSpec({
+        command: ["exports", "wait"],
+        usage: "blitzreels exports wait --export-id ID [--interval-ms 3000] [--timeout-ms 1200000] [--json]",
+        flags: ["export-id", "interval-ms", "timeout-ms"],
+    }),
+    commandSpec({
+        command: ["exports", "download"],
+        usage: "blitzreels exports download --export-id ID --output ./short.mp4",
+        flags: ["export-id", "output"],
+    }),
+    commandSpec({
+        command: ["api", "docs"],
+        usage: "blitzreels api docs",
+    }),
+    commandSpec({
+        command: ["api", "spec"],
+        usage: "blitzreels api spec",
+    }),
+];
+class CliUsageError extends Error {
+    code;
+    suggestions;
+    usage;
+    constructor({ code, message, suggestions = [], usage, }) {
+        super(message);
+        this.name = "CliUsageError";
+        this.code = code;
+        this.suggestions = suggestions;
+        this.usage = usage;
+    }
+}
 async function main() {
     const parsed = parseArgs({ argv: process.argv.slice(2) });
-    if (parsed.command.length === 0 ||
-        getBooleanFlag({ flags: parsed.flags, name: "help" })) {
+    if (parsed.command.length === 0) {
         printHelp();
         return;
     }
+    if (getBooleanFlag({ flags: parsed.flags, name: "help" })) {
+        printCommandHelpOrThrow({ command: parsed.command });
+        return;
+    }
+    validateParsedArgs({ parsed });
     const config = await loadConfig();
     const apiKey = getStringFlag({ flags: parsed.flags, name: "api-key" }) ??
         process.env.BLITZREELS_API_KEY ??
@@ -408,7 +860,55 @@ async function runCommand({ context }) {
                 flags: context.args.flags,
                 name: "allow-duplicate",
             }),
+            positionPreset: parseMediaPositionPreset({
+                value: getStringFlag({
+                    flags: context.args.flags,
+                    name: "position-preset",
+                }),
+            }),
+            positionX: getNumberFlag({
+                flags: context.args.flags,
+                name: "position-x",
+            }),
+            positionY: getNumberFlag({
+                flags: context.args.flags,
+                name: "position-y",
+            }),
+            widthPx: getNumberFlag({
+                flags: context.args.flags,
+                name: "width-px",
+            }),
+            heightPx: getNumberFlag({
+                flags: context.args.flags,
+                name: "height-px",
+            }),
+            scale: getNumberFlag({ flags: context.args.flags, name: "scale" }),
+            opacity: getNumberFlag({ flags: context.args.flags, name: "opacity" }),
+            animationPreset: parseMediaAnimationPreset({
+                value: getStringFlag({
+                    flags: context.args.flags,
+                    name: "animation-preset",
+                }),
+            }),
         });
+        const requestedLayer = getNumberFlag({
+            flags: context.args.flags,
+            name: "layer-index",
+        });
+        if (requestedLayer !== undefined) {
+            await Promise.all(result.inserted
+                .map((item) => item.timeline_item_id)
+                .filter((item) => typeof item === "string")
+                .map((timelineItemId) => context.client.timeline.move({
+                projectId: requireStringFlag({
+                    flags: context.args.flags,
+                    name: "project-id",
+                }),
+                timelineItemId,
+                newStartSeconds: result.inserted.find((item) => item.timeline_item_id === timelineItemId)?.start_seconds ?? 0,
+                newLayerIndex: requestedLayer,
+            })));
+        }
         printResult({
             json: context.json,
             value: result,
@@ -600,21 +1100,33 @@ async function runCommand({ context }) {
         return;
     }
     if (group === "text" && action === "add") {
+        const text = requireStringFlag({ flags: context.args.flags, name: "text" });
+        const durationSeconds = getNumberFlag({ flags: context.args.flags, name: "duration" }) ?? 4;
+        const spec = parseJsonObjectFlag({ flags: context.args.flags, name: "spec-json" }) ??
+            (hasTextStyleFlags({ flags: context.args.flags })
+                ? buildTextOverlaySpec({
+                    text,
+                    name: getStringFlag({ flags: context.args.flags, name: "name" }),
+                    durationSeconds,
+                    flags: context.args.flags,
+                })
+                : undefined);
         const result = await context.client.text.add({
             projectId: requireStringFlag({
                 flags: context.args.flags,
                 name: "project-id",
             }),
-            text: requireStringFlag({ flags: context.args.flags, name: "text" }),
+            text,
             name: getStringFlag({ flags: context.args.flags, name: "name" }),
             startSeconds: parseTimecode({
                 value: getStringFlag({ flags: context.args.flags, name: "at" }) ?? "0",
             }),
-            durationSeconds: getNumberFlag({ flags: context.args.flags, name: "duration" }) ?? 4,
+            durationSeconds,
             layerIndex: getNumberFlag({
                 flags: context.args.flags,
                 name: "layer-index",
             }),
+            spec,
         });
         printResult({
             json: context.json,
@@ -656,6 +1168,29 @@ async function runCommand({ context }) {
         return;
     }
     if (group === "text" && action === "update") {
+        const explicitSpec = parseJsonObjectFlag({
+            flags: context.args.flags,
+            name: "spec-json",
+        });
+        const spec = explicitSpec ??
+            (hasTextStyleFlags({ flags: context.args.flags })
+                ? await buildUpdatedTextSpec({
+                    context,
+                    projectId: requireStringFlag({
+                        flags: context.args.flags,
+                        name: "project-id",
+                    }),
+                    contentItemId: requireStringFlag({
+                        flags: context.args.flags,
+                        name: "content-item-id",
+                    }),
+                    nextText: getStringFlag({
+                        flags: context.args.flags,
+                        name: "text",
+                    }),
+                    flags: context.args.flags,
+                })
+                : undefined);
         const result = await context.client.text.update({
             projectId: requireStringFlag({
                 flags: context.args.flags,
@@ -667,15 +1202,94 @@ async function runCommand({ context }) {
             }),
             text: getStringFlag({ flags: context.args.flags, name: "text" }),
             name: getStringFlag({ flags: context.args.flags, name: "name" }),
-            spec: parseJsonObjectFlag({
+            spec,
+        });
+        printResult({
+            json: context.json,
+            value: result,
+            human: ["Text updated."],
+        });
+        return;
+    }
+    if (group === "timeline" && action === "transform") {
+        const result = await context.client.timeline.transform({
+            projectId: requireStringFlag({
+                flags: context.args.flags,
+                name: "project-id",
+            }),
+            timelineItemId: requireStringFlag({
+                flags: context.args.flags,
+                name: "timeline-item-id",
+            }),
+            positionX: getNumberFlag({
+                flags: context.args.flags,
+                name: "position-x",
+            }),
+            positionY: getNumberFlag({
+                flags: context.args.flags,
+                name: "position-y",
+            }),
+            widthPx: parseNullableNumberFlag({
+                flags: context.args.flags,
+                name: "width-px",
+            }),
+            heightPx: parseNullableNumberFlag({
+                flags: context.args.flags,
+                name: "height-px",
+            }),
+            keepAspectRatio: getOptionalBooleanFlag({
                 flags: context.args.flags,
-                name: "spec-json",
+                name: "keep-aspect-ratio",
             }),
         });
         printResult({
             json: context.json,
             value: result,
-            human: ["Text updated."],
+            human: [JSON.stringify(result, null, 2)],
+        });
+        return;
+    }
+    if (group === "timeline" && action === "move") {
+        const result = await context.client.timeline.move({
+            projectId: requireStringFlag({
+                flags: context.args.flags,
+                name: "project-id",
+            }),
+            timelineItemId: requireStringFlag({
+                flags: context.args.flags,
+                name: "timeline-item-id",
+            }),
+            newStartSeconds: parseTimecode({
+                value: requireStringFlag({ flags: context.args.flags, name: "at" }),
+            }),
+            newLayerIndex: getNumberFlag({
+                flags: context.args.flags,
+                name: "layer-index",
+            }),
+        });
+        printResult({
+            json: context.json,
+            value: result,
+            human: [JSON.stringify(result, null, 2)],
+        });
+        return;
+    }
+    if (group === "timeline" && action === "delete") {
+        const result = await context.client.timeline.delete({
+            projectId: requireStringFlag({
+                flags: context.args.flags,
+                name: "project-id",
+            }),
+            timelineItemIds: parseTimelineItemIds({ flags: context.args.flags }),
+            autoPack: getOptionalBooleanFlag({
+                flags: context.args.flags,
+                name: "auto-pack",
+            }),
+        });
+        printResult({
+            json: context.json,
+            value: result,
+            human: [JSON.stringify(result, null, 2)],
         });
         return;
     }
@@ -850,6 +1464,154 @@ async function runCommand({ context }) {
         });
         return;
     }
+    if (group === "captions" && action === "words" && subaction === "list") {
+        const result = await context.client.captions.listWords({
+            projectId: requireStringFlag({
+                flags: context.args.flags,
+                name: "project-id",
+            }),
+            timelineItemId: getStringFlag({
+                flags: context.args.flags,
+                name: "timeline-item-id",
+            }),
+            matchText: getStringFlag({
+                flags: context.args.flags,
+                name: "match-text",
+            }),
+            limit: getNumberFlag({ flags: context.args.flags, name: "limit" }),
+            offset: getNumberFlag({ flags: context.args.flags, name: "offset" }),
+        });
+        printResult({
+            json: context.json,
+            value: result,
+            human: result.words.map((word) => JSON.stringify(word)),
+        });
+        return;
+    }
+    if (group === "captions" && action === "words" && subaction === "text") {
+        const result = await context.client.captions.updateWordText({
+            projectId: requireStringFlag({
+                flags: context.args.flags,
+                name: "project-id",
+            }),
+            wordId: requireStringFlag({ flags: context.args.flags, name: "word-id" }),
+            newText: getStringFlag({ flags: context.args.flags, name: "new-text" }) ??
+                requireStringFlag({ flags: context.args.flags, name: "text" }),
+        });
+        printResult({
+            json: context.json,
+            value: result,
+            human: [
+                `Updated ${result.word_id}: ${result.old_text} -> ${result.new_text}`,
+            ],
+        });
+        return;
+    }
+    if (group === "captions" &&
+        action === "words" &&
+        subaction === "batch-text") {
+        const result = await context.client.captions.batchUpdateWordText({
+            projectId: requireStringFlag({
+                flags: context.args.flags,
+                name: "project-id",
+            }),
+            updates: parseWordTextUpdatesFlag({
+                flags: context.args.flags,
+                name: "updates-json",
+            }),
+        });
+        printResult({
+            json: context.json,
+            value: result,
+            human: [result.message],
+        });
+        return;
+    }
+    if (group === "captions" && action === "words" && subaction === "style") {
+        const styleJson = parseNullableJsonObjectFlag({
+            flags: context.args.flags,
+            name: "style-json",
+        });
+        const style = styleJson === undefined
+            ? buildCaptionWordStyleFromFlags({ flags: context.args.flags })
+            : styleJson;
+        const result = await context.client.captions.setWordStyle({
+            ...buildCaptionWordSelector({ flags: context.args.flags }),
+            style,
+            clearExisting: getOptionalBooleanFlag({
+                flags: context.args.flags,
+                name: "clear-existing",
+            }),
+        });
+        printResult({
+            json: context.json,
+            value: result,
+            human: [`Updated ${result.updated_count} caption word(s).`],
+        });
+        return;
+    }
+    if (group === "captions" && action === "words" && subaction === "emphasis") {
+        const result = await context.client.captions.setWordEmphasis({
+            ...buildCaptionWordSelector({ flags: context.args.flags }),
+            emphasis: getOptionalBooleanFlag({
+                flags: context.args.flags,
+                name: "emphasis",
+            }) ?? true,
+        });
+        printResult({
+            json: context.json,
+            value: result,
+            human: [`Updated ${result.updated_count} caption word(s).`],
+        });
+        return;
+    }
+    if (group === "captions" && action === "words" && subaction === "delete") {
+        const result = await context.client.captions.deleteWords({
+            projectId: requireStringFlag({
+                flags: context.args.flags,
+                name: "project-id",
+            }),
+            wordIds: parseWordIds({ flags: context.args.flags }),
+        });
+        printResult({
+            json: context.json,
+            value: result,
+            human: [result.message],
+        });
+        return;
+    }
+    if (group === "captions" && action === "words" && subaction === "merge") {
+        const result = await context.client.captions.mergeWords({
+            projectId: requireStringFlag({
+                flags: context.args.flags,
+                name: "project-id",
+            }),
+            wordIds: parseWordIds({ flags: context.args.flags }),
+            text: getStringFlag({ flags: context.args.flags, name: "text" }),
+        });
+        printResult({
+            json: context.json,
+            value: result,
+            human: [result.message],
+        });
+        return;
+    }
+    if (group === "captions" && action === "words" && subaction === "split") {
+        const result = await context.client.captions.splitWord({
+            projectId: requireStringFlag({
+                flags: context.args.flags,
+                name: "project-id",
+            }),
+            wordId: requireStringFlag({ flags: context.args.flags, name: "word-id" }),
+            words: parseCsvRequiredFlag({ flags: context.args.flags, name: "words" }),
+        });
+        printResult({
+            json: context.json,
+            value: result,
+            human: [result.message],
+        });
+        return;
+    }
     if (group === "captions" && action === "themes" && subaction === "list") {
         const result = await context.client.captions.listThemes();
         printResult({
@@ -955,7 +1717,7 @@ async function runCommand({ context }) {
         });
         return;
     }
-    throw new Error(`Unknown command: ${context.args.command.join(" ")}`);
+    throw buildUnknownCommandError({ command: context.args.command });
 }
 async function setApiKey({ context }) {
     const apiKey = getStringFlag({ flags: context.args.flags, name: "api-key" }) ??
@@ -1228,6 +1990,118 @@ function parseArgs({ argv }) {
     }
     return { command, flags };
 }
+function validateParsedArgs({ parsed }) {
+    const spec = findCommandSpec({ command: parsed.command });
+    if (!spec) {
+        throw buildUnknownCommandError({ command: parsed.command });
+    }
+    const allowedFlags = new Set([...GLOBAL_FLAGS, ...spec.flags]);
+    for (const flag of Object.keys(parsed.flags)) {
+        if (!allowedFlags.has(flag)) {
+            throw buildUnknownFlagError({ spec, flag });
+        }
+    }
+}
+function findCommandSpec({ command, }) {
+    return COMMAND_SPECS.find((spec) => commandsEqual(spec.command, command));
+}
+function commandsEqual(left, right) {
+    return (left.length === right.length &&
+        left.every((part, index) => part === right[index]));
+}
+function commandLabel({ command }) {
+    return command.join(" ");
+}
+function printCommandHelpOrThrow({ command }) {
+    const spec = findCommandSpec({ command });
+    if (!spec) {
+        throw buildUnknownCommandError({ command });
+    }
+    printCommandHelp({ spec });
+}
+function printCommandHelp({ spec }) {
+    const flags = [...new Set([...spec.flags, ...GLOBAL_FLAGS])].sort();
+    console.log(`Usage:
+  ${spec.usage}
+
+Flags:
+${flags.map((flag) => `  --${flag}`).join("\n")}
+`);
+}
+function buildUnknownCommandError({ command, }) {
+    const suggestions = suggestCommands({ command }).map((spec) => spec.usage);
+    return new CliUsageError({
+        code: "unknown_command",
+        message: `Unknown command: ${commandLabel({ command })}`,
+        suggestions,
+        usage: suggestions[0],
+    });
+}
+function buildUnknownFlagError({ spec, flag, }) {
+    const flags = [...new Set([...spec.flags, ...GLOBAL_FLAGS])];
+    const suggestions = suggestValues({ value: flag, candidates: flags }).map((candidate) => `--${candidate}`);
+    return new CliUsageError({
+        code: "unknown_flag",
+        message: `Unknown flag --${flag} for \`${commandLabel({ command: spec.command })}\`.`,
+        suggestions,
+        usage: spec.usage,
+    });
+}
+function suggestCommands({ command }) {
+    const joined = commandLabel({ command });
+    const prefixMatches = COMMAND_SPECS.filter((spec) => commandsEqual(spec.command.slice(0, command.length), command));
+    if (prefixMatches.length > 0) {
+        return prefixMatches.slice(0, 3);
+    }
+    return COMMAND_SPECS.map((spec) => ({
+        spec,
+        score: commandSimilarity({
+            left: joined,
+            right: commandLabel({ command: spec.command }),
+        }),
+    }))
+        .filter((item) => item.score >= 0.45)
+        .sort((left, right) => right.score - left.score)
+        .slice(0, 3)
+        .map((item) => item.spec);
+}
+function suggestValues({ value, candidates, }) {
+    return candidates
+        .map((candidate) => ({
+        candidate,
+        score: commandSimilarity({ left: value, right: candidate }),
+    }))
+        .filter((item) => item.score >= 0.45)
+        .sort((left, right) => right.score - left.score)
+        .slice(0, 3)
+        .map((item) => item.candidate);
+}
+function commandSimilarity({ left, right, }) {
+    const maxLength = Math.max(left.length, right.length);
+    if (maxLength === 0) {
+        return 1;
+    }
+    return 1 - levenshteinDistance({ left, right }) / maxLength;
+}
+function levenshteinDistance({ left, right, }) {
+    const previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+    const current = Array.from({ length: right.length + 1 }, () => 0);
+    for (let leftIndex = 1; leftIndex <= left.length; leftIndex++) {
+        current[0] = leftIndex;
+        for (let rightIndex = 1; rightIndex <= right.length; rightIndex++) {
+            const substitutionCost = left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1;
+            current[rightIndex] = Math.min((current[rightIndex - 1] ?? 0) + 1, (previous[rightIndex] ?? 0) + 1, (previous[rightIndex - 1] ?? 0) + substitutionCost);
+        }
+        for (let index = 0; index < previous.length; index++) {
+            previous[index] = current[index] ?? 0;
+        }
+    }
+    return previous[right.length] ?? 0;
+}
+function usageForCurrentCommand() {
+    const parsed = parseArgs({ argv: process.argv.slice(2) });
+    return findCommandSpec({ command: parsed.command })?.usage;
+}
 function getStringFlag({ flags, name, }) {
     const value = flags[name];
     return typeof value === "string" ? value : undefined;
@@ -1259,6 +2133,20 @@ function getNumberFlag({ flags, name, }) {
     }
     return parsed;
 }
+function parseNullableNumberFlag({ flags, name, }) {
+    const value = getStringFlag({ flags, name });
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === "null") {
+        return null;
+    }
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed)) {
+        throw new Error(`--${name} must be a number or null.`);
+    }
+    return parsed;
+}
 function parseJsonObjectFlag({ flags, name, }) {
     const value = getStringFlag({ flags, name });
     if (value === undefined) {
@@ -1270,6 +2158,31 @@ function parseJsonObjectFlag({ flags, name, }) {
     }
     return parsed;
 }
+function parseNullableJsonObjectFlag({ flags, name, }) {
+    const value = getStringFlag({ flags, name });
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === "null") {
+        return null;
+    }
+    const parsed = JSON.parse(value);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`--${name} must be a JSON object or null.`);
+    }
+    return parsed;
+}
+function parseJsonArrayFlag({ flags, name, }) {
+    const value = getStringFlag({ flags, name });
+    if (value === undefined) {
+        return undefined;
+    }
+    const parsed = JSON.parse(value);
+    if (!Array.isArray(parsed)) {
+        throw new Error(`--${name} must be a JSON array.`);
+    }
+    return parsed;
+}
 function parseCsvFlag({ flags, name, }) {
     const value = getStringFlag({ flags, name });
     if (value === undefined) {
@@ -1280,6 +2193,13 @@ function parseCsvFlag({ flags, name, }) {
         .map((item) => item.trim())
         .filter((item) => item.length > 0);
 }
+function parseCsvRequiredFlag({ flags, name, }) {
+    const parsed = parseCsvFlag({ flags, name });
+    if (parsed === undefined || parsed.length === 0) {
+        throw new Error(`Missing required --${name}.`);
+    }
+    return parsed;
+}
 function parseNullableStringFlag({ flags, name, }) {
     const value = getStringFlag({ flags, name });
     if (value === undefined) {
@@ -1480,6 +2400,45 @@ function parseYoutubeQuality({ value, }) {
     }
     throw new Error("--quality must be 720p, 1080p, 1440p, or 2160p.");
 }
+function parseMediaPositionPreset({ value, }) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === "center" ||
+        value === "top-left" ||
+        value === "top-right" ||
+        value === "bottom-left" ||
+        value === "bottom-right" ||
+        value === "full-screen") {
+        return value;
+    }
+    throw new Error("--position-preset must be center, top-left, top-right, bottom-left, bottom-right, or full-screen.");
+}
+function parseMediaAnimationPreset({ value, }) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === "none" ||
+        value === "fadeIn" ||
+        value === "fadeOut" ||
+        value === "zoomIn" ||
+        value === "slideIn" ||
+        value === "popIn" ||
+        value === "bounce" ||
+        value === "spin") {
+        return value;
+    }
+    throw new Error("--animation-preset must be none, fadeIn, fadeOut, zoomIn, slideIn, popIn, bounce, or spin.");
+}
+function parseCaptionMatchPattern({ value, }) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === "numbers" || value === "caps" || value === "exclamations") {
+        return value;
+    }
+    throw new Error("--match-pattern must be numbers, caps, or exclamations.");
+}
 function parseFolderIdFlag({ flags, name, }) {
     const value = getStringFlag({ flags, name });
     if (value === undefined) {
@@ -1508,6 +2467,45 @@ function parseAssetIds({ flags }) {
         .map((item) => item.trim())
         .filter((item) => item.length > 0);
 }
+function parseTimelineItemIds({ flags }) {
+    const csv = getStringFlag({ flags, name: "timeline-item-ids" }) ??
+        getStringFlag({ flags, name: "timeline-item-id" });
+    if (!csv) {
+        throw new Error("Missing required --timeline-item-id or --timeline-item-ids.");
+    }
+    return csv
+        .split(",")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+}
+function parseWordIds({ flags }) {
+    const csv = getStringFlag({ flags, name: "word-ids" }) ??
+        getStringFlag({ flags, name: "word-id" });
+    if (!csv) {
+        throw new Error("Missing required --word-id or --word-ids.");
+    }
+    return csv
+        .split(",")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+}
+function parseWordTextUpdatesFlag({ flags, name, }) {
+    const parsed = parseJsonArrayFlag({ flags, name });
+    if (parsed === undefined) {
+        throw new Error(`Missing required --${name}.`);
+    }
+    return parsed.map((item, index) => {
+        if (!item || typeof item !== "object" || Array.isArray(item)) {
+            throw new Error(`--${name}[${index}] must be an object.`);
+        }
+        const record = item;
+        if (typeof record.word_id !== "string" ||
+            typeof record.new_text !== "string") {
+            throw new Error(`--${name}[${index}] must include word_id and new_text.`);
+        }
+        return { word_id: record.word_id, new_text: record.new_text };
+    });
+}
 function inferContentType({ filePath }) {
     const extension = extname(filePath).toLowerCase();
     switch (extension) {
@@ -1618,6 +2616,271 @@ function buildWorkspaceDefaults({ flags }) {
     }
     return defaults;
 }
+const TEXT_STYLE_FLAG_NAMES = [
+    "font-family",
+    "font-size",
+    "font-weight",
+    "color",
+    "background-color",
+    "padding-x",
+    "padding-y",
+    "border-radius",
+    "top",
+    "left",
+    "text-align",
+    "text-shadow",
+    "no-background",
+];
+function hasTextStyleFlags({ flags }) {
+    return TEXT_STYLE_FLAG_NAMES.some((name) => name in flags);
+}
+function buildTextOverlaySpec({ text, name, durationSeconds, flags, }) {
+    const durationInFrames = Math.max(1, Math.round(durationSeconds * 30));
+    const top = getStringFlag({ flags, name: "top" }) ?? "18%";
+    const left = getStringFlag({ flags, name: "left" }) ?? "50%";
+    const textStyle = buildTextStyle({ flags });
+    return {
+        id: `cli-${Date.now()}`,
+        fps: 30,
+        mode: "elements",
+        name: name ?? text,
+        fonts: [String(textStyle.fontFamily ?? "Inter")],
+        width: 1080,
+        height: 1920,
+        defaults: {
+            color: textStyle.color,
+            fontSize: textStyle.fontSize,
+            fontFamily: textStyle.fontFamily,
+        },
+        elements: [
+            {
+                id: `group-${Date.now()}`,
+                type: "group",
+                style: {
+                    top,
+                    left,
+                    display: "inline-flex",
+                    opacity: {
+                        keyframes: [
+                            { frame: 0, value: 0 },
+                            { frame: 10, value: 1 },
+                            { frame: Math.max(10, durationInFrames - 10), value: 1 },
+                            { frame: durationInFrames, value: 0 },
+                        ],
+                    },
+                    position: "absolute",
+                    transform: "translate(-50%, -50%)",
+                    alignItems: "center",
+                    flexDirection: "column",
+                },
+                children: [
+                    {
+                        id: `text-${Date.now()}`,
+                        type: "text",
+                        style: textStyle,
+                        layout: "none",
+                        content: text,
+                    },
+                ],
+            },
+        ],
+        metadata: {
+            kind: "overlay",
+            createdBy: "blitzreels-cli",
+        },
+        durationInFrames,
+    };
+}
+function buildTextStyle({ flags }) {
+    const noBackground = getBooleanFlag({ flags, name: "no-background" });
+    const backgroundColor = noBackground
+        ? "transparent"
+        : (getStringFlag({ flags, name: "background-color" }) ??
+            "rgba(17, 24, 39, 0.86)");
+    const style = {
+        color: getStringFlag({ flags, name: "color" }) ?? "#FFFFFF",
+        padding: `${getNumberFlag({ flags, name: "padding-y" }) ?? 12}px ${getNumberFlag({ flags, name: "padding-x" }) ?? 24}px`,
+        fontSize: getNumberFlag({ flags, name: "font-size" }) ?? 48,
+        textAlign: parseTextAlign({
+            value: getStringFlag({ flags, name: "text-align" }) ?? "center",
+        }),
+        fontFamily: getStringFlag({ flags, name: "font-family" }) ?? "Inter",
+        fontWeight: getStringFlag({ flags, name: "font-weight" }) ?? "700",
+        lineHeight: 1.12,
+        textShadow: getStringFlag({ flags, name: "text-shadow" }) ??
+            "0 8px 22px rgba(0, 0, 0, 0.52)",
+        borderRadius: getNumberFlag({ flags, name: "border-radius" }) ?? 18,
+        letterSpacing: 0,
+        backgroundColor,
+        bubbleJoinStyle: "reverse-radius",
+        boxDecorationBreak: "clone",
+    };
+    return style;
+}
+async function buildUpdatedTextSpec({ context, projectId, contentItemId, nextText, flags, }) {
+    const items = await context.client.text.list({ projectId });
+    const item = items.data.find((candidate) => candidate.content_item_id === contentItemId);
+    if (!item?.spec) {
+        throw new Error(`Content item ${contentItemId} has no editable text spec.`);
+    }
+    return applyTextStyleToSpec({
+        spec: item.spec,
+        text: nextText,
+        flags,
+    });
+}
+function applyTextStyleToSpec({ spec, text, flags, }) {
+    const cloned = JSON.parse(JSON.stringify(spec));
+    const elements = Array.isArray(cloned.elements) ? cloned.elements : [];
+    const firstGroup = elements.find((element) => Boolean(element) &&
+        typeof element === "object" &&
+        element.type === "group");
+    const children = Array.isArray(firstGroup?.children)
+        ? firstGroup.children
+        : [];
+    const firstText = children.find((child) => Boolean(child) &&
+        typeof child === "object" &&
+        child.type === "text");
+    if (!firstText) {
+        throw new Error("Text overlay spec has no editable text element.");
+    }
+    firstText.style = {
+        ...(firstText.style ?? {}),
+        ...buildTextStyle({ flags }),
+    };
+    if (text !== undefined) {
+        firstText.content = text;
+    }
+    if (firstGroup) {
+        const style = (firstGroup.style ??
+            {});
+        firstGroup.style = {
+            ...style,
+            top: getStringFlag({ flags, name: "top" }) ?? style.top,
+            left: getStringFlag({ flags, name: "left" }) ?? style.left,
+        };
+    }
+    return cloned;
+}
+function parseTextAlign({ value, }) {
+    if (value === "left" ||
+        value === "center" ||
+        value === "right" ||
+        value === "justify") {
+        return value;
+    }
+    throw new Error("--text-align must be left, center, right, or justify.");
+}
+function buildCaptionWordSelector({ flags }) {
+    const wordIds = parseCsvFlag({ flags, name: "word-ids" }) ??
+        parseCsvFlag({ flags, name: "word-id" });
+    return {
+        projectId: requireStringFlag({ flags, name: "project-id" }),
+        wordIds,
+        matchText: getStringFlag({ flags, name: "match-text" }),
+        matchPattern: parseCaptionMatchPattern({
+            value: getStringFlag({ flags, name: "match-pattern" }),
+        }),
+        timelineItemId: getStringFlag({ flags, name: "timeline-item-id" }),
+    };
+}
+function buildCaptionWordStyleFromFlags({ flags, }) {
+    const style = {};
+    setIfDefined({
+        target: style,
+        key: "fontFamily",
+        value: getStringFlag({ flags, name: "font-family" }),
+    });
+    setIfDefined({
+        target: style,
+        key: "fontWeight",
+        value: getStringFlag({ flags, name: "font-weight" }),
+    });
+    setIfDefined({
+        target: style,
+        key: "color",
+        value: getStringFlag({ flags, name: "color" }),
+    });
+    setIfDefined({
+        target: style,
+        key: "activeColor",
+        value: getStringFlag({ flags, name: "active-color" }),
+    });
+    setIfDefined({
+        target: style,
+        key: "backgroundColor",
+        value: getStringFlag({ flags, name: "background-color" }),
+    });
+    setIfDefined({
+        target: style,
+        key: "fontStyle",
+        value: getStringFlag({ flags, name: "font-style" }),
+    });
+    setIfDefined({
+        target: style,
+        key: "activeAnimation",
+        value: getStringFlag({ flags, name: "active-animation" }),
+    });
+    setIfDefined({
+        target: style,
+        key: "textTransform",
+        value: getStringFlag({ flags, name: "text-transform" }),
+    });
+    setIfDefined({
+        target: style,
+        key: "textShadow",
+        value: getStringFlag({ flags, name: "text-shadow" }),
+    });
+    setIfDefined({
+        target: style,
+        key: "glowColor",
+        value: getStringFlag({ flags, name: "glow-color" }),
+    });
+    setIfDefined({
+        target: style,
+        key: "scale",
+        value: getNumberFlag({ flags, name: "scale" }),
+    });
+    setIfDefined({
+        target: style,
+        key: "offsetX",
+        value: getNumberFlag({ flags, name: "offset-x" }),
+    });
+    setIfDefined({
+        target: style,
+        key: "offsetY",
+        value: getNumberFlag({ flags, name: "offset-y" }),
+    });
+    setIfDefined({
+        target: style,
+        key: "rotationDeg",
+        value: getNumberFlag({ flags, name: "rotation-deg" }),
+    });
+    setIfDefined({
+        target: style,
+        key: "letterSpacing",
+        value: getNumberFlag({ flags, name: "letter-spacing" }),
+    });
+    setIfDefined({
+        target: style,
+        key: "opacity",
+        value: getNumberFlag({ flags, name: "opacity" }),
+    });
+    setIfDefined({
+        target: style,
+        key: "glowBlurPx",
+        value: getNumberFlag({ flags, name: "glow-blur-px" }),
+    });
+    if (Object.keys(style).length === 0) {
+        throw new Error("Provide --style-json or at least one caption word style flag.");
+    }
+    return style;
+}
+function setIfDefined({ target, key, value, }) {
+    if (value !== undefined) {
+        target[key] = value;
+    }
+}
 function parseContextMode({ value, }) {
     if (value === "summary" ||
         value === "assets" ||
@@ -1644,52 +2907,7 @@ function printHelp() {
     console.log(`blitzreels
 
 Usage:
-  blitzreels auth login [--no-browser]
-  blitzreels auth set-key --api-key KEY [--base-url URL]
-  blitzreels auth whoami [--json]
-  blitzreels workspace settings get [--json]
-  blitzreels workspace settings update [--name NAME] [--protected-words foo,bar]
-  blitzreels projects list [--search QUERY] [--status active|archived|all]
-  blitzreels projects create --name NAME [--aspect-ratio 9:16]
-  blitzreels projects get --project-id ID [--json]
-  blitzreels projects rename --project-id ID --name NAME
-  blitzreels projects update --project-id ID [--name NAME] [--description TEXT]
-  blitzreels projects delete --project-id ID --confirm-delete
-  blitzreels media list [--asset-type video|audio|image|document] [--json]
-  blitzreels media get --asset-id ID [--json]
-  blitzreels media delete --asset-id ID --confirm-delete
-  blitzreels media upload --file ./video.mp4 [--auto-transcribe true]
-  blitzreels media import-youtube --url URL [--folder-id ID] [--quality 1080p]
-  blitzreels media rename --asset-id ID --name NAME
-  blitzreels media update --asset-id ID [--description TEXT] [--folder-id ID|root]
-  blitzreels media move --asset-id ID --target-folder-id ID|root
-  blitzreels media attach --project-id ID --asset-id ID [--at 0]
-  blitzreels media folders list [--json]
-  blitzreels media folders create --name NAME [--parent-folder-id ID]
-  blitzreels media folders rename --folder-id ID --name NAME
-  blitzreels media folders update --folder-id ID [--parent-folder-id ID|root]
-  blitzreels media folders delete --folder-id ID --confirm-delete
-  blitzreels project inspect --project-id ID [--mode full] [--json]
-  blitzreels project timeline --project-id ID [--json]
-  blitzreels project snapshot --project-id ID --at 00:03 [--json]
-  blitzreels project snapshots --project-id ID --at 00:01,00:03 [--json]
-  blitzreels text add --project-id ID --text "Hook" [--at 0] [--duration 4]
-  blitzreels text list --project-id ID [--json]
-  blitzreels text update --project-id ID --content-item-id ID [--text "New hook"]
-  blitzreels text remove --project-id ID --content-item-id ID
-  blitzreels audio add --project-id ID --asset-id ID [--at 0] [--volume 0.6]
-  blitzreels silence plan --project-id ID --timeline-item-id ID [--json]
-  blitzreels silence apply --project-id ID --timeline-item-id ID --confirm-preview
-  blitzreels mistakes plan --project-id ID --timeline-item-id ID [--json]
-  blitzreels mistakes apply --project-id ID --timeline-item-id ID --confirm-preview
-  blitzreels captions themes list [--json]
-  blitzreels captions theme set --project-id ID --theme-id ID
-  blitzreels captions theme set-default --theme-id ID
-  blitzreels exports start --project-id ID [--resolution 1080p] [--format mp4]
-  blitzreels exports wait --export-id ID [--json]
-  blitzreels exports download --export-id ID --output ./short.mp4
-  blitzreels api docs
-  blitzreels api spec
+${COMMAND_SPECS.map((spec) => `  ${spec.usage}`).join("\n")}
 
 Global flags:
   --api-key KEY
@@ -1698,14 +2916,69 @@ Global flags:
 `);
 }
 main().catch((error) => {
+    const json = isJsonOutputRequested();
     if (error instanceof BlitzReelsError) {
-        const requestId = error.requestId ? ` request_id=${error.requestId}` : "";
-        console.error(`BlitzReels API error ${error.status}:${requestId} ${error.message}`);
+        printCliError({
+            json,
+            code: "api_error",
+            message: `BlitzReels API error ${error.status}: ${error.message}`,
+            status: error.status,
+            requestId: error.requestId ?? undefined,
+            usage: usageForCurrentCommand(),
+        });
         process.exitCode = 1;
         return;
     }
-    const message = error instanceof Error ? error.message : String(error);
-    console.error(message);
+    if (error instanceof CliUsageError) {
+        printCliError({
+            json,
+            code: error.code,
+            message: error.message,
+            suggestions: error.suggestions,
+            usage: error.usage,
+        });
+        process.exitCode = 1;
+        return;
+    }
+    const usage = usageForCurrentCommand();
+    printCliError({
+        json,
+        code: "cli_error",
+        message: error instanceof Error ? error.message : String(error),
+        usage,
+    });
     process.exitCode = 1;
 });
+function isJsonOutputRequested() {
+    return process.argv.slice(2).some((value) => value === "--json");
+}
+function printCliError({ json, code, message, suggestions = [], usage, status, requestId, }) {
+    if (json) {
+        console.error(JSON.stringify({
+            error: {
+                code,
+                message,
+                suggestions,
+                usage,
+                status,
+                request_id: requestId,
+            },
+        }, null, 2));
+        return;
+    }
+    console.error(message);
+    if (suggestions.length > 0) {
+        console.error("Did you mean?");
+        for (const suggestion of suggestions) {
+            console.error(`  ${suggestion.startsWith("--") ? suggestion : suggestion}`);
+        }
+    }
+    if (usage) {
+        console.error("Usage:");
+        console.error(`  ${usage}`);
+    }
+    if (requestId) {
+        console.error(`Request ID: ${requestId}`);
+    }
+}
 //# sourceMappingURL=index.js.map