vvgen CLI (--remote)

The same vvgen command-line tool that runs locally can send every call to the hosted service. The service holds the provider key and your credits; the CLI needs only your API key.

1. Install

pipx install vincevangen          # or: uvx vvgen --help (see the repository README for the current install line)

2. Point it at the service

One-off:

export VVGEN_URL="https://api.vincevangen.com"
export VVGEN_TOKEN="igk_live_..."
vvgen gen "a lighthouse at dusk, oil painting" --model fast -n 3

Or with flags (before the subcommand):

vvgen --remote https://api.vincevangen.com --token "$VVGEN_TOKEN" gen "a red fox" --model fast

Or per project in vvgen.toml, keeping the key out of git:

[remote]
url = "https://api.vincevangen.com"
token_env = "VVGEN_TOKEN"

Order of precedence: --remote/--token, VVGEN_URL/VVGEN_TOKEN, project vvgen.toml, .env, user config. --local ignores a configured remote.

Results are downloaded next to your project (assets/generated/ by default), with a provenance sidecar, exactly like a local run.

Spec runs

vvgen run assets.yaml works remotely too: the plan is priced by the service for free, and the lockfile is written on your machine.

Exit codes

Code	Meaning
0	Done
2	Refused or unsupported remotely
3	Nothing passed acceptance
4	Key refused (401)
5	Out of credits (402)
6	Call is over the confirmation threshold (428); on a terminal you are asked, in CI pass --yes
7	Service unreachable or 5xx

Not available remotely

--budget, --dry-run, --no-cache, --force, --steps, --guidance, upscale, schema and history are local-only. Use POST /v1/plan (or vvgen gen --post rmbg, --enhance, which do work).