ai-cli 0.0.13 → 0.1.1

package/README.md

@@ -1,6 +1,6 @@
-# ai-cli
+# ai
 
-Minimal terminal AI assistant.
+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
 
@@ -8,292 +8,113 @@ Minimal terminal AI assistant.
 npm install -g ai-cli
 ```
 
-## Setup
-
-```bash
-ai init
-```
-
-Get your API key from [Vercel AI Gateway](https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai%2Fapi-keys&title=Go+to+AI+Gateway)
+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                           # interactive mode
-ai "hello"                   # single message
-ai -m gpt-5 "hello"          # use specific model
-ai --image ./img.png "what?" # analyze image (single message)
-ai -l                        # list models
-echo "explain this" | ai     # pipe input
-ai --system "respond in Spanish" "hola"  # custom system prompt
-
-# in interactive mode, ctrl+v to paste image from clipboard
+ai image "a cute dog"
+ai video "a spinning triangle"
+ai text "explain quantum computing"
+ai models                          # list available models
 ```
 
-## Headless Mode
-
-Run the full agent non-interactively. Useful for CI pipelines, scripts, and automation.
+### Piping
 
 ```bash
-ai -p "explain this codebase"                          # output to stdout
-ai -p --json "write tests for src/auth.ts" > result.json  # structured JSON
-ai -p --force "fix all type errors"                    # skip confirmations
-ai -p --no-save "what dependencies are outdated?"      # ephemeral (no history)
-git diff | ai -p "review this for bugs"                # pipe + headless
-ai -p -m gpt-5 --force "refactor the database layer"  # combine flags
-ai -p --plan "how should I refactor auth?"             # plan mode (read-only)
-ai -p -r <chatId> "continue"                           # resume a session
-ai -p --timeout 60 "fix type errors"                   # abort after 60s
-ai -p -q "explain this codebase"                       # suppress stderr status
+ai image "a dragon" | ai video "animate this"
+cat notes.txt | ai text "summarize this"
+git diff | ai text "explain these changes"
 ```
 
-Exit codes: `0` success, `1` error, `2` agent stuck.
-
-**Note:** When `--timeout` fires during a tool execution (e.g., mid-file-write), the agent is interrupted immediately. The workspace may contain partial changes. Combine with version control or review the working tree after a timeout.
-
-JSON output format:
-
-```json
-{
-  "output": "...",
-  "model": "anthropic/claude-sonnet-4.5",
-  "tokens": 1234,
-  "cost": 0.05,
-  "exitCode": 0,
-  "chatId": "abc123",
-  "usage": {
-    "inputTokens": 800,
-    "outputTokens": 434,
-    "cacheReadTokens": 0,
-    "cacheWriteTokens": 0,
-    "reasoningTokens": 0
-  }
-}
-```
+### Common Options
 
