🎬 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

Install globally via npm:

npm install -g veogent

🔐 Quick Start (Authentication)

Veogent CLI supports both browser callback login and headless device-code login.

1. Browser callback flow (desktop):

   veogent login

2. Device-code flow (VM/server/headless):

   veogent login --device

3. For device flow, open the printed URL on any browser, approve, then CLI will finish automatically.
4. Verify your session:

   veogent status

Agent orchestration notes (request/scene semantics)

• scene.requestId: backward-compatible legacy pointer; may refer to latest relevant request but is not type-specific.
• scene.latestImageRequestId: latest image-related request (GENERATE_IMAGES / EDIT_IMAGE) regardless of status.
• scene.latestVideoRequestId: latest video request (GENERATE_VIDEO) regardless of status.
• scene.latestSuccessfulImageRequestId: latest image-related request in COMPLETED.
• scene.latestSuccessfulVideoRequestId: latest video request in COMPLETED.

For robust automation:

• Prefer veogent scene-status -p <project> -c <chapter> or veogent workflow-status -p <project> -c <chapter>.
• Use latestSuccessful* fields when selecting canonical output URIs.

🛠️ Key Capabilities

All responses are provided in strict, pretty-printed JSON format to easily pipe veogent into jq or be parsed natively by AI Agents.

📁 Project Management

# List all your active projects
veogent projects

# View available Image Material styles (e.g., CINEMATIC, PIXAR_3D)
veogent image-materials

# Create a brand new AI Story Project using your prompt
veogent create-project -n "Cyberpunk T-Rex" -k "T-rex, Neon, Sci-fi" -d "A massive T-rex walking inside Tokyo" -l "English" -m "CINEMATIC" -c 5

📖 Storyboard, Chapters & Scenes

# Get all chapters within a project ID
veogent chapters <projectId>

# View characters cast for the project (includes readiness info)
veogent characters <projectId>
# Response includes: { characters: [{id, name, imageUri, ready}], characterReadiness: {total, ready, allReady} }

# Check scene materialization status (how many scenes are ready)
veogent scene-materialization-status -p <projectId> -c <chapterId>
# Response: { expectedScenes, materializedScenes, status: "PROCESSING"|"READY"|"EMPTY" }

# Create scenes automatically using AI-generated narrative scripts
veogent create-scene -p <projectId> -c <chapterId> --flowkey -C "The T-Rex looks up at the sky." "A meteor shower begins."

🖌️ Directing & Editing (AI Prompt adjustments)

# Edit an existing image prompt for a scene.
# Note: Use camera direction verbs like "Wide shot," "Tilt up," or "Close-up."
veogent edit-scene -p <proj> -c <chap> -s <scene> -u "Low angle shot of the T-Rex, dramatic lighting."

# Apply a direct image in-paint edit to a specific character model
veogent edit-character -p <proj> -c "drelenavance" -u "change outfit to dark leather jacket" -e

🎬 Media Generation (Gen Models)

Queue generation jobs directly from the terminal. Note: VEOGENT uses strict validation depending on the request type.

# List supported models
veogent image-models   # → { models: ["imagen3.5"] }
veogent video-models   # → { models: ["veo_3_1_fast", "veo_3_1_fast_r2v"] }

# Generate Image (Supports: imagen3.5)
veogent request -t "GENERATE_IMAGES" -p <proj> -c <chap> -s <scene> -i "imagen3.5"

# Generate Video (Supports: veo_3_1_fast, veo_3_1_fast_r2v)
# Default/recommended model: veo_3_1_fast
veogent request -t "GENERATE_VIDEO" -p <proj> -c <chap> -s <scene> -v "veo_3_1_fast" -S "normal"

# Upscale Video (request DTO mode)
veogent request -t "VIDEO_UPSCALE" -p <proj> -c <chap> -s <scene> -o "HORIZONTAL"

# Upscale Video (shortcut command)
veogent upscale -p <proj> -c <chap> -s <scene> -o "VERTICAL" -r "VIDEO_RESOLUTION_4K"

📊 Monitoring & Status

# View all requests (most recent first)
veogent requests

# Get N most recent requests
veogent requests -n 10

# Filter by project / chapter / status
veogent requests -p <projectId> -c <chapterId> -n 5
veogent requests -s FAILED -n 20
veogent requests -s COMPLETED -p <projectId>

# Scene-level status with embedded asset URLs (image + video)
veogent scene-status -p <projectId> -c <chapterId>
# Each scene returns: { sceneId, image: { status, url }, video: { status, url } }

# Full workflow snapshot (scenes + requests + assets)
veogent workflow-status -p <projectId> -c <chapterId>

# Wait for all images to finish processing
veogent wait-images -p <projectId> -c <chapterId>

# Wait and verify all images succeeded (not just finished)
veogent wait-images -p <projectId> -c <chapterId> --require-success

# Same for videos
veogent wait-videos -p <projectId> -c <chapterId> --require-success

# Queue concurrency status
veogent queue-status

# Google Flow credit/plan info (requires flow key)
veogent flow-credits
veogent flow-credits -f "ya29.a0ATk..."

🤖 For AI Agents

Veogent CLI ships with a comprehensive skills/SKILL.md guide optimized for LLM/Coding Agents context processing. It defines exact DTO validations, model enumerations, camera prompting techniques, the full production pipeline, and error handling — everything an agent needs to orchestrate complete projects without hitting 400 Bad Request.

Recommended Agent Workflow (Production)

1. Resolve optional IDs first (if missing):
   • veogent custom-prompts
   • veogent image-materials (default fallback: CINEMATIC)
2. Prepare story input (arc, summary, key notes).
3. Generate project description:
   • veogent create-project-description ...
4. Create project from generated payload.
5. Create chapter content with scene count:
   • veogent create-chapter-content -s <sceneCount>
   • Rule: each scene maps to ~8s clip.
6. Create scenes from returned script list:
   • veogent create-scene -p <projectId> -c <chapterId> -C "scene 1" "scene 2" ... --flowkey
7. Wait for character generation completion (imageUri required for all characters):
   • veogent characters <projectId> — check characterReadiness.allReady === true
   • veogent scene-materialization-status -p <projectId> -c <chapterId> — verify status: "READY"
   • If missing/fail: inspect veogent requests -n 20, recover via veogent edit-character.
8. Generate scene images:
   • veogent request -t "GENERATE_IMAGES" ...
   • If image is reported wrong, decode image to Base64 and send to AI reviewer for evaluation.
   • If mismatch persists, fix via:
     • veogent edit-scene -u "..." (prompt refinement), or
     • veogent edit-scene -R <requestId> ... (direct edit on prior generated image)
9. Generate video only after matching-orientation image exists successfully:
   • veogent request -t "GENERATE_VIDEO" ...

📖 For the full detailed guide with all commands, options tables, and examples, see skills/SKILL.md.

Important: veogent requests is the primary status board for image/video/edit workflows.

• Use -n <N> to get only the N most recent requests.
• Use -s FAILED / -s COMPLETED to filter by status.
• Use --require-success on wait-images / wait-videos to ensure assets actually exist (not just "finished").

Concurrency: maximum 5 requests can be processed simultaneously. If the API reports maximum limit reached, treat it as queue-full (wait/retry), not a hard failure.

📜 License

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