ai-cli weekly downloads statistics

ai

<p> <a href="https://vercel.com/labs#active-experiments"><img alt="Vercel Labs Experiment" src="https://img.shields.io/badge/LABS-EXPERIMENT-0a0a0a.svg?style=for-the-badge&amp;logo=Vercel&amp;labelColor=000000" height="28"></a> <a href="https://www.npmjs.com/package/ai-cli"><img alt="npm version: ai-cli" src="https://img.shields.io/npm/v/ai-cli.svg?style=for-the-badge&amp;labelColor=000000" height="28"></a> <a href="https://www.apache.org/licenses/LICENSE-2.0"><img alt="License: Apache-2.0" src="https://img.shields.io/npm/l/ai-cli.svg?style=for-the-badge&amp;labelColor=000000" height="28"></a> </p>

Generate anything from your terminal

Create text, images, video, and audio, and make typed decisions with composable commands, stdin support, and predictable outputs. Built with the Vercel AI SDK and AI Gateway for 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 decide --boolean "refund=Refund requested?" < ticket.txt
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 --images 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

Generation commands support:

-m, --model <id>         Model ID (creator/model-name), comma-separated for multi-model
-o, --output <path>      Output file path or directory
-n, --n <n>              Image/video outputs per model (default: 1)
-n, --count <n>          Text/audio 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 300, video 600)
-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. 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.

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.

decide

ai evaluate remains available as a backward-compatible alias for ai decide.

Make decisions with named Boolean, Choice, and Score questions using AI SDK evaluation models:

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"

All questions share one unchanged input. Text keeps its line breaks; JSON objects and arrays keep their shape. Each question has an explicit type and a unique ID. Choices and levels bind to that ID regardless of flag order. Repeat the flags to ask more questions in the same request.

• Boolean returns probability: P(true) from 0 to 1, including strong no answers near zero.
• Choice returns one supplied option and its distribution when available.
• Score returns a fractional position on ordered levels, starting at zero, and a distribution when available. Jev uses the probability-weighted mean.

The command calls AI SDK's experimental_decide: stdin maps to state, and typed flags build its named questions. --choices creates a Choice criteria map; --levels creates a Score criteria array. The file form uses the SDK question schema directly. Jev is the default evaluation model; other supported evaluation models use the same interface.

Pass images with -i, --images (paths, data URLs, or public URLs; repeatable). They follow stdin as file parts in the same state, in order; stdin is optional when images are given:

ai decide --boolean "receipt=Is this a receipt?" -i scan.png
echo "Order #123" | ai decide --boolean "match=Does the photo show order #123?" -i photo.jpg

For richer criteria, save a named question map to triage.json:…