🎬 Veogent CLI

The official Command-Line Interface for the VEOGENT API.

Veogent CLI gives you (and your AI Agents) the power to manage full-scale AI video and story projects directly from the terminal. Connect to projects, orchestrate multi-frame scenes, edit image prompts with professional camera cues, and trigger large-scale generation jobs natively.

Perfectly engineered for Agentic workflows — enabling tools like OpenClaw, Claude, and Codex to autonomously generate JSON-driven movies from scratch.

🚀 Installation

npm install -g veogent

🔐 Authentication

veogent login              # Browser callback (desktop)
veogent login --device     # Device-code flow (VM/server/headless — recommended for AI Agents)
veogent status             # Verify session
veogent logout             # Clear credentials
veogent setup-flow --flowkey "ya29.a0AW..." --tier "PAYGATE_TIER_TWO"   # Setup Flow Key

Global Flags

| Flag | Description | |------|-------------| | --json | Output machine-readable JSON only | | --agent-safe | Agent-safe mode — no emoji, no browser surprises, stable JSON output | | --version | Print CLI version |

For AI Agents: always use --agent-safe for deterministic, parseable JSON output.

🎯 Recommended Workflow

How VEOGENT Works — The Mental Model

Core chapter story text → Project + Characters (reference images)
                        → Chapter Content (storyboard)
                        → Scenes → Images → Videos

Key concept: Pass rich story text directly to create-project (chapter-structured). VEOGENT uses named entities from that story to build project-level references for consistency.

The Pipeline (4 Phases)

Phase 1: Create Project

veogent create-project \
  --name "Boss Babe in Fur" \
  --story "Chapter 1.
Bella the white Bichon Frisé CEO in a pink blazer enters the luxury Saigon mall with two Doberman bodyguards Rex and Duke. She shops designer stores, faces a tense crowd moment, then exits with golden bags under neon lights." \
  --lang English \
  --material CINEMATIC

Story format rules:

• If --chapters is omitted, default is 1
• Must include headings like Chapter 1. (and Chapter 2. ... when chapters > 1)
• Keep each chapter as core plot text (VEOGENT will expand into scenes later)

What happens internally:

1. CLI sends your --story directly to /app/project (no /app/description call)
2. VEOGENT creates project + chapter shell, then create-chapter-content expands story into scene scripts

Phase 2: Generate Storyboard + Scenes

# Get chapter ID
veogent chapters <projectId>

# Generate storyboard (VEOGENT AI writes scene scripts from the rich description)
veogent create-chapter-content --project <projectId> --chapter <chapterId> --scenes 5

# Create scenes from storyboard scripts
veogent create-scene --project <projectId> --chapter <chapterId> \
  --content "Scene 1 script..." "Scene 2 script..." "Scene 3..." "Scene 4..." "Scene 5..." \
  --flowkey

# Wait for materialization (~30s per scene)
# Poll: veogent scenes <projectId> <chapterId> until all scenes have scriptSegment

# Wait for characters to be ready (reference images generated)
# Poll: veogent characters <projectId> until characterReadiness.allReady === true

--lang English --material CINEMATIC --scenes 5 --wait

#### Phase 3: Generate Images + Videos (Async Polling)

