---
title: "Commands"
description: "Full reference for all ai-cli commands and flags."
canonical_url: "https://ai-cli.dev/docs/commands"
---
# Commands

## image

Image and video option names follow AI SDK keys in kebab case. Nested options use
JSON files with the SDK's original camelCase keys.

```text
-i, --images <path-or-url>   prompt.images reference (repeatable)
--mask <path-or-url>         prompt.mask for editing
-n, --n <n>                 Number of images per model (default: 1)
--max-images-per-call <n>    SDK batching limit
--size <widthxheight>                Image size, e.g. 1024x1024
--aspect-ratio <width:height>         Aspect ratio, e.g. 16:9
--api <api>                 generateImage or generateText (default: model catalog)
--generate-text-options <path> JSON generateText settings and provider tools
```

Reference images and masks accept local paths, `file://`, HTTP(S), and data URLs.
Stdin supplies an additional reference image. A mask requires a reference image.

```bash
ai image --images subject.png --images style.png "combine these"
ai image --images photo.png --mask mask.png "replace the background"
ai image "a sunset" --n 3 --max-images-per-call 2 --json -o ./renders/
```

Both image and video generation accept `--model` / `-m` (comma-separated),
`--output` / `-o`, `--concurrency` / `-p` (image 4, video 2), `--quiet` / `-q`,
`--json`, `--no-preview`, and `--timeout` in seconds (image 300, video 600).
JSON manifests save every artifact to a file and include SDK diagnostics.
`--quiet` suppresses progress but retains errors. New output directories must
end with `/`; explicit filenames keep the extension you provide.
For image and video `--n`, fewer returned outputs than requested are reported as
an incomplete result with a nonzero exit code. Available media is still saved.
When a batching limit splits generation into calls, successful calls are saved
even if another call fails. For `generateImage` and video generation, JSON
results include successful call diagnostics in `batches` and failed call or
download details in `failures`.
For image/video generation, exit 1 means every model result is unsuccessful,
including a partial result that saved files. Exit 2 means some models succeeded
and others did not. Input validation errors also exit 1.

Both also support these request controls:

```text
--seed <integer>            SDK seed, including 0
--provider-options <path>   JSON providerOptions, keyed by provider name
--headers <path>            JSON object of HTTP headers
--max-retries <n>            SDK maxRetries (default: 2; 0 disables retries)
--base-url <url>             Gateway baseURL (e.g. https://ai-gateway.vercel.sh/v4/ai)
--team-id-or-slug <team>     Gateway teamIdOrSlug
```

For example, `image-options.json` can contain:

```json
{
  "openai": { "quality": "high", "outputFormat": "webp", "background": "transparent" },
  "gateway": { "order": ["openai"] }
}
```

```bash
ai image "a transparent sticker" --provider-options image-options.json -o ./renders/
```

