# @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)