ai-cli 0.0.1 → 0.0.3

package/README.md

@@ -1,44 +1,223 @@
 # ai-cli
 
-AI CLI using OpenAI's open source model.
+minimal terminal AI assistant
 
-## Installation
+## install
 
 ```bash
 npm install -g ai-cli
 ```
 
-## Setup
+## setup
 
-Set your AI Gateway API key in your shell configuration:
+```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)
+
+## 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
+
+# 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
+- `/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.
+
+### managing skills
+
+```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
+```
+
+full github url:
+
+```bash
+/skills add https://github.com/anthropics/skills/tree/main/skills/pdf
+```
+
+local path:
+
+```bash
+/skills add /path/to/skill
+```
+
+### creating skills
+
+```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
+```
+
+## 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](https://modelcontextprotocol.io):
 
 ```bash
-# Add to ~/.zshrc or ~/.bashrc
-export AI_GATEWAY_API_KEY=your-api-key
+/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
 ```
 
-Get your API key at https://vercel.com/docs/ai-gateway
+### transports
 
-## Usage
+- **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"]
+    }
+  }
+}
+```
+
+environment variables expand with `${VAR}` or `${VAR:-default}`.
+
+mcp tools are prefixed with server name (e.g., `weather_get_forecast`).
+
+## models
+
+supports fuzzy matching:
 
 ```bash
-ai "whats up bro"
-ai hello
-echo "explain this code" | ai
-ai -m openai/gpt-oss-120b "who is rauchg"
+ai -m claude-4       # → anthropic/claude-sonnet-4
+ai -m gpt-5          # → openai/gpt-5
+ai -m sonnet         # → finds sonnet model
 ```
 
-## Options
+## storage
 
-- `-m, --model` - Specify AI model (default: openai/gpt-oss-120b)
-- `-h, --help` - Show help message
+all data in `~/.ai-cli/`:
 
-## Switching Models
+```
+~/.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
+```
 
-You can use any model available through Vercel AI Gateway by using the `-m` flag:
+## environment
+
+alternatively set your API key:
 
 ```bash
-ai -m claude-4-sonnet "who am i"
-ai -m openai/gpt-4o "count to 3"
-ai -m anthropic/claude-4.1-opus "spend my money"
-```
+export AI_GATEWAY_API_KEY=your-key
+```