ai-cli

minimal terminal AI assistant

install

npm install -g ai-cli

setup

ai init

get your API key from Vercel AI Gateway

usage

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

# in interactive mode, ctrl+v to paste image from clipboard

options

• -m, --model - model (default: anthropic/claude-sonnet-4.5)
• --image - attach image file
• -l, --list - list models
• -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

git

• /git status - file status
• /git diff - unstaged changes
• /git staged - staged changes
• /git branch - list/switch branches
• /git commit - ai-generated commit message
• /git push - push to remote
• /git log - recent commits
• /git stash - stash/pop changes

context

• /usage - token usage and cost
• /compress - compress history

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
• /alias - shortcuts
• /purge - delete all chats
• /help - commands

skills

skills extend the AI with specialized capabilities. they follow the Agent Skills open standard.

managing skills

/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):

/skills add vercel-labs/agent-skills/skills/react-best-practices
/skills add anthropics/skills/skills/pdf
/skills add owner/repo

full github url:

/skills add https://github.com/anthropics/skills/tree/main/skills/pdf

local path:

/skills add /path/to/skill

creating skills

/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:

/rules show    # view rules
/rules edit    # open in editor
/rules clear   # remove rules
/rules path    # show path

tools

the AI can:

files - read, write, edit, delete, copy, rename, search

commands - run shell commands, background processes

memory - save facts across sessions ("remember X")

web - search, fetch urls, check weather

mcp

connect to external tools via model context protocol:

/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

transports

• http - HTTP endpoint
• sse - server-sent events
• stdio - spawn local process

config

servers stored in ~/.ai-cli/mcp.json:

{
  "servers": {
    "weather": {
      "type": "http",
      "url": "https://mcp.example.com"
    },
    "db": {
      "type": "stdio",
      "command": "npx",
      "args": ["@example/mcp-db"]
    }
  }
}

environment variables expand with ${VAR} or ${VAR:-default}.

mcp tools are prefixed with server name (e.g., weather_get_forecast).

models

supports fuzzy matching:

ai -m claude-4       # → anthropic/claude-sonnet-4
ai -m gpt-5          # → openai/gpt-5
ai -m sonnet         # → finds sonnet model

storage

all data in ~/.ai-cli/:

~/.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:

export AI_GATEWAY_API_KEY=your-key