ai-cli 0.0.2-beta.0 → 0.0.3

package/README.md

@@ -1,145 +1,223 @@
 # ai-cli
 
-AI CLI using Vercel AI Gateway
+minimal terminal AI assistant
 
-## Installation
+## install
 
 ```bash
 npm install -g ai-cli
 ```
 
-## Setup
+## 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)
+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)
 
-## Usage
+## usage
 
 ```bash
 ai                           # interactive mode
 ai "hello"                   # single message
 ai -m gpt-5 "hello"          # use specific model
-ai --image ./img.png "what?" # analyze image
-ai -l                        # list available models
+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
+## options
 
 - `-m, --model` - model (default: anthropic/claude-sonnet-4.5)
-- `--image` - attach image file (png, jpg, gif, webp)
-- `-l, --list` - list available models
+- `--image` - attach image file
+- `-l, --list` - list models
 - `-h, --help` - help
 
-## Interactive Mode
+## 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
+- `/list` - select model
+- `/model` - current model
+
+### system
+- `/processes` - background processes
+- `/memory` - saved memories
+- `/mcp` - mcp servers
+- `/settings` - preferences
+- `/alias` - shortcuts
+- `/help` - commands
+
+## skills
+
+skills extend the AI with specialized capabilities. they follow the [Agent Skills](https://agentskills.io) open standard.
 
-Type `ai` to enter interactive mode with file access and chat history.
+### managing skills
 
-### Commands
+```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
+```
 
-**Chat**
-- `/new` - start new chat
-- `/chats` - list saved chats
-- `/chat <n>` - load chat by number
-- `/delete` - delete current chat
-- `/purge` - delete all chats
-- `/clear` - clear screen and history
+### installing skills
 
-**Files**
-- `/copy` - copy last response to clipboard
-- `/rollback` - view/undo file changes
-- `/diff` - view recent file changes
+shorthand (like skills.sh):
 
-**Context**
-- `/context` - show token usage and loaded context files
-- `/compress` - compress chat history
-- `/usage` - show chat stats and cost
+```bash
+/skills add vercel-labs/agent-skills/skills/react-best-practices
+/skills add anthropics/skills/skills/pdf
+/skills add owner/repo
+```
 
-**Models**
-- `/list` - select model (with search)
-- `/model` - show current model
+full github url:
 
-**Processes**
-- `/processes` - manage background processes
+```bash
+/skills add https://github.com/anthropics/skills/tree/main/skills/pdf
+```
 
-**Memory**
-- `/memory` - view saved memories
-- `/memory clear` - clear all memories
+local path:
 
-**Settings**
-- `/alias` - manage command shortcuts
-- `/settings` - configure preferences
-- `/init` - setup api key
-- `/credits` - show balance
-- `/storage` - show storage info
-- `/version` - show version
-- `/help` - show commands
+```bash
+/skills add /path/to/skill
+```
 
-**Exit**
-- `exit` or `quit`
+### creating skills
 
-## Context Files
+```bash
+/skills create my-skill
+```
 
-The CLI automatically loads context files into the AI's system prompt:
+creates `~/.ai-cli/skills/my-skill/SKILL.md`
 
-- `CLAUDE.md` - project instructions
-- `CLAUDE.local.md` - local instructions (not committed)
-- `AGENTS.md` - agent-specific instructions
-- `.cursorrules` - cursor rules
-- `.cursor/rules/*.md` - cursor rule files (supports globs and alwaysApply)
-- `~/CLAUDE.md` - global instructions
+## rules
 
-Use `/context` to see which files are loaded.
+custom instructions loaded into every conversation:
 
-## Aliases
+- `~/.ai-cli/AGENTS.md` - global rules
+- `./AGENTS.md` - project rules
 
-Create custom command shortcuts:
+manage with `/rules`:
 
 ```bash
-/alias h help      # /h → /help
-/alias c copy      # /c → /copy
-/alias m model     # /m → /model
-/alias -d h        # remove alias
-/alias             # list all aliases
+/rules show    # view rules
+/rules edit    # open in editor
+/rules clear   # remove rules
+/rules path    # show path
 ```
 
-Aliases are stored in `~/.airc` and shown in `/help`.
+## 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")
 
-## Tools
+**web** - search, fetch urls, check weather
 
-The AI can interact with your system:
+## mcp
+
+connect to external tools via [model context protocol](https://modelcontextprotocol.io):
+
+```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
+```
 
-**Files**
-- read/write/edit files
-- create folders
-- rename/move/copy/delete files
-- search in files
-- find files by pattern
+### 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"]
+    }
+  }
+}
+```
 
-**Commands**
-- run shell commands (build, test, install)
-- start background processes (dev servers)
-- manage running processes
+environment variables expand with `${VAR}` or `${VAR:-default}`.
 
-**Memory**
-- say "remember X" to save facts across sessions
-- ask "what do you remember" to recall
+mcp tools are prefixed with server name (e.g., `weather_get_forecast`).
 
-## Switching Models
+## models
 
-Supports fuzzy matching:
+supports fuzzy matching:
 
 ```bash
 ai -m claude-4       # → anthropic/claude-sonnet-4
 ai -m gpt-5          # → openai/gpt-5
-ai -m sonnet         # → finds a sonnet model
+ai -m sonnet         # → finds sonnet model
 ```
 
-## Storage
+## 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
+```
 
-- Config: `~/.airc`
-- Chats: `~/.ai-chats/`
-- Memories: `~/.ai-memories`
+## environment
+
+alternatively set your API key:
+
+```bash
+export AI_GATEWAY_API_KEY=your-key
+```