ai

A tiny, agent-native CLI for generating images, video, audio and text with dead-simple commands, stdin support and predictable artifact outputs. Uses Vercel AI SDK and AI Gateway for unified access to hundreds of models.

Install

npm install -g ai-cli

Requires Node.js 22+ and an AI Gateway API key or a provider-specific key (e.g. OPENAI_API_KEY).

Usage

ai image "a cute dog"
ai video "a spinning triangle"
ai text "explain quantum computing"
ai audio speak "Thanks for trying ai-cli"
ai audio transcribe recording.mp3
ai models                          # list available models

Piping and References

ai image "a dragon" | ai video "animate this"
ai video -i input.png "animate this"
ai image --image reference.png "make a sticker in this style"
ai image -i sketch.png -i palette.jpg "render this product concept"
ai text --image screenshot.png "what is broken in this UI?"
cat photo.png | ai text "describe this image"
cat notes.txt | ai text "summarize this"
git diff | ai text "explain these changes"
echo "Ship the changelog" | ai audio speak -o changelog.mp3
cat recording.mp3 | ai audio transcribe

Common Options

All commands support:

-m, --model <id>         Model ID (creator/model-name), comma-separated for multi-model
-o, --output <path>      Output file path or directory
-n, --count <n>          Number of generations per model (default: 1)
-p, --concurrency <n>    Max parallel generations (default: 4, video: 2)
--timeout <seconds>      Request timeout in seconds (default: text/audio 120, image/video 300)
-q, --quiet              Suppress progress output
--json                   Output metadata as JSON

When using --json, stdout contains only metadata. Generated text, image, video and audio outputs are written to files even when stdout is piped.

Model IDs can be specified as creator/model-name or just model-name (resolved against models fetched from the gateway):

ai text -m gpt-5.5 "hello"          # resolves to openai/gpt-5.5
ai image -m flux-2-pro "a sunset"   # resolves to bfl/flux-2-pro
ai audio speak -m tts-1 "hello"     # resolves to openai/tts-1

Model IDs must contain printable ASCII characters without spaces. This applies to both --model values and the AI_CLI_*_MODEL environment variables.

image

-i, --image <path-or-url> Reference image path or URL (repeatable)
--size <WxH>             Image size (e.g. 1024x1024)
--aspect-ratio <W:H>     Aspect ratio (e.g. 16:9)
--quality <level>        Quality (standard, hd)
--style <style>          Style (vivid, natural)
--no-preview             Disable inline image preview

Reference images can be local paths, file:// URLs, http(s):// URLs or data URLs. You can repeat --image to pass multiple references, and you can still pipe one image through stdin:

cat input.png | ai image -i style.png "combine the subject with this style"

Reference-image support is model-dependent; unsupported models may reject image inputs.

Gemini image models (e.g. google/gemini-2.5-flash-image) don't support --size; use --aspect-ratio instead.

video

-i, --image <path-or-url> Image input path or URL
--aspect-ratio <W:H>     Aspect ratio (e.g. 16:9)
--duration <seconds>     Duration in seconds
--no-preview             Disable inline video frame preview

Image inputs can be local paths, file:// URLs, http(s):// URLs or data URLs. Video generation accepts one input image, provided either through --image or piped stdin:

ai video -i input.png "animate this"
cat input.png | ai video "animate this"

text

-f, --format <fmt>       Output format: md, txt (default: md)
-i, --image <path-or-url> Image input path or URL for vision (repeatable)
-s, --system <prompt>    System prompt
--max-tokens <n>         Maximum tokens to generate
-t, --temperature <n>    Temperature (0-2)

For vision-capable text models, ai text accepts images from --image or piped stdin:

ai text -i chart.png -i table.jpg "summarize the data"
cat screenshot.png | ai text "list the visible errors"

audio

audio has two subcommands:

ai audio speak "Hello from AI Gateway"
ai audio transcribe recording.mp3

audio speak

-f, --format <fmt>       Audio output format (default: mp3)
--voice <voice>          Voice to use for speech generation
--instructions <text>    Instructions for speech generation
--speed <n>              Speech speed
--language <code>        Language code (e.g. en, fr) or auto
--no-play                Disable audio playback after generation
--no-waveform            Disable accurate terminal waveform preview

