@cocoviral/cli 1.5.4

package/README.md

@@ -0,0 +1,159 @@
+# cviral — the CocoViral CLI
+
+Generate AI images and video, drive Director Studio, and build, run and deliver
+[Viral Flow](https://www.cocoviral.ai) graphs, from your terminal or a script.
+
+Driving CocoViral from an agent instead? Use the MCP server:
+[`@cocoviral/mcp-server`](https://www.npmjs.com/package/@cocoviral/mcp-server),
+or the Claude Code / Codex plugin, which needs no install:
+
+```
+/plugin marketplace add https://cdn.cocoviral.ai/plugins/cocoviral-claude-marketplace.json
+```
+
+## Install
+
+```bash
+npm install -g @cocoviral/cli
+export COCOVIRAL_API_KEY=cv_your_api_key_here
+cviral credits
+```
+
+Get an API key at [cocoviral.ai/mcp-skills](https://www.cocoviral.ai/mcp-skills).
+`COCOVIRAL_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 |
+
+```bash
+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:
+
+```bash
+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 |
+|--------|-------|
+| 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` |
+| 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` |
+| Midjourney | `midjourney/v8.2`, `midjourney/v8.2/edit` |
+| GPT Image | `openai/gpt-image-2`, `openai/gpt-image-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 |
+|--------|-------|----------|------------|
+| **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` |
+| **FLUX 3** | `flux3`, `flux3-i2v`, `flux3-keyframes`, `flux3-extend` | 5–20s | `hd` (720p) `fhd` (1080p) |
+| **Seedance 2.5** | `seedance2.5`, `seedance2.5-i2v`, `seedance2.5-omni` | **4–30s single pass** | `sd` `hd` |
+| Seedance 2.0 | `seedance2`, `seedance2-i2v`, `seedance2-omni` (+ `-fast`, `-mini`) | 3–20s | `sd` `hd` `fhd` `uhd` |
+| Kling 3.0 | `kling3-standard`, `kling3-pro`, `kling3-4k` (+ `-i2v`) | 3–20s | `sd` `hd` `fhd` `uhd` |
+| Veo 3.1 *(default)* | `veo3.1`, `veo3.1-fast` | 3–20s | `sd` `hd` `fhd` `uhd` |
+
+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
+
+```bash
+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