Provider options pass through unchanged, including nested routing, fallbacks,
compression, fidelity, and model-specific controls. Supported keys and values
depend on the provider/model; use the [AI SDK provider docs](https://ai-sdk.dev/providers/ai-sdk-providers)
and [Gateway provider options](https://vercel.com/docs/ai-gateway/models-and-providers/provider-options).
`--output` selects a filesystem destination; `outputFormat` selects an encoded format.

Gemini image models use `generateText`. Set their resolution with
`{"google":{"imageConfig":{"imageSize":"4K"}}}` in the provider-options file.
`--aspect-ratio` merges into `google.imageConfig.aspectRatio` without removing
`imageSize`. `--size`, `--mask`, `--max-images-per-call`, and `--n` other than 1
are rejected for `generateText`; that API can still return multiple image files,
which are all saved. Other language image models use provider-specific controls.

`--api generateText` selects a language model explicitly; `--api generateImage`
selects a dedicated image model. If discovery fails, returns an invalid catalog,
or omits the selected image model, automatic routing stops with an error. The
known Quiver Arrow 2 SVG language-image models still route to `generateText`
when they are absent from the image catalog.
Explicit `--api` and a full model ID allow generation without discovery.
When the catalog is available, `generateText` also resolves short names against
language models, including when selected by `--generate-text-options`.

For OpenAI image generation through a language model, use
`--generate-text-options text-image.json` (which selects `generateText`):

```json
{
  "maxOutputTokens": 4096,
  "tools": {
    "image_generation": {
      "type": "provider",
      "id": "openai.image_generation",
      "args": { "outputFormat": "webp", "quality": "high" }
    }
  }
}
```

```bash
ai image -m gpt-5.5 "draw a lighthouse" --generate-text-options text-image.json --json -o ./renders/
```

The file also accepts SDK `system`, `temperature`, `topP`, `topK`,
`presencePenalty`, `frequencyPenalty`, `stopSequences`, `reasoning`, `toolChoice`,
and `activeTools`. Tools must be executed by the provider; JavaScript callbacks
and local tool execution require using the SDK directly. Image-tool results,
all returned image files, and accompanying text are retained. Quiver Arrow SVG
output remains supported, including inline previews.

## video

```text
-i, --image <path-or-url>     prompt.image (or pipe one image through stdin)
--frame-images <path>        JSON frameImages array
--input-references <path>    JSON inputReferences array
-n, --n <n>                  Number of videos per model (default: 1)
--max-videos-per-call <n>     SDK batching limit
--aspect-ratio <width:height|adaptive> SDK aspectRatio
--resolution <widthxheight>           SDK resolution, e.g. 1920x1080
--duration <seconds>         Positive duration, including fractional seconds
--fps <number>               Positive frames per second
--generate-audio             Request generated audio
--no-generate-audio          Disable generated audio (unset uses provider default)
--poll-interval-ms <ms>      SDK poll.intervalMs (default: 5000)
--poll-timeout-ms <ms>       SDK poll.timeoutMs (default: --timeout in milliseconds)
--download-max-bytes <bytes> SDK createDownload maxBytes (default: 2 GiB)
```

Use the SDK's exact frame roles in `frames.json`:

```json
[
  { "image": "start.png", "frameType": "first_frame" },
  { "image": "end.png", "frameType": "last_frame" }
]
```

```bash
ai video "a smooth camera move" --frame-images frames.json --duration 5
ai video --image scene.png "animate this" --aspect-ratio adaptive --generate-audio
```

Either frame may be supplied alone. The prompt is optional when image, frame,
or reference inputs are provided. Frame paths accept local paths, `file://`,
HTTP(S), and data URLs. Paths inside JSON files are relative to the working
directory. Use data URLs for inline base64 content.

For reference-to-video generation, `references.json` can contain:

```json
[
  "character.png",
  { "data": "https://example.com/motion.mp4", "mediaType": "video/mp4" }
]
```

```bash
ai video "follow this motion" --input-references references.json --json -o ./clips/
```

Specify `mediaType` for video URLs. SDK precedence rules apply: `frameImages`
replace `inputReferences`, and a `first_frame` replaces `prompt.image`; warnings
are retained in JSON. Duplicate frame roles are rejected locally.

Generation polls the SDK start/status API by default, avoiding a single long-lived
video response. `--timeout` defaults to 600 seconds and bounds generation plus
download; `--poll-timeout-ms` limits the polling stage. `--concurrency` limits
parallel models; `n` and `maxVideosPerCall` control SDK batching within a model.
For multiple SDK calls, JSON output associates each video with its call's response
ID, even if another batch is short or fails. Successful batch diagnostics remain
in `batches`; a short result or failed batch exits nonzero while preserving
returned videos. A failed URL download within a call is recorded in `failures`
without discarding its successfully downloaded siblings. The top-level Gateway
cost fields sum reported costs from completed batches; `batches` keeps each
call's original provider metadata.

To submit a job and return immediately:

```bash
ai video start "a scene" --n 2 --output operation.json
ai video status operation.json
ai video status operation.json --download --output ./clips/
```

`video start` accepts generation/request options and `--webhook-url <url>`.
It prints `{ model, operation, warnings, providerMetadata, response }` as JSON
and optionally saves that same object with `--output`. It accepts one model and
one SDK operation; `n` must fit `maxVideosPerCall`. It does not take polling,
download, preview, or concurrency flags. Keep the operation JSON private: provider
metadata can contain a webhook signing secret. Reuse the same Gateway base URL,
team, and authentication when checking it.

`video status` performs one check and prints SDK `pending`, `completed`, or
`error` status. By default it returns URLs/base64 data without downloading.
`--download` saves completed videos and returns a manifest; `--output` requires
`--download`. Request headers, retries, Gateway connection settings, timeout,
and download limits can be set on status requests too. Provider errors exit 1;
pending operations exit 0 and can be checked again later. If one video download
fails, successful downloads are still saved and `failures` records the error.
When a URL reports a generic media type, recognized video bytes determine the
saved file's format and extension.

Model support determines valid frame/reference combinations, durations,
resolutions, FPS, and audio. Inspect `ai models <model> --json` for native
`video_capabilities`, `modalities`, and `supported_specifications` when supplied
by Gateway. For example, Seedance 2.0 currently advertises 4–15 second clips:
1, 2, or 3 second sections require a different model or trimming. Frame inputs
guide generation and do not guarantee exact frame matching.

## Media migration

- `--count` becomes `--n`; `-n` remains. Counts use SDK batching instead of separate one-output jobs.
- Image `--image` becomes `--images`; `-i` remains. Video retains SDK `--image`.
- Video `--start-frame` / `--end-frame` become `--frame-images` with `first_frame` / `last_frame` JSON entries.
- Image `--quality` / `--style` move to their provider's JSON options. DALL·E's `standard`/`hd` and `vivid`/`natural` values are not universal image settings.
- Image/video JSON uses `elapsedMs`, per-model results, `images`/`videos` artifact arrays, and SDK diagnostics. Multiple outputs always go to separate files, including when stdout is piped. Use `--json` for a machine-readable manifest.

## text

Generate text from a prompt.

```bash
ai text "explain quantum computing"
ai text "summarize this" < notes.txt
```

### Options

#### `-m, --model`

Type: `string`

Model ID (`creator/model`). Comma-separated for multi-model.

#### `-o, --output`

Type: `path`

Output file path or directory.

#### `-f, --format`

Type: `md | txt` | Default: `md`

Output format.

#### `-n, --count`

Type: `number` | Default: `1`

Number of generations per model.

#### `-p, --concurrency`

Type: `number` | Default: `4`

Max parallel generations.

#### `--timeout`

Type: `seconds` | Default: `120`

Request timeout in seconds. Must be a positive integer.

#### `-s, --system`

Type: `string`

System prompt.

#### `--max-tokens`

Type: `number`

Maximum tokens to generate.

#### `-t, --temperature`

Type: `number`

Temperature (0–2).

#### `-q, --quiet`

Type: `boolean`

Suppress progress output.

#### `--json`

Type: `boolean`

Output metadata as JSON.

***

## audio

Generate speech from text or transcribe audio to text.

```bash
ai audio speak "Hello from AI Gateway"
ai audio transcribe recording.mp3
cat voice-note.mp3 | ai audio transcribe -o transcript.txt
```

### audio speak

#### `-m, --model`

Type: `string`

Speech model ID. Comma-separated for multi-model.

#### `-o, --output`

Type: `path`

Output file path or directory.

#### `-f, --format`

Type: `string` | Default: `mp3`

Audio output format.

#### `--voice`

Type: `string`

Voice to use for speech generation.

#### `--instructions`

Type: `string`

Instructions for speech generation.

#### `--speed`

Type: `number`

Speech speed.

#### `--language`

Type: `code`

Language code, such as `en` or `fr`, or `auto`.

#### `-n, --count`

Type: `number` | Default: `1`

Number of generations per model.

#### `-p, --concurrency`

Type: `number` | Default: `4`

Max parallel generations.

#### `--timeout`

Type: `seconds` | Default: `120`

Request timeout in seconds. Must be a positive integer.

#### `-q, --quiet`

Type: `boolean`

Suppress progress output.

#### `--json`

Type: `boolean`

Output metadata as JSON.

#### `--no-play`

Type: `boolean`

Disable audio playback after generation.

#### `--no-waveform`

Type: `boolean`

Disable accurate terminal waveform preview.

`audio speak` accepts text from an argument or stdin:

```bash
echo "Ship the changelog" | ai audio speak -o changelog.mp3
cat announcement.txt | ai audio speak --format wav -o announcement.wav
```

### audio transcribe

#### `-m, --model`

Type: `string`

Transcription model ID. Comma-separated for multi-model.

#### `-o, --output`

Type: `path`

Output file path or directory.

#### `-f, --format`

Type: `md | txt` | Default: `txt`

Transcript output format.

#### `-n, --count`

Type: `number` | Default: `1`

Number of transcriptions per model.

#### `-p, --concurrency`

Type: `number` | Default: `4`

Max parallel transcriptions.

#### `--timeout`

Type: `seconds` | Default: `120`

Request timeout in seconds. Must be a positive integer.

#### `-q, --quiet`

Type: `boolean`

Suppress progress output.

#### `--json`

Type: `boolean`

Output metadata as JSON.

`audio transcribe` accepts a local path, `file://` URL, `http(s)://` URL, or piped audio:

```bash
ai audio transcribe meeting.mp3
ai audio transcribe https://example.com/call.wav
cat recording.mp3 | ai audio transcribe
```

***

## decide

Ask named Boolean, Choice, and Score questions against shared stdin:

```bash
cat ticket.txt |
  ai decide \
    --boolean "refund=Refund requested?" \
    --choice "team=Which team?" \
    --choices "team=billing,support" \
    --score "tone=How positive?" \
    --levels "tone=angry,neutral,happy"

ai decide --questions triage.json < ticket.json
```

Output is the SDK evaluation result as JSON, including named typed answers,
probabilities, usage, provider metadata, and response information. Repeat question
flags to ask more questions in one request.
Text, JSON objects, and arrays remain one shared state.

Use `--questions` for structured instructions and criteria, `--input auto|text|json`
to control parsing, `--model` to choose one evaluation model, `--provider-options`
for the SDK’s provider-specific settings, and `--max-retries` or `--timeout` for request controls.

See [Decide](/docs/decide) for every flag, the question-file schema, probability
semantics, and examples of using the answers in scripts. Valid evaluations exit
zero even for false or uncertain answers; your code owns thresholds and routing.

***

## models

List available models from the AI Gateway, or show detailed info for one model.

```bash
ai models
ai models --type image
ai models --type evaluation
ai models --creator openai --json
ai models claude-opus-4.6
ai models anthropic/claude-opus-4.6 --json
```

### Arguments

#### `[model]`

Type: `string`

Model ID or short name. Shows a detail card with context window, max
output, pricing (input, output, cache read/write, web search), release
date and per-provider latency, throughput and uptime.

### Options

#### `--type`

Type: `text | image | video | audio | speech | transcription | evaluation`

Filter by modality (list mode only).

#### `--creator`

Type: `string`

Filter by creator (e.g. `openai`, `google`) (list mode only).

#### `--json`

Type: `boolean`

Output as JSON with descriptions.

Models are fetched live from the AI Gateway.
JSON preserves native metadata, including `video_capabilities`, `modalities`,
and `supported_specifications`. Model discovery also accepts `--base-url`,
`--team-id-or-slug`, and `--headers <json-file>` for Gateway connection settings.

***

## Timeouts

Requests that exceed the per-command timeout are aborted automatically:

| Command            | Timeout                           |
| ------------------ | --------------------------------- |
| `decide`           | 30 seconds per evaluation request |
| `text`             | 120 seconds                       |
| `image`            | 300 seconds                       |
| `video`            | 600 seconds                       |
| `audio speak`      | 120 seconds                       |
| `audio transcribe` | 120 seconds                       |

Image and video generation use a longer timeout because models typically need more processing time.

Use `--timeout <seconds>` to allow a longer request without changing models. The value must be a positive integer:

```bash
ai image --timeout 600 "a detailed sprite atlas"
```

## Exit codes

| Code | Meaning                                                  |
| ---- | -------------------------------------------------------- |
| `0`  | Success                                                  |
| `1`  | Invalid input or request failure; all generations failed |
| `2`  | Partial generation failure (some succeeded, some failed) |