# CLI

`vidlab` is the VidLab API from your shell: find a model, price it, run it, wait and save the file, in one command. It is for scripts, CI and people who live in a terminal; your agent can use it too. Node.js 18.17 or newer, no other dependencies.

```bash
npx @vidlab/cli models --kind video
```

Install it once to drop the `npx @vidlab/cli`:

```bash
npm install -g @vidlab/cli
```

## Your key

`vidlab login` checks a key and saves it in the macOS Keychain or the Linux Secret Service (else a private file under `~/.config/vidlab`). `VIDLAB_API_KEY`, when it is set, always wins. The key is never printed and never passed on a command line.

```bash
vidlab login
```

## Commands

```bash
vidlab models --kind video --search seedance      # find
vidlab model seedance-2.5                         # its inputs and every price
vidlab estimate seedance-2.5 --prompt "a red fox" --duration 5 --resolution 720p
vidlab run seedance-2.5 --prompt "a red fox" --duration 5 --max-price 2 --wait --out fox.mp4
vidlab get gen_... --wait                         # read a job later, download when done
vidlab upload ./photo.png                         # prints the link; --image ./photo.png does this by itself
vidlab formats                                    # our ad formats: a finished video from a brief
vidlab format run drama-ad --input brief="A tired dad finally sleeps." --max-price 6 --wait --out ad.mp4
vidlab balance
vidlab setup                                      # the VidLab skill for Claude Code and Codex, and a check of your key
```

- `--max-price` on `run` is the request's `max_cost_usd`: a route dearer than it is skipped. On `format run` it approves the price up to that amount.
- `run` always sends an `Idempotency-Key`, so its own retries never pay twice.
- `--json` on every command prints one JSON document, errors included: `{"error": {"code", "message", "status", "hint"}}`.
- Exit codes: `0` done, `1` API or network error, `2` usage error, `3` the generation or format run failed (nothing charged), `4` still running when `--wait` ran out, `5` a format run needs answers.
- `--base-url` (or `VIDLAB_BASE_URL`) points it at another address; the default is https://vidlab.ai.

## Input

`--prompt`, `--image <link or file>` (repeat for several), `--duration`, `--resolution`, `--aspect-ratio`, `--video`, `--audio`, `--end-image`, `--text`, `--voice`, `--seed`, `--n`, and `--param key=value` for any field a model lists (`vidlab model <id>`). A local file is uploaded first and its link sent.