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.
npm install -g ai-cliRequires Node.js 22+ and an AI Gateway API key or a provider-specific key (e.g. OPENAI_API_KEY).
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 modelsai 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 transcribeAll 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)
-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-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.
-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"-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 has two subcommands:
ai audio speak "Hello from AI Gateway"
ai audio transcribe recording.mp3-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.wavWhen 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).
-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[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%
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 totalWhen 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.
- 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.
| Variable | Description |
|---|---|
AI_GATEWAY_API_KEY |
AI Gateway authentication key |
OPENAI_API_KEY |
Provider-specific key (or other provider keys) |
AI_CLI_TEXT_MODEL |
Default text model (overrides openai/gpt-5.5) |
AI_CLI_IMAGE_MODEL |
Default image model (overrides openai/gpt-image-2) |
AI_CLI_VIDEO_MODEL |
Default video model (overrides bytedance/seedance-2.0) |
AI_CLI_SPEECH_MODEL |
Default speech model (overrides openai/tts-1) |
AI_CLI_TRANSCRIPTION_MODEL |
Default transcription model (overrides openai/whisper-1) |
AI_CLI_OUTPUT_DIR |
Default output directory for generated files |
AI_CLI_PREVIEW |
Set to 1 to force inline image preview, 0 to disable |
NO_COLOR |
Disable ANSI color output |
FORCE_COLOR |
Force color output even when not a TTY |
The -m flag always takes priority over AI_CLI_*_MODEL env vars. The -o flag always takes priority over AI_CLI_OUTPUT_DIR.
Requests that exceed the timeout are aborted automatically:
| Command | Timeout |
|---|---|
text |
120 seconds |
image |
300 seconds |
video |
300 seconds |
audio speak |
120 seconds |
audio transcribe |
120 seconds |
| Code | Meaning |
|---|---|
0 |
Success |
1 |
All generations failed |
2 |
Partial failure (some succeeded, some failed) |