Viral Engine CLI

Command-line interface for Viral Engine — generate AI images and videos, build funnels, manage leads, and run automations from your terminal.

Install

npm install -g viral-engine-cli

Requires Node.js 18 or newer.

The CLI installs two binaries: viral-engine and the shorter alias ve.

Quick start

# Log in: opens your browser to authorize this machine (no password typing)
ve login

# Headless machine? Use the email+password fallback:
ve login --password

# Check your credit balance
ve credits

# Generate an image
ve images generate "a cinematic shot of a cyberpunk samurai at dusk" --model nano-banana-2

# Generate a video from a prompt (Sora, Veo, Kling, Higgsfield, and more)
ve videos generate "a slow drone shot over a misty forest" --provider sora -d 8 --watch --output ./out

# Discover live model + provider catalogs
ve images models
ve videos providers

# List the last 20 items in your gallery
ve gallery list --limit 20

Run ve --help to see every command, or ve <command> --help for details on a specific one.

What you can do

| Area | Examples | |------|----------| | Images | ve images generate, ve images enhance, ve images analyze | | Videos | ve videos generate, ve videos extend, ve videos voiceover | | VSL Studio | ve vsl run, ve vsl scripts | | Gallery | ve gallery list, ve gallery favorite, ve gallery collections | | Agents | ve agents list, ve agents create, ve agents run | | Workflows | ve workflows list, ve workflows run | | Funnels | ve funnels create, ve funnels publish | | Leads | ve leads list, ve leads export | | Automation | ve automation sequences, ve automation send-email | | Account | ve credits, ve checkout, ve settings |

Configuration

Config lives at ~/.viral-engine/config.json and is created on first login.

# View current config
ve config show

# Change a default
ve config set defaultModel flux
ve config set defaultAspectRatio 9:16

# Point at a self-hosted instance
ve config set baseUrl https://your-instance.example.com

Per-command overrides:

ve --base-url https://staging.viralengine.art images generate "..."
ve --token <your-token> credits
ve --json gallery list      # raw JSON output for scripting
ve --quiet images generate  # minimal output for pipelines

Scripting

Every command supports --json for machine-readable output:

ve --json gallery list --limit 50 | jq '.items[].url'

Long-running jobs (videos, batch image runs) return a job ID. Poll with:

JOB=$(ve --json videos generate "..." | jq -r .jobId)
ve jobs wait "$JOB"
ve jobs get "$JOB" --json

Authentication

ve login opens a browser window to https://viralengine.art/cli-auth with a short pairing code (like AB3F-K7YR). Confirm the code matches, click Authorize, and the CLI stores your session token in ~/.viral-engine/config.json with 0700 permissions.

On a headless machine (CI, remote server, no display), use:

ve login --password

Log out at any time:

ve logout

Updating

npm update -g viral-engine-cli
ve --version

Links

• Website: https://viralengine.art
• API docs: https://viralengine.art/docs
• Support: https://viralengine.art/support

License

MIT