Add TUI documentation (index + getting started) (#313)

* docs: add TUI documentation index page

- Create docs/tui/ directory structure
- Add comprehensive TUI overview and index page
- Document TUI features: multi-terminal support, teams, parallel execution
- Add comparison table: TUI vs CLI use cases
- Include system requirements and supported terminals
- Document keyboard shortcuts and commands reference
- Add architecture overview and component structure
- Include quick start guide and documentation navigation

* docs: add TUI main interface screenshot

- Add cai-tui-main.png screenshot to docs/media/
- Screenshot shows TUI interface for documentation

* docs: add TUI getting started guide

- Add comprehensive getting-started.md for TUI
- Cover all 9 steps from launch to monitoring costs
- Include prerequisites and system requirements
- Document API key configuration process
- Explain model and agent selection
- Provide practical examples for first conversations
- Document multi-terminal workflows
- Explain team configurations
- Add troubleshooting section for common issues
- Include next steps and learning paths

* docs: improve security and update model information in getting-started

- Replace private IP 192.168.1.1 with documentation IP 198.51.100.50 (RFC 5737)
- Add GPT-5 model to available models table
- Add Claude 4-5 model to available models table
- Update model descriptions for clarity
- Ensure example IPs are safe for public documentation

* docs: minimum change

* docs: rename getting-started.md to getting_started.md for consistency

- Rename docs/tui/getting-started.md to getting_started.md (underscore format)
- Update all references in tui_index.md (3 occurrences)
- Maintain consistency with other markdown files naming convention

* docs: simplify TUI launch section in getting_started

- Remove alternative launch methods for cleaner first steps
- Remove 'Launch with Initial Prompt' section
- Remove 'Launch with YAML Configuration' section
- Focus on basic launch command for new users

* docs: prepare TUI docs for PR by managing broken links

- Replace broken documentation links with 🚧 indicators
- Add explanatory notes about documentation in development
- Convert inline links to plain text references
- Keep existing links (getting_started.md, cai_installation.md, cai_architecture.md)
- Maintain documentation structure for future expansion

* docs: add CAI-Pro exclusive banner to TUI documentation
This commit is contained in:
danielsanchezprieto01 2025-10-27 12:05:16 +01:00 committed by GitHub
parent 1bdc0522d7
commit 6498ade7da
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 561 additions and 0 deletions

BIN
docs/media/cai-tui-main.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 84 KiB

345
docs/tui/getting_started.md Normal file
View File

@ -0,0 +1,345 @@
# Getting Started with CAI TUI
> **⚡ CAI-Pro Exclusive Feature**
> The Terminal User Interface (TUI) is available exclusively in **CAI-Pro**. To access this feature and unlock advanced multi-agent workflows, visit [Alias Robotics](https://aliasrobotics.com) for more information.
---
This guide will walk you through launching the CAI TUI for the first time and performing your first security assessment.
## Prerequisites
Before starting, ensure you have:
- ✅ CAI installed (see [Installation Guide](../cai_installation.md))
- ✅ Python 3.9+ installed
- ✅ A valid `ALIAS_API_KEY` from [Alias Robotics](https://aliasrobotics.com)
## Step 1: Launch the TUI
Open your terminal and run:
```bash
cai --tui
```
If your `ALIAS_API_KEY` is not configured, you'll see an authentication error. Don't worry—we'll fix this in the next step.
## Step 2: Configure Your API Key
The first time you use CAI TUI, you need to configure your API key:
1. **Open the Sidebar**
- Press `Ctrl+S` to toggle the sidebar (if not already visible)
2. **Navigate to Keys Tab**
- Click on the **"Keys"** tab in the sidebar
- This shows all configured API keys
3. **Add Your API Key**
- Click the **"Add New Key"** button
- A dialog will appear with two fields:
- **Key Name**: Enter `ALIAS_API_KEY`
- **Key Value**: Enter your API key (e.g., `ak_live_1234567890abcdef`)
4. **Save the Key**
- Click the **"Save"** button
- Your key is now securely stored in `~/.cai/.env`
### Alternative: Using Environment Variables
You can also set your API key via environment variable:
```bash
export ALIAS_API_KEY="your_api_key_here"
cai --tui
```
Or create a `.env` file in your project directory:
```env
ALIAS_API_KEY=your_api_key_here
```
## Step 3: Select Your Model
CAI supports multiple AI models. For optimal performance and cost balance, we recommend `alias1`:
### Option 1: Using the Dropdown (Recommended)
1. Look at the terminal header (top bar of each terminal)
2. Find the **"model"** dropdown (center-right area)
3. Click on it to see available models
4. Select **`alias1`**
### Option 2: Using a Command
Type in the input field at the bottom:
```
/model alias1
```
Press **Enter**.
### Available Models
| Model | Provider | Best For | Cost |
|-------|----------|----------|------|
| `alias1` | Alias Robotics | **Recommended** - Balanced performance | Medium |
| `gpt-5` | OpenAI | Latest reasoning and code generation | Very High |
| `gpt-4o` | OpenAI | Complex reasoning and multi-modal | High |
| `claude-4-5` | Anthropic | Advanced reasoning and long contexts | Very High |
| `claude-3-5-sonnet-20241022` | Anthropic | Fast responses with good quality | High |
> **💡 Tip**: You can change models at any time without losing your conversation history.
## Step 4: Choose Your Agent
CAI comes with specialized agents for different security tasks. Here's how to choose:
### Option 1: Use the Agent Recommendation System
The easiest way to start:
1. Click the **agent** dropdown in the terminal header
2. Select **`selection_agent`**
3. Type your task description: `"I need to test a web application for SQL injection"`
4. The agent will recommend the best agent for your task
Alternatively, use the command:
```
/agent selection_agent
```
Then describe your task.
### Option 2: Choose Directly from the Dropdown
If you know which agent you need:
1. Click the **agent** dropdown
2. Browse available agents (scroll if needed)
3. Select your desired agent (e.g., `redteam_agent`, `bug_bounter_agent`)
### Option 3: List All Agents
To see all available agents with descriptions:
```
/agent list
```
### Common Agent Types
| Agent | Purpose | When to Use |
|-------|---------|-------------|
| `redteam_agent` | Offensive security testing | Default for penetration testing |
| `blueteam_agent` | Defensive security analysis | Security posture assessment |
| `bug_bounter_agent` | Bug bounty hunting | Finding high-value vulnerabilities |
| `retester_agent` | Vulnerability retesting | Confirming fixes |
| `selection_agent` | Agent recommendation | **When unsure which agent to use** |
> **💡 Pro Tip**: Start with `selection_agent` if you're new to CAI—it will guide you to the right agent for your task.
## Step 5: Start Your First Conversation
Now you're ready to interact with CAI!
### Example 1: Basic Reconnaissance
In the input field at the bottom (marked with `CAI>`), type:
```
Scan 198.51.100.50 for open ports and services
```
Press **Enter**.
The agent will:
- Process your request
- Use appropriate tools (nmap, etc.)
- Display results in the terminal output area
### Example 2: Web Application Testing
Prompt example:
```
Test https://example.com for common web vulnerabilities
```
Press **Enter**.
The agent will:
- Process your request
- Use appropriate tools (nmap, etc.)
- Display results in the terminal output area
### Example 3: Network Analysis
Prompt example:
```
Analyze the network traffic from this pcap file: capture.pcap
```
### Understanding the Output
As the agent works, you'll see:
1. **Tool Execution**: Messages showing which tools are being launched
2. **Streaming Output**: Real-time results from tools
3. **Agent Reasoning**: The agent's thought process (if `CAI_DEBUG=1`)
4. **Final Response**: Summary and recommendations
### Queuing Prompts
If the agent is busy, you can send another prompt—it will be **automatically queued**:
- View the queue: Press `Ctrl+Shift+Q` or use `/queue`
- The next prompt will execute when the current one finishes
## Step 6: Working with Multiple Terminals
One of the TUI's most powerful features is multi-terminal support.
### Adding a New Terminal
Click the **"Add +"** button in the top of the screen
Each new terminal:
- Starts with `alias1` model and `redteam_agent`
- Has an independent conversation history
- Can run a different agent and model
### Navigating Between Terminals
- **Next terminal**: `Ctrl+N`
- **Previous terminal**: `Ctrl+B`
- **Click directly** on any terminal to focus it
### Example Workflow: Dual-Perspective Analysis
1. **Terminal 1**: Keep `redteam_agent` for offensive testing
2. **Terminal 2**: Add a new terminal, switch to `blueteam_agent`
3. Send the same target to both:
- T1: Offensive analysis
- T2: Defensive recommendations
4. Compare results side-by-side
## Step 7: Using Preconfigured Teams
For common multi-agent workflows, use **Teams**:
1. Open the sidebar (`Ctrl+S`)
2. Click the **"Teams"** tab
3. Select a team (e.g., **"#1: 2 red + 2 bug"**)
This will:
- Automatically open 4 terminals (or reuse existing ones)
- Assign agents according to the team configuration
- Ready to process your prompt in parallel
**Popular Teams**:
- **2 Red + 2 Bug**: Comprehensive penetration testing + bug hunting
- **2 Red + 2 Blue**: Offensive + defensive analysis
- **Red + Blue + Retester + Bug**: Full security assessment lifecycle
Learn more about Teams and Parallel Execution in the full TUI documentation.
## Step 8: Saving Your Work
To save your conversation for later:
```
/save my-assessment.json
```
Or in Markdown format:
```
/save my-assessment.md
```
Files are saved in your current working directory.
### Loading a Saved Session
```
/load my-assessment.json
```
This restores the conversation history for the current terminal.
## Step 9: Monitoring Costs
CAI tracks your API usage and costs in real-time.
### View Costs for Current Agent
```
/cost
```
This shows:
- Total tokens used (input + output)
- Estimated cost in USD
- Breakdown by interaction
### Check Stats in Sidebar
Open the sidebar (`Ctrl+S`) and go to **"Stats"** tab to see:
- Session duration
- Total agents used
- Total cost across all terminals
## Common First-Time Issues
### Issue: Agent is not responding
**Solution**:
- Press `Ctrl+C` to cancel the current agent
- Check your internet connection
- Verify your API key is valid
### Issue: Terminal output is cluttered
**Solution**:
- Clear the terminal: `Ctrl+L` or `/clear`
- Reduce debug output: Set `CAI_DEBUG=0` before launching
- Use `/flush` to clear conversation history
### Issue: I can't see the full interface
**Solution**:
- Resize your terminal window to at least 120x40 characters
- Try full-screen mode: `F11` (on most terminals)
- Zoom out: `Ctrl+-` (on most terminals)
## Next Steps
Congratulations! You've completed the basics of CAI TUI. Here's what to explore next:
> **Note**: Additional TUI documentation is currently being developed. Topics marked with 🚧 will be available soon.
### Learn More Commands
- 📖 Commands Reference 🚧 - Master all available commands
- ⌨️ Keyboard Shortcuts 🚧 - Speed up your workflow
### Explore Advanced Features
- 👥 Teams and Parallel Execution 🚧 - Multi-agent workflows
- 🔧 MCP Integration 🚧 - Connect external tools
- 💾 Session Management 🚧 - Advanced save/load
### Customize Your Setup
- ⚙️ Configuration 🚧 - Environment variables and settings
### Get Help
- ❓ FAQ 🚧 - Common questions
- 🔧 Troubleshooting 🚧 - Solve issues
- 💬 [Community Discord](https://discord.gg/aliasrobotics) - Ask questions

216
docs/tui/tui_index.md Normal file
View File

@ -0,0 +1,216 @@
# CAI Terminal User Interface (TUI)
> **⚡ CAI-Pro Exclusive Feature**
> The Terminal User Interface (TUI) is available exclusively in **CAI-Pro**. To access this feature and unlock advanced multi-agent workflows, visit [Alias Robotics](https://aliasrobotics.com) for more information.
---
The CAI TUI provides a modern, terminal-based interface for interacting with CAI agents, enabling powerful multi-agent workflows, parallel execution, and advanced security testing capabilities.
![CAI TUI Interface](../media/cai-tui-main.png)
## Overview
The TUI is built on [Textual](https://textual.textualize.io/), offering:
- **🖥️ Multi-Terminal Support**: Work with up to 4 agents simultaneously in split-screen layouts
- **👥 Preconfigured Teams**: One-click deployment of specialized agent teams for security assessments
- **⚡ Parallel Execution**: Execute multiple agents in parallel with independent conversations
- **📊 Real-Time Stats**: Monitor costs, tokens, and agent performance
- **🎯 Smart Agent Selection**: Built-in agent recommendation system
- **🔧 MCP Integration**: Connect to external tools via Model Context Protocol
- **💾 Session Management**: Save and restore conversations across sessions
## When to Use the TUI vs CLI
| Feature | TUI | CLI |
|---------|-----|-----|
| **Visual feedback** | ✅ Rich UI with colors and layouts | ⚠️ Basic text output |
| **Multi-agent workflows** | ✅ Visual split-screen | ❌ Sequential only |
| **Agent teams** | ✅ One-click preconfigured teams | ❌ Manual setup |
| **Real-time monitoring** | ✅ Stats sidebar | ⚠️ Limited |
| **Session management** | ✅ Visual queue and history | ⚠️ Command-based |
| **Scripting/Automation** | ❌ Interactive only | ✅ Full scripting support |
| **Resource usage** | ⚠️ Higher (UI overhead) | ✅ Minimal |
**Use TUI for**: Interactive security testing, bug bounty hunting, team-based analysis, exploratory testing
**Use CLI for**: Automation, scripting, CI/CD integration, headless environments
## Quick Start
Launch the TUI:
```bash
cai --tui
```
Basic workflow:
1. Configure your `ALIAS_API_KEY` in **Sidebar → Keys**
2. Select a model (recommended: `alias1`) from the terminal header dropdown
3. Choose an agent or use `selection_agent` for recommendations
4. Type your prompt and press **Enter**
See the [Getting Started Guide](getting_started.md) for detailed instructions.
## System Requirements
- **Python**: 3.9 or higher
- **Terminal**: Modern terminal with 256+ color support
- **Minimum window size**: 120x40 characters (recommended)
- **API Key**: Valid `ALIAS_API_KEY` (get one from [Alias Robotics](https://aliasrobotics.com))
### Supported Terminals
- ✅ iTerm2 (macOS)
- ✅ Terminal.app (macOS)
- ✅ GNOME Terminal (Linux)
- ✅ Konsole (Linux)
- ✅ Windows Terminal (Windows)
- ✅ Alacritty (all platforms)
- ⚠️ tmux/screen (limited color support)
## Key Features
### 🖥️ Multiple Terminals
Work with multiple agents simultaneously in responsive layouts:
- **1 terminal**: Full-screen mode
- **2 terminals**: Horizontal split
- **3 terminals**: 2+1 grid layout
- **4+ terminals**: 2x2 grid with scroll
Each terminal maintains its own:
- Independent agent and model selection
- Isolated conversation history
- Separate execution context
Learn more about terminal management in the full TUI documentation.
### 👥 Preconfigured Teams
Access specialized agent teams from the sidebar:
- **Team: 2 Red + 2 Bug**: Offensive testing + bug hunting
- **Team: 2 Red + 2 Blue**: Dual-perspective security analysis
- **Team: Red + Blue + Retester + Bug**: Comprehensive assessment workflow
Learn more about Teams and Parallel Execution in the full TUI documentation.
### 🎯 Smart Agent Selection
Use the `selection_agent` to get intelligent agent recommendations based on your task:
```
/agent selection_agent
```
Or simply select it from the agent dropdown.
Learn more about commands in the full TUI documentation.
### 📊 Sidebar Features
The collapsible sidebar (`Ctrl+S`) provides:
- **Teams**: One-click team deployment
- **Queue**: Visual prompt queue management
- **Stats**: Real-time session statistics and costs
- **Keys**: Manage API keys for multiple providers
Learn more about sidebar features in the full TUI documentation.
## Documentation Structure
> **Note**: TUI documentation is being actively developed. Topics marked with 🚧 are coming soon.
### For New Users
1. [Getting Started](getting_started.md) ✅ - First steps and basic usage
2. User Interface 🚧 - Understanding the layout
3. Keyboard Shortcuts 🚧 - Essential shortcuts
### For Regular Users
4. Commands Reference 🚧 - Complete command list
5. Terminals Management 🚧 - Working with multiple terminals
6. Sidebar Features 🚧 - Sidebar tabs and capabilities
### For Advanced Users
7. Teams and Parallel Execution 🚧 - Multi-agent workflows
8. Configuration 🚧 - Environment variables and settings
9. Advanced Features 🚧 - MCP, Meta Agent, and more
### Support Resources
10. Troubleshooting 🚧 - Common issues and solutions
11. FAQ 🚧 - Frequently asked questions
## Quick Reference
### Essential Keyboard Shortcuts
| Shortcut | Action |
|----------|--------|
| `Ctrl+S` | Toggle sidebar |
| `Ctrl+L` | Clear all terminals |
| `Ctrl+Q` | Exit CAI |
| `Ctrl+N` / `Ctrl+B` | Navigate terminals |
| `Ctrl+C` | Cancel current agent |
| `ESC` | Cancel all agents |
See complete keyboard shortcuts reference in the full TUI documentation (coming soon).
### Most Used Commands
| Command | Description |
|---------|-------------|
| `/help` | Show help |
| `/agent list` | List all agents |
| `/agent <name>` | Switch agent |
| `/model <name>` | Change model |
| `/queue` | Show prompt queue |
| `/cost` | Show costs and tokens |
| `/save <file>` | Save conversation |
| `/load <file>` | Load conversation |
See complete commands reference in the full TUI documentation (coming soon).
## Architecture
```
CAI TUI
├── Core Components
│ ├── SessionManager - Coordinates all terminals
│ ├── TerminalRunner - Manages agent execution per terminal
│ └── AgentExecutor - Handles parallel execution
├── UI Components
│ ├── UniversalTerminal - Individual terminal widget
│ ├── StableTerminalGrid - Layout manager
│ ├── Sidebar - Navigation and features
│ └── InfoStatusBar - Real-time status display
└── Display System
├── DisplayManager - Output routing
├── StreamingDisplay - Real-time streaming
└── AgentDisplay - Agent message formatting
```
For technical details, see the [Architecture Overview](../cai_architecture.md).
## Community and Support
- **Documentation**: [https://docs.aliasrobotics.com](https://docs.aliasrobotics.com)
- **GitHub Issues**: [https://github.com/aliasrobotics/cai/issues](https://github.com/aliasrobotics/cai/issues)
- **Discord**: [Join our community](https://discord.gg/aliasrobotics)
- **Twitter**: [@aliasrobotics](https://twitter.com/aliasrobotics)
## What's Next?
- 📖 [Getting Started Guide](getting_started.md) ✅ - Learn the basics
- ⌨️ Keyboard Shortcuts 🚧 - Boost your productivity
- 🎯 Commands Reference 🚧 - Master the commands
- 👥 Teams and Parallel Execution 🚧 - Advanced workflows
---
*Last updated: October 2025 | CAI TUI v0.6+*