# vvgen CLI (--remote) quickstart

> Run the vvgen command line against the hosted service. No provider key needed locally.

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

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

## 2. Point it at the service

One-off:

```bash
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):

```bash
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:

```toml
[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).