321 lines
6.6 KiB
Markdown
321 lines
6.6 KiB
Markdown
# @ai-assistant/cli
|
|
|
|
Command-line interface for AI Terminal Assistant - interact with AI directly from your terminal.
|
|
|
|
## 📦 Installation
|
|
|
|
```bash
|
|
# Global installation
|
|
pnpm add -g @ai-assistant/cli
|
|
|
|
# Or run directly with npx/bunx
|
|
npx @ai-assistant/cli
|
|
bunx @ai-assistant/cli
|
|
```
|
|
|
|
## 🌟 Features
|
|
|
|
- **Dual Modes** - Server mode and client attach mode
|
|
- **Interactive Chat** - Rich terminal UI with syntax highlighting
|
|
- **Streaming Responses** - Real-time AI responses
|
|
- **File Attachments** - Attach files to messages
|
|
- **Command History** - Navigate through previous commands
|
|
- **Auto-completion** - Tab completion for commands
|
|
- **Colored Output** - Beautiful terminal formatting
|
|
- **Session Management** - Persistent conversation history
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Server Mode
|
|
|
|
Start a local AI server:
|
|
|
|
```bash
|
|
# Start server on default port 3000
|
|
ai-assist serve
|
|
|
|
# Start on custom port
|
|
ai-assist serve --port 8080
|
|
|
|
# With specific model
|
|
ai-assist serve --model claude-haiku-3-20251120
|
|
|
|
# With verbose logging
|
|
ai-assist serve --verbose
|
|
```
|
|
|
|
### Client Mode
|
|
|
|
Attach to a running AI server:
|
|
|
|
```bash
|
|
# Attach to local server
|
|
ai-assist attach
|
|
|
|
# Attach to remote server
|
|
ai-assist attach https://ai-server.example.com
|
|
|
|
# Attach with authentication
|
|
ai-assist attach https://ai-server.example.com --token YOUR_TOKEN
|
|
|
|
# Attach to specific session
|
|
ai-assist attach --session my-session-id
|
|
```
|
|
|
|
## 📚 Commands
|
|
|
|
### Global Options
|
|
|
|
```bash
|
|
ai-assist [command] [options]
|
|
|
|
Options:
|
|
-h, --help Show help
|
|
-v, --version Show version
|
|
--config <path> Path to config file
|
|
--verbose Enable verbose logging
|
|
```
|
|
|
|
### Server Command
|
|
|
|
```bash
|
|
ai-assist serve [options]
|
|
|
|
Options:
|
|
-p, --port <port> Server port (default: 3000)
|
|
-h, --host <host> Server host (default: localhost)
|
|
--api-key <key> Anthropic API key (or use ANTHROPIC_API_KEY env)
|
|
--model <model> AI model to use
|
|
--max-tokens <n> Maximum response tokens
|
|
--no-auth Disable authentication
|
|
--cors-origin <origin> CORS allowed origins
|
|
```
|
|
|
|
### Attach Command
|
|
|
|
```bash
|
|
ai-assist attach [server-url] [options]
|
|
|
|
Arguments:
|
|
server-url Server URL (default: http://localhost:3000)
|
|
|
|
Options:
|
|
-s, --session <id> Session ID to attach to
|
|
-t, --token <token> Authentication token
|
|
--no-history Don't load session history
|
|
--stream Enable streaming mode
|
|
```
|
|
|
|
## ⌨️ Interactive Commands
|
|
|
|
Once connected, use these commands in the chat interface:
|
|
|
|
```
|
|
/help Show available commands
|
|
/clear Clear the screen
|
|
/history Show message history
|
|
/attach <file> Attach a file to the next message
|
|
/model <name> Switch AI model
|
|
/session new Start a new session
|
|
/session list List available sessions
|
|
/session switch <id> Switch to another session
|
|
/export <file> Export conversation to file
|
|
/quit Exit the CLI
|
|
```
|
|
|
|
## 🎨 Terminal UI Features
|
|
|
|
### Message Display
|
|
- **User messages** - Displayed with `>` prefix in cyan
|
|
- **AI responses** - Formatted with syntax highlighting
|
|
- **Code blocks** - Highlighted based on language
|
|
- **Markdown** - Rendered with terminal formatting
|
|
- **Progress indicators** - Animated spinners during processing
|
|
|
|
### Keyboard Shortcuts
|
|
- `↑/↓` - Navigate message history
|
|
- `Tab` - Auto-complete commands
|
|
- `Ctrl+C` - Cancel current operation
|
|
- `Ctrl+D` - Exit (same as /quit)
|
|
- `Ctrl+L` - Clear screen (same as /clear)
|
|
- `PgUp/PgDn` - Scroll through long responses
|
|
|
|
## 🔧 Configuration
|
|
|
|
### Configuration File
|
|
|
|
Create `~/.ai-assistant/config.json`:
|
|
|
|
```json
|
|
{
|
|
"defaultServer": "http://localhost:3000",
|
|
"apiKey": "sk-ant-xxxxx",
|
|
"model": "claude-sonnet-4-20250514",
|
|
"theme": "dark",
|
|
"editor": "vim",
|
|
"history": {
|
|
"enabled": true,
|
|
"maxSize": 1000
|
|
},
|
|
"display": {
|
|
"showTimestamps": true,
|
|
"syntax_highlighting": true,
|
|
"word_wrap": true,
|
|
"max_width": 120
|
|
}
|
|
}
|
|
```
|
|
|
|
### Environment Variables
|
|
|
|
```bash
|
|
# API Configuration
|
|
export ANTHROPIC_API_KEY=sk-ant-xxxxx
|
|
export AI_MODEL=claude-sonnet-4-20250514
|
|
|
|
# CLI Configuration
|
|
export AI_CLI_SERVER=http://localhost:3000
|
|
export AI_CLI_SESSION=my-session
|
|
export AI_CLI_TOKEN=auth-token
|
|
|
|
# Display Configuration
|
|
export AI_CLI_COLOR=true
|
|
export AI_CLI_EDITOR=vim
|
|
```
|
|
|
|
## 🔌 Scripting and Automation
|
|
|
|
### Pipe Input
|
|
|
|
```bash
|
|
# Send a single message
|
|
echo "What is TypeScript?" | ai-assist attach
|
|
|
|
# Process a file
|
|
cat code.ts | ai-assist attach --message "Review this code"
|
|
|
|
# Chain with other commands
|
|
git diff | ai-assist attach --message "Explain these changes"
|
|
```
|
|
|
|
### Script Mode
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
|
|
# Create a script for batch processing
|
|
ai-assist attach <<EOF
|
|
/session new
|
|
Analyze the following log file
|
|
/attach /var/log/application.log
|
|
What are the main errors?
|
|
/export analysis.md
|
|
/quit
|
|
EOF
|
|
```
|
|
|
|
### JSON Output
|
|
|
|
```bash
|
|
# Get JSON response for parsing
|
|
ai-assist attach --json --message "List TypeScript features" | jq '.response.content'
|
|
```
|
|
|
|
## 🧪 Testing
|
|
|
|
```bash
|
|
# Run tests
|
|
pnpm test
|
|
|
|
# Run with coverage
|
|
pnpm test:coverage
|
|
|
|
# Run specific test suite
|
|
pnpm test -- cli.test.ts
|
|
```
|
|
|
|
## 🚀 Advanced Usage
|
|
|
|
### Custom Tools
|
|
|
|
Register custom tools in your config:
|
|
|
|
```json
|
|
{
|
|
"tools": [
|
|
{
|
|
"name": "deploy",
|
|
"command": "kubectl apply -f",
|
|
"description": "Deploy to Kubernetes"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Plugins
|
|
|
|
Install and use CLI plugins:
|
|
|
|
```bash
|
|
# Install a plugin
|
|
ai-assist plugin install @ai-assistant/plugin-git
|
|
|
|
# List plugins
|
|
ai-assist plugin list
|
|
|
|
# Use plugin command
|
|
ai-assist git analyze
|
|
```
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
### Connection Issues
|
|
|
|
```bash
|
|
# Test server connection
|
|
ai-assist test-connection http://localhost:3000
|
|
|
|
# Check server status
|
|
curl http://localhost:3000/api/health
|
|
```
|
|
|
|
### Debug Mode
|
|
|
|
```bash
|
|
# Enable debug logging
|
|
DEBUG=* ai-assist attach
|
|
|
|
# Save debug log
|
|
ai-assist attach --debug 2> debug.log
|
|
```
|
|
|
|
### Common Issues
|
|
|
|
1. **"Cannot connect to server"**
|
|
- Check if server is running
|
|
- Verify server URL and port
|
|
- Check firewall settings
|
|
|
|
2. **"Authentication failed"**
|
|
- Verify API key is set
|
|
- Check token expiration
|
|
- Ensure server auth is configured
|
|
|
|
3. **"Session not found"**
|
|
- Session may have expired
|
|
- Use `/session list` to see available sessions
|
|
- Create new session with `/session new`
|
|
|
|
## 🤝 Contributing
|
|
|
|
Contributions are welcome! See the main repository's contributing guide.
|
|
|
|
## 📄 License
|
|
|
|
MIT License - see [LICENSE](../../LICENSE) for details.
|
|
|
|
## 🔗 Links
|
|
|
|
- [Main Repository](https://github.com/username/ai-terminal-assistant)
|
|
- [Documentation](https://docs.example.com/cli)
|
|
- [Issue Tracker](https://github.com/username/ai-terminal-assistant/issues) |