> ## Documentation Index
> Fetch the complete documentation index at: https://docs.snapgen.org/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Run every SnapGen image, video and text model from your terminal, scripts and CI with the snapgen command.

The `snapgen` command reads models, input schemas and prices from the live
SnapGen catalog, turns each model's input fields into flags, submits jobs and
waits for the results. Browsing the catalog needs no API key.

```bash theme={null}
npx -y @snapgen/cli help
# the short package name runs the same CLI
npx -y snapgen help
# or install once
npm install -g @snapgen/cli && snapgen help
```

Requires Node.js 20 or newer.

## Three steps from discovery to result

<Steps>
  <Step title="Find and inspect a model">
    ```bash theme={null}
    snapgen models video --q seedance --limit 5
    snapgen describe seedance-2.0-t2v
    ```

    `describe` lists every flag with its type, default and allowed values, plus
    the execution mode and the current price.
  </Step>

  <Step title="Save your API key">
    Create a key on the [API keys page](https://snapgen.org/apikeys), then:

    ```bash theme={null}
    snapgen auth login     # asks for the key without echoing it
    snapgen account        # available balance and reserved amount (USD)
    ```

    The key is stored in the macOS Keychain, the Linux Secret Service keyring
    (`secret-tool`), or otherwise in `~/.config/snapgen/config.json`, readable
    only by you. `SNAPGEN_API_KEY` takes precedence when set.
  </Step>

  <Step title="Run the model">
    ```bash theme={null}
    snapgen run seedance-2.0-t2v \
      --prompt "A red fox trotting through fresh snow at dawn" \
      --seconds 5 --resolution 720p --aspect-ratio 16:9 --format json
    ```

    This is a paid request. Check the price with `describe` first; failed
    generations are not charged.
  </Step>
</Steps>

## Commands

| Command                                                                            | Does                                                                |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `snapgen models [text\|image\|video\|audio] [--q TEXT] [--limit N]`                | List models with category, execution mode and price. No key needed. |
| `snapgen describe <model>`                                                         | Input flags, protocols, execution mode and pricing. No key needed.  |
| `snapgen run <model> [--<field> <value> ...]`                                      | Submit and wait (default 90 s, polling every 2 s).                  |
| `snapgen submit <model> [--<field> <value> ...]`                                   | Submit and print the task id right away.                            |
| `snapgen task get <task_id>`                                                       | Status, progress, charge and output URLs.                           |
| `snapgen task wait <task_id> [--timeout 300] [--interval 5]`                       | Wait for a task to finish.                                          |
| `snapgen chat <model> --prompt "..." [--system "..."] [--max-tokens N] [--stream]` | One chat turn with a text model.                                    |
| `snapgen account`                                                                  | Available balance and the amount reserved for running tasks.        |
| `snapgen auth login \| logout \| status`                                           | Store, remove or inspect your API key.                              |

## Flags come from the live schema

Each field of a model's input schema becomes a flag: `aspect_ratio` is
`--aspect-ratio`, booleans are `--generate-audio` / `--no-generate-audio`, and
list fields repeat the flag, take commas, or take JSON. Integers, enums and list
sizes are checked against the schema, and fields you leave out get the schema
default.

Unknown flags and invalid values stop the command with exit code 2 before
anything paid is sent. `snapgen run <model> --help` lists a model's flags, and
`--dry-run` prints the exact request without sending it.

## Long jobs

Use `submit` for video and other long jobs, keep the task id, and continue from
any terminal or CI step:

```bash theme={null}
snapgen submit seedance-2.0-t2v --prompt "Neon city in the rain" --seconds 10
snapgen task wait task_abc123 --timeout 600
```

When `--timeout` runs out the task keeps running: `snapgen` prints the task id
and the `task wait` command to resume, and exits with code 4. Submissions send an
`Idempotency-Key`, so repeating a failed submit with the same key returns the
original task instead of starting a second one.

## Output for scripts

`--format table|json|jsonl|csv`. The default is a table on a terminal and JSON
when the output is piped. `--output FILE` writes the result to a file. Progress
and hints go to stderr.

| Exit code | Meaning                                                     |
| --------- | ----------------------------------------------------------- |
| 0         | Success                                                     |
| 1         | API error or failed task                                    |
| 2         | Invalid usage or input (nothing was sent)                   |
| 3         | Missing or invalid API key                                  |
| 4         | Still running when `--timeout` ran out (the task continues) |
| 130       | Interrupted                                                 |

## Environment

| Variable           | Default                   |
| ------------------ | ------------------------- |
| `SNAPGEN_API_KEY`  | The stored key            |
| `SNAPGEN_BASE_URL` | `https://api.snapgen.org` |