cviral — the CloneViral CLI

Generate AI images and video, drive Director Studio, and build, run and deliver Viral Flow graphs, from your terminal or a script.

Driving CloneViral from an agent instead? Use the MCP server: @cloneviral/mcp-server, or the Claude Code / Codex plugin, which needs no install:

/plugin marketplace add https://cdn.cloneviral.ai/plugins/claude-marketplace.json

Install

npm install -g @cloneviral/cli
export CLONEVIRAL_API_KEY=cv_your_api_key_here
cviral credits

Get an API key at cloneviral.ai/mcp-skills. CLONEVIRAL_API_URL overrides the API host if you need it.

Commands

| Command | What it does | |---------|--------------| | cviral credits | Credit balance and subscription | | cviral videos [--limit N] [--status S] | List recent videos | | cviral image <prompt> [--model --ratio --ref] | Generate an image | | cviral edit <prompt> --url <url> | Edit an existing image | | cviral video <prompt> [options] | Generate a video | | cviral status <predictionId> [--type video\|image] | Poll a generation | | cviral analyze <videoUrl> | Analyze a video for remixing | | cviral remix <videoUrl> [--count --product --modify] | Analyze and build remix variants | | cviral translate <videoUrl> --lang ja [--tone] | Translate and dub a video | | cviral translate-status <jobId> | Poll a translation job | | cviral characters | List saved AI characters |

Viral Flow

Local files are the reason to reach for the CLI: it uploads from disk and downloads finished assets, which the hosted MCP tools cannot do.

| Command | What it does | |---------|--------------| | cviral flows | List your flows | | cviral flow show <flowId> | Nodes, readiness and estimated cost | | cviral flow upload <path> | Upload a local file, get a URL for a node | | cviral flow run <flowId> --node <id> [--watch] | Run one node | | cviral flow status <flowId> --node <id> | Check a running node | | cviral flow pull <flowId> [--out dir] [--generated] | Download its assets |

cviral flows
cviral flow show flow_abc123
cviral flow upload ./hero.jpg
cviral flow run flow_abc123 --node node_7 --watch
cviral flow pull flow_abc123 --out ./assets

Director Studio

| Command | What it does | |---------|--------------| | cviral presets [looks\|moves\|sizes\|camera] | List looks, camera moves, shot sizes, camera setup | | cviral frame <scene> [options] | Generate a cinematic still frame | | cviral shot --start <url> [options] | Animate a frame with a camera move |

A look grades the still, a camera move animates it:

cviral presets looks --category lighting
cviral frame "a lone astronaut on a rain-soaked rooftop" --look blockbuster --size wide
cviral shot --start https://example.com/frame.png --move crash-zoom-in --duration 5

frame also takes --lighting, --palette, --camera, --lens, --aperture, --ratio and --model. shot takes --direction, --scene, --duration, --ratio, --res and --model.

Options

Image — --model (default flux-2-pro), --ratio (1:1 16:9 9:16 4:3 3:4), --ref (repeatable reference image URL). edit additionally requires --url.

Video — --model (default veo3.1), --ratio (default 9:16; 21:9 is Seedance 2.5 only), --duration (default 5), --res (sd hd fhd 2k), --start / --end frame URLs, and --ref / --refvid / --refaudio for the -omni and -ref models (repeatable).

Translate — --lang (ja zh ko es fr de pt ar hi ru), --tone (casual professional energetic formal).

Remix — --count (default 3), --product, --modify.

Run cviral --help for every flag with its default.

Image Models

Pass a slug as model. The /edit variants take an image_url to modify.

| Family | Slugs | |--------|-------| | Nano Banana | fal-ai/nano-banana-2, fal-ai/nano-banana-2/edit, google/nano-banana-pro | | Seedream 5 | fal-ai/bytedance/seedream/v5/lite/text-to-image, .../lite/edit, .../pro/text-to-image, .../pro/edit | | FLUX | black-forest-labs/flux-2-pro | | GPT Image | openai/gpt-image-2, openai/gpt-image-2/edit | | GPT Image 2.5 | openai/gpt-image-2.5-flare/text-to-image, .../flare/edit, openai/gpt-image-2.5-sunburst/text-to-image, .../sunburst/edit | | Midjourney | midjourney/v8.2, midjourney/v8.2/edit |

Video Models

Pass a slug as model. Use -i2v for image-to-video and -omni / -ref for reference-to-video.

| Family | Slugs | Duration | Resolution | |--------|-------|----------|------------| | Veo 3.1 | veo3.1, veo3.1-fast | 3–20s | sd hd fhd uhd | | Kling 3.0 | kling3-standard, kling3-pro, kling3-4k (+ -i2v) | 3–20s | sd hd fhd uhd | | Seedance 2.0 | seedance2, seedance2-i2v, seedance2-omni (+ -fast, -mini) | 3–20s | sd hd fhd uhd | | Seedance 2.5 | seedance2.5, seedance2.5-i2v, seedance2.5-omni | 4–30s single pass | sd hd | | FLUX 3 | flux3, flux3-i2v, flux3-keyframes, flux3-extend | 5–20s | hd (720p) fhd (1080p) | | MiniMax H3 | minimax-h3, -i2v, -ref | 5–15s (whole seconds) | 2k only | | MiniMax H3 Max | minimax-h3-max, -i2v, -ref | 5–15s | up to 768p |

Seedance 2.5 also accepts 21:9, and seedance2.5-omni takes up to 50 mixed reference_images / reference_videos / reference_audios. seedance2.5-i2v always matches its source image's aspect ratio. minimax-h3-ref takes up to 9 images, 3 videos and 3 audios. FLUX 3 has native audio and uses auto as its aspect-ratio sentinel (not Seedance's adaptive); flux3-keyframes pins up to 10 images to exact frame positions, and flux3-extend continues a clip under 15s / 50 MB. H3 Max is capped at 768p but costs about half of H3 per second. End frames (end_image_url) work on veo3.1*, flux3-i2v, seedance2.5-i2v and minimax-h3-i2v.

Examples

cviral image "a sunset over Tokyo" --model gpt-image-2 --ratio 16:9
cviral edit "make the sky purple" --url https://example.com/photo.jpg --model nano-banana-2
cviral video "UGC skincare ad" --model seedance2 --ratio 9:16 --duration 10
cviral video "one-take product story" --model seedance2.5 --duration 30 --ratio 21:9
cviral video "she turns and speaks" --model seedance2.5-omni \
  --ref https://example.com/hero.jpg --refaudio https://example.com/voice.mp3
cviral video "founder to camera" --model minimax-h3-max --res hd --duration 12
cviral status pred_abc123
cviral remix https://tiktok.com/... --count 5 --product "my face cream"
cviral translate https://example.com/video.mp4 --lang ja --tone casual

Development

The CLI and the MCP server are built from one source tree in mcp-server/; sync-dist.sh copies the two files cviral needs into dist/ at pack time, so neither copy can drift.

License

MIT