-On error, includes an `error` field with the message.
-
-## Options
-
-- `-m, --model` - model (default: anthropic/claude-sonnet-4.5)
-- `--image` - attach image file
-- `-r, --resume` - resume a previous chat by ID
-- `--plan` - start in plan mode (think before acting)
-- `-p, --print` - headless mode: full agent, output to stdout, then exit
-- `--json` - structured JSON output (implies --print)
-- `--system` - append custom text to the system prompt
-- `--fast` - enable Anthropic fast mode (speed=fast)
-- `--force` - auto-approve all tool actions (--print only)
-- `--no-save` - don't persist the chat to history (--print only)
-- `--timeout` - abort after N seconds (--print only)
-- `-q, --quiet` - suppress stderr status output (--print only)
-- `-l, --list` - list models
-- `--no-color` - disable color output
-- `-v, --version` - show version
-- `-h, --help` - help
-
-## Commands
-
-### Chat
-- `/new` - new chat
-- `/chats` - list chats
-- `/chat <n>` - load chat
-- `/delete` - delete chat
-- `/clear` - clear screen
-
-### Files
-- `/copy` - copy response
-- `/rollback` - undo changes
-
-### Context
-- `/usage` - token usage and cost
-- `/compress` - compress history
-- `/plan` - toggle plan mode (think before acting)
-- `/review` - review loop (auto-reviews changes for bugs)
-
-### Model
-- `/model` - select model interactively
-- `/model <query>` - switch to matching model
-
-### System
-- `/info` - version, model, balance, storage
-- `/processes` - background processes
-- `/memory` - saved memories
-- `/mcp` - mcp servers
-- `/settings` - preferences
-- `/permissions` - tool permission rules
-- `/alias` - shortcuts
-- `/purge` - delete all chats
-- `/help` - commands
-
-## Skills
-
-Skills extend the AI with specialized capabilities. They follow the [Agent Skills](https://agentskills.io) open standard.
-
-### Managing Skills
+All commands support:
 
-```bash
-/skills                    # list installed
-/skills add <url>          # install from git
-/skills remove <name>      # uninstall
-/skills show <name>        # view content
-/skills create <name>      # create new
-/skills path               # show directory
 ```
-
-### Installing Skills
-
-Shorthand (like skills.sh):
-
-```bash
-/skills add vercel-labs/agent-skills/skills/react-best-practices
-/skills add anthropics/skills/skills/pdf
-/skills add owner/repo
+-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
 ```
 
-Full GitHub URL:
+### image
 
-```bash
-/skills add https://github.com/anthropics/skills/tree/main/skills/pdf
 ```
-
-Local path:
-
-```bash
-/skills add /path/to/skill
+--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
 ```
 
-### Creating Skills
+### video
 
-```bash
-/skills create my-skill
 ```
-
-Creates `~/.ai-cli/skills/my-skill/SKILL.md`
-
-## Rules
-
-Custom instructions loaded into every conversation:
-
-- `~/.ai-cli/AGENTS.md` - global rules
-- `./AGENTS.md` - project rules
-
-Manage with `/rules`:
-
-```bash
-/rules show    # view rules
-/rules edit    # open in editor
-/rules clear   # remove rules
-/rules path    # show path
+--aspect-ratio <W:H>     Aspect ratio (e.g. 16:9)
+--duration <seconds>     Duration in seconds
+--no-preview             Disable inline video frame preview
 ```
 
-## Review Loop
-
-After the coding agent finishes making file changes, a separate review agent automatically inspects all modifications for severe and high-priority bugs. If it finds issues, it fixes them and re-reviews, up to a configurable number of passes.
-
-The review agent runs in its own isolated context with a strict system prompt -- it has no attachment to the code it's reviewing and is intentionally more critical than the coding agent.
+### text
 
-Enabled by default. Toggle with:
-
-```bash
-/review on     # enable
-/review off    # disable
-/review        # show status
 ```
-
-Configure max iterations in `~/.ai-cli/config.json`:
-
-```json
-{
-  "review": {
-    "enabled": true,
-    "maxIterations": 3
-  }
-}
+-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)
 ```
 
-## Tools
-
-The AI can:
-
-**files** - read, write, edit, delete, copy, rename, search
+### models
 
-**commands** - run shell commands, background processes
-
-**memory** - save facts across sessions ("remember X")
+```
+--type <type>            Filter by type: text, image, video
+--provider <name>        Filter by provider (e.g. openai, google)
+--json                   Output as JSON (includes descriptions)
+```
 
-**web** - search, fetch urls, check weather
+All model types (text, image, video) are fetched live from the AI Gateway. If the gateway is unreachable, all model types fall back to a built-in list.
 
-## MCP
+### Multi-Model Comparison
 
-Connect to external tools via [Model Context Protocol](https://modelcontextprotocol.io):
+Generate with multiple models by comma-separating `-m`:
 
 ```bash
-/mcp                                    # list servers
-/mcp add weather http https://mcp.example.com
-/mcp add db stdio npx @example/mcp-db
-/mcp remove weather                     # remove server
-/mcp reload                             # reconnect all
+ai image "a sunset" -m "openai/gpt-image-1,xai/grok-imagine-image,bfl/flux-2-pro"
 ```
 
-### Transports
-
-- **http** - HTTP endpoint
-- **sse** - server-sent events
-- **stdio** - spawn local process
-
-### Config
-
-Servers stored in `~/.ai-cli/mcp.json`:
-
-```json
-{
-  "servers": {
-    "weather": {
-      "type": "http",
-      "url": "https://mcp.example.com"
-    },
-    "db": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["@example/mcp-db"]
-    }
-  }
-}
+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
 ```
 
-Environment variables expand with `${VAR}` or `${VAR:-default}`.
+### Inline Preview
 
-MCP tools are prefixed with server name (e.g., `weather_get_forecast`).
+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.
 
-## Models
+### Output Behavior
 
-Supports fuzzy matching:
+- **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
 
-```bash
-ai -m claude-4       # → anthropic/claude-sonnet-4
-ai -m gpt-5          # → openai/gpt-5
-ai -m sonnet         # → finds sonnet model
-```
+### Environment Variables
 
-## Storage
+| 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 |
 
-All data in `~/.ai-cli/`:
+The `-m` flag always takes priority over `AI_CLI_*_MODEL` env vars. The `-o` flag always takes priority over `AI_CLI_OUTPUT_DIR`.
 
-```
-~/.ai-cli/
-├── config.json      # settings and api key
-├── mcp.json         # mcp servers
-├── chats/           # chat history
-├── memories.json    # saved memories
-├── skills/          # installed skills
-└── AGENTS.md        # global rules
-```
-
-## Environment
-
-Alternatively set your API key:
+## License
 
-```bash
-export AI_GATEWAY_API_KEY=your-key
-```
+[Apache-2.0](LICENSE)

package/package.json

@@ -1,49 +1,48 @@
 {
   "name": "ai-cli",
-  "version": "0.0.13",
-  "main": "dist/ai.mjs",
-  "bin": {
-    "ai": "dist/ai.mjs"
+  "version": "0.1.1",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vercel-labs/ai-cli.git"
   },
-  "engines": {
-    "node": ">=18.0.0"
+  "bin": {
+    "ai": "./src/index.ts"
   },
   "files": [
-    "dist/",
+    "src",
     "README.md"
   ],
+  "keywords": [
+    "ai",
+    "cli",
+    "generative",
+    "image",
+    "video",
+    "text",
+    "ai-sdk",
+    "vercel"
+  ],
   "scripts": {
-    "build": "node build.mjs",
-    "test": "bun test tests/*.test.ts",
-    "test:coverage": "bun test --coverage tests/*.test.ts",
-    "test:e2e": "bun test tests/e2e/",
-    "test:evals": "bun test tests/evals/",
-    "test:evals:matrix": "bun run tests/evals/run-matrix.ts",
-    "lint": "biome lint .",
-    "format": "biome format . --write",
+    "dev": "bun run src/index.ts",
+    "build": "bun build src/index.ts --compile --outfile=dist/ai",
     "typecheck": "tsc --noEmit",
-    "format:check": "biome format .",
-    "check": "biome check .",
-    "prepublishOnly": "bun run build"
+    "format": "oxfmt --write src/",
+    "format:check": "oxfmt --check src/",
+    "lint": "oxlint src/",
+    "test": "bun test",
+    "prepublishOnly": "bun run typecheck"
   },
-  "type": "module",
   "dependencies": {
-    "@ai-sdk/gateway": "3.0.40",
-    "@ai-sdk/mcp": "^1.0.18",
-    "@mozilla/readability": "^0.6.0",
-    "linkedom": "^0.18.12"
+    "ai": "^6.0.173",
+    "commander": "^14.0.3"
   },
   "devDependencies": {
-    "@ai-cli/typescript-config": "workspace:*",
-    "@types/node": "^24.1.0",
-    "@xterm/headless": "^6.0.0",
-    "ai": "6.0.79",
-    "ansi-escapes": "^7.3.0",
-    "arg": "^5.0.2",
-    "esbuild": "^0.25.8",
-    "rc9": "^2.1.2",
-    "typescript": "^5.8.3",
-    "yoctocolors": "^2.1.1",
-    "zod": "^4.1.8"
+    "@types/bun": "^1.3.13",
+    "oxfmt": "^0.47.0",
+    "oxlint": "^1.62.0",
+    "typescript": "^6.0.3"
   }
 }

package/src/cli.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, test } from "bun:test";
+
+const CLI = ["bun", "run", "src/index.ts"];
+const ROOT = import.meta.dir + "/..";
+
+async function run(...args: string[]) {
+  const proc = Bun.spawn([...CLI, ...args], {
+    cwd: ROOT,
+    stdout: "pipe",
+    stderr: "pipe",
+    stdin: "ignore",
+  });
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  const exitCode = await proc.exited;
+  return { exitCode, stdout, stderr };
+}
+
+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"]) {
+      expect(stdout).toContain(sub);
+    }
+  });
+
+  test("--version exits 0 and prints semver", async () => {
+    const { exitCode, stdout } = await run("--version");
+    expect(exitCode).toBe(0);
+    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);
+    expect(stderr).toContain("prompt is required");
+  });
+
+  test("text --help exits 0 and lists flags", async () => {
+    const { exitCode, stdout } = await run("text", "--help");
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("--model");
+    expect(stdout).toContain("--format");
+    expect(stdout).toContain("--temperature");
+  });
+
+  test("image --help exits 0 and lists flags", async () => {
+    const { exitCode, stdout } = await run("image", "--help");
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("--no-preview");
+    expect(stdout).toContain("--size");
+    expect(stdout).toContain("--aspect-ratio");
+  });
+
+  test("video --help exits 0 and lists flags", async () => {
+    const { exitCode, stdout } = await run("video", "--help");
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("--duration");
+    expect(stdout).toContain("--aspect-ratio");
+  });
+
+  test("models --type invalid exits 1", async () => {
+    const { exitCode, stderr } = await run("models", "--type", "audio");
+    expect(exitCode).toBe(1);
+    expect(stderr).toContain("must be one of");
+  });
+});