```bash
# 1. Trigger generation (without --wait) to avoid locking your terminal
veogent batch-request --type GENERATE_IMAGES \
  --project <projectId> --chapter <chapterId> --all --orientation VERTICAL

# 2. Extract `requestId` from the output
# 3. Poll status asynchronously:
veogent request-status --id <requestId>
# ... loop until requestStatus === "COMPLETED"

# Repeat for GENERATE_VIDEO once images are ready

Tip for Agents: While the --wait flag exists, using request-status is recommended so you don't lock your main process for the 5-10 minutes it takes to render a video.

Phase 4: QA + Fix Loop

# Check results
veogent workflow-status --project <projectId> --chapter <chapterId>

edit-scene has TWO modes:

Mode A — Edit storyboard/prompt only (no image regen):

veogent edit-scene --project X --chapter Y --scene Z \
  --prompt "Bella walks through mall on all four paws"
# Then trigger image gen separately:
veogent request --type GENERATE_IMAGES --project X --chapter Y --scene Z --orientation VERTICAL --wait

Use when image is fundamentally wrong (wrong character, wrong scene).

Mode B — Regenerate image directly (with request ID):

veogent edit-scene --project X --chapter Y --scene Z \
  --prompt "adjust lighting to warmer tones" --request <requestId> --wait

Use when image is close but needs a tweak (lighting, pose, angle).

Fix video only (image is fine):

veogent request --type GENERATE_VIDEO \
  --project X --chapter Y --scene Z \
  --videomodel veo_3_1_fast --orientation VERTICAL --wait

📋 Command Reference

Authentication & Config

| Command | Description | |---------|-------------| | login [--device] | Login (use --device for headless/VM) | | logout | Clear credentials | | status | Show session + Flow Key details | | setup-flow | Setup Google Flow Key + payment tier |

Project Management

| Command | Description | |---------|-------------| | projects | List all projects | | project <id> | Get project details | | create-project | Create project from chapter-structured --story text |

Chapters & Scenes

| Command | Description | |---------|-------------| | chapters <projectId> | List chapters | | recent-chapters | Recently updated chapters | | create-chapter-content | Generate storyboard (scene scripts) via AI | | scenes <projectId> <chapterId> | List scenes | | create-scene | Create scenes from script content | | edit-scene | Edit scene storyboard/prompt, or regenerate image with --request |

Characters

| Command | Description | |---------|-------------| | characters <projectId> | List characters + readiness (reference images) | | edit-character | Update character description or edit image via AI |

Generation

| Command | Description | |---------|-------------| | request | Create a single generation job (GENERATE_IMAGES / GENERATE_VIDEO / UPSCALE_VIDEO) | | batch-request | Batch generation for multiple/all scenes (--all) | | requests | List existing generation jobs | | request-status | Check a specific job by request ID (includes asset URL) | | failed-requests | List failed requests for a chapter | | wait-images | Poll until all image jobs finish | | wait-videos | Poll until all video jobs finish | | queue-status | Current queue/concurrency status | | download-upscale | Download 4K upscaled video as .mp4 (decodes base64 from flow-media) |

Monitoring

| Command | Description | |---------|-------------| | scene-status | Scene-level image+video status with asset URLs | | workflow-status | Full snapshot: scenes + requests + assets (best for agents) | | request-status | Check a specific job by request ID |

YouTube

| Command | Description | |---------|-------------| | generate-yt-metadata | Generate Title/Description/Tags for a chapter | | generate-yt-thumbnail | Trigger thumbnail generation | | yt-thumbnails | Get generated thumbnails |

Utility

| Command | Description | |---------|-------------| | image-materials | List available image styles | | custom-prompts | List custom prompt templates | | obtain-flow | Auto-extract Flow Token via browser | | flow-credits | Check plan + credit info | | skill | Print the Agent SKILL.md guide |

Video Speed Modes

| Mode | Flag | Use case | |------|------|----------| | normal | --speed normal (default) | Most scenes | | timelapse | --speed timelapse | Sunrise, cooking montage, traffic | | slowmotion | --speed slowmotion | Impact, water splash, dramatic reveal |

Chained Video (endScene)

Smooth transition between two consecutive scenes:

veogent request --type GENERATE_VIDEO --project X --chapter Y --scene sceneA \
  --endscene sceneB --videomodel veo_3_1_fast --orientation VERTICAL

Uses sceneA's image as start frame, sceneB's image as end frame. Both scenes must have successful images. Only works with veo_3_1_fast.

Video Upscale (4K)

# 1. Trigger upscale
veogent request --type UPSCALE_VIDEO \
  --project X --chapter Y --scene Z \
  --orientation VERTICAL --resolution VIDEO_RESOLUTION_4K

# 2. Poll status by request ID
veogent request-status --id <requestId>

# 3. Download the upscaled video
veogent download-upscale \
  --project X --chapter Y --scene Z \
  --orientation VERTICAL --out ./scene_4k.mp4

download-upscale calls /app/scene/flow-media, decodes the base64 encodedVideo, and writes a .mp4 file.

Concurrency

Maximum 5 concurrent requests. If queue is full (E10071), CLI auto-retries once after 30s.

batch-request respects the 5-request limit with inter-batch throttling.

🤖 For AI Agents

• Always use --agent-safe flag
• Use workflow-status for the most complete snapshot
• Character reference images are created from named entities in --story and generated scene scripts
• Use character NAMES only in prompts — never describe appearance (reference images define it)
• See skills/SKILL.md for the full agent guide

📜 License

MIT License. Crafted with ❤️ by Pym & Tuan Nguyen.