audio speak accepts text from an argument or stdin and saves audio to <id>.mp3 by default:

ai audio speak --voice alloy "Read this as a friendly update"
cat announcement.txt | ai audio speak --format wav -o announcement.wav

When using OpenAI speech models, ai audio speak defaults to the alloy voice unless --voice is provided.

When -o points to a file with a known audio extension and --format is omitted, the extension selects the audio format. If both are provided, --format must match the filename extension.

In interactive terminals, audio speak plays the generated audio after saving it and shows an accurate waveform derived from decoded audio samples. Use --no-play to skip playback and --no-waveform or --quiet to suppress the waveform. Playback and waveform previews are skipped for --json and binary stdout pipeline output. WAV output is decoded directly; MP3 and other encoded formats use a local decoder when available (ffmpeg, mpg123, sox, or afconvert).

audio transcribe

-f, --format <fmt>       Output format: md, txt (default: txt)

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

ai audio transcribe meeting.mp3
ai audio transcribe https://example.com/call.wav
cat voice-note.mp3 | ai audio transcribe -o transcript.txt

models

[model]                  Show detailed info for a model (e.g. anthropic/claude-opus-4.6)
--type <type>            Filter by type: text, image, video, audio, speech, transcription
--creator <name>         Filter by creator (e.g. openai, google)
--json                   Output as JSON (includes descriptions)

All model types (text, image, video, speech, transcription) are fetched live from the AI Gateway.

Pass a model ID (or short name) to see its context window, max output, pricing, release date and per-provider latency, throughput and uptime:

$ ai models claude-opus-4.6

Claude Opus 4.6  anthropic/claude-opus-4.6
Released 2026-02-05 · tool-use · reasoning · vision · web-search

  Context      1M
  Max output   128K
  Input        $5/M
  Output       $25/M
  Cache read   $0.5/M
  Cache write  $6.25/M
  Web search   $10/K + input costs

Providers
  provider   context  latency  throughput  uptime
  anthropic  1M       1.4s     49tps       99.9%
  bedrock    1M       1.4s     56tps       99.9%

Multi-Model Comparison

Generate with multiple models by comma-separating -m:

ai image "a sunset" -m "openai/gpt-image-1,xai/grok-imagine-image,bfl/flux-2-pro"

Combine with -n to generate multiple per model:

ai image "a sunset" -n 2 -m "openai/gpt-image-1,bfl/flux-2-pro"   # 4 images total

Inline Preview

When running in a terminal that supports the Kitty graphics protocol (Kitty, Ghostty, WezTerm, Warp, iTerm2), generated images and videos are displayed inline automatically. Video previews decode an H.264 keyframe from the midpoint of the video using openh264 compiled to WebAssembly — no native dependencies required. audio speak can also play generated speech and render a terminal waveform after saving. Use --no-preview for image/video previews, --no-play or --no-waveform for audio previews, or set AI_CLI_PREVIEW=1 to force visual previews on in undetected terminals.

Output Behavior

• text: saves to <id>.md (interactive), stdout when piped
• image/video: saves to <id>.png / <id>.mp4 (interactive), raw binary stdout when piped
• audio speak: saves to <id>.mp3 (interactive), raw binary stdout when piped
• audio transcribe: saves to <id>.txt (interactive), stdout when piped
• -o <dir>: saves inside the directory with auto-generated names

When the CLI needs to choose a filename, it uses a response id when available and falls back to a random 8-character id.

Environment Variables

The -m flag always takes priority over AI_CLI_*_MODEL env vars. The -o flag always takes priority over AI_CLI_OUTPUT_DIR.

Timeouts

Requests that exceed the timeout are aborted automatically:

Use --timeout <seconds> to override the default for text, image, video, audio speak, or audio transcribe. The value must be a positive integer. For example, ai image --timeout 600 "a detailed sprite atlas" allows the request to run for up to 10 minutes.

Exit Codes

License

Apache-2.0