ai-cli 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,147 @@
+# ai
+
+A tiny, agent-native CLI for generating images, video and text with dead-simple commands, stdin support and predictable artifact outputs. Uses [Vercel AI SDK](https://sdk.vercel.ai) and [AI Gateway](https://vercel.com/docs/ai-gateway) for unified access to hundreds of models.
+
+## Install
+
+```bash
+npm install -g ai-cli
+```
+
+Requires an [AI Gateway](https://vercel.com/docs/ai-gateway) API key or a provider-specific key (e.g. `OPENAI_API_KEY`).
+
+## Usage
+
+```bash
+ai image "a cute dog"
+ai video "a spinning triangle"
+ai text "explain quantum computing"
+ai models                          # list available models
+```
+
+### Piping
+
+```bash
+ai image "a dragon" | ai video "animate this"
+cat notes.txt | ai text "summarize this"
+git diff | ai text "explain these changes"
+```
+
+### 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)
+-q, --quiet              Suppress progress output
+--json                   Output metadata as JSON
+```
+
+Model IDs can be specified as `creator/model-name` or just `model-name` (resolved against models fetched from the gateway):
+
+```bash
+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
+```
+
+### image
+
+```
+--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
+```
+
+### video
+
+```
+--aspect-ratio <W:H>     Aspect ratio (e.g. 16:9)
+--duration <seconds>     Duration in seconds
+--no-preview             Disable inline video frame preview
+```
+
+### text
+
+```
+-f, --format <fmt>       Output format: md, txt (default: md)
+-s, --system <prompt>    System prompt
+--max-tokens <n>         Maximum tokens to generate
+-t, --temperature <n>    Temperature (0-2)
+```
+
+### models
+
+```
+--type <type>            Filter by type: text, image, video
+--creator <name>         Filter by creator (e.g. openai, google)
+--json                   Output as JSON (includes descriptions)
+```
+
+All model types (text, image, video) are fetched live from the AI Gateway.
+
+### Multi-Model Comparison
+
+Generate with multiple models by comma-separating `-m`:
+
+```bash
+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:
+
+```bash
+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](https://sw.kovidgoyal.net/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](https://github.com/cisco/openh264) compiled to WebAssembly — no native dependencies required. Use `--no-preview` to disable this, or set `AI_CLI_PREVIEW=1` to force it on in undetected terminals.
+
+### Output Behavior
+
+- **text**: saves to `output.md` (interactive), stdout when piped
+- **image/video**: saves to file (interactive), raw binary stdout when piped
+- **`-o <dir>`**: saves inside the directory with auto-generated names
+
+### Environment Variables
+
+| 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_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`.
+
+### Timeouts
+
+Requests that exceed the timeout are aborted automatically:
+
+| Command | Timeout |
+|---|---|
+| `text` | 120 seconds |
+| `image` | 120 seconds |
+| `video` | 300 seconds |
+
+### Exit Codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success |
+| `1` | All generations failed |
+| `2` | Partial failure (some succeeded, some failed) |
+
+## License
+
+[Apache-2.0](LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A tiny, agent-native CLI for generating images, video and text with dead-simple commands, stdin support and predictable artifact outputs",
   "type": "module",
   "license": "Apache-2.0",

package/src/cli.test.ts

@@ -22,7 +22,7 @@ describe("cli integration", () => {
   test("--help exits 0 and lists subcommands", async () => {
     const { exitCode, stdout } = await run("--help");
     expect(exitCode).toBe(0);
-    for (const sub of ["text", "image", "video", "models", "completions"]) {
+    for (const sub of ["text", "image", "video", "models"]) {
       expect(stdout).toContain(sub);
     }
   });
@@ -33,31 +33,6 @@ describe("cli integration", () => {
     expect(stdout.trim()).toMatch(/^\d+\.\d+\.\d+/);
   });
 
-  test("completions zsh exits 0 with valid output", async () => {
-    const { exitCode, stdout } = await run("completions", "zsh");
-    expect(exitCode).toBe(0);
-    expect(stdout).toContain("#compdef ai");
-    expect(stdout).toContain("--no-preview");
-  });
-
-  test("completions bash exits 0 with valid output", async () => {
-    const { exitCode, stdout } = await run("completions", "bash");
-    expect(exitCode).toBe(0);
-    expect(stdout).toContain("complete -F");
-  });
-
-  test("completions fish exits 0 with valid output", async () => {
-    const { exitCode, stdout } = await run("completions", "fish");
-    expect(exitCode).toBe(0);
-    expect(stdout).toContain("complete -c ai");
-  });
-
-  test("completions with invalid shell exits 1", async () => {
-    const { exitCode, stderr } = await run("completions", "powershell");
-    expect(exitCode).toBe(1);
-    expect(stderr).toContain("Unknown shell");
-  });
-
   test("text with no prompt and no stdin exits 1", async () => {
     const { exitCode, stderr } = await run("text");
     expect(exitCode).toBe(1);

package/src/commands/image.ts

@@ -1,8 +1,8 @@
-import { generateImage, gateway } from "ai";
+import { generateImage, generateText, gateway } from "ai";
 import type { Command } from "commander";
 
 import { buildJobs, runJobs } from "../lib/jobs.js";
-import { resolveModels } from "../lib/models.js";
+import { fetchGatewayModels, resolveModels } from "../lib/models.js";
 import { parsePositiveInt, parseSize, parseAspectRatio } from "../lib/parse.js";
 import { readStdin } from "../lib/stdin.js";
 
@@ -57,15 +57,17 @@ export function registerImageCommand(program: Command) {
         );
         process.exit(1);
       }
-      let imagePrompt: string | { images: Uint8Array[]; text?: string } =
-        prompt!;
+      let imagePrompt: string | { images: Uint8Array[]; text?: string };
       if (stdin) {
         imagePrompt = prompt
           ? { images: [new Uint8Array(stdin)], text: prompt }
           : { images: [new Uint8Array(stdin)] };
+      } else {
+        imagePrompt = prompt!;
       }
 
-      const models = resolveModels("image", opts.model);
+      const gatewayModels = await fetchGatewayModels();
+      const models = resolveModels("image", opts.model, gatewayModels.image);
       const countPerModel = opts.count
         ? parsePositiveInt(opts.count, "count")
         : 1;
@@ -90,7 +92,62 @@ export function registerImageCommand(program: Command) {
         jobs,
         async (modelId) => {
           const abort = AbortSignal.timeout(DEFAULT_TIMEOUT_MS);
+
+          if (gatewayModels.languageImageModelIds.has(modelId)) {
+            const messageContent: Array<
+              | { type: "text"; text: string }
+              | { type: "image"; image: Uint8Array }
+            > = [];
+            if (typeof imagePrompt === "string") {
+              messageContent.push({ type: "text", text: imagePrompt });
+            } else {
+              for (const img of imagePrompt.images) {
+                messageContent.push({ type: "image", image: img });
+              }
+              if (imagePrompt.text) {
+                messageContent.push({
+                  type: "text",
+                  text: imagePrompt.text,
+                });
+              } else {
+                messageContent.push({
+                  type: "text",
+                  text: "Generate an image",
+                });
+              }
+            }
+            const creator = gatewayModels.all.find(
+              (m) => m.id === modelId
+            )?.creator;
+            const result = await generateText({
+              headers: {
+                "http-referer": "https://github.com/vercel-labs/ai-cli",
+                "x-title": "ai-cli",
+              },
+              model: gateway(modelId),
+              messages: [{ role: "user", content: messageContent }],
+              abortSignal: abort,
+              providerOptions:
+                creator === "google"
+                  ? { google: { responseModalities: ["IMAGE", "TEXT"] } }
+                  : undefined,
+            });
+            const imageFile = result.files?.find((f) =>
+              f.mediaType.startsWith("image/")
+            );
+            if (!imageFile) {
+              throw new Error(
+                `Model ${modelId} did not return an image in the response`
+              );
+            }
+            return Buffer.from(imageFile.uint8Array);
+          }
+
           const result = await generateImage({
+            headers: {
+              "http-referer": "https://github.com/vercel-labs/ai-cli",
+              "x-title": "ai-cli",
+            },
             model: gateway.image(modelId),
             prompt: imagePrompt,
             abortSignal: abort,

package/src/commands/models.ts

@@ -1,14 +1,16 @@
 import type { Command } from "commander";
 
-import { fetchGatewayModels, type ModelEntry } from "../lib/models.js";
+import {
+  fetchGatewayModels,
+  type Modality,
+  type ModelEntry,
+} from "../lib/models.js";
 
-function groupByProvider(models: ModelEntry[]): Map<string, ModelEntry[]> {
+function groupByCreator(models: ModelEntry[]): Map<string, ModelEntry[]> {
   const groups = new Map<string, ModelEntry[]>();
   for (const m of models) {
-    const slash = m.id.indexOf("/");
-    const provider = slash !== -1 ? m.id.slice(0, slash) : "other";
-    if (!groups.has(provider)) groups.set(provider, []);
-    groups.get(provider)!.push(m);
+    if (!groups.has(m.creator)) groups.set(m.creator, []);
+    groups.get(m.creator)!.push(m);
   }
   return new Map(
     [...groups.entries()].sort((a, b) => a[0].localeCompare(b[0]))
@@ -25,61 +27,42 @@ export function registerModelsCommand(program: Command) {
     .command("models")
     .description("List available models from AI Gateway")
     .option("--type <type>", "Filter by type: text, image, video")
-    .option("--provider <name>", "Filter by provider (e.g. openai, google)")
+    .option("--creator <name>", "Filter by creator (e.g. openai, google)")
     .option("--json", "Output as JSON (includes descriptions)")
     .action(
-      async (opts: { type?: string; provider?: string; json?: boolean }) => {
+      async (opts: { type?: string; creator?: string; json?: boolean }) => {
         const validTypes = ["text", "image", "video"];
-        const filterType = opts.type?.toLowerCase();
+        const filterType = opts.type?.toLowerCase() as Modality | undefined;
         if (filterType && !validTypes.includes(filterType)) {
           process.stderr.write(
             `Error: --type must be one of: ${validTypes.join(", ")} (got "${opts.type}")\n`
           );
           process.exit(1);
         }
-        const filterProvider = opts.provider?.toLowerCase();
+        const filterCreator = opts.creator?.toLowerCase();
 
         const gatewayModels = await fetchGatewayModels();
 
-        const filterGrouped = (grouped: Map<string, ModelEntry[]>) => {
-          if (!filterProvider) return grouped;
-          const filtered = new Map<string, ModelEntry[]>();
-          for (const [provider, models] of grouped) {
-            if (provider.toLowerCase() === filterProvider) {
-              filtered.set(provider, models);
-            }
-          }
-          return filtered;
-        };
-
         if (opts.json) {
-          const output: Record<string, unknown> = {};
-          const jsonMapper = (m: ModelEntry) => ({
-            id: m.id,
-            ...(m.name ? { name: m.name } : {}),
-            ...(m.description ? { description: m.description } : {}),
-          });
-          if (!filterType || filterType === "text") {
-            output.text = Object.fromEntries(
-              [...filterGrouped(groupByProvider(gatewayModels.text))].map(
-                ([provider, models]) => [provider, models.map(jsonMapper)]
-              )
+          let entries = gatewayModels.all;
+          if (filterType) {
+            entries = entries.filter((m) =>
+              m.capabilities.includes(filterType)
             );
           }
-          if (!filterType || filterType === "image") {
-            output.image = Object.fromEntries(
-              [...filterGrouped(groupByProvider(gatewayModels.image))].map(
-                ([provider, models]) => [provider, models.map(jsonMapper)]
-              )
-            );
-          }
-          if (!filterType || filterType === "video") {
-            output.video = Object.fromEntries(
-              [...filterGrouped(groupByProvider(gatewayModels.video))].map(
-                ([provider, models]) => [provider, models.map(jsonMapper)]
-              )
+          if (filterCreator) {
+            entries = entries.filter(
+              (m) => m.creator.toLowerCase() === filterCreator
             );
           }
+          const output = entries.map((m) => ({
+            id: m.id,
+            ...(m.name ? { name: m.name } : {}),
+            ...(m.description ? { description: m.description } : {}),
+            creator: m.creator,
+            capabilities: m.capabilities,
+            ...(m.pricing ? { pricing: m.pricing } : {}),
+          }));
           process.stdout.write(JSON.stringify(output, null, 2) + "\n");
           return;
         }
@@ -94,13 +77,19 @@ export function registerModelsCommand(program: Command) {
 
         let totalCount = 0;
         for (const section of sections) {
-          const grouped = filterGrouped(groupByProvider(section.entries));
+          let entries = section.entries;
+          if (filterCreator) {
+            entries = entries.filter(
+              (m) => m.creator.toLowerCase() === filterCreator
+            );
+          }
+          const grouped = groupByCreator(entries);
           const count = [...grouped.values()].reduce((s, m) => s + m.length, 0);
           if (count === 0) continue;
           totalCount += count;
           process.stdout.write(`\n${section.title} models (${count}):\n`);
-          for (const [provider, models] of grouped) {
-            process.stdout.write(`\n  ${provider}\n`);
+          for (const [creator, models] of grouped) {
+            process.stdout.write(`\n  ${creator}\n`);
             for (const m of models) {
               process.stdout.write(`    ${modelName(m.id)}\n`);
             }

package/src/commands/text.ts

@@ -2,7 +2,7 @@ import { generateText, gateway } from "ai";
 import type { Command } from "commander";
 
 import { buildJobs, runJobs } from "../lib/jobs.js";
-import { resolveModels } from "../lib/models.js";
+import { fetchGatewayModels, resolveModels } from "../lib/models.js";
 import type { OutputFormat } from "../lib/output.js";
 import { parsePositiveInt, parseTemperature } from "../lib/parse.js";
 import { readStdin, stdinAsText } from "../lib/stdin.js";
@@ -69,7 +69,8 @@ export function registerTextCommand(program: Command) {
       }
 
       const format = resolveFormat(opts.format);
-      const models = resolveModels("text", opts.model);
+      const gatewayModels = await fetchGatewayModels();
+      const models = resolveModels("text", opts.model, gatewayModels.text);
       const countPerModel = opts.count
         ? parsePositiveInt(opts.count, "count")
         : 1;
@@ -87,6 +88,10 @@ export function registerTextCommand(program: Command) {
         async (modelId) => {
           const abort = AbortSignal.timeout(DEFAULT_TIMEOUT_MS);
           const result = await generateText({
+            headers: {
+              "http-referer": "https://github.com/vercel-labs/ai-cli",
+              "x-title": "ai-cli",
+            },
             model: gateway(modelId),
             prompt: fullPrompt,
             system: opts.system,

package/src/commands/video.ts

@@ -2,7 +2,7 @@ import { experimental_generateVideo as generateVideo, gateway } from "ai";
 import type { Command } from "commander";
 
 import { buildJobs, runJobs } from "../lib/jobs.js";
-import { resolveModels } from "../lib/models.js";
+import { fetchGatewayModels, resolveModels } from "../lib/models.js";
 import {
   parsePositiveInt,
   parseAspectRatio,
@@ -65,7 +65,8 @@ export function registerVideoCommand(program: Command) {
           : { image: new Uint8Array(stdin) };
       }
 
-      const models = resolveModels("video", opts.model);
+      const gatewayModels = await fetchGatewayModels();
+      const models = resolveModels("video", opts.model, gatewayModels.video);
       const countPerModel = opts.count
         ? parsePositiveInt(opts.count, "count")
         : 1;
@@ -83,6 +84,10 @@ export function registerVideoCommand(program: Command) {
         async (modelId) => {
           const abort = AbortSignal.timeout(DEFAULT_TIMEOUT_MS);
           const result = await generateVideo({
+            headers: {
+              "http-referer": "https://github.com/vercel-labs/ai-cli",
+              "x-title": "ai-cli",
+            },
             model: gateway.video(modelId),
             prompt: videoPrompt,
             abortSignal: abort,

package/src/index.ts

@@ -2,7 +2,6 @@
 import { Command } from "commander";
 
 import pkg from "../package.json";
-import { registerCompletionsCommand } from "./commands/completions.js";
 import { registerImageCommand } from "./commands/image.js";
 import { registerModelsCommand } from "./commands/models.js";
 import { registerTextCommand } from "./commands/text.js";
@@ -21,7 +20,6 @@ registerTextCommand(program);
 registerImageCommand(program);
 registerVideoCommand(program);
 registerModelsCommand(program);
-registerCompletionsCommand(program);
 
 program.parseAsync(process.argv).catch((err: unknown) => {
   const msg = err instanceof Error ? err.message : String(err);