{"_id":"revid-cli","_rev":"9-1c9ef880b6ef56a221d76f197482f506","name":"revid-cli","dist-tags":{"latest":"0.2.3"},"versions":{"0.1.0":{"name":"revid-cli","version":"0.1.0","keywords":["revid","video","ai-video","cli","agents"],"license":"UNLICENSED","_id":"revid-cli@0.1.0","maintainers":[{"name":"tmaker","email":"tibo@tmaker.io"}],"homepage":"https://www.revid.ai","bugs":{"url":"https://www.revid.ai"},"bin":{"revid":"bin/revid.mjs"},"dist":{"shasum":"e6d3d4018502a78ef78dcb13a1dc9babca47a31c","tarball":"https://registry.npmjs.org/revid-cli/-/revid-cli-0.1.0.tgz","fileCount":3,"integrity":"sha512-Jd+wFSJkBRxS+szZdxDT8ZApDw1UvwhLWAQfvZlVOKIsNEn64akJVTavnGIdhvu3W7JD2nRIIypVTn/nAY1lzw==","signatures":[{"sig":"MEYCIQCqKeaBOg4/ZKBf6owcg9CibDKQ+ulzLue0zhRKsPV2LgIhAPe5jsjJ5+3tUSYqtBndcooiHNLP9H2xUX+tE8NekQlx","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":46587},"type":"module","engines":{"node":">=18"},"gitHead":"cd74875665cb56eb6dbc1136bd1f672d9fa2c237","scripts":{"test":"node --test test/*.test.mjs","check":"node --check bin/revid.mjs","pack:dry-run":"npm pack --dry-run"},"_npmUser":{"name":"tmaker","email":"tibo@tmaker.io"},"_npmVersion":"10.8.2","description":"Command-line interface for creating videos with the Revid API.","directories":{},"_nodeVersion":"20.19.3","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/revid-cli_0.1.0_1777520625217_0.4593968149688463","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"revid-cli","version":"0.1.1","keywords":["revid","video","ai-video","cli","agents"],"license":"UNLICENSED","_id":"revid-cli@0.1.1","maintainers":[{"name":"tmaker","email":"tibo@tmaker.io"}],"homepage":"https://www.revid.ai","bugs":{"url":"https://www.revid.ai"},"bin":{"revid":"bin/revid.mjs"},"dist":{"shasum":"103b1cb891aeb2e0e4628e4c27133980b2d7b19f","tarball":"https://registry.npmjs.org/revid-cli/-/revid-cli-0.1.1.tgz","fileCount":3,"integrity":"sha512-CiTrLrIqjKMWY9XXNbBd/5WX4RhC8nH/ukdR+0M1BbaQ0yzwlp21yVqy8lxvu17TJhXcs6SMMO6VNrMIS8yazg==","signatures":[{"sig":"MEYCIQDRl0RsgUb7lx3MvVxgnUw1seeD7PzBD6nNwMXPLH5tQgIhAODBFbD7+3oJ1a9IzWy7cMh4O9Hy34rUeBTzCxP8ItLj","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":56899},"type":"module","engines":{"node":">=18"},"gitHead":"19711209b2454d25ae22935879a21b3bd4e2abe0","scripts":{"test":"node --test test/*.test.mjs","check":"node --check bin/revid.mjs","pack:dry-run":"npm pack --dry-run"},"_npmUser":{"name":"tmaker","email":"tibo@tmaker.io"},"_npmVersion":"10.8.2","description":"Command-line interface for creating videos with the Revid API.","directories":{},"_nodeVersion":"20.19.3","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/revid-cli_0.1.1_1777521431974_0.6708293021442124","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"revid-cli","version":"0.1.2","keywords":["revid","video","ai-video","cli","agents"],"license":"UNLICENSED","_id":"revid-cli@0.1.2","maintainers":[{"name":"tmaker","email":"tibo@tmaker.io"}],"homepage":"https://www.revid.ai","bugs":{"url":"https://www.revid.ai"},"bin":{"revid":"bin/revid.mjs"},"dist":{"shasum":"c4dec8a23d58925d12adab2a2c2cb33ffb6cca30","tarball":"https://registry.npmjs.org/revid-cli/-/revid-cli-0.1.2.tgz","fileCount":3,"integrity":"sha512-hEAP8n8BVLICunnALEon4j0tO0JcrDrhHxByiFk/8fWtU5jXdvr3vWzLCqjwE4NwDCVpJhGxBhj0qjL1aTOKdw==","signatures":[{"sig":"MEYCIQDognud80tNE2mjcW5f8sQ4h7ke0m+7QOrr8JkXiCzohgIhAP7GcjRKD1B2Bo9P7nvpMXRDhiRxEhEz5Rs2Y2Fq7Vt2","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":76355},"type":"module","engines":{"node":">=18"},"gitHead":"bd1ce3c81d8e719dc470c1c8b2dcfde34b0e6575","scripts":{"test":"node --test test/*.test.mjs","check":"node --check bin/revid.mjs","pack:dry-run":"npm pack --dry-run"},"_npmUser":{"name":"tmaker","email":"tibo@tmaker.io"},"_npmVersion":"10.8.2","description":"Command-line interface for creating videos with the Revid API.","directories":{},"_nodeVersion":"20.19.3","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/revid-cli_0.1.2_1777869645715_0.7058296815571479","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"revid-cli","version":"0.1.3","keywords":["revid","video","ai-video","cli","agents"],"license":"UNLICENSED","_id":"revid-cli@0.1.3","maintainers":[{"name":"tmaker","email":"tibo@tmaker.io"}],"homepage":"https://www.revid.ai","bugs":{"url":"https://www.revid.ai"},"bin":{"revid":"bin/revid.mjs"},"dist":{"shasum":"24524bbda2e024bd74b78842754d008a3b7e5f79","tarball":"https://registry.npmjs.org/revid-cli/-/revid-cli-0.1.3.tgz","fileCount":3,"integrity":"sha512-Prsvbv2BRc2aHbCQdV5vd4UTosqjQaStchukqYqs3/pi2tdznyAMUHNYmkUfqT4Do9kbJrnwm/0WcIeGoiJvXw==","signatures":[{"sig":"MEYCIQCNhsH8zXyCtaWs5LiU4bziiZmrvx1zlPe/vqb8RYqegQIhAMt4Y/kM96fyzIVYUUE9MuaGHIIdXcJL1vKi2jWxswi9","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":96694},"type":"module","engines":{"node":">=18"},"gitHead":"75b867b9995f9491fd68993d8a54dd52da015be6","scripts":{"test":"node --test test/*.test.mjs","check":"node --check bin/revid.mjs","pack:dry-run":"npm pack --dry-run"},"_npmUser":{"name":"tmaker","email":"tibo@tmaker.io"},"_npmVersion":"10.8.2","description":"Command-line interface for creating videos with the Revid API.","directories":{},"_nodeVersion":"20.19.3","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/revid-cli_0.1.3_1777873552872_0.8071738077220527","host":"s3://npm-registry-packages-npm-production"}},"0.1.4":{"name":"revid-cli","version":"0.1.4","keywords":["revid","video","ai-video","cli","agents"],"license":"UNLICENSED","_id":"revid-cli@0.1.4","maintainers":[{"name":"tmaker","email":"tibo@tmaker.io"}],"homepage":"https://www.revid.ai","bugs":{"url":"https://www.revid.ai"},"bin":{"revid":"bin/revid.mjs"},"dist":{"shasum":"42be8a159b4dd640502155f3e67e4e2352617666","tarball":"https://registry.npmjs.org/revid-cli/-/revid-cli-0.1.4.tgz","fileCount":3,"integrity":"sha512-sw2CWpnkc+hMMpZCFgQC9EVzP1bIV6DGjGdykW2iCEzDpaGVBzC70CWuWQFovLOf142ILBOHgdHC4H4RRtHoQA==","signatures":[{"sig":"MEUCIQCH2U4QdlhANnduCrluu18hsq+CPfucmQeAYoHfR6KY6AIgbyOGki9vzP3o3dgaWKQXYKhfSrLujGUN6pq1ut+lkF8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":109014},"type":"module","engines":{"node":">=18"},"gitHead":"d35e7c70d7b902e4f63939bc371138ddbf4ae952","scripts":{"test":"node --test test/*.test.mjs","check":"node --check bin/revid.mjs","pack:dry-run":"npm pack --dry-run"},"_npmUser":{"name":"tmaker","email":"tibo@tmaker.io"},"_npmVersion":"10.8.2","description":"Command-line interface for creating videos with the Revid API.","directories":{},"_nodeVersion":"20.19.3","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/revid-cli_0.1.4_1777888957395_0.7806916673783997","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"revid-cli","version":"0.2.0","keywords":["revid","video","ai-video","cli","agents"],"license":"UNLICENSED","_id":"revid-cli@0.2.0","maintainers":[{"name":"tmaker","email":"tibo@tmaker.io"}],"homepage":"https://www.revid.ai","bugs":{"url":"https://www.revid.ai"},"bin":{"revid":"bin/revid.mjs"},"dist":{"shasum":"2c9c2862a8e785f65c9d8bf83829726613e5d259","tarball":"https://registry.npmjs.org/revid-cli/-/revid-cli-0.2.0.tgz","fileCount":3,"integrity":"sha512-DoreIDeEV1igqcWBagKd10Gez71WdaCiSfJn6y9UscWbVMkCJabj6QVlkDwR5kPPm64hrd1WmWcdyl2EB8+PnA==","signatures":[{"sig":"MEYCIQDGKtBGeAjAgPMJVvwoPJYi3vdluNGd7bNyBEM+a0N50wIhAK/+P3J8GEdngXThcGS0ptEnrLKXu+zf5UBV73TaIwLn","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":118730},"type":"module","engines":{"node":">=18"},"gitHead":"d35e7c70d7b902e4f63939bc371138ddbf4ae952","scripts":{"test":"node --test test/*.test.mjs","check":"node --check bin/revid.mjs","pack:dry-run":"npm pack --dry-run"},"_npmUser":{"name":"tmaker","email":"tibo@tmaker.io"},"_npmVersion":"10.8.2","description":"Command-line interface for creating videos with the Revid API.","directories":{},"_nodeVersion":"20.19.3","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/revid-cli_0.2.0_1788253245470_0.8869597627593595","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"revid-cli","version":"0.2.1","keywords":["revid","video","ai-video","cli","agents"],"license":"UNLICENSED","_id":"revid-cli@0.2.1","maintainers":[{"name":"tmaker","email":"tibo@tmaker.io"}],"homepage":"https://www.revid.ai","bugs":{"url":"https://www.revid.ai"},"bin":{"revid":"bin/revid.mjs"},"dist":{"shasum":"07963375fe210137d73080449b1e9e42a92387aa","tarball":"https://registry.npmjs.org/revid-cli/-/revid-cli-0.2.1.tgz","fileCount":3,"integrity":"sha512-R+sAPeGrj0oHztcghtqXKaB1p76UIcHzQxRm1L7L3v93wxNUaMZSNhKCGzxQ/9JwuEyAZMyIFr3G65OSQ79fbg==","signatures":[{"sig":"MEQCIFzNCgGN/sMcc2iBNj+E5uTyJ5HtwdXIcFkyoH9UUnzKAiBXwKTMX4SjRzT97le4dmhsp2LzuRx7sNH78MPgG1El2g==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":120581},"type":"module","engines":{"node":">=18"},"gitHead":"d35e7c70d7b902e4f63939bc371138ddbf4ae952","scripts":{"test":"node --test test/*.test.mjs","check":"node --check bin/revid.mjs","pack:dry-run":"npm pack --dry-run"},"_npmUser":{"name":"tmaker","email":"tibo@tmaker.io"},"_npmVersion":"10.8.2","description":"Command-line interface for creating videos with the Revid API.","directories":{},"_nodeVersion":"20.19.3","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/revid-cli_0.2.1_1788255092674_0.6320491001398649","host":"s3://npm-registry-packages-npm-production"}},"0.2.2":{"name":"revid-cli","version":"0.2.2","keywords":["revid","video","ai-video","cli","agents"],"license":"UNLICENSED","_id":"revid-cli@0.2.2","maintainers":[{"name":"tmaker","email":"tibo@tmaker.io"}],"homepage":"https://www.revid.ai","bugs":{"url":"https://www.revid.ai"},"bin":{"revid":"bin/revid.mjs"},"dist":{"shasum":"5449ebcb34f0c7715c866f906ae4b22bacbea9d5","tarball":"https://registry.npmjs.org/revid-cli/-/revid-cli-0.2.2.tgz","fileCount":3,"integrity":"sha512-GmfDMdr6/Xmz/XXAqjZuEE6uN1pcfkD10dXCUimZvznN7Teo1KTZRa7p+SH9O84OHqqN3uYJqn7Es3W9PA76nw==","signatures":[{"sig":"MEUCIAvo18CNXC09xa1rhvqIfz6VV7glocvViDjPxtIrdBMmAiEAydF/SnwUB1rD7ZR0tMuPgSugbhSMcAvdgSQcU7ISiU0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":121502},"type":"module","engines":{"node":">=18"},"gitHead":"ae4a043aa120af2fd364c3654911387b4b7cc360","scripts":{"test":"node --test test/*.test.mjs","check":"node --check bin/revid.mjs","pack:dry-run":"npm pack --dry-run"},"_npmUser":{"name":"tmaker","email":"tibo@tmaker.io"},"_npmVersion":"10.8.2","description":"Command-line interface for creating videos with the Revid API.","directories":{},"_nodeVersion":"20.19.3","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/revid-cli_0.2.2_1788882008463_0.005446835126965199","host":"s3://npm-registry-packages-npm-production"}},"0.2.3":{"_id":"revid-cli@0.2.3","bin":{"revid":"bin/revid.mjs"},"bugs":{"url":"https://www.revid.ai"},"dist":{"shasum":"1530d4524d74339d826df6fb466dd755fafb00c7","tarball":"https://registry.npmjs.org/revid-cli/-/revid-cli-0.2.3.tgz","fileCount":3,"integrity":"sha512-8DUWRFD99sLGdLAKuz1RWoMiXRR085TlRYmL5Gm/ipaygw9o7a9/4o4PLQnRieCN4eygxz/KREyeHCWfAY445w==","signatures":[{"sig":"MEYCIQDNey0TIlOtM7K7ZNJXbhuhP3astg7K/7LZdPsHnAuxwQIhAKsqBqcP3CjjDq2BBjmaDwxLnYx+smONAG0zUQ1X//Tn","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBnfzID11slKeJ2e1iXRa+hrdGA9u2MfCd2gawN6aZLOAiAWeee3fjqYYpGoYNyLBRr/4U3GmqXEkkukGEoMfN6YlQ=="}],"unpackedSize":130149},"name":"revid-cli","type":"module","engines":{"node":">=18"},"gitHead":"ae4a043aa120af2fd364c3654911387b4b7cc360","license":"UNLICENSED","scripts":{"test":"node --test test/*.test.mjs","check":"node --check bin/revid.mjs","pack:dry-run":"npm pack --dry-run"},"version":"0.2.3","_npmUser":{"name":"tmaker","email":"tibo@tmaker.io"},"homepage":"https://www.revid.ai","keywords":["revid","video","ai-video","cli","agents"],"_npmVersion":"10.8.2","description":"Command-line interface for creating videos with the Revid API.","directories":{},"maintainers":[{"name":"tmaker","email":"tibo@tmaker.io"}],"_nodeVersion":"20.19.3","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/revid-cli_0.2.3_1790258122688_0.42713666479185375"}}},"time":{"created":"2026-04-30T03:43:45.114Z","modified":"2026-09-24T13:55:22.967Z","0.1.0":"2026-04-30T03:43:45.353Z","0.1.1":"2026-04-30T03:57:12.107Z","0.1.2":"2026-05-04T04:40:45.865Z","0.1.3":"2026-05-04T05:45:53.035Z","0.1.4":"2026-05-04T10:02:37.535Z","0.2.0":"2026-09-01T09:00:45.595Z","0.2.1":"2026-09-01T09:31:32.804Z","0.2.2":"2026-09-08T15:40:08.589Z","0.2.3":"2026-09-24T13:55:22.786Z"},"bugs":{"url":"https://www.revid.ai"},"license":"UNLICENSED","homepage":"https://www.revid.ai","keywords":["revid","video","ai-video","cli","agents"],"description":"Command-line interface for creating videos with the Revid API.","maintainers":[{"name":"tmaker","email":"tibo@tmaker.io"}],"readme":"# Revid CLI\n\nCreate videos from the command line using the Revid public API.\n\nThe CLI is optimized for AI agents and automation:\n\n- Stable JSON output with `--json`\n- Exact API payload mode with `--payload`\n- Fast one-line creation with `--prompt`, `--text`, or `--url`\n- Guided JSON planning with `revid guided --json` so agents pick the right workflow and models before rendering\n- Planning mode with `revid plan` for the same machine-readable planning contract\n- Interactive guided creation with `revid guided`\n- Async render handling through `create`, `status`, `wait`, and `export`\n- Offline context for agents through `revid guide --json`\n- Live helper commands for voices and visual presets\n- Viral video research with `revid search` (transcripts, engagement data, hooks)\n- Structured missing-field errors that tell agents exactly which helper command to run\n\nRequires Node.js 18 or newer.\n\n## Install\n\n```bash\nnpm install -g revid-cli\n```\n\nDuring local development from this folder:\n\n```bash\nnpm link\nrevid --help\n```\n\n## Authentication\n\nFor AI agents, CI, and production automation, use an environment variable:\n\n```bash\nexport REVID_API_KEY=\"your_revid_api_key\"\n```\n\nFor local human use:\n\n```bash\nrevid auth login\nrevid auth status\n```\n\nAuth precedence:\n\n1. `--api-key`\n2. `REVID_API_KEY`\n3. Local config from `revid auth login`\n\nUse `--base-url` or `REVID_BASE_URL` for staging or local API targets. The default production API is `https://www.revid.ai`.\n\nA valid key is not always enough: rendering, media generation, export, characters, and voice cloning need an active Revid plan, and credits alone do not unlock them. Without one the API answers `402` with `code: \"SUBSCRIPTION_REQUIRED\"` and an `upgrade` object, and the CLI prints the subscribe link on the error line itself: https://www.revid.ai/pricing. Agents should pass that link on to the user.\n\n## Quick Start\n\nIf an agent has no Revid context, start with:\n\n```bash\nrevid guide --json\nrevid guided --json --goal \"Create a satirical Pixar-style roast video from this X profile picture\" --reference-image-url \"https://example.com/profile.jpg\" --media-preset PIXAR\nrevid plan --goal \"Create a satirical Pixar-style roast video from this X profile picture\" --reference-image-url \"https://example.com/profile.jpg\" --media-preset PIXAR --json\nrevid workflows --json\nrevid presets --json\nrevid voices --json\nrevid examples prompt-to-video --json\n```\n\nPrompt to video:\n\n```bash\nrevid create --prompt \"A cinematic 30 second product launch video\" --wait --json\n```\n\nFor AI agents, the recommended way to start is the guided JSON flow:\n\n```bash\nrevid guided --json \\\n  --goal \"Create a satirical Pixar-style roast video from this X profile picture\" \\\n  --reference-image-url \"https://example.com/profile.jpg\" \\\n  --media-preset PIXAR\n```\n\nThis is recommended for agents because it returns stable JSON: workflow choice, expected output, model questions, common wrong choices, and a starter payload. Plain `revid guided` remains the interactive human wizard.\n\nYou can also call the planning command directly:\n\n```bash\nrevid plan \\\n  --goal \"Create a satirical Pixar-style roast video from this X profile picture\" \\\n  --reference-image-url \"https://example.com/profile.jpg\" \\\n  --media-preset PIXAR \\\n  --json\n```\n\n`revid plan` returns the recommended workflow, expected output, model-selection questions, warnings for common wrong workflow choices, and a starter payload. For example, a profile picture used as inspiration should become `prompt-to-video` with `media.provided[]`; it should not become `avatar-to-video` unless the user explicitly wants a talking head.\n\nScript to video:\n\n```bash\nrevid create --text \"Paste the narration script here.\" --aspect-ratio portrait --wait\n```\n\nArticle to video:\n\n```bash\nrevid create --workflow article-to-video --url \"https://example.com/post\" --wait --json\n```\n\nGuided mode:\n\n```bash\nrevid guided\n```\n\n## Agent Payload Mode\n\nSend an exact Revid v3 render payload:\n\n```bash\nrevid create --payload payload.json --wait --json\n```\n\nRead from stdin:\n\n```bash\ncat payload.json | revid create --payload - --wait --json\n```\n\nOverride payload fields without editing the JSON file:\n\n```bash\nrevid create --payload payload.json --set render.resolution=1080p --set options.outputCount=2 --wait --json\n```\n\nPrint the request payload without calling Revid:\n\n```bash\nrevid create --prompt \"A clean SaaS launch video\" --dry-run --json\n```\n\n## Agent Discovery Commands\n\nUse these when the caller does not already know Revid's API concepts:\n\n```bash\nrevid guide --json\nrevid workflows --json\nrevid examples --json\nrevid examples prompt-to-video --json\nrevid template script-to-video\nrevid docs --json\nrevid docs --local --json\nrevid guided --json --goal \"Create a product launch video\"\nrevid plan --goal \"Create a product launch video\" --json\nrevid presets --json\nrevid presets --search cinematic --json\nrevid voices --json\nrevid voices labels --json\nrevid voices --gender female --language en --json\nrevid search \"ai tools for founders\" --min-views 100000 --json\n```\n\nCore mental model:\n\n- `create` starts an asynchronous Revid project and returns a `pid`.\n- `wait` polls that `pid` until `videoUrl` is available or the job fails.\n- `webhookUrl` is preferred for production callbacks.\n- `--payload` sends exact Revid v3 JSON.\n- `--reference-image-url` puts an image in `media.provided[]` as a visual/person/style reference for generated scenes.\n- `--avatar-url` is only for talking-avatar videos where the provided image/video should become the on-screen speaker.\n- Missing model choices return `code: \"MISSING_MODEL_SELECTION\"` with `data.modelSelection.questions[]`.\n- `media.imageModel` is requested only when image generation is relevant and `media.type` is not `ai-video`.\n- `media.videoModel` is requested when generated video motion is relevant.\n- `media.type: motion-graphics` renders animated motion graphics scenes; its `media.videoModel` tiers are `base` (fast director, 30 credits/scene) and `pro` (premium director, 60 credits/scene) — higher models are mapped to `pro` by the API.\n- Motion graphics mirror the Revid create form: `media.mediaPreset` (`--media-preset`) picks the style, `MOTION_INSPIRATION_CLEAN_WORDMARK` (default), `MOTION_INSPIRATION_WARM_LAUNCH` or `MOTION_INSPIRATION_DARK_SAAS` (loose spellings like `dark-saas` are accepted), and `media.continuousMode` (`--continuous-mode`) keeps one composition running through the whole video instead of independent scenes. Generated clips are charged on top of the scenes, so `revid credits` reports an upper bound.\n- Use `--auto-models` to accept the CLI's recommended defaults.\n- `--set path=value` lets agents override a payload field without rewriting JSON.\n- `--dry-run --json` prints the request payload before spending credits.\n- Missing required fields return `code: \"MISSING_REQUIRED_FIELDS\"` with `data.missingFields[]`, including the path, the flag to use, and a helper command.\n- In an interactive terminal, missing required fields are prompted automatically. Use `--no-prompt` to force agent-style errors, or `--ask-missing` to prompt even with `--json`.\n\nVoice and preset selection:\n\n- Run `revid voices --json` to list voice IDs for `voice.voiceId` or `--voice-id`.\n- Run `revid voices labels --json` to see filterable labels such as language, gender, accent, age, and use case.\n- Run `revid presets --json` to list visual preset values for `media.mediaPreset` or `--media-preset`. The motion graphics styles are listed under `motionGraphics`.\n- Run `revid presets --media-type motion-graphics --json` for the motion graphics styles alone.\n- Run `revid presets --search <term> --json` when the desired style is known loosely.\n\nWorkflow selection:\n\n- Use `prompt-to-video` for a full generated video from a creative brief, including profile-picture roasts, stylized stories, satire, explainers, or creative videos with reference images.\n- Use `avatar-to-video` only when the user wants the provided avatar/profile image to speak directly to camera as a talking avatar.\n- Use `script-to-video` when the user provides the exact narration/script that should drive the video.\n- Use `caption-video` when the user has an existing video and mainly wants subtitles/reframing.\n\nWorkflow requirements:\n\n| Workflow | Required fields |\n| --- | --- |\n| `script-to-video` | `source.text` |\n| `audio-to-video` | `source.url` |\n| `prompt-to-video` | `source.prompt` |\n| `music-to-video` | `source.url` |\n| `article-to-video` | `source.url` |\n| `avatar-to-video` | `source.text`, `avatar.url` |\n| `static-background-video` | `source.text` or `source.url` |\n| `motion-transfer` | `source.url`, `media.provided[]` |\n| `caption-video` | `source.url` |\n| `ad-generator` | `source.prompt` or `media.provided[]` |\n\n## Viral Video Search\n\nResearch what performs before creating content. `revid search` queries the same engine as [revid.ai/search](https://www.revid.ai/search): semantic search over viral short-form videos and posts across YouTube, Instagram, TikTok, X, Reddit, Threads, and LinkedIn.\n\n```bash\nrevid search \"ai tools for founders\" --json\nrevid search \"morning routine\" --platforms tiktok,instagram --min-views 100000 --sort popular --json\nrevid search \"startup story\" --viral-only --json\nrevid search \"product demo\" --content-type Tutorial --mood Informative --json\n```\n\nEach result includes `mediaUrl` (a Revid-hosted media file that plays directly), `platformPageUrl` (the original post page), the full transcript, an AI summary, the opening hook, author info, engagement counts and rate (views, likes, comments, shares), engagement tier, hashtags, posting date, and AI-analyzed style labels. This makes it a strong first step for agents: find what already works, study the transcripts and hooks, then feed the learnings into `revid guided` or `revid create`.\n\n**When showing results to users, always link `mediaUrl`.** It is listed first on every video and plays directly — no login wall, no region block, no deleted-post risk. Treat `platformPageUrl` as a secondary \"view on platform\" link, and use it as the primary link only when `mediaUrl` is absent (text posts and some YouTube rows). The response's `display` field repeats this rule so agents pick it up from the JSON itself.\n\nNotes for agents:\n\n- Searching costs 0 credits but is rate limited per plan (rolling 24h): free API keys get 20 searches/day, paid plans 500/day, Elite 2000/day, Enterprise 10000/day. Hitting the limit returns `code: \"RATE_LIMITED\"` with an `upgrade` object (message, next tier, pricing URL).\n- Results are capped at 12 per call with no pagination; vary the query or filters to discover more.\n- Filters: `--platforms`, `--viral-only`, `--language`, `--hashtags`, `--min-likes`, `--min-views`, `--min-shares`, `--min-comments`, `--min-duration`, `--max-duration` (durations apply to TikTok results only), `--posted-after`, `--posted-before`, `--perspective`, `--setting`, `--visual-origin`, `--shooting-style`, `--mood`, `--content-type`, `--brand-promotion`, `--sort <relevance|recent|popular>`, `--limit`.\n- Invalid enum values return `code: \"INVALID_PARAMETER\"` with the allowed values, so agents can self-correct.\n- `--no-transcripts` trims transcripts from the output when context space is tight.\n- `--viral-only` filters to posts in the `high`/`viral` engagement tier and excludes TikTok results (no tier data there).\n\nRun `revid search --help` for the full flag reference.\n\n## Async Render Flow\n\nThe recommended production flow is:\n\n1. Start a render:\n\n   ```bash\n   revid create --payload payload.json --json\n   ```\n\n2. Store the returned `pid`.\n3. Prefer `--webhook-url` for production systems.\n4. For agents and local scripts, poll with:\n\n   ```bash\n   revid wait <pid> --json\n   ```\n\n5. Download the final video when needed:\n\n   ```bash\n   revid wait <pid> --output ./video.mp4 --json\n   ```\n\n`--wait` on `create` combines start and polling in one command. `--output` on `create` implies waiting.\n\n## Useful Commands\n\n```bash\nrevid workflows --json\nrevid guided --json --goal \"Satirical Pixar roast from a profile picture\" --reference-image-url https://example.com/profile.jpg --media-preset PIXAR\nrevid plan --goal \"Satirical Pixar roast from a profile picture\" --reference-image-url https://example.com/profile.jpg --media-preset PIXAR --json\nrevid presets --json\nrevid presets --media-type motion-graphics --json\nrevid create --prompt \"Announce our new analytics feature\" --media-type motion-graphics --media-preset MOTION_INSPIRATION_DARK_SAAS --continuous-mode --video-model pro --wait --json\nrevid voices --json\nrevid template prompt-to-video\nrevid docs --json\nrevid credits --payload payload.json --json\nrevid projects --limit 10 --json\nrevid status <pid> --json\nrevid export <pid> --json\n```\n\n## Publishing\n\nBefore publishing:\n\n```bash\nnpm test\nnpm run check\nnpm pack --dry-run\n```\n\nFirst manual publish:\n\n```bash\nnpm login\nnpm publish --access public\n```\n\nDo not put Revid API keys in this package, test fixtures, docs, or npm metadata.\n","readmeFilename":"README.md"}