@clipit-ai/cli 0.2.1

package/bin/clipit.mjs

@@ -0,0 +1,2183 @@
+#!/usr/bin/env node
+import { createHash, randomBytes } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { createReadStream } from 'node:fs';
+import { Transform } from 'node:stream';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const VERSION = '0.2.1';
+const DEFAULT_BASE_URL = 'https://clipit.dev';
+const DEFAULT_SCOPES = [
+  'clippy_agent',
+  'video_processing',
+  'url_extraction',
+  'file_upload',
+  'transcription',
+  'clip_generation',
+  'caption_generation',
+  'thumbnail_generation',
+  'broll_generation',
+  'audio_generation',
+  'video_alteration',
+];
+
+const GET_RETRY_DELAYS_MS = [500, 2000];
+const RETRY_AFTER_CAP_MS = 10_000;
+const RETRYABLE_GET_STATUSES = new Set([429, 502, 503, 504]);
+const RECENT_LIMIT = 20;
+const REMOTION_ESTIMATED_USD_PER_VIDEO_SECOND = 0.0015;
+const MAX_CREDITS_ESTIMATE_MAP = Object.freeze({
+  'exports start': [{ operationType: 'lambda_render', provider: 'aws_lambda', modelId: 'remotion-4.0', metrics: 'remotion-render' }],
+  'thumbnails generate': [{ operationType: 'thumbnail_generation', provider: 'replicate', modelId: 'openai/gpt-image-2', metrics: 'one-generation' }],
+  'broll plan': [{ operationType: 'ai_chat', provider: 'openrouter', modelId: 'minimax/minimax-m2.7', metrics: 'broll-plan' }],
+  'broll generate': [
+    { operationType: 'image_generation', provider: 'replicate', modelId: 'openai/gpt-image-2', metrics: 'broll-images' },
+    { operationType: 'video_generation', provider: 'replicate', modelId: 'alibaba/happyhorse-1.0', metrics: 'broll-video' },
+  ],
+  'clips render': [{ operationType: 'lambda_render', provider: 'aws_lambda', modelId: 'remotion-4.0', metrics: 'remotion-render' }],
+  'videos import-url': [{ operationType: null, provider: null, metrics: 'url-import' }],
+  'social post': [{ operationType: 'social_post', provider: 'zernio', metrics: 'social-platforms' }],
+  'social schedule': [{ operationType: 'social_post', provider: 'zernio', metrics: 'social-platforms' }],
+});
+
+const EXIT = {
+  OK: 0,
+  USAGE: 2,
+  AUTH: 10,
+  PERMISSION: 11,
+  CONFIRMATION: 12,
+  CREDITS: 13,
+  NETWORK: 20,
+  SERVER: 21,
+};
+const TERMINAL_JOB_STATUSES = new Set(['completed', 'failed', 'cancelled']);
+const TERMINAL_WORKFLOW_STATUSES = new Set(['completed', 'failed', 'cancelled']);
+const WORKFLOW_APPROVAL_DECISIONS = new Set(['approved', 'cheaper', 'cancelled']);
+const KNOWN_AGENT_TARGETS = ['codex', 'claude', 'hermes', 'generic'];
+const TRUSTED_HOSTS = new Set(['clipit.dev', 'www.clipit.dev', 'localhost', '127.0.0.1', '::1', '[::1]']);
+const AGENT_SKILL_META_FILENAME = 'SKILL.meta.json';
+
+function configDir() {
+  if (process.env.CLIPIT_CONFIG_DIR) return process.env.CLIPIT_CONFIG_DIR;
+  if (process.platform === 'win32' && process.env.APPDATA) return path.join(process.env.APPDATA, 'ClipIt');
+  return path.join(os.homedir(), '.config', 'clipit');
+}
+
+function configPath() {
+  return path.join(configDir(), 'config.json');
+}
+
+async function readConfig() {
+  try {
+    return JSON.parse(await fs.readFile(configPath(), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+async function writeConfig(config) {
+  await fs.mkdir(configDir(), { recursive: true, mode: 0o700 });
+  await fs.writeFile(configPath(), `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+}
+
+function profileName(config, options) {
+  return String(options.profile || process.env.CLIPIT_PROFILE || config.currentProfile || 'default');
+}
+
+function legacyProfile(config) {
+  return {
+    baseUrl: config.baseUrl,
+    apiKey: config.apiKey,
+    keyInfo: config.keyInfo,
+    loginSource: config.loginSource,
+    activeContext: config.activeContext,
+    recent: config.recent,
+    updatedAt: config.updatedAt,
+  };
+}
+
+function profileData(config, options) {
+  const name = profileName(config, options);
+  const fromProfiles = config.profiles?.[name] || {};
+  return name === 'default' ? { ...legacyProfile(config), ...fromProfiles } : fromProfiles;
+}
+
+function updateProfile(config, options, updates) {
+  const name = profileName(config, options);
+  const profiles = { ...(config.profiles || {}) };
+  const current = profileData(config, options);
+  const nextProfile = { ...current, ...updates, updatedAt: new Date().toISOString() };
+  profiles[name] = nextProfile;
+
+  const next = {
+    ...config,
+    profiles,
+    currentProfile: name,
+    updatedAt: nextProfile.updatedAt,
+  };
+
+  if (name === 'default') {
+    Object.assign(next, nextProfile);
+  }
+
+  return next;
+}
+
+function recentEntries(config, options) {
+  const recent = profileData(config, options).recent;
+  return Array.isArray(recent) ? recent : [];
+}
+
+function appendRecentEntry(config, options, type, id) {
+  if (!id) return config;
+  const entry = { type, id: String(id), at: new Date().toISOString() };
+  const recent = [
+    entry,
+    ...recentEntries(config, options).filter((item) => item?.type !== entry.type || item?.id !== entry.id),
+  ].slice(0, RECENT_LIMIT);
+  return updateProfile(config, options, { recent });
+}
+
+function appendRecentEntries(config, options, entries) {
+  return entries.reduce((nextConfig, entry) => appendRecentEntry(nextConfig, options, entry.type, entry.id), config);
+}
+
+function removeProfileFields(config, options, fields) {
+  const name = profileName(config, options);
+  const profiles = { ...(config.profiles || {}) };
+  const nextProfile = { ...profileData(config, options), updatedAt: new Date().toISOString() };
+  for (const field of fields) delete nextProfile[field];
+  profiles[name] = nextProfile;
+
+  const next = {
+    ...config,
+    profiles,
+    currentProfile: name,
+    updatedAt: nextProfile.updatedAt,
+  };
+
+  if (name === 'default') {
+    for (const field of fields) delete next[field];
+    Object.assign(next, nextProfile);
+  }
+
+  return next;
+}
+
+function parseArgv(argv) {
+  const options = {};
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith('--')) {
+      positionals.push(arg);
+      continue;
+    }
+    const eq = arg.indexOf('=');
+    if (eq !== -1) {
+      options[arg.slice(2, eq)] = arg.slice(eq + 1);
+      continue;
+    }
+    const key = arg.slice(2);
+    const next = argv[i + 1];
+    if (next && !next.startsWith('--')) {
+      options[key] = next;
+      i++;
+    } else {
+      options[key] = true;
+    }
+  }
+  return { options, positionals };
+}
+
+function wantJson(options) {
+  return options.json === true || options.json === 'true';
+}
+
+function redact(value) {
+  if (typeof value !== 'string') return value;
+  return value
+    .replace(/clipper_[a-f0-9]{24,}/gi, 'clipper_[redacted]')
+    .replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/g, 'Bearer [redacted]')
+    .replace(/([?&](?:X-Amz-Signature|Signature|token|key)=)[^&\s]+/gi, '$1[redacted]');
+}
+
+function output(data, options) {
+  if (wantJson(options)) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+  if (typeof data === 'string') {
+    console.log(data);
+    return;
+  }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+function redactDeep(value) {
+  if (typeof value === 'string') return redact(value);
+  if (Array.isArray(value)) return value.map((item) => redactDeep(item));
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, redactDeep(entry)]));
+  }
+  return value;
+}
+
+function usage() {
+  return [
+    'ClipIt CLI',
+    '',
+    'Global flags: --json --profile <name> --base-url <url> --allow-custom-host --no-retry --max-credits <n>',
+    '',
+    'Usage:',
+    '  clipit login [--base-url URL] [--profile NAME] [--no-browser]',
+    '  clipit setup [--agent codex|claude|hermes|openclaw|<any-framework>]',
+    '  clipit doctor [--json]',
+    '  clipit auth status [--json]',
+    '  clipit auth set-key --stdin',
+    '  clipit auth profiles',
+    '  clipit context use [--video-id id] [--clip-id id] [--project-id id] [--sequence-id id]',
+    '  clipit context show|clear|build [--json]',
+    '  clipit skills list [--json]',
+    '  clipit tools list [--skill clip] [--json]',
+    '  clipit tools describe <functionName>',
+    '  clipit ask "<prompt>" [--video-id id] [--clip-id id] [--conversation-id id] [--quick] [--stream] [--json]',
+    '  clipit workflow status|wait <jobId> [--stream] [--json]',
+    '  clipit workflow approve <jobId> --approval-id id [--decision approved|cheaper|cancelled]',
+    '  clipit run <functionName> [--params @file.json] [--clip-id id] [--video-id id] [--confirm] [--max-credits n]',
+    '  clipit videos list|get|upload|import-url|transcribe|transcript|suggest-clips|delete ...',
+    '  clipit clips list|get|create|update|render|download|delete ...',
+    '  clipit jobs get|wait <jobId>',
+    '  clipit credits balance|usage|estimate ...',
+    '  clipit analytics overview|top-clips|post ...',
+    '  clipit exports start|list|get|wait|download|cancel ...',
+    '  clipit assets list|upload|delete ...',
+    '  clipit thumbnails generate|get|list ...',
+    '  clipit broll plan|generate|list|get ...',
+    '  clipit social accounts|post|schedule|posts|get|cancel ...',
+    '  clipit open clip|video|settings ...',
+    '  clipit links clip|video|settings ...',
+    '  clipit agent install|update|uninstall|doctor|print-skill|list codex|claude|hermes|openclaw|<any-framework>',
+    '  clipit examples',
+  ].join('\n');
+}
+
+function getBaseUrl(config, options) {
+  const profile = profileData(config, options);
+  return String(options['base-url'] || process.env.CLIPPER_BASE_URL || profile.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '');
+}
+
+function getApiKey(config, options) {
+  const profile = profileData(config, options);
+  return process.env.CLIPPER_API_KEY || options['api-key'] || profile.apiKey || null;
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+function boolOption(value) {
+  return value === true || value === 'true' || value === '1' || value === 'yes';
+}
+
+function configuredTrustedHosts() {
+  return String(process.env.CLIPIT_TRUSTED_HOSTS || '')
+    .split(',')
+    .map((host) => host.trim().toLowerCase())
+    .filter(Boolean);
+}
+
+function isTrustedBaseUrl(baseUrl) {
+  try {
+    const parsed = new URL(baseUrl);
+    const hostname = parsed.hostname.toLowerCase();
+    if (parsed.protocol !== 'https:' && !(parsed.protocol === 'http:' && TRUSTED_HOSTS.has(hostname))) {
+      return false;
+    }
+    return TRUSTED_HOSTS.has(hostname)
+      || hostname.endsWith('.clipit.dev')
+      || configuredTrustedHosts().includes(hostname);
+  } catch {
+    return false;
+  }
+}
+
+function allowCustomHost(options) {
+  return boolOption(options['allow-custom-host']) || boolOption(process.env.CLIPIT_ALLOW_CUSTOM_HOST);
+}
+
+function assertTrustedBaseUrl(baseUrl, options) {
+  if (isTrustedBaseUrl(baseUrl) || allowCustomHost(options)) return;
+  throw Object.assign(
+    new Error(`Refusing to contact untrusted ClipIt API host: ${baseUrl}. Pass --allow-custom-host or set CLIPIT_ALLOW_CUSTOM_HOST=true for staging/self-hosted use.`),
+    { exitCode: EXIT.USAGE },
+  );
+}
+
+function requireConfirm(options, action) {
+  if (!boolOption(options.confirm) && !boolOption(options.yes)) {
+    throw Object.assign(new Error(`${action} requires --confirm.`), { exitCode: EXIT.CONFIRMATION });
+  }
+}
+
+function confirmPaid(options, label) {
+  requireConfirm(options, label);
+}
+
+function requiredString(value, label) {
+  if (value === undefined || value === null || String(value).trim() === '') {
+    throw Object.assign(new Error(`${label} is required.`), { exitCode: EXIT.USAGE });
+  }
+  return String(value);
+}
+
+function numberOption(value, label) {
+  if (value === undefined) return undefined;
+  if (value === true || value === false) {
+    throw Object.assign(new Error(`${label} must be a number.`), { exitCode: EXIT.USAGE });
+  }
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    throw Object.assign(new Error(`${label} must be a number.`), { exitCode: EXIT.USAGE });
+  }
+  return parsed;
+}
+
+function stringList(value) {
+  if (!value) return undefined;
+  return String(value)
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function compactObject(value) {
+  for (const key of Object.keys(value)) {
+    if (value[key] === undefined) delete value[key];
+  }
+  return value;
+}
+
+function queryString(params) {
+  const query = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== null && value !== '') query.set(key, String(value));
+  }
+  const suffix = query.toString();
+  return suffix ? `?${suffix}` : '';
+}
+
+function retryAfterMs(response) {
+  const retryAfter = response.headers.get('retry-after');
+  if (!retryAfter) return null;
+  const seconds = Number(retryAfter);
+  if (Number.isFinite(seconds)) return Math.min(Math.max(0, seconds * 1000), RETRY_AFTER_CAP_MS);
+  const dateMs = Date.parse(retryAfter);
+  if (Number.isFinite(dateMs)) return Math.min(Math.max(0, dateMs - Date.now()), RETRY_AFTER_CAP_MS);
+  return null;
+}
+
+function retryDelayMs(response, retryIndex) {
+  return retryAfterMs(response) ?? GET_RETRY_DELAYS_MS[retryIndex] ?? GET_RETRY_DELAYS_MS.at(-1);
+}
+
+async function apiFetch(config, options, method, endpoint, body, extra = {}) {
+  const baseUrl = getBaseUrl(config, options);
+  assertTrustedBaseUrl(baseUrl, options);
+  const methodName = String(method).toUpperCase();
+  const canRetry = methodName === 'GET' && !boolOption(options['no-retry']);
+  const headers = {
+    'User-Agent': `clipit-cli/${VERSION} (${process.platform}; ${process.arch})`,
+    ...(extra.headers || {}),
+  };
+  const isFormData = typeof FormData !== 'undefined' && body instanceof FormData;
+  if (body !== undefined && !isFormData && !extra.rawBody) headers['Content-Type'] = 'application/json';
+  const apiKey = extra.noAuth ? null : getApiKey(config, options);
+  if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
+
+  let response;
+  for (let attempt = 0; attempt <= GET_RETRY_DELAYS_MS.length; attempt++) {
+    try {
+      const request = {
+        method: methodName,
+        headers,
+        body: body === undefined ? undefined : extra.rawBody ? body : isFormData ? body : JSON.stringify(body),
+      };
+      if (extra.rawBody && body !== undefined) {
+        request.duplex = 'half';
+      }
+      response = await fetch(`${baseUrl}${endpoint}`, request);
+    } catch (error) {
+      if (canRetry && attempt < GET_RETRY_DELAYS_MS.length) {
+        await sleep(GET_RETRY_DELAYS_MS[attempt]);
+        continue;
+      }
+      throw Object.assign(new Error(`Network error: ${error.message}`), { exitCode: EXIT.NETWORK });
+    }
+
+    if (canRetry && RETRYABLE_GET_STATUSES.has(response.status) && attempt < GET_RETRY_DELAYS_MS.length) {
+      await response.arrayBuffer().catch(() => undefined);
+      await sleep(retryDelayMs(response, attempt));
+      continue;
+    }
+    break;
+  }
+
+  const requestId = response.headers.get('x-request-id') || response.headers.get('X-Request-Id') || undefined;
+  const text = await response.text();
+  let data = null;
+  if (text.trim()) {
+    try {
+      data = JSON.parse(text);
+    } catch {
+      data = { raw: text };
+    }
+  }
+  if (!response.ok) {
+    const message = response.status === 402 ? creditsErrorMessage(data) : data?.error || data?.message || response.statusText;
+    const exitCode = response.status === 401
+      ? EXIT.AUTH
+      : response.status === 403
+        ? EXIT.PERMISSION
+        : response.status === 402
+          ? EXIT.CREDITS
+          : EXIT.SERVER;
+    throw Object.assign(new Error(`${response.status}: ${message}${requestId ? ` (request id: ${requestId})` : ''}`), {
+      exitCode,
+      status: response.status,
+      data,
+      requestId,
+    });
+  }
+  return data;
+}
+
+function pkcePair() {
+  const verifier = randomBytes(32).toString('base64url');
+  const challenge = createHash('sha256').update(verifier).digest('base64url');
+  return { verifier, challenge };
+}
+
+function openBrowser(url) {
+  const platform = process.platform;
+  const command = platform === 'darwin' ? 'open' : platform === 'win32' ? 'cmd' : 'xdg-open';
+  const args = platform === 'win32' ? ['/c', 'start', '', url] : [url];
+  const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+  child.unref();
+}
+
+async function sleep(ms) {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function maxCreditsLimit(options) {
+  if (options['max-credits'] === undefined) return null;
+  const limit = numberOption(options['max-credits'], '--max-credits');
+  if (limit < 0) {
+    throw Object.assign(new Error('--max-credits must be 0 or greater.'), { exitCode: EXIT.USAGE });
+  }
+  return limit;
+}
+
+function clipCostLabel(value) {
+  return `${Number(value).toFixed(2).replace(/\.00$/, '')} $CLIP`;
+}
+
+const SPEND_LIMIT_EXCEEDED_MESSAGE = 'Spend limit exceeded for this API key \u2014 raise the key\'s spend limit in ClipIt Settings or use a different key.';
+const INSUFFICIENT_CREDITS_MESSAGE = 'Insufficient credits \u2014 top up at https://clipit.dev/settings (Billing).';
+
+function isSpendLimitCode(value) {
+  return value === 'SPEND_LIMIT_EXCEEDED';
+}
+
+function spendLimitViolationFromData(data) {
+  if (!data || typeof data !== 'object') return null;
+  if (data.spendLimitViolation) return data.spendLimitViolation;
+  if (isSpendLimitCode(data.code) || isSpendLimitCode(data.errorCode) || isSpendLimitCode(data.error_code)) return data;
+  const details = data.details;
+  if (details && typeof details === 'object') {
+    if (details.spendLimitViolation) return details.spendLimitViolation;
+    if (isSpendLimitCode(details.code) || isSpendLimitCode(details.errorCode) || isSpendLimitCode(details.error_code)) return details;
+  }
+  return null;
+}
+
+function creditsErrorMessage(data) {
+  return spendLimitViolationFromData(data) ? SPEND_LIMIT_EXCEEDED_MESSAGE : INSUFFICIENT_CREDITS_MESSAGE;
+}
+
+function warnIfEstimateUnaffordable(estimates) {
+  if (estimates.some((estimate) => estimate.affordable === false)) {
+    console.error('Warning: estimated cost exceeds your current balance.');
+  }
+}
+
+function throwSpendLimitExceeded(commandKey, spendLimitViolation, estimates) {
+  throw Object.assign(new Error(SPEND_LIMIT_EXCEEDED_MESSAGE), {
+    exitCode: EXIT.CREDITS,
+    data: {
+      command: commandKey,
+      spendLimitViolation,
+      estimates,
+    },
+  });
+}
+
+function isYoutubeUrl(value) {
+  try {
+    const hostname = new URL(value).hostname.toLowerCase();
+    return hostname.includes('youtube.com') || hostname.includes('youtu.be');
+  } catch {
+    return false;
+  }
+}
+
+function qualityMultiplier(quality) {
+  if (quality === '4k') return 2;
+  if (quality === 'standard') return 0.75;
+  return 1;
+}
+
+function remotionProviderCostUsd(durationSeconds, quality) {
+  return Math.max(0, durationSeconds * REMOTION_ESTIMATED_USD_PER_VIDEO_SECOND * qualityMultiplier(quality));
+}
+
+function brollVideoProviderCostUsd(durationSeconds, resolution) {
+  const perSecondUsd = resolution === '1080p' ? 0.28 : 0.14;
+  return Math.max(0, durationSeconds * perSecondUsd);
+}
+
+function durationFromClip(clip, body = {}) {
+  const bodyStart = Number(body.startTime);
+  const bodyEnd = Number(body.endTime);
+  if (Number.isFinite(bodyStart) && Number.isFinite(bodyEnd) && bodyEnd > bodyStart) return bodyEnd - bodyStart;
+
+  const direct = Number(clip?.durationSeconds ?? clip?.duration);
+  if (Number.isFinite(direct) && direct > 0) return direct;
+
+  const start = Number(clip?.startTime);
+  const end = Number(clip?.endTime);
+  if (Number.isFinite(start) && Number.isFinite(end) && end > start) return end - start;
+  return null;
+}
+
+async function fetchClipForEstimate(config, options, clipId) {
+  return apiFetch(config, options, 'GET', `/api/v1/clips/${encodeURIComponent(clipId)}`);
+}
+
+function progressTransform(progress) {
+  return new Transform({
+    transform(chunk, encoding, callback) {
+      progress.track(chunk);
+      callback(null, chunk);
+    },
+  });
+}
+
+async function buildMaxCreditsEstimateRequest(config, options, spec, context = {}) {
+  if (spec.metrics === 'url-import') {
+    const youtube = isYoutubeUrl(requiredString(context.url, 'URL'));
+    return {
+      operationType: youtube ? 'proxy_extraction' : 'url_extraction',
+      provider: youtube ? 'webshare' : 'internal',
+      metrics: { generationCount: 1 },
+    };
+  }
+
+  if (spec.metrics === 'one-generation') {
+    return { ...spec, metrics: { generationCount: 1 } };
+  }
+
+  if (spec.metrics === 'broll-plan') {
+    return { ...spec, metrics: { inputTokens: 4000, outputTokens: 1000 } };
+  }
+
+  if (spec.metrics === 'broll-images') {
+    const mode = context.body?.mode || 'single_image';
+    return { ...spec, metrics: { generationCount: mode === 'start_end_frame' ? 3 : 1 } };
+  }
+
+  if (spec.metrics === 'broll-video') {
+    const durationSeconds = Number(context.body?.durationSeconds ?? 6);
+    const resolution = context.body?.resolution || '720p';
+    if (!Number.isFinite(durationSeconds) || durationSeconds <= 0) return null;
+    return {
+      ...spec,
+      metrics: {
+        videoSeconds: durationSeconds,
+        providerCostUsd: brollVideoProviderCostUsd(durationSeconds, resolution),
+      },
+    };
+  }
+
+  if (spec.metrics === 'social-platforms') {
+    const platforms = Array.isArray(context.body?.platforms) ? context.body.platforms : [];
+    if (!platforms.length) return null;
+    return { ...spec, metrics: { generationCount: platforms.length } };
+  }
+
+  if (spec.metrics === 'remotion-render') {
+    const clipId = requiredString(context.clipId, '--clip-id');
+    const clip = context.clip || await fetchClipForEstimate(config, options, clipId);
+    const durationSeconds = durationFromClip(clip, context.body);
+    if (!durationSeconds) return null;
+    const quality = context.body?.quality || context.body?.qualitySettings?.qualityPreset || 'high';
+    return {
+      ...spec,
+      metrics: {
+        videoSeconds: durationSeconds,
+        providerCostUsd: remotionProviderCostUsd(durationSeconds, quality),
+      },
+    };
+  }
+
+  return null;
+}
+
+function printEstimateUnavailable(commandKey) {
+  console.error(`estimate unavailable for ${commandKey}; --confirm is required.`);
+}
+
+async function enforceMaxCredits(config, options, commandKey, context = {}) {
+  const limit = maxCreditsLimit(options);
+  if (limit === null) return;
+
+  const specs = MAX_CREDITS_ESTIMATE_MAP[commandKey];
+  if (!specs) {
+    printEstimateUnavailable(commandKey);
+    requireConfirm(options, commandKey);
+    return;
+  }
+
+  const requests = [];
+  for (const spec of specs) {
+    const request = await buildMaxCreditsEstimateRequest(config, options, spec, context);
+    if (!request) {
+      printEstimateUnavailable(commandKey);
+      requireConfirm(options, commandKey);
+      return;
+    }
+    requests.push(compactObject({
+      operationType: request.operationType,
+      provider: request.provider,
+      modelId: request.modelId,
+      metrics: request.metrics,
+    }));
+  }
+
+  const estimates = [];
+  for (const request of requests) {
+    const estimate = await apiFetch(config, options, 'POST', '/api/v1/credits/estimate', request);
+    estimates.push({
+      operationType: request.operationType,
+      provider: request.provider,
+      modelId: request.modelId,
+      estimatedCostClip: Number(estimate?.estimatedCostClip ?? 0),
+      affordable: estimate?.affordable,
+      spendLimitViolation: estimate?.spendLimitViolation ?? null,
+    });
+  }
+
+  const spendLimitViolation = estimates.find((estimate) => estimate.spendLimitViolation)?.spendLimitViolation;
+  if (spendLimitViolation) throwSpendLimitExceeded(commandKey, spendLimitViolation, estimates);
+  warnIfEstimateUnaffordable(estimates);
+
+  const estimatedCostClip = estimates.reduce((sum, estimate) => sum + estimate.estimatedCostClip, 0);
+  if (estimatedCostClip > limit) {
+    throw Object.assign(
+      new Error(`Estimated cost ${clipCostLabel(estimatedCostClip)} exceeds --max-credits ${clipCostLabel(limit)} for ${commandKey}.`),
+      {
+        exitCode: EXIT.CONFIRMATION,
+        data: {
+          command: commandKey,
+          maxCredits: limit,
+          estimatedCostClip,
+          estimates,
+        },
+      },
+    );
+  }
+}
+
+async function enforceRunMaxCredits(config, options, functionName) {
+  if (maxCreditsLimit(options) === null) return;
+  const catalog = await apiFetch(config, options, 'GET', '/api/v1/agent/tools');
+  const tools = Array.isArray(catalog?.tools) ? catalog.tools : Array.isArray(catalog) ? catalog : [];
+  const tool = tools.find((item) => item.name === functionName);
+  const runEstimate = tool?.estimate ?? tool?.confirmation?.estimate ?? tool?.confirmation?.costEstimate ?? null;
+  const spendLimitViolation = spendLimitViolationFromData(runEstimate) ?? spendLimitViolationFromData(tool?.confirmation);
+  if (spendLimitViolation) throwSpendLimitExceeded(`run ${functionName}`, spendLimitViolation, runEstimate ? [runEstimate] : []);
+  if (runEstimate?.affordable === false || tool?.confirmation?.affordable === false) {
+    console.error('Warning: estimated cost exceeds your current balance.');
+  }
+  if (!tool?.confirmation?.required) return;
+  printEstimateUnavailable(`run ${functionName}`);
+  requireConfirm(options, `Running confirmation-gated tool ${functionName}`);
+}
+
+async function login(config, options) {
+  const { verifier, challenge } = pkcePair();
+  const baseUrl = getBaseUrl(config, options);
+  const started = await apiFetch(config, options, 'POST', '/api/v1/cli-auth/start', {
+    codeChallenge: challenge,
+    codeChallengeMethod: 'S256',
+    requestedScopes: DEFAULT_SCOPES,
+    deviceName: os.hostname(),
+    cliVersion: VERSION,
+    platform: `${process.platform}/${process.arch}`,
+  }, { noAuth: true });
+
+  if (!options['no-browser']) {
+    try {
+      openBrowser(started.verificationUrlComplete);
+    } catch {}
+  }
+
+  if (!wantJson(options)) {
+    console.log('Approve ClipIt CLI in your browser:');
+    console.log(`  ${started.verificationUrlComplete}`);
+    console.log(`Code: ${started.userCode}`);
+    console.log('');
+    console.log('Waiting for approval...');
+  }
+
+  const expiresAt = new Date(started.expiresAt).getTime();
+  let lastStatus = 'pending';
+  while (Date.now() < expiresAt) {
+    await sleep((started.pollIntervalSeconds || 3) * 1000);
+    const poll = await apiFetch(config, options, 'POST', '/api/v1/cli-auth/poll', {
+      deviceCode: started.deviceCode,
+    }, { noAuth: true });
+    lastStatus = poll.status;
+    if (poll.status === 'approved') break;
+    if (['denied', 'expired', 'exchanged'].includes(poll.status)) {
+      throw Object.assign(new Error(`CLI login ${poll.status}`), { exitCode: EXIT.AUTH });
+    }
+  }
+
+  if (lastStatus !== 'approved') {
+    throw Object.assign(new Error('CLI login expired before approval'), { exitCode: EXIT.AUTH });
+  }
+
+  const exchanged = await apiFetch(config, options, 'POST', '/api/v1/cli-auth/exchange', {
+    deviceCode: started.deviceCode,
+    codeVerifier: verifier,
+  }, { noAuth: true });
+
+  const nextConfig = updateProfile(config, options, {
+    baseUrl,
+    apiKey: exchanged.apiKey,
+    keyInfo: exchanged.keyInfo,
+    loginSource: 'browser',
+  });
+  await writeConfig(nextConfig);
+
+  output({
+    success: true,
+    message: 'ClipIt CLI connected',
+    profile: profileName(config, options),
+    baseUrl,
+    keyName: exchanged.keyInfo?.keyName,
+    permissions: exchanged.keyInfo?.permissions,
+  }, options);
+}
+
+async function setup(config, options) {
+  await login(config, options);
+  if (options.agent) {
+    const updatedConfig = await readConfig();
+    await agent(updatedConfig, options, 'install', [String(options.agent)]);
+    return;
+  }
+  if (!wantJson(options)) {
+    console.log('');
+    console.log('Next steps:');
+    console.log('  clipit agent install codex');
+    console.log('  clipit doctor');
+    console.log('  clipit skills list');
+  }
+}
+
+async function authStatus(config, options) {
+  const apiKey = getApiKey(config, options);
+  if (!apiKey) {
+    throw Object.assign(new Error('Not logged in. Run clipit login.'), { exitCode: EXIT.AUTH });
+  }
+  const me = await apiFetch(config, options, 'GET', '/api/v1/agent/me');
+  output(me, options);
+}
+
+async function setKey(config, options) {
+  if (!options.stdin) {
+    throw Object.assign(new Error('Use --stdin to avoid shell history leaks.'), { exitCode: EXIT.USAGE });
+  }
+  const apiKey = (await readStdin()).trim();
+  if (!apiKey) {
+    throw Object.assign(new Error('No API key received on stdin.'), { exitCode: EXIT.USAGE });
+  }
+  const nextConfig = updateProfile(config, options, {
+    baseUrl: getBaseUrl(config, options),
+    apiKey,
+    loginSource: 'manual',
+  });
+  const me = await apiFetch(nextConfig, options, 'GET', '/api/v1/agent/me');
+  await writeConfig(updateProfile(nextConfig, options, { keyInfo: me.apiKey }));
+  output({ success: true, message: 'API key stored', profile: profileName(config, options), account: me.user, apiKey: me.apiKey }, options);
+}
+
+async function logout(config, options) {
+  const next = removeProfileFields(config, options, ['apiKey', 'keyInfo', 'loginSource']);
+  await writeConfig(next);
+  output({ success: true, message: 'Local ClipIt CLI credentials removed', profile: profileName(config, options) }, options);
+}
+
+async function listProfiles(config, options) {
+  const profiles = config.profiles || {};
+  const names = [...new Set(['default', ...Object.keys(profiles)])];
+  output({
+    currentProfile: profileName(config, options),
+    profiles: names.map((name) => {
+      const data = name === 'default'
+        ? { ...legacyProfile(config), ...(profiles.default || {}) }
+        : profiles[name] || {};
+      return {
+        name,
+        baseUrl: data.baseUrl || DEFAULT_BASE_URL,
+        hasCredential: Boolean(data.apiKey),
+        loginSource: data.loginSource || null,
+        keyName: data.keyInfo?.keyName || null,
+        updatedAt: data.updatedAt || null,
+      };
+    }),
+  }, options);
+}
+
+async function doctor(config, options) {
+  const checks = {
+    version: VERSION,
+    node: process.version,
+    platform: `${process.platform}/${process.arch}`,
+    configPath: configPath(),
+    profile: profileName(config, options),
+    baseUrl: getBaseUrl(config, options),
+    hasCredential: Boolean(getApiKey(config, options)),
+    credentialSource: process.env.CLIPPER_API_KEY ? 'env' : getApiKey(config, options) ? 'config' : 'missing',
+    auth: null,
+  };
+  try {
+    checks.auth = await apiFetch(config, options, 'GET', '/api/v1/agent/me');
+  } catch (error) {
+    checks.auth = { ok: false, error: redact(error.message), status: error.status };
+  }
+  output(checks, options);
+}
+
+async function listSkills(config, options) {
+  output(await apiFetch(config, options, 'GET', '/api/v1/agent/skills'), options);
+}
+
+async function listTools(config, options) {
+  const params = new URLSearchParams();
+  if (options.skill) params.set('skill', String(options.skill));
+  if (options.category) params.set('category', String(options.category));
+  const suffix = params.toString() ? `?${params}` : '';
+  output(await apiFetch(config, options, 'GET', `/api/v1/agent/tools${suffix}`), options);
+}
+
+async function describeTool(config, options, name) {
+  if (!name) throw Object.assign(new Error('Tool name is required.'), { exitCode: EXIT.USAGE });
+  const catalog = await apiFetch(config, options, 'GET', '/api/v1/agent/tools');
+  const tool = catalog.tools?.find((item) => item.name === name);
+  if (!tool) throw Object.assign(new Error(`Tool not found: ${name}`), { exitCode: EXIT.USAGE });
+  output(tool, options);
+}
+
+async function readJsonOption(value) {
+  if (!value) return {};
+  if (value === '@-') {
+    return JSON.parse(await readStdin());
+  }
+  if (value.startsWith('@')) {
+    return JSON.parse(await fs.readFile(value.slice(1), 'utf8'));
+  }
+  return JSON.parse(value);
+}
+
+function readMetricsOption(value) {
+  return value ? readJsonOption(String(value)) : {};
+}
+
+async function buildContext(config, options) {
+  const activeContext = profileData(config, options).activeContext || {};
+  const context = { ...activeContext };
+  for (const [flag, field] of [
+    ['video-id', 'videoId'],
+    ['clip-id', 'clipId'],
+    ['project-id', 'projectId'],
+    ['sequence-id', 'sequenceId'],
+  ]) {
+    if (options[flag]) context[field] = String(options[flag]);
+  }
+  if (options['selected-clip-ids']) context.selectedClipIds = stringList(options['selected-clip-ids']);
+  if (options.playhead !== undefined) context.playheadPosition = numberOption(options.playhead, '--playhead');
+  if (options.context) {
+    const fromFile = await readJsonOption(String(options.context));
+    Object.assign(context, fromFile);
+  }
+  return context;
+}
+
+async function contextCommand(config, options, action) {
+  if (action === 'show') {
+    const profile = profileData(config, options);
+    output({ ...(profile.activeContext || {}), recent: recentEntries(config, options) }, options);
+    return;
+  }
+
+  if (action === 'clear') {
+    const next = updateProfile(config, options, { activeContext: {} });
+    await writeConfig(next);
+    output({ success: true, profile: profileName(config, options), activeContext: {} }, options);
+    return;
+  }
+
+  if (action === 'use') {
+    const activeContext = await buildContext({ ...config, activeContext: {} }, options);
+    let next = updateProfile(config, options, { activeContext });
+    next = appendRecentEntries(next, options, [
+      { type: 'video', id: activeContext.videoId },
+      { type: 'clip', id: activeContext.clipId },
+      { type: 'project', id: activeContext.projectId },
+      { type: 'sequence', id: activeContext.sequenceId },
+    ]);
+    await writeConfig(next);
+    output({ success: true, profile: profileName(config, options), activeContext }, options);
+    return;
+  }
+
+  if (action === 'build') {
+    output(await buildContext(config, options), options);
+    return;
+  }
+
+  throw Object.assign(new Error(`Unknown context command: ${action || ''}`), { exitCode: EXIT.USAGE });
+}
+
+async function runTool(config, options, functionName) {
+  if (!functionName) throw Object.assign(new Error('Function name is required.'), { exitCode: EXIT.USAGE });
+  const parameters = await readJsonOption(options.params || options['params-json']);
+  const context = await buildContext(config, options);
+  const payload = {
+    functionName,
+    parameters,
+    confirmed: boolOption(options.confirm),
+  };
+  for (const [flag, field] of [
+    ['video-id', 'videoId'],
+    ['clip-id', 'clipId'],
+    ['project-id', 'projectId'],
+    ['sequence-id', 'sequenceId'],
+  ]) {
+    if (options[flag]) payload[field] = String(options[flag]);
+  }
+  if (context.videoId && !payload.videoId) payload.videoId = context.videoId;
+  if (context.clipId && !payload.clipId) payload.clipId = context.clipId;
+  if (context.projectId && !payload.projectId) payload.projectId = context.projectId;
+  if (context.sequenceId && !payload.sequenceId) payload.sequenceId = context.sequenceId;
+  if (context.selectedClipIds) payload.selectedClipIds = context.selectedClipIds;
+  if (context.playheadPosition !== undefined) payload.playheadPosition = context.playheadPosition;
+  if (Object.keys(context).length) payload.context = context.context || context;
+  await enforceRunMaxCredits(config, options, functionName);
+  const result = await apiFetch(config, options, 'POST', '/api/v1/agent/execute', payload);
+  if (result?.requiresConfirmation && !payload.confirmed) {
+    output(result, options);
+    process.exitCode = EXIT.CONFIRMATION;
+    return;
+  }
+  output(result, options);
+}
+
+function workflowEndpoint(jobId) {
+  return `/api/v1/agent/workflows/${encodeURIComponent(jobId)}`;
+}
+
+function workflowValue(value) {
+  if (value === undefined || value === null) return null;
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  return JSON.stringify(value);
+}
+
+function workflowStreamEvent(workflow) {
+  return redactDeep({
+    type: 'workflow.status',
+    jobId: workflow.jobId,
+    status: workflow.status,
+    progress: workflow.progress,
+    name: workflow.name,
+    pendingApproval: workflow.pendingApproval,
+    finalResponse: workflow.finalResponse,
+    error: workflow.error,
+    createdAt: workflow.createdAt,
+    completedAt: workflow.completedAt,
+  });
+}
+
+function workflowFailureMessage(workflow, jobId) {
+  const error = workflow.error;
+  if (typeof error === 'string' && error.trim()) return `Workflow ${jobId} failed: ${redact(error)}`;
+  if (error && typeof error === 'object' && typeof error.message === 'string') {
+    return `Workflow ${jobId} failed: ${redact(error.message)}`;
+  }
+  return `Workflow ${jobId} failed.`;
+}
+
+function approvalTaskLine(task, index) {
+  const label = workflowValue(task.label ?? task.title ?? task.name ?? task.id ?? `Task ${index + 1}`);
+  const tool = workflowValue(task.tool ?? task.toolName ?? task.functionName);
+  const estimatedCost = workflowValue(task.estimatedCost ?? task.costEstimate ?? task.cost);
+  const details = [];
+  if (tool) details.push(`tool: ${tool}`);
+  if (estimatedCost) details.push(`estimated cost: ${estimatedCost}`);
+  return `  ${index + 1}. ${label}${details.length ? ` (${details.join(', ')})` : ''}`;
+}
+
+function printApprovalTranscript(workflow, jobId) {
+  const pending = workflow.pendingApproval || {};
+  console.log(`Workflow awaiting approval: ${workflow.jobId || jobId}`);
+  console.log(`Approval id: ${pending.approvalId || ''}`);
+  console.log('');
+  console.log('Pending tasks:');
+  const tasks = Array.isArray(pending.tasks) ? pending.tasks : [];
+  if (tasks.length) {
+    for (const [index, task] of tasks.entries()) console.log(approvalTaskLine(task, index));
+  } else {
+    console.log('  (No task details returned.)');
+  }
+  if (pending.totalEstimatedCost !== undefined) {
+    console.log(`Total estimated cost: ${workflowValue(pending.totalEstimatedCost)}`);
+  }
+  if (pending.expiresAt) console.log(`Expires at: ${pending.expiresAt}`);
+  console.log('');
+  console.log('Approve and continue:');
+  console.log(`  clipit workflow approve ${workflow.jobId || jobId} --approval-id ${pending.approvalId || '<approvalId>'} --decision approved`);
+}
+
+async function pollWorkflow(config, options, jobId) {
+  if (!jobId) throw Object.assign(new Error('Workflow job id is required.'), { exitCode: EXIT.USAGE });
+  const startedAt = Date.now();
+  const timeoutMs = numberOption(options['timeout-ms'], '--timeout-ms') ?? 15 * 60 * 1000;
+  const intervalMs = numberOption(options.interval, '--interval') || 3000;
+  let lastStreamEvent = null;
+
+  while (true) {
+    const workflow = await apiFetch(config, options, 'GET', workflowEndpoint(jobId));
+    const redactedWorkflow = redactDeep(workflow);
+
+    if (options.stream) {
+      const event = workflowStreamEvent(workflow);
+      const serialized = JSON.stringify(event);
+      if (serialized !== lastStreamEvent) {
+        console.log(serialized);
+        lastStreamEvent = serialized;
+      }
+    }
+
+    if (workflow.status === 'awaiting_approval') {
+      if (wantJson(options)) {
+        output({
+          jobId: workflow.jobId || jobId,
+          status: workflow.status,
+          pendingApproval: redactedWorkflow.pendingApproval,
+        }, options);
+      } else {
+        printApprovalTranscript(redactedWorkflow, jobId);
+      }
+      process.exitCode = EXIT.CONFIRMATION;
+      return workflow;
+    }
+
+    if (workflow.status === 'failed') {
+      throw Object.assign(new Error(workflowFailureMessage(redactedWorkflow, jobId)), {
+        exitCode: EXIT.SERVER,
+        data: redactedWorkflow,
+      });
+    }
+
+    if (TERMINAL_WORKFLOW_STATUSES.has(workflow.status)) {
+      output(redactedWorkflow, options);
+      return workflow;
+    }
+
+    if (Date.now() - startedAt > timeoutMs) {
+      throw Object.assign(new Error(`Timed out waiting for workflow ${jobId}.`), { exitCode: EXIT.SERVER });
+    }
+    await sleep(intervalMs);
+  }
+}
+
+async function askWorkflow(config, options, promptParts) {
+  const userMessage = promptParts.filter((part) => part !== undefined).join(' ').trim();
+  if (!userMessage) throw Object.assign(new Error('Prompt is required.'), { exitCode: EXIT.USAGE });
+
+  const context = await buildContext(config, options);
+  const payload = { userMessage };
+  for (const field of ['videoId', 'clipId', 'projectId', 'sequenceId']) {
+    if (context[field]) payload[field] = context[field];
+  }
+  if (options['conversation-id']) payload.conversationId = String(options['conversation-id']);
+  if (options.quick !== undefined) payload.quickMode = boolOption(options.quick);
+
+  const accepted = await apiFetch(config, options, 'POST', '/api/v1/agent/orchestrate', payload);
+  if (boolOption(options['no-wait'])) {
+    output(redactDeep(accepted), options);
+    return;
+  }
+  await pollWorkflow(config, options, accepted.jobId);
+}
+
+async function workflow(config, options, action, args) {
+  if (action === 'status') {
+    const jobId = args[0];
+    if (!jobId) throw Object.assign(new Error('Workflow job id is required.'), { exitCode: EXIT.USAGE });
+    output(redactDeep(await apiFetch(config, options, 'GET', workflowEndpoint(jobId))), options);
+    return;
+  }
+
+  if (action === 'wait') {
+    await pollWorkflow(config, options, args[0]);
+    return;
+  }
+
+  if (action === 'approve') {
+    const jobId = args[0];
+    if (!jobId) throw Object.assign(new Error('Workflow job id is required.'), { exitCode: EXIT.USAGE });
+    if (!options['approval-id']) throw Object.assign(new Error('--approval-id is required.'), { exitCode: EXIT.USAGE });
+    const decision = String(options.decision || 'approved');
+    if (!WORKFLOW_APPROVAL_DECISIONS.has(decision)) {
+      throw Object.assign(new Error('--decision must be approved, cheaper, or cancelled.'), { exitCode: EXIT.USAGE });
+    }
+
+    let accepted;
+    try {
+      accepted = await apiFetch(config, options, 'POST', `${workflowEndpoint(jobId)}/approval`, {
+        approvalId: String(options['approval-id']),
+        decision,
+      });
+    } catch (error) {
+      if (error.status === 409) {
+        output(redactDeep(error.data || { error: error.message }), options);
+        process.exitCode = EXIT.CONFIRMATION;
+        return;
+      }
+      throw error;
+    }
+
+    const redactedAccepted = redactDeep(accepted);
+    if (wantJson(options)) {
+      output(redactedAccepted, options);
+    } else {
+      console.log(`Continuation workflow queued: ${redactedAccepted.jobId}`);
+    }
+    if (boolOption(options['no-wait'])) return;
+    await pollWorkflow(config, options, accepted.jobId);
+    return;
+  }
+
+  throw Object.assign(new Error(`Unknown workflow command: ${action || ''}`), { exitCode: EXIT.USAGE });
+}
+
+function mimeForPath(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  if (ext === '.jpg' || ext === '.jpeg') return 'image/jpeg';
+  if (ext === '.png') return 'image/png';
+  if (ext === '.webp') return 'image/webp';
+  if (ext === '.gif') return 'image/gif';
+  if (ext === '.mov') return 'video/quicktime';
+  if (ext === '.webm') return 'video/webm';
+  if (ext === '.mkv') return 'video/x-matroska';
+  if (ext === '.m4v') return 'video/x-m4v';
+  if (ext === '.mp3') return 'audio/mpeg';
+  if (ext === '.m4a') return 'audio/mp4';
+  if (ext === '.wav') return 'audio/wav';
+  return 'video/mp4';
+}
+
+function multipartFilename(value) {
+  return String(value).replace(/["\r\n]/g, '_');
+}
+
+function shouldReportUploadProgress(options) {
+  return Boolean(process.stderr.isTTY) && !wantJson(options);
+}
+
+function formatMb(bytes) {
+  return (bytes / (1024 * 1024)).toFixed(1);
+}
+
+function createUploadProgress(options, totalBytes) {
+  if (!shouldReportUploadProgress(options) || !Number.isFinite(totalBytes) || totalBytes <= 0) {
+    return { track() {}, finish() {} };
+  }
+
+  let uploaded = 0;
+  let lastPrintedAt = 0;
+
+  function print(force = false) {
+    const now = Date.now();
+    if (!force && now - lastPrintedAt < 2000 && uploaded < totalBytes) return;
+    lastPrintedAt = now;
+    const percent = Math.min(100, Math.round((uploaded / totalBytes) * 100));
+    process.stderr.write(`\ruploaded ${formatMb(uploaded)} / ${formatMb(totalBytes)} MB (${percent}%)`);
+  }
+
+  return {
+    track(chunk) {
+      uploaded = Math.min(totalBytes, uploaded + Buffer.byteLength(chunk));
+      print(false);
+    },
+    finish() {
+      print(true);
+      process.stderr.write('\n');
+    },
+  };
+}
+
+async function* multipartFileBody(filePath, filename, contentType, boundary, progress) {
+  yield Buffer.from(
+    `--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="${multipartFilename(filename)}"\r\nContent-Type: ${contentType}\r\n\r\n`,
+  );
+  for await (const chunk of createReadStream(filePath)) {
+    progress?.track(chunk);
+    yield chunk;
+  }
+  yield Buffer.from(`\r\n--${boundary}--\r\n`);
+}
+
+async function uploadVideo(config, options, filePath) {
+  if (!filePath) throw Object.assign(new Error('Video file path is required.'), { exitCode: EXIT.USAGE });
+  const resolved = path.resolve(filePath);
+  const stat = await fs.stat(resolved);
+  if (!stat.isFile()) {
+    throw Object.assign(new Error(`Upload path is not a file: ${resolved}`), { exitCode: EXIT.USAGE });
+  }
+  const filename = options.filename || path.basename(resolved);
+  const contentType = mimeForPath(resolved);
+  const boundary = `clipit-cli-${randomBytes(12).toString('hex')}`;
+  const headerLength = Buffer.byteLength(
+    `--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="${multipartFilename(filename)}"\r\nContent-Type: ${contentType}\r\n\r\n`,
+  );
+  const footerLength = Buffer.byteLength(`\r\n--${boundary}--\r\n`);
+  const progress = createUploadProgress(options, stat.size);
+  const body = multipartFileBody(resolved, filename, contentType, boundary, progress);
+  try {
+    output(await apiFetch(config, options, 'POST', '/api/v1/videos', body, {
+      rawBody: true,
+      headers: {
+        'Content-Type': `multipart/form-data; boundary=${boundary}`,
+        'Content-Length': String(headerLength + stat.size + footerLength),
+      },
+    }), options);
+  } finally {
+    progress.finish();
+  }
+}
+
+async function videos(config, options, action, args) {
+  if (action === 'list') {
+    output(await apiFetch(config, options, 'GET', `/api/v1/videos${queryString({ limit: options.limit, offset: options.offset })}`), options);
+    return;
+  }
+  if (action === 'get') {
+    if (!args[0]) throw Object.assign(new Error('Video id is required.'), { exitCode: EXIT.USAGE });
+    const result = await apiFetch(config, options, 'GET', `/api/v1/videos/${encodeURIComponent(args[0])}`);
+    await writeConfig(appendRecentEntry(config, options, 'video', args[0]));
+    output(result, options);
+    return;
+  }
+  if (action === 'import-url') {
+    const url = args[0] || options.url;
+    if (!url) throw Object.assign(new Error('URL is required.'), { exitCode: EXIT.USAGE });
+    await enforceMaxCredits(config, options, 'videos import-url', { url });
+    output(await apiFetch(config, options, 'POST', '/api/v1/videos/from-url', { url, title: options.title }), options);
+    return;
+  }
+  if (action === 'upload') {
+    await uploadVideo(config, options, args[0] || options.file);
+    return;
+  }
+  if (action === 'transcribe') {
+    if (!args[0]) throw Object.assign(new Error('Video id is required.'), { exitCode: EXIT.USAGE });
+    output(await apiFetch(config, options, 'POST', `/api/v1/videos/${encodeURIComponent(args[0])}/transcribe`, {}), options);
+    return;
+  }
+  if (action === 'transcript') {
+    if (!args[0]) throw Object.assign(new Error('Video id is required.'), { exitCode: EXIT.USAGE });
+    output(await apiFetch(config, options, 'GET', `/api/v1/videos/${encodeURIComponent(args[0])}/transcript`), options);
+    return;
+  }
+  if (action === 'suggest-clips') {
+    if (!args[0]) throw Object.assign(new Error('Video id is required.'), { exitCode: EXIT.USAGE });
+    const body = options.params
+      ? await readJsonOption(String(options.params))
+      : {
+          count: numberOption(options.count, '--count') || 5,
+          minDuration: numberOption(options['min-duration'], '--min-duration'),
+          maxDuration: numberOption(options['max-duration'], '--max-duration'),
+          targetPlatforms: stringList(options.platforms),
+          themes: stringList(options.themes),
+        };
+    output(await apiFetch(config, options, 'POST', `/api/v1/videos/${encodeURIComponent(args[0])}/suggest-clips`, body), options);
+    return;
+  }
+  if (action === 'delete') {
+    if (!args[0]) throw Object.assign(new Error('Video id is required.'), { exitCode: EXIT.USAGE });
+    requireConfirm(options, 'Deleting a video');
+    await apiFetch(config, options, 'DELETE', `/api/v1/videos/${encodeURIComponent(args[0])}`);
+    output({ success: true, deleted: args[0] }, options);
+    return;
+  }
+  throw Object.assign(new Error(`Unknown videos command: ${action || ''}`), { exitCode: EXIT.USAGE });
+}
+
+async function clips(config, options, action, args) {
+  if (action === 'list') {
+    output(await apiFetch(config, options, 'GET', `/api/v1/clips${queryString({
+      videoId: options['video-id'],
+      limit: options.limit,
+      offset: options.offset,
+    })}`), options);
+    return;
+  }
+  if (action === 'get') {
+    if (!args[0]) throw Object.assign(new Error('Clip id is required.'), { exitCode: EXIT.USAGE });
+    const result = await apiFetch(config, options, 'GET', `/api/v1/clips/${encodeURIComponent(args[0])}`);
+    await writeConfig(appendRecentEntry(config, options, 'clip', args[0]));
+    output(result, options);
+    return;
+  }
+  if (action === 'create') {
+    const body = options.params
+      ? await readJsonOption(String(options.params))
+      : {
+          videoId: options['video-id'],
+          startTime: numberOption(options.start, '--start'),
+          endTime: numberOption(options.end, '--end'),
+          title: options.title,
+          caption: options.caption,
+        };
+    if (!body.videoId) throw Object.assign(new Error('--video-id is required.'), { exitCode: EXIT.USAGE });
+    if (body.startTime === undefined) throw Object.assign(new Error('--start is required.'), { exitCode: EXIT.USAGE });
+    if (body.endTime === undefined) throw Object.assign(new Error('--end is required.'), { exitCode: EXIT.USAGE });
+    output(await apiFetch(config, options, 'POST', '/api/v1/clips', body), options);
+    return;
+  }
+  if (action === 'update') {
+    if (!args[0]) throw Object.assign(new Error('Clip id is required.'), { exitCode: EXIT.USAGE });
+    const body = options.params
+      ? await readJsonOption(String(options.params))
+      : {
+          startTime: numberOption(options.start, '--start'),
+          endTime: numberOption(options.end, '--end'),
+          title: options.title,
+          caption: options.caption,
+        };
+    for (const key of Object.keys(body)) {
+      if (body[key] === undefined) delete body[key];
+    }
+    output(await apiFetch(config, options, 'PATCH', `/api/v1/clips/${encodeURIComponent(args[0])}`, body), options);
+    return;
+  }
+  if (action === 'render') {
+    if (!args[0]) throw Object.assign(new Error('Clip id is required.'), { exitCode: EXIT.USAGE });
+    const body = options.params
+      ? await readJsonOption(String(options.params))
+      : {
+          aspectRatio: options.aspect || options['aspect-ratio'],
+          quality: options.quality,
+          includeCaptions: options.captions === undefined ? undefined : boolOption(options.captions),
+          captionStyle: options['caption-style'],
+          watermark: options.watermark === undefined ? undefined : boolOption(options.watermark),
+        };
+    for (const key of Object.keys(body)) {
+      if (body[key] === undefined) delete body[key];
+    }
+    await enforceMaxCredits(config, options, 'clips render', { clipId: args[0], body });
+    output(await apiFetch(config, options, 'POST', `/api/v1/clips/${encodeURIComponent(args[0])}/render`, body), options);
+    return;
+  }
+  if (action === 'download') {
+    if (!args[0]) throw Object.assign(new Error('Clip id is required.'), { exitCode: EXIT.USAGE });
+    const result = await apiFetch(config, options, 'GET', `/api/v1/clips/${encodeURIComponent(args[0])}/download`);
+    if (options.open && result?.downloadUrl) openBrowser(result.downloadUrl);
+    output(result, options);
+    return;
+  }
+  if (action === 'delete') {
+    if (!args[0]) throw Object.assign(new Error('Clip id is required.'), { exitCode: EXIT.USAGE });
+    requireConfirm(options, 'Deleting a clip');
+    await apiFetch(config, options, 'DELETE', `/api/v1/clips/${encodeURIComponent(args[0])}`);
+    output({ success: true, deleted: args[0] }, options);
+    return;
+  }
+  throw Object.assign(new Error(`Unknown clips command: ${action || ''}`), { exitCode: EXIT.USAGE });
+}
+
+async function credits(config, options, action) {
+  if (action === 'balance') {
+    output(await apiFetch(config, options, 'GET', '/api/v1/credits/balance'), options);
+    return;
+  }
+  if (action === 'usage') {
+    output(await apiFetch(config, options, 'GET', `/api/v1/credits/usage${queryString({ period: options.period })}`), options);
+    return;
+  }
+  if (action === 'estimate') {
+    const operationType = requiredString(options['operation-type'], '--operation-type');
+    const provider = requiredString(options.provider, '--provider');
+    const metrics = await readMetricsOption(options.metrics);
+    output(await apiFetch(config, options, 'POST', '/api/v1/credits/estimate', compactObject({
+      operationType,
+      provider,
+      modelId: options['model-id'],
+      metrics,
+    })), options);
+    return;
+  }
+  throw Object.assign(new Error(`Unknown credits command: ${action || ''}`), { exitCode: EXIT.USAGE });
+}
+
+async function analytics(config, options, action, args) {
+  if (action === 'overview') {
+    const suffix = queryString({ days: options.days ?? 30 });
+    const [aggregate, byPlatform] = await Promise.all([
+      apiFetch(config, options, 'GET', `/api/v1/analytics/aggregate${suffix}`),
+      apiFetch(config, options, 'GET', `/api/v1/analytics/by-platform${suffix}`),
+    ]);
+    output({ aggregate, byPlatform }, options);
+    return;
+  }
+  if (action === 'top-clips') {
+    output(await apiFetch(config, options, 'GET', `/api/v1/analytics/top-clips${queryString({
+      days: options.days ?? 30,
+      limit: options.limit ?? 10,
+      metric: options.metric,
+    })}`), options);
+    return;
+  }
+  if (action === 'post') {
+    const socialPostId = requiredString(args[0], 'Social post id');
+    output(await apiFetch(config, options, 'GET', `/api/v1/analytics/posts/${encodeURIComponent(socialPostId)}/metrics`), options);
+    return;
+  }
+  throw Object.assign(new Error(`Unknown analytics command: ${action || ''}`), { exitCode: EXIT.USAGE });
+}
+
+function defaultExportStartBody(clipId) {
+  return {
+    clipId,
+    qualitySettings: {
+      resolution: '1080p',
+      bitrate: 8000000,
+      framerate: 30,
+      codec: 'h264',
+      qualityPreset: 'medium',
+      hardwareAcceleration: true,
+      colorSpace: 'sdr',
+      audioCodec: 'aac',
+      audioBitrate: 192000,
+      audioSampleRate: 48000,
+    },
+    format: 'mp4',
+    includeAudio: true,
+  };
+}
+
+async function pollExport(config, options, jobId) {
+  const startedAt = Date.now();
+  const timeoutMs = numberOption(options['timeout-ms'], '--timeout-ms');
+  const intervalMs = numberOption(options.interval, '--interval') || 3000;
+  while (true) {
+    const job = await apiFetch(config, options, 'GET', `/api/v1/exports/${encodeURIComponent(jobId)}`);
+    if (options.stream) console.log(JSON.stringify({ type: 'export.progress', job }));
+    if (TERMINAL_JOB_STATUSES.has(job.status)) {
+      output(job, options);
+      return;
+    }
+    if (timeoutMs && Date.now() - startedAt > timeoutMs) {
+      throw Object.assign(new Error(`Timed out waiting for export ${jobId}.`), { exitCode: EXIT.SERVER });
+    }
+    await sleep(intervalMs);
+  }
+}
+
+async function exportsCommand(config, options, action, args) {
+  if (action === 'start') {
+    const clipId = requiredString(options['clip-id'], '--clip-id');
+    const params = options.params ? await readJsonOption(String(options.params)) : {};
+    const body = {
+      ...defaultExportStartBody(clipId),
+      ...params,
+      clipId,
+    };
+    await enforceMaxCredits(config, options, 'exports start', { clipId, body });
+    confirmPaid(options, 'Starting an export');
+    output(await apiFetch(config, options, 'POST', '/api/v1/exports', body), options);
+    return;
+  }
+  if (action === 'list') {
+    output(await apiFetch(config, options, 'GET', `/api/v1/exports${queryString({ limit: options.limit, offset: options.offset })}`), options);
+    return;
+  }
+  if (action === 'get') {
+    const jobId = requiredString(args[0], 'Export job id');
+    output(await apiFetch(config, options, 'GET', `/api/v1/exports/${encodeURIComponent(jobId)}`), options);
+    return;
+  }
+  if (action === 'wait') {
+    await pollExport(config, options, requiredString(args[0], 'Export job id'));
+    return;
+  }
+  if (action === 'download') {
+    const jobId = requiredString(args[0], 'Export job id');
+    const result = await apiFetch(config, options, 'GET', `/api/v1/exports/${encodeURIComponent(jobId)}/download`);
+    if (options.open && result?.downloadUrl) openBrowser(result.downloadUrl);
+    output(result, options);
+    return;
+  }
+  if (action === 'cancel') {
+    const jobId = requiredString(args[0], 'Export job id');
+    output(await apiFetch(config, options, 'POST', `/api/v1/exports/${encodeURIComponent(jobId)}/cancel`, {}), options);
+    return;
+  }
+  throw Object.assign(new Error(`Unknown exports command: ${action || ''}`), { exitCode: EXIT.USAGE });
+}
+
+function objectPathFromKey(key) {
+  return String(key).startsWith('/objects/') ? String(key) : `/objects/${key}`;
+}
+
+async function putSignedUpload(uploadUrl, filePath, contentType, size, options) {
+  let response;
+  const progress = createUploadProgress(options, size);
+  const body = createReadStream(filePath).pipe(progressTransform(progress));
+  try {
+    response = await fetch(uploadUrl, {
+      method: 'PUT',
+      headers: {
+        'Content-Type': contentType,
+        'Content-Length': String(size),
+      },
+      body,
+      duplex: 'half',
+    });
+  } catch (error) {
+    throw Object.assign(new Error(`Upload failed: ${error.message}`), { exitCode: EXIT.NETWORK });
+  } finally {
+    progress.finish();
+  }
+  if (!response.ok) {
+    const text = await response.text().catch(() => '');
+    throw Object.assign(new Error(`Upload failed: ${response.status} ${redact(text || response.statusText)}`), { exitCode: EXIT.SERVER });
+  }
+}
+
+async function uploadAsset(config, options, filePath) {
+  const resolved = path.resolve(requiredString(filePath, 'Asset file path'));
+  const stat = await fs.stat(resolved);
+  if (!stat.isFile()) {
+    throw Object.assign(new Error(`Upload path is not a file: ${resolved}`), { exitCode: EXIT.USAGE });
+  }
+  const filename = String(options.filename || path.basename(resolved));
+  const contentType = String(options['content-type'] || mimeForPath(resolved));
+  const signBody = compactObject({
+    filename,
+    contentType,
+    size: stat.size,
+    kind: options.kind,
+  });
+  const signed = await apiFetch(config, options, 'POST', '/api/v1/assets/sign-upload', signBody);
+  if (!signed?.uploadUrl || !signed?.key || !signed?.assetId) {
+    throw Object.assign(new Error('Asset sign-upload returned an unexpected response.'), { exitCode: EXIT.SERVER, data: signed });
+  }
+  await putSignedUpload(signed.uploadUrl, resolved, contentType, stat.size, options);
+  const objectPath = objectPathFromKey(signed.key);
+  output(await apiFetch(config, options, 'POST', `/api/v1/assets/${encodeURIComponent(signed.assetId)}/finalize`, {
+    objectPath,
+    fileSize: stat.size,
+    duration: options.duration === undefined ? null : numberOption(options.duration, '--duration'),
+  }), options);
+}
+
+async function assets(config, options, action, args) {
+  if (action === 'list') {
+    output(await apiFetch(config, options, 'GET', `/api/v1/assets${queryString({
+      type: options.type,
+      limit: options.limit,
+      offset: options.offset,
+    })}`), options);
+    return;
+  }
+  if (action === 'upload') {
+    await uploadAsset(config, options, args[0] || options.file);
+    return;
+  }
+  if (action === 'delete') {
+    const assetId = requiredString(args[0], 'Asset id');
+    requireConfirm(options, 'Deleting an asset');
+    output(await apiFetch(config, options, 'DELETE', `/api/v1/assets/${encodeURIComponent(assetId)}`), options);
+    return;
+  }
+  throw Object.assign(new Error(`Unknown assets command: ${action || ''}`), { exitCode: EXIT.USAGE });
+}
+
+async function thumbnails(config, options, action, args) {
+  if (action === 'generate') {
+    const prompt = requiredString(options.prompt, '--prompt');
+    const body = compactObject({
+      clipId: options['clip-id'],
+      prompt,
+      aspectRatio: options.aspect || options['aspect-ratio'],
+      resolution: options.resolution,
+      quality: options.quality,
+      useExistingThumbnail: options['use-existing-thumbnail'] === undefined ? undefined : boolOption(options['use-existing-thumbnail']),
+    });
+    await enforceMaxCredits(config, options, 'thumbnails generate', { body });
+    confirmPaid(options, 'Generating a thumbnail');
+    output(await apiFetch(config, options, 'POST', '/api/v1/thumbnails', body), options);
+    return;
+  }
+  if (action === 'get') {
+    const thumbnailId = requiredString(args[0], 'Thumbnail id');
+    output(await apiFetch(config, options, 'GET', `/api/v1/thumbnails/${encodeURIComponent(thumbnailId)}`), options);
+    return;
+  }
+  if (action === 'list') {
+    const clipId = requiredString(options['clip-id'] || args[0], '--clip-id');
+    output(await apiFetch(config, options, 'GET', `/api/v1/clips/${encodeURIComponent(clipId)}/thumbnails`), options);
+    return;
+  }
+  throw Object.assign(new Error(`Unknown thumbnails command: ${action || ''}`), { exitCode: EXIT.USAGE });
+}
+
+async function broll(config, options, action, args) {
+  if (action === 'plan') {
+    const clipId = requiredString(args[0], 'Clip id');
+    const body = compactObject({
+      clipId,
+      numberOfConcepts: numberOption(options.count, '--count') ?? 3,
+      theme: options.theme,
+    });
+    await enforceMaxCredits(config, options, 'broll plan', { clipId, body });
+    confirmPaid(options, 'Planning B-Roll');
+    output(await apiFetch(config, options, 'POST', `/api/v1/clips/${encodeURIComponent(clipId)}/broll/plan`, body), options);
+    return;
+  }
+  if (action === 'generate') {
+    const clipId = requiredString(args[0], 'Clip id');
+    const conceptIndex = numberOption(options['concept-index'], '--concept-index');
+    const promptOverride = options.prompt || options['prompt-override'];
+    if (conceptIndex === undefined && !promptOverride) {
+      throw Object.assign(new Error('--concept-index or --prompt is required.'), { exitCode: EXIT.USAGE });
+    }
+    const durationSeconds = numberOption(options.duration || options['duration-seconds'], '--duration') ?? 6;
+    const startTimeInClip = numberOption(options.start || options['start-time'], '--start') ?? 0;
+    const endTimeInClip = numberOption(options.end || options['end-time'], '--end') ?? startTimeInClip + durationSeconds;
+    const body = compactObject({
+      clipId,
+      conceptIndex,
+      promptOverride,
+      mode: options.mode,
+      endFrameDescription: options['end-frame-description'],
+      transitionDescription: options['transition-description'],
+      durationSeconds,
+      resolution: options.resolution,
+      imageQuality: options['image-quality'],
+      startTimeInClip,
+      endTimeInClip,
+    });
+    await enforceMaxCredits(config, options, 'broll generate', { clipId, body });
+    confirmPaid(options, 'Generating B-Roll');
+    output(await apiFetch(config, options, 'POST', `/api/v1/clips/${encodeURIComponent(clipId)}/broll/generate`, body), options);
+    return;
+  }
+  if (action === 'list') {
+    const clipId = requiredString(options['clip-id'] || args[0], '--clip-id');
+    output(await apiFetch(config, options, 'GET', `/api/v1/clips/${encodeURIComponent(clipId)}/broll`), options);
+    return;
+  }
+  if (action === 'get') {
+    const brollId = requiredString(args[0], 'B-Roll id');
+    output(await apiFetch(config, options, 'GET', `/api/v1/broll/${encodeURIComponent(brollId)}`), options);
+    return;
+  }
+  throw Object.assign(new Error(`Unknown broll command: ${action || ''}`), { exitCode: EXIT.USAGE });
+}
+
+function socialPlatformList(value) {
+  const platforms = stringList(value);
+  if (!platforms?.length) {
+    throw Object.assign(new Error('--platforms is required.'), { exitCode: EXIT.USAGE });
+  }
+  return platforms.map((platform) => platform.toLowerCase() === 'x' ? 'twitter' : platform);
+}
+
+function socialPostBody(options, scheduled) {
+  const body = compactObject({
+    clipId: requiredString(options['clip-id'], '--clip-id'),
+    platforms: socialPlatformList(options.platforms),
+    caption: requiredString(options.caption, '--caption'),
+    title: options.title,
+    hashtags: stringList(options.hashtags),
+  });
+  if (scheduled) body.scheduledFor = requiredString(options.at, '--at');
+  return body;
+}
+
+async function social(config, options, action, args) {
+  if (action === 'accounts') {
+    output(await apiFetch(config, options, 'GET', '/api/v1/social/accounts'), options);
+    return;
+  }
+  if (action === 'post') {
+    const body = socialPostBody(options, false);
+    await enforceMaxCredits(config, options, 'social post', { body });
+    confirmPaid(options, 'Publishing a social post');
+    output(await apiFetch(config, options, 'POST', '/api/v1/social/post', body), options);
+    return;
+  }
+  if (action === 'schedule') {
+    const body = socialPostBody(options, true);
+    await enforceMaxCredits(config, options, 'social schedule', { body });
+    confirmPaid(options, 'Scheduling a social post');
+    output(await apiFetch(config, options, 'POST', '/api/v1/social/schedule', body), options);
+    return;
+  }
+  if (action === 'posts') {
+    output(await apiFetch(config, options, 'GET', `/api/v1/social/posts${queryString({
+      clipId: options['clip-id'],
+      status: options.status,
+      limit: options.limit,
+      offset: options.offset,
+    })}`), options);
+    return;
+  }
+  if (action === 'get') {
+    const postId = requiredString(args[0], 'Social post id');
+    output(await apiFetch(config, options, 'GET', `/api/v1/social/posts/${encodeURIComponent(postId)}`), options);
+    return;
+  }
+  if (action === 'cancel') {
+    const postId = requiredString(args[0], 'Social post id');
+    requireConfirm(options, 'Cancelling a social post');
+    await apiFetch(config, options, 'DELETE', `/api/v1/social/posts/${encodeURIComponent(postId)}`);
+    output({ success: true, cancelled: postId }, options);
+    return;
+  }
+  throw Object.assign(new Error(`Unknown social command: ${action || ''}`), { exitCode: EXIT.USAGE });
+}
+
+async function jobs(config, options, action, args) {
+  if (!['get', 'wait'].includes(action)) {
+    throw Object.assign(new Error(`Unknown jobs command: ${action || ''}`), { exitCode: EXIT.USAGE });
+  }
+  const jobId = args[0];
+  if (!jobId) throw Object.assign(new Error('Job id is required.'), { exitCode: EXIT.USAGE });
+  const startedAt = Date.now();
+  const timeoutMs = numberOption(options['timeout-ms'], '--timeout-ms');
+  const intervalMs = numberOption(options.interval, '--interval') || 3000;
+  while (true) {
+    const job = await apiFetch(config, options, 'GET', `/api/v1/jobs/${encodeURIComponent(jobId)}`);
+    if (action === 'get' || TERMINAL_JOB_STATUSES.has(job.status)) {
+      output(job, options);
+      return;
+    }
+    if (options.stream) console.log(JSON.stringify({ type: 'job.progress', job }));
+    if (timeoutMs && Date.now() - startedAt > timeoutMs) {
+      throw Object.assign(new Error(`Timed out waiting for job ${jobId}.`), { exitCode: EXIT.SERVER });
+    }
+    await sleep(intervalMs);
+  }
+}
+
+function appUrl(config, options, kind, id) {
+  const baseUrl = getBaseUrl(config, options);
+  if (!kind || kind === 'home') return baseUrl;
+  if (kind === 'settings') return `${baseUrl}/settings?tab=${encodeURIComponent(options.tab || 'api-keys')}`;
+  if (kind === 'dashboard') return `${baseUrl}/dashboard`;
+  if (kind === 'library') return `${baseUrl}/clips`;
+  if (kind === 'editor') return `${baseUrl}/editor`;
+  if (kind === 'pricing') return `${baseUrl}/pricing`;
+  if (kind === 'credits') return `${baseUrl}/settings/credits`;
+  if (kind === 'clip') return `${baseUrl}/clips/review${id ? `?clipId=${encodeURIComponent(id)}` : ''}`;
+  if (kind === 'video') return `${baseUrl}/clips${id ? `?videoId=${encodeURIComponent(id)}` : ''}`;
+  if (kind === 'project') return `${baseUrl}/editor/projects${id ? `?projectId=${encodeURIComponent(id)}` : ''}`;
+  if (kind === 'sequence') return `${baseUrl}/editor/projects${id ? `?sequenceId=${encodeURIComponent(id)}` : ''}`;
+  if (kind === 'route') return `${baseUrl}/${String(id || '').replace(/^\/+/, '')}`;
+  return baseUrl;
+}
+
+async function openCommand(config, options, kind, id) {
+  const url = appUrl(config, options, kind, id);
+  if (options.print) {
+    output(url, options);
+    return;
+  }
+  openBrowser(url);
+  output({ opened: url }, options);
+}
+
+async function links(config, options, kind, id) {
+  const result = {
+    kind: kind || 'home',
+    id: id || null,
+    appUrl: appUrl(config, options, kind, id),
+  };
+  if (kind === 'clip' && id && boolOption(options.download)) {
+    try {
+      Object.assign(result, await apiFetch(config, options, 'GET', `/api/v1/clips/${encodeURIComponent(id)}/download`));
+    } catch (error) {
+      result.downloadError = redact(error.message);
+    }
+  }
+  output(result, options);
+}
+
+async function examples(options) {
+  const data = {
+    login: 'clipit login',
+    installCodexSkill: 'clipit agent install codex',
+    validate: 'clipit doctor --json',
+    importUrl: 'clipit videos import-url "https://www.youtube.com/watch?v=..." --json',
+    waitForJob: 'clipit jobs wait <jobId> --json',
+    ask: 'clipit ask "Find the strongest clip in this video" --video-id <videoId>',
+    approveWorkflow: 'clipit workflow approve <jobId> --approval-id <approvalId> --decision approved',
+    waitForWorkflow: 'clipit workflow wait <jobId> --stream',
+    setContext: 'clipit context use --video-id <videoId>',
+    suggestClips: 'clipit videos suggest-clips <videoId> --count 5 --json',
+    createClip: 'clipit clips create --video-id <videoId> --start 12 --end 42 --title "Strong hook" --json',
+    renderClip: 'clipit clips render <clipId> --aspect 9:16 --quality high --json',
+    creditsBalance: 'clipit credits balance --json',
+    analyticsOverview: 'clipit analytics overview --days 30 --json',
+    exportClip: 'clipit exports start --clip-id <clipId> --confirm --json',
+    uploadAsset: 'clipit assets upload ./brand-logo.png --kind image --json',
+    thumbnail: 'clipit thumbnails generate --clip-id <clipId> --prompt "Expressive high-contrast thumbnail" --confirm --json',
+    brollPlan: 'clipit broll plan <clipId> --count 3 --confirm --json',
+    socialPost: 'clipit social post --clip-id <clipId> --platforms x,tiktok --caption "New clip" --confirm --json',
+    runTool: 'clipit run <functionName> --clip-id <clipId> --params @params.json --json',
+    reviewLink: 'clipit links clip <clipId> --json',
+  };
+  if (wantJson(options)) {
+    output(data, options);
+    return;
+  }
+  output(Object.entries(data).map(([name, command]) => `${name}: ${command}`).join('\n'), options);
+}
+
+function skillMarkdown(agent) {
+  return `# ClipIt CLI
+
+Use the ClipIt CLI to operate ClipIt through the user's authenticated account. This is the generic offline fallback skill; when possible, run \`clipit agent update ${agent}\` after login to fetch server-rendered instructions scoped to the current API key.
+
+Rules:
+- Run \`clipit auth status --json\` before assuming ClipIt is connected.
+- If not connected, ask the user to run \`clipit login\` and approve the browser link.
+- Never ask the user to paste API keys into chat.
+- Use \`clipit skills list --json\` and \`clipit tools list --json\` to discover capability.
+- Prefer friendly commands such as \`clipit videos list --json\`, \`clipit clips list --json\`, \`clipit credits balance --json\`, and \`clipit jobs wait <jobId> --json\`.
+- Use \`clipit ask "..."\` for natural-language Clippy workflows, and \`clipit workflow wait <jobId> --json\` or \`clipit workflow approve <jobId> --approval-id <id>\` for workflow follow-through.
+- Use \`clipit run <functionName> --params @file.json --json\` for exact Clippy tools.
+- Treat paid generation, publishing, deletion, broad mutation, and \`requiresConfirmation\` responses as user approval checkpoints.
+- Treat exit code 13 as insufficient credits or an API key spend-limit block; top up billing or adjust the key's spend limit in ClipIt Settings.
+- Use \`clipit open clip <id>\` when the user should review work in ClipIt.
+- Use \`clipit context use --video-id <id>\` or \`clipit context use --clip-id <id>\` to persist the current target for later commands.
+- Do not write API keys into this skill file or any project files.
+
+Useful commands:
+\`\`\`bash
+clipit doctor --json
+clipit auth status --json
+clipit skills list --json
+clipit tools list --json
+clipit tools describe <functionName> --json
+clipit ask "Find the strongest clip in this video" --video-id <videoId> --json
+clipit workflow wait <jobId> --stream
+clipit videos list --json
+clipit videos import-url "https://example.com/video" --json
+clipit videos transcript <videoId> --json
+clipit videos suggest-clips <videoId> --count 5 --json
+clipit clips list --json
+clipit clips create --video-id <videoId> --start 12 --end 42 --title "Hook" --json
+clipit clips render <clipId> --aspect 9:16 --quality high --json
+clipit jobs wait <jobId> --stream
+clipit credits balance --json
+clipit credits usage --json
+clipit credits estimate --operation-type transcription --provider deepgram --metrics @metrics.json --json
+clipit analytics overview --days 30 --json
+clipit exports start --clip-id <clipId> --confirm --json
+clipit thumbnails generate --clip-id <clipId> --prompt "High contrast thumbnail" --confirm --json
+clipit social post --clip-id <clipId> --platforms x,tiktok --caption "New clip" --confirm --json
+clipit run renderClipWithRemotion --clip-id <clipId> --params @params.json --json
+\`\`\`
+
+Common workflow:
+1. Run \`clipit doctor --json\`.
+2. Use \`clipit context show --json\` to see whether a target video or clip is already active.
+3. Discover available tools before using \`clipit run\`.
+4. For long-running jobs, wait with \`clipit jobs wait <jobId> --json\`, \`clipit exports wait <jobId> --json\`, or stream NDJSON progress with \`--stream\`.
+5. Report review links with \`clipit links clip <clipId> --json\` or open the web app with \`clipit open clip <clipId>\`.
+
+Agent target: ${agent}
+`;
+}
+
+function fallbackSkillResult(target, reason) {
+  const generatedAt = new Date().toISOString();
+  return {
+    markdown: skillMarkdown(target),
+    source: 'fallback',
+    fallbackReason: reason,
+    meta: {
+      generatedAt,
+      target,
+    },
+  };
+}
+
+async function resolveAgentSkill(config, options, target) {
+  if (!getApiKey(config, options)) {
+    return fallbackSkillResult(target, 'not authenticated');
+  }
+
+  let response;
+  try {
+    response = await apiFetch(config, options, 'GET', `/api/v1/agent/instructions${queryString({ target, format: 'json' })}`);
+  } catch (error) {
+    if (error.status === 400 && !KNOWN_AGENT_TARGETS.includes(target)) {
+      // Older servers reject unknown framework names; their generic rendering
+      // is identical to what newer servers return for this target.
+      try {
+        response = await apiFetch(config, options, 'GET', `/api/v1/agent/instructions${queryString({ target: 'generic', format: 'json' })}`);
+      } catch (retryError) {
+        return fallbackSkillResult(target, redact(retryError.message));
+      }
+    } else {
+      return fallbackSkillResult(target, redact(error.message));
+    }
+  }
+
+  if (
+    !response ||
+    typeof response.markdown !== 'string' ||
+    !response.meta ||
+    typeof response.meta !== 'object' ||
+    Array.isArray(response.meta) ||
+    typeof response.meta.generatedAt !== 'string'
+  ) {
+    throw Object.assign(new Error('Instructions endpoint returned unexpected JSON shape; expected { markdown, meta }.'), {
+      exitCode: EXIT.SERVER,
+      data: response,
+    });
+  }
+
+  return {
+    markdown: response.markdown,
+    source: 'server',
+    meta: response.meta,
+  };
+}
+
+function agentSkillMetaPath(baseDir) {
+  return path.join(baseDir, AGENT_SKILL_META_FILENAME);
+}
+
+async function readAgentSkillMeta(baseDir) {
+  try {
+    return JSON.parse(await fs.readFile(agentSkillMetaPath(baseDir), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function agentSkillSidecar(target, skill) {
+  return compactObject({
+    target,
+    source: skill.source,
+    generatedAt: skill.meta?.generatedAt,
+    serverMeta: skill.source === 'server' ? skill.meta : undefined,
+    fallbackReason: skill.fallbackReason,
+  });
+}
+
+function printFallbackNotice(skill, installed = false) {
+  if (skill.source === 'fallback') {
+    const prefix = installed ? 'Installed' : 'Using';
+    console.error(`${prefix} generic offline ClipIt skill; server-rendered instructions unavailable (${skill.fallbackReason}).`);
+  }
+}
+
+function agentInstallDir(target, options) {
+  if (options.dir) return path.resolve(String(options.dir));
+  if (target === 'codex') return path.join(os.homedir(), '.codex', 'skills', 'clipit-cli');
+  if (target === 'claude') return path.join(os.homedir(), '.claude', 'skills', 'clipit-cli');
+  if (target === 'hermes') return path.join(os.homedir(), '.hermes', 'skills', 'clipit-cli');
+  return path.join(configDir(), 'agent-skills', target, 'clipit-cli');
+}
+
+async function installedAgentStatus(target, options) {
+  const baseDir = agentInstallDir(target, options);
+  try {
+    const stat = await fs.stat(path.join(baseDir, 'SKILL.md'));
+    const sidecar = await readAgentSkillMeta(baseDir);
+    return {
+      target,
+      installed: true,
+      path: baseDir,
+      updatedAt: stat.mtime.toISOString(),
+      skillSource: sidecar?.source || 'unknown',
+      generatedAt: sidecar?.generatedAt || null,
+      fallbackReason: sidecar?.fallbackReason || null,
+      serverMeta: sidecar?.serverMeta || null,
+    };
+  } catch {
+    return { target, installed: false, path: baseDir };
+  }
+}
+
+async function agent(config, options, action, args) {
+  const target = args[0] || 'generic';
+  const baseDir = agentInstallDir(target, options);
+
+  if (action === 'print-skill') {
+    const skill = await resolveAgentSkill(config, options, target);
+    printFallbackNotice(skill);
+    output(skill.markdown, options);
+    return;
+  }
+  if (action === 'list') {
+    output({ agents: await Promise.all(KNOWN_AGENT_TARGETS.map((name) => installedAgentStatus(name, options))) }, options);
+    return;
+  }
+  if (action === 'doctor') {
+    const status = await installedAgentStatus(target, options);
+    status.cli = {
+      version: VERSION,
+      configPath: configPath(),
+      profile: profileName(config, options),
+      hasCredential: Boolean(getApiKey(config, options)),
+    };
+    output(status, options);
+    return;
+  }
+  if (action === 'install' || action === 'update') {
+    const skill = await resolveAgentSkill(config, options, target);
+    printFallbackNotice(skill, true);
+    await fs.mkdir(baseDir, { recursive: true });
+    await fs.writeFile(path.join(baseDir, 'SKILL.md'), skill.markdown, 'utf8');
+    await fs.writeFile(agentSkillMetaPath(baseDir), `${JSON.stringify(agentSkillSidecar(target, skill), null, 2)}\n`, 'utf8');
+    output({
+      success: true,
+      action,
+      target,
+      path: baseDir,
+      skillSource: skill.source,
+      generatedAt: skill.meta?.generatedAt || null,
+      fallback: skill.source === 'fallback',
+    }, options);
+    return;
+  }
+  if (action === 'uninstall') {
+    await fs.rm(baseDir, { recursive: true, force: true });
+    output({ success: true, action, target, path: baseDir }, options);
+    return;
+  }
+  throw Object.assign(new Error(`Unknown agent command: ${action || ''}`), { exitCode: EXIT.USAGE });
+}
+
+async function main() {
+  const { options, positionals } = parseArgv(process.argv.slice(2));
+  const config = await readConfig();
+  const [command, subcommand, ...rest] = positionals;
+
+  if (!command || options.help) {
+    console.log(usage());
+    return;
+  }
+  if (command === 'version' || command === '--version' || command === '-v') {
+    output({ version: VERSION }, options);
+    return;
+  }
+  if (command === 'login') return login(config, options);
+  if (command === 'setup') return setup(config, options);
+  if (command === 'logout') return logout(config, options);
+  if (command === 'doctor') return doctor(config, options);
+  if (command === 'auth' && subcommand === 'status') return authStatus(config, options);
+  if (command === 'auth' && subcommand === 'set-key') return setKey(config, options);
+  if (command === 'auth' && subcommand === 'open-settings') return openCommand(config, options, 'settings');
+  if (command === 'auth' && subcommand === 'profiles') return listProfiles(config, options);
+  if (command === 'context') return contextCommand(config, options, subcommand);
+  if (command === 'skills' && subcommand === 'list') return listSkills(config, options);
+  if (command === 'tools' && subcommand === 'list') return listTools(config, options);
+  if (command === 'tools' && subcommand === 'describe') return describeTool(config, options, rest[0]);
+  if (command === 'ask') return askWorkflow(config, options, [subcommand, ...rest]);
+  if (command === 'workflow') return workflow(config, options, subcommand, rest);
+  if (command === 'run') return runTool(config, options, subcommand);
+  if (command === 'videos') return videos(config, options, subcommand, rest);
+  if (command === 'clips') return clips(config, options, subcommand, rest);
+  if (command === 'jobs') return jobs(config, options, subcommand, rest);
+  if (command === 'credits') return credits(config, options, subcommand, rest);
+  if (command === 'analytics') return analytics(config, options, subcommand, rest);
+  if (command === 'exports') return exportsCommand(config, options, subcommand, rest);
+  if (command === 'assets') return assets(config, options, subcommand, rest);
+  if (command === 'thumbnails') return thumbnails(config, options, subcommand, rest);
+  if (command === 'broll') return broll(config, options, subcommand, rest);
+  if (command === 'social') return social(config, options, subcommand, rest);
+  if (command === 'open') return openCommand(config, options, subcommand, rest[0]);
+  if (command === 'links') return links(config, options, subcommand, rest[0]);
+  if (command === 'agent') return agent(config, options, subcommand, rest);
+  if (command === 'examples') return examples(options);
+
+  throw Object.assign(new Error(`Unknown command: ${command}`), { exitCode: EXIT.USAGE });
+}
+
+function handleMainError(error) {
+  const exitCode = error.exitCode || EXIT.SERVER;
+  const message = redact(error.message || String(error));
+  if (process.argv.includes('--json')) {
+    console.error(JSON.stringify(compactObject({
+      error: message,
+      status: error.status,
+      requestId: error.requestId,
+      details: redactDeep(error.data),
+    }), null, 2));
+  } else {
+    console.error(message);
+  }
+  process.exit(exitCode);
+}
+
+async function isDirectRun() {
+  if (!process.argv[1]) return false;
+  const modulePath = fileURLToPath(import.meta.url);
+  try {
+    const [invoked, current] = await Promise.all([
+      fs.realpath(process.argv[1]),
+      fs.realpath(modulePath),
+    ]);
+    return invoked === current;
+  } catch {
+    return path.resolve(process.argv[1]) === modulePath;
+  }
+}
+
+if (await isDirectRun()) {
+  main().catch(handleMainError);
+}
+
+export { main, redact };