ai-terminal-assistant/packages/cli/README.md

@ai-assistant/cli

Command-line interface for AI Terminal Assistant - interact with AI directly from your terminal.

📦 Installation

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

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

# 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

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

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

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:

{
  "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

# 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

# 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

#!/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

# Get JSON response for parsing
ai-assist attach --json --message "List TypeScript features" | jq '.response.content'

🧪 Testing

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

{
  "tools": [
    {
      "name": "deploy",
      "command": "kubectl apply -f",
      "description": "Deploy to Kubernetes"
    }
  ]
}

Plugins

Install and use CLI plugins:

# 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

# Test server connection
ai-assist test-connection http://localhost:3000

# Check server status
curl http://localhost:3000/api/health

Debug Mode

# 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 for details.

🔗 Links

• Main Repository
• Documentation
• Issue Tracker