diff --git a/README.md b/README.md index aadad9ea..6803a0cf 100644 --- a/README.md +++ b/README.md @@ -1122,41 +1122,21 @@ Use ```/agent``` to list all the agents available.
- Where can I list all the environment variables? /config + Where can I list all the environment variables? /env ![cai-008-config](imgs/readme_imgs/cai-008-config.png)
- How can I monitor context usage and token consumption? /context or /ctx ๐Ÿš€ CAI PRO + How can I monitor token usage and costs? -> **โšก CAI PRO Exclusive Feature** -> The `/context` command is available exclusively in **[CAI PRO](https://aliasrobotics.com/cybersecurityai.php)**. To access this feature and unlock advanced monitoring capabilities, visit [Alias Robotics](https://aliasrobotics.com/cybersecurityai.php) for more information. - -Use ```/context``` (or the short form ```/ctx```) to view your current context window usage and token statistics. - -This command displays: -- Total context usage (used tokens / max tokens) with percentage -- Visual grid representation with the CAI logo showing filled context -- Detailed breakdown by category: - - System prompt tokens - - Tool definitions tokens - - Memory/RAG tokens - - User prompts tokens - - Assistant responses tokens - - Tool calls tokens - - Tool results tokens -- Free space available - -**Why this matters**: Different models have different context limits (e.g., GPT-4: 128k tokens, Claude: 200k tokens). Monitoring your context usage helps you avoid hitting these limits during long conversations, which could cause errors or require conversation truncation. +Use **`/cost`** in the REPL for session spend and token statistics, **`/compact`** when conversations grow long, and (in **TUI** mode) the per-terminal cost and model indicators in the UI. ```bash -# Show context usage -/context - -# Or use the short form -/ctx +CAI> /cost ``` + +See the [CLI commands reference](docs/cli/commands_reference.md) for the full command list.
diff --git a/docs/api.md b/docs/api.md index b39631ea..6f252e5a 100644 --- a/docs/api.md +++ b/docs/api.md @@ -10,7 +10,7 @@ cai --api --api-host 0.0.0.0 --api-port 8080 # the next free port and prints it in the console. ``` -CLI flags and environment variables: +CLI flags and environment variables (API subset): | Flag | Env | Description | | --- | --- | --- | @@ -20,6 +20,8 @@ CLI flags and environment variables: | `--api-reload` | `CAI_API_RELOAD` | Dev autoreload. | | `--api-workers` | `CAI_API_WORKERS` | Worker processes (ignored with reload). | +For **all** `cai` binary flags (`--tui`, `--resume`, `--yaml`, `--version`, โ€ฆ), see the single source of truth: [CLI commands reference โ€” Binary `cai` CLI flags](cli/commands_reference.md#binary-cai-cli-flags). + Interactive docs at `/api/docs` and OpenAPI spec at `/api/openapi.json`. ### Authentication diff --git a/docs/cai/getting-started/commands.md b/docs/cai/getting-started/commands.md index 7f177ec5..cd5b350d 100644 --- a/docs/cai/getting-started/commands.md +++ b/docs/cai/getting-started/commands.md @@ -1,443 +1,13 @@ -# CAI REPL Commands +# CAI commands (hub) -This document provides documentation for all commands available in the CAI (Context-Aware Interface) REPL system. +The **canonical** command reference (binary flags and REPL slash commands) lives here: -## Base Command System (`base.py`) +- **[CLI commands reference](../../cli/commands_reference.md)** โ€” use this for day-to-day lookup and GitHub Pages. + +TUI-specific routing and shortcuts: + +- **[TUI commands reference](../../tui/commands_reference.md)** --- -## Core Commands - -### **Agent Management (`agent.py`)** -### **AgentCommand** -- **Command**: `/agent` -- **Purpose**: Managing and switching between different AI agents -- **Features**: - - List available agents - - Switch between agents - - Display agent information - - Visualize agent interaction graphs - -### **Configuration Management (`config.py`)** -### **ConfigCommand** -- **Command**: `/config` -- **Purpose**: Display and configure environment variables -- **Features**: - - Show current environment variable settings - - Configure CTF (Capture The Flag) variables - - Manage configuration through environment variables - -### **Context Usage Monitoring (`context.py`)** ๐Ÿš€ **CAI PRO Exclusive** -### **ContextCommand** -> **โšก CAI PRO Exclusive Feature** -> The `/context` command is available exclusively in **[CAI PRO](https://aliasrobotics.com/cybersecurityai.php)**. To access this feature and unlock advanced monitoring capabilities, visit [Alias Robotics](https://aliasrobotics.com/cybersecurityai.php) for more information. - -- **Command**: `/context` or `/ctx` -- **Purpose**: View context usage and token statistics for the current conversation -- **Features**: - - Display total context usage (used/max tokens) with percentage - - Visual grid representation of context usage with CAI logo - - Detailed breakdown by category: - - System prompt tokens - - Tool definitions tokens - - Memory/RAG tokens - - User prompts tokens - - Assistant responses tokens - - Tool calls tokens - - Tool results tokens - - Free space visualization - - Context usage tracking across conversation history - - Real-time token consumption monitoring -- **Usage Example**: - ```bash - # Show context usage for current agent - /context - - # Alternative short form - /ctx - ``` -- **Output Includes**: - - Visual grid showing filled vs free context space - - Percentage breakdown per category - - Token counts formatted with 'k' suffix for thousands - - Color-coded categories for easy identification - - Summary of total input tokens from last iteration - -### **Cost Tracking (`cost.py`)** -### **CostCommand** -- **Command**: `/cost` -- **Purpose**: View usage costs and statistics -- **Features**: - - Display current session costs - - Show cost breakdowns by model - - Track usage over time - - Cost statistics and reporting - -### **Exit (`exit.py`)** -### **ExitCommand** -- **Command**: `/exit` -- **Purpose**: Terminate the CAI REPL session -- **Features**: - - Clean shutdown of the REPL - - Save current session data - - Cleanup background processes - -### **Help System (`help.py`)** -### **HelpCommand** -- **Command**: `/help` or `/?` -- **Purpose**: Display help information and command documentation -- **Features**: - - List available commands - - Show command usage - - Display command aliases - - Provide help for specific commands - -### **History Management (`history.py`)** -### **HistoryCommand** -- **Command**: `/history` -- **Purpose**: Display conversation history with agent filtering -- **Features**: - - Show conversation history - - Filter by specific agents - - Display message tree structure - - Export history functionality - ---- - -## Data Management Commands - -### **Compact Conversation (`compact.py`)** -### **CompactCommand** -- **Command**: `/compact` -- **Purpose**: Compact current conversation and manage model/prompt settings -- **Features**: - - Reduce conversation context size - - Change model during compaction - - Modify prompt settings - - Maintain conversation flow while reducing tokens - -### **Environment Display (`env.py`)** -### **EnvCommand** -- **Command**: `/env` -- **Purpose**: Display current environment variables -- **Features**: - - Show all environment variables - - Filter by variable patterns - - Display CAI-specific environment settings - -### **Load Data (`load.py`)** -### **LoadCommand** -- **Command**: `/load` -- **Purpose**: Load JSONL data into the current session context -- **Features**: - - Load conversation history from files - - Import external data - - Integrate with parallel configurations - - Support for various data formats - -### **Memory Management (`memory.py`)** -### **MemoryCommand** -- **Command**: `/memory` -- **Purpose**: Manage persistent memory storage in `.cai/memory` -- **Features**: - - Store conversation context persistently - - Apply memory to current context - - Manage memory entries - - Persistent storage across sessions - -### **Flush History (`flush.py`)** -### **FlushCommand** -- **Command**: `/flush` -- **Purpose**: Clear conversation history -- **Features**: - - Clear current conversation - - Reset agent contexts - - Clean up memory - - Start fresh conversation - ---- - -## Model Management Commands - -### **Model Configuration (`model.py`)** -### **ModelCommand** -- **Command**: `/model` -- **Purpose**: View and change the current LLM model -- **Features**: - - Switch between different models - - Display model information - - Configure model parameters - - Support for LiteLLM and Ollama - -### **ModelShowCommand** -- **Command**: `/model-show` -- **Purpose**: Show all available models from LiteLLM repository -- **Features**: - - List all available models - - Display model categories - - Show model capabilities - - Filter by provider - ---- - -## Advanced Features - -### **Graph Visualization (`graph.py`)** -### **GraphCommand** -- **Command**: `/graph` -- **Purpose**: Visualize agent interaction graphs -- **Features**: - - Display directed graph of conversations - - Show user and agent interactions - - Highlight tool calls - - Visualize conversation flow - -### **Parallel Execution (`parallel.py`)** -### **ParallelCommand** -- **Command**: `/parallel` -- **Purpose**: Manage parallel agent configurations -- **Features**: - - Configure multiple agents - - Set different models per agent - - Execute agents in parallel - - Manage parallel configurations - -### **Run Parallel (`run.py`)** -### **RunCommand** -- **Command**: `/run` -- **Purpose**: Execute queued prompts in parallel mode -- **Features**: - - Queue prompts for different agents - - Execute all queued prompts - - Manage parallel execution - - Collect results from multiple agents - -### **Merge Histories (`merge.py`)** -### **MergeCommand** -- **Command**: `/merge` -- **Purpose**: Merge agent message histories (alias for `/parallel merge`) -- **Features**: - - Combine histories from multiple agents - - Integrate parallel conversation results - - Shortcut for parallel merge functionality - ---- - -## Integration Commands - -### **MCP Integration (`mcp.py`)** -### **MCPCommand** -- **Command**: `/mcp` -- **Purpose**: Manage MCP (Model Context Protocol) servers and their tools -- **Features**: - - Load SSE MCP servers - - Load STDIO MCP servers - - List active MCP connections - - Add MCP tools to agents - - Manage MCP server lifecycle - -### **Platform Features (`platform.py`)** -### **PlatformCommand** -- **Command**: `/platform` -- **Purpose**: Interact with platform-specific features -- **Features**: - - Access platform extensions - - Platform-specific integrations - - Check platform availability - ---- - -## System Management Commands - -### **Process Management (`kill.py`)** -### **KillCommand** -- **Command**: `/kill` -- **Purpose**: Terminate active processes or sessions -- **Features**: - - Kill background processes - - Terminate stuck sessions - - Process cleanup - -### **Shell Access (`shell.py`)** -### **ShellCommand** -- **Command**: `/shell` -- **Purpose**: Execute shell commands from within the REPL -- **Features**: - - Run system commands - - Access workspace directory - - Container workspace support - - Signal handling for processes - -### **Virtualization (`virtualization.py`)** -### **VirtualizationCommand** -- **Command**: `/virtualization` or `/virt` -- **Purpose**: Manage Docker-based virtualization environments -- **Features**: - - Set up Docker containers - - Manage container lifecycle - - Workspace virtualization - - Environment isolation - -### **Workspace Management (`workspace.py`)** -### **WorkspaceCommand** -- **Command**: `/workspace` or `/ws` -- **Purpose**: Manage workspace within Docker containers or locally -- **Features**: - - Navigate workspace directories - - Mount external directories - - Container workspace management - - File system operations - -### **Quickstart (`quickstart.py`)** -### **QuickstartCommand** -- **Command**: `/quickstart` -- **Purpose**: Display setup information for new users -- **Features**: - - Essential setup guidance - - Configuration instructions - - Getting started tutorial - - Auto-runs on first launch - ---- - -## Utility Commands - -### **Command Completion (`completer.py`)** -### **FuzzyCommandCompleter** -- **Purpose**: Intelligent command completion with fuzzy matching -- **Features**: - - Command auto-completion - - Fuzzy matching for typos - - Subcommand suggestions - - Argument completion - - Command shadowing detection - ---- - -## Usage Examples - -### Basic Workflow -```bash -# Start CAI REPL -cai - -# View available agents -/agent list - -# Switch to a specific agent -/agent switch - -# View conversation history -/history - -# Change model -/model gpt-4 - -# Clear conversation -/flush - -# Exit -/exit -``` - -### Advanced Features -```bash -# Set up parallel execution -/parallel create agent1 --model gpt-4 -/parallel create agent2 --model claude-3 - -# Queue prompts -/run queue agent1 "Analyze this code" -/run queue agent2 "Review the analysis" - -# Execute in parallel -/run execute - -# Merge results -/merge -``` - -### Integration Examples -```bash -# Load MCP server -/mcp load http://localhost:9876/sse burp - -# Add MCP tools to agent -/mcp add-to-agent burp - -# Set up virtualized environment -/virtualization create ubuntu:latest -/workspace /path/to/project -``` - ---- - -## Command Registration - -All commands are automatically registered when their respective modules are imported through the `__init__.py` file. The command system uses a registry pattern to track all available commands and their aliases. - ---- - -## File Structure - -``` -src/cai/repl/commands/ -โ”œโ”€โ”€ __init__.py # Module exports and imports -โ”œโ”€โ”€ base.py # Base command class -โ”œโ”€โ”€ agent.py # Agent management -โ”œโ”€โ”€ compact.py # Conversation compaction -โ”œโ”€โ”€ completer.py # Command completion -โ”œโ”€โ”€ config.py # Configuration management -โ”œโ”€โ”€ cost.py # Cost tracking -โ”œโ”€โ”€ env.py # Environment variables -โ”œโ”€โ”€ exit.py # REPL exit -โ”œโ”€โ”€ flush.py # History clearing -โ”œโ”€โ”€ graph.py # Graph visualization -โ”œโ”€โ”€ help.py # Help system -โ”œโ”€โ”€ history.py # History management -โ”œโ”€โ”€ kill.py # Process management -โ”œโ”€โ”€ load.py # Data loading -โ”œโ”€โ”€ mcp.py # MCP integration -โ”œโ”€โ”€ memory.py # Memory management -โ”œโ”€โ”€ merge.py # History merging -โ”œโ”€โ”€ model.py # Model management -โ”œโ”€โ”€ parallel.py # Parallel execution -โ”œโ”€โ”€ platform.py # Platform features -โ”œโ”€โ”€ quickstart.py # User onboarding -โ”œโ”€โ”€ run.py # Parallel execution trigger -โ”œโ”€โ”€ shell.py # Shell access -โ”œโ”€โ”€ virtualization.py # Container management -โ””โ”€โ”€ workspace.py # Workspace management -``` - ---- - -## Extending the Command System - -To add new commands: - -1. Create a new Python file in `src/cai/repl/commands/` -2. Import the base `Command` class from `base.py` -3. Extend the `Command` class with your implementation -4. Use the `register_command` decorator or function -5. Add the import to `__init__.py` - -Example: -```python -from cai.repl.commands.base import Command, register_command - -class MyCommand(Command): - def __init__(self): - super().__init__( - name="/mycommand", - description="My custom command", - aliases=["/my", "/mc"] - ) - - def execute(self, args): - # Command implementation - pass - -register_command(MyCommand()) -``` - +*This hub replaces the long per-file command list to avoid drift; the CLI reference is updated with each framework release.* diff --git a/docs/cai/getting-started/configuration.md b/docs/cai/getting-started/configuration.md index 4ffeae36..3d1ab600 100644 --- a/docs/cai/getting-started/configuration.md +++ b/docs/cai/getting-started/configuration.md @@ -16,6 +16,8 @@ The OPENAI_API_KEY must not be left blank. It should contain either "sk-123" (as For a complete reference organized by use case, see [Environment Variables Reference](../../environment_variables.md). +**In the REPL:** `/env list` shows the catalog with **current values** and index numbers; bare `/env` shows `CAI_*` / `CTF_*` in this session. **`/help`** includes the **full environment reference** (tables) after the quick guide; **`/help var NAME`** opens **long-form** help for a single variable. See also [Environment Variables โ€” Discovering variables in the REPL](../../environment_variables.md#discovering-variables-in-the-repl). + | Variable | Description | Default | |----------|-------------|---------| | CTF_NAME | Name of the CTF challenge to run (e.g. "picoctf_static_flag") | - | diff --git a/docs/cai_faq.md b/docs/cai_faq.md index fd90224d..8e538c89 100644 --- a/docs/cai_faq.md +++ b/docs/cai_faq.md @@ -84,8 +84,14 @@ ![cai-010-agents-menu](media/cai-010-agents-menu.png) -??? question "Where can I list all the environment variables? /config" +??? question "Where can I list all the environment variables? /env" + Use **`/env list`** to see the full catalog with **current values** and index numbers for **`/env set`**. Bare **`/env`** shows only `CAI_*` / `CTF_*` keys in the current session. + + For **full documentation tables** (defaults, constraints, when each applies), run **`/help`** and scroll past the quick guide, or **`/help topics`** and read to the end. For **one variable** in depth, use **`/help var VARIABLE_NAME`** (e.g. `/help var CAI_DEBUG`). + + The same topics are covered on the site in [Environment Variables](environment_variables.md). + ![cai-008-config](media/cai-008-config.png) ??? question "How to know more about the CLI? /help" diff --git a/docs/cai_pro.md b/docs/cai_pro.md index d1883944..0a39117a 100644 --- a/docs/cai_pro.md +++ b/docs/cai_pro.md @@ -19,39 +19,41 @@ The cybersecurity AI landscape is rapidly evolving, and professionals need tools - **๐Ÿ‡ช๐Ÿ‡บ European Hosting**: GDPR and NIS2 compliant infrastructure ensuring maximum privacy and data sovereignty - **๐Ÿ’ฌ Professional Support**: Dedicated technical support to help you maximize your security testing capabilities - **๐Ÿ“ฑ Mobile UI (iOS)**: Native iOS app for security testing on the go - **[Join TestFlight Beta](https://testflight.apple.com/join/nXZZD4Z5)** -- **โšก Advanced Features**: Terminal UI (deprecated), context monitoring, and exclusive tools not available in the Community Edition +- **โšก Advanced Features**: Terminal UI (CLI recommended), usage and cost tooling (`/cost`, compaction), and exclusive tools not available in the Community Edition --- ## CAI FREE vs CAI PRO -
-| Feature | CAI FREE | CAI PRO | -|---------|-------------------|---------| -| **Core Framework** | โœ… Access, ~6-months behind | โœ… Full Access | -| **300+ AI Models** | โœ… BYO API Keys | โœ… BYO API Keys | -| **Built-in Security Tools** | โœ… Full Suite | โœ… Full Suite | -| **Agent Patterns** | โœ… All Patterns | โœ… All Patterns | -| **Command Line Interface** | โœ… Yes | โœ… Yes | -| **European Data Hosting** | โœ… **GDPR + NIS2 Compliant** | โœ… **GDPR + NIS2 Compliant** | -| **`alias1` Model** | โŒ Not Available | โœ… **Unlimited Tokens** | -| **Mobile UI (iOS App)** | โŒ | โœ… **Native iOS App** - [TestFlight](https://testflight.apple.com/join/nXZZD4Z5) | -| **Terminal User Interface (TUI)** | โŒ | โœ… Multi-terminal (Deprecated) | -| **Context Monitoring (`/context`)** | โŒ | โœ… Real-time token tracking | -| **Advanced Reporting** | โŒ | โœ… Professional formats | -| **Priority Support** | โŒ Community | โœ… **Professional** | -| **Commercial Use License** | โŒ Research Only | โœ… **Full Commercial** | -| **Custom Extensions** | โŒ | โœ… Available on request | -| **Pricing** | **Free** (Research) | **โ‚ฌ350/month** | -
+ +| Feature | CAI FREE | CAI PRO | +| ----------------------------------- | --------------------------- | ------------------------------------------------------------------------------- | +| **Core Framework** | โœ… Access, ~6-months behind | โœ… Full Access | +| **300+ AI Models** | โœ… BYO API Keys | โœ… BYO API Keys | +| **Built-in Security Tools** | โœ… Full Suite | โœ… Full Suite | +| **Agent Patterns** | โœ… All Patterns | โœ… All Patterns | +| **Command Line Interface** | โœ… Yes | โœ… Yes | +| **European Data Hosting** | โœ… **GDPR + NIS2 Compliant** | โœ… **GDPR + NIS2 Compliant** | +| `**alias1` Model** | โŒ Not Available | โœ… **Unlimited Tokens** | +| **Mobile UI (iOS App)** | โŒ | โœ… **Native iOS App** - [TestFlight](https://testflight.apple.com/join/nXZZD4Z5) | +| **Terminal User Interface (TUI)** | โŒ | โœ… Multi-terminal (Deprecated) | +| **Usage & cost visibility** | โŒ | โœ… `/cost`, TUI cost panels, reporting workflows | +| **Advanced Reporting** | โŒ | โœ… Professional formats | +| **Priority Support** | โŒ Community | โœ… **Professional** | +| **Commercial Use License** | โŒ Research Only | โœ… **Full Commercial** | +| **Custom Extensions** | โŒ | โœ… Available on request | +| **Pricing** | **Free** (Research) | **โ‚ฌ350/month** | + + + --- ## The `alias1` Model -
+ ### ๐Ÿ† **Beats GPT-5 in Cybersecurity Benchmarks** @@ -63,11 +65,12 @@ The `alias1` model is our flagship cybersecurity AI, specifically trained for: - **Zero Refusals**: No ethical restrictions for authorized security testing **Performance Highlights:** + - Outperforms GPT-5 in AI vs AI cybersecurity benchmarks - 500B-parameter architecture optimized for security workflows - Unrestricted responses for authorized pentesting engagements -
+ [View Full Benchmarks โ†’](https://aliasrobotics.com/alias1.php#benchmarking) @@ -75,20 +78,16 @@ The `alias1` model is our flagship cybersecurity AI, specifically trained for: The performance of `alias1` and the CAI framework is validated through rigorous peer-reviewed research: -- ๐Ÿ“Š [**CAIBench: Cybersecurity AI Benchmark**](https://arxiv.org/pdf/2510.24317) (2025) - Modular meta-benchmark framework for evaluating LLM models across offensive and defensive cybersecurity domains. `alias1` demonstrates superior performance compared to general-purpose models. - -- ๐ŸŽฏ [**Evaluating Agentic Cybersecurity in Attack/Defense CTFs**](https://arxiv.org/pdf/2510.17521) (2025) - Real-world evaluation showing defensive agents achieved 54.3% patching success versus 28.3% offensive initial access. Validates practical effectiveness of CAI agents in live CTF environments. - -- ๐Ÿš€ [**Cybersecurity AI (CAI) Framework**](https://arxiv.org/pdf/2504.06017) (2025) - Core framework paper demonstrating that CAI outperforms humans by up to **3,600ร— in specific security testing scenarios**, establishing a new standard for automated security assessment. - -- ๐Ÿ›ก๏ธ [**Hacking the AI Hackers via Prompt Injection**](https://arxiv.org/pdf/2508.21669) (2025) - Demonstrates four-layer guardrail defenses against prompt injection attacks, ensuring `alias1` remains secure even when processing adversarial inputs. - -- ๐Ÿ“š [**CAI Fluency: Educational Framework**](https://arxiv.org/pdf/2508.13588) (2025) - Comprehensive educational platform for democratizing cybersecurity AI knowledge and best practices. +- ๐Ÿ“Š **[CAIBench: Cybersecurity AI Benchmark](https://arxiv.org/pdf/2510.24317)** (2025) +Modular meta-benchmark framework for evaluating LLM models across offensive and defensive cybersecurity domains. `alias1` demonstrates superior performance compared to general-purpose models. +- ๐ŸŽฏ **[Evaluating Agentic Cybersecurity in Attack/Defense CTFs](https://arxiv.org/pdf/2510.17521)** (2025) +Real-world evaluation showing defensive agents achieved 54.3% patching success versus 28.3% offensive initial access. Validates practical effectiveness of CAI agents in live CTF environments. +- ๐Ÿš€ **[Cybersecurity AI (CAI) Framework](https://arxiv.org/pdf/2504.06017)** (2025) +Core framework paper demonstrating that CAI outperforms humans by up to **3,600ร— in specific security testing scenarios**, establishing a new standard for automated security assessment. +- ๐Ÿ›ก๏ธ **[Hacking the AI Hackers via Prompt Injection](https://arxiv.org/pdf/2508.21669)** (2025) +Demonstrates four-layer guardrail defenses against prompt injection attacks, ensuring `alias1` remains secure even when processing adversarial inputs. +- ๐Ÿ“š **[CAI Fluency: Educational Framework](https://arxiv.org/pdf/2508.13588)** (2025) +Comprehensive educational platform for democratizing cybersecurity AI knowledge and best practices. **Explore all research:** [Alias Robotics Research Library](https://aliasrobotics.com/research-security.php#papers) (24+ peer-reviewed publications) @@ -128,12 +127,14 @@ Building and maintaining CAI is resource-intensive. CAI PRO enables us to: ### Fair Pricing **โ‚ฌ350/month** provides: + - **Unlimited `alias1` tokens** (compare: OpenAI GPT-4o costs ~$2.50 per 1M tokens) - **Professional support** (compare: enterprise support typically $1000+/month) - **Privacy guarantees** (priceless for security professionals) - **Commercial license** (required for security consulting businesses) Most security professionals already pay similar or higher amounts for: + - **Burp Suite Professional**: $449/year ($37/month) - **ChatGPT Plus/Pro**: $20-200/month (with severe restrictions) - **Other AI security tools**: $500-2000/month (closed-source, inferior models) @@ -155,16 +156,9 @@ Run multiple agents in parallel with an intuitive multi-terminal interface: [TUI Documentation โ†’](tui/tui_index.md) -### ๐Ÿ“Š Context Monitoring (`/context`) +### ๐Ÿ“Š Usage and long threads -Track token usage and optimize your conversations: - -- **Real-time Tracking**: Monitor context window consumption as you work -- **Category Breakdown**: See tokens by system, tools, memory, and messages -- **Visual Grid**: CAI logo-based visualization of context utilization -- **Optimization Insights**: Understand when to compact or clear history - -[Context Command Docs โ†’](cai/getting-started/commands.md#context-usage-monitoring-contextpy-cai-pro-exclusive) +Track spend with **`/cost`**, use **`/compact`** when conversations grow large, and use the **TUI** cost/model indicators for per-terminal visibility. ### ๐Ÿ“ Advanced Reporting @@ -205,11 +199,13 @@ CAI_GUARDRAILS=true ### 3. Launch CAI PRO #### CLI Mode (Standard) + ```bash cai ``` #### TUI Mode (Multi-terminal) + ```bash cai --tui ``` @@ -222,10 +218,10 @@ Check that you're using CAI PRO features: CAI> /model # Should show alias1 is available -CAI> /context -# Should display context usage +CAI> /cost +# Should display session usage / costs -CAI> --tui +cai --tui # Should launch multi-terminal interface ``` @@ -237,7 +233,7 @@ CAI> --tui **CAI PRO subscribers receive:** -- **Email Support**: research@aliasrobotics.com (48-hour response SLA) +- **Email Support**: [research@aliasrobotics.com](mailto:research@aliasrobotics.com) (48-hour response SLA) - **Priority Discord**: Exclusive #pro-support channel - **Quarterly Strategy Calls**: Discuss roadmap and feature requests - **Custom Development**: Request tailored agents and extensions @@ -246,7 +242,7 @@ CAI> --tui - **[TUI Guide](tui/tui_index.md)**: Complete Terminal UI documentation - **[Agent Reference](agents.md)**: All available agents and configurations -- **[Command Reference](cai/getting-started/commands.md)**: Full CLI/TUI command list +- **[Command Reference](cli/commands_reference.md)**: Full CLI/TUI command list - **[Benchmarks](cai_benchmark.md)**: Performance data and comparisons ### Community Resources @@ -276,7 +272,8 @@ No. The Community Edition license restricts use to research and educational purp ### Do you offer team/enterprise pricing? -Yes! Contact research@aliasrobotics.com for: +Yes! Contact [research@aliasrobotics.com](mailto:research@aliasrobotics.com) for: + - **Team plans** (5+ users): Volume discounts - **Enterprise plans** (20+ users): Custom pricing, on-premise deployment - **Academic licenses**: Special rates for universities and research institutions @@ -284,6 +281,7 @@ Yes! Contact research@aliasrobotics.com for: ### Is my security testing data private? **Absolutely.** CAI PRO guarantees: + - **No training on your data**: Your pentesting activities never improve our models (unless you explicitly opt in) - **European hosting**: All data processed in GDPR-compliant datacenters - **No third-party sharing**: Unlike OpenAI/Anthropic, we never send your data elsewhere @@ -292,6 +290,7 @@ Yes! Contact research@aliasrobotics.com for: ### Can I switch between models? Yes! CAI PRO includes: + - **Unlimited `alias1` tokens** (your PRO model) - **BYO API keys**: Continue using OpenAI, Anthropic, etc. with your own keys - **Mix and match**: Use `alias1` for exploitation, GPT-4 for reporting, etc. @@ -299,6 +298,7 @@ Yes! CAI PRO includes: ### What if alias1 refuses a query? `alias1` has **zero refusals** for authorized security testing. If you encounter issues: + 1. Ensure your prompt includes security context (e.g., "authorized pentest of...") 2. Check your `CAI_GUARDRAILS` setting (may block malicious patterns) 3. Contact supportโ€”we'll investigate immediately @@ -309,13 +309,13 @@ Yes! CAI PRO includes: **Transform your security testing workflow with CAI PRO.** -
+ ### ๐Ÿš€ **Ready to Upgrade?** - โœ… Unlimited `alias1` access - โœ… Terminal UI with parallel agents -- โœ… Context monitoring and optimization +- โœ… Usage and cost visibility (`/cost`, compaction, TUI) - โœ… Professional support - โœ… European data privacy - โœ… Commercial use license @@ -324,11 +324,8 @@ Yes! CAI PRO includes: **[Get CAI PRO โ†’](https://aliasrobotics.com/cybersecurityai.php)** -
+ --- - -*Have questions? Contact research@aliasrobotics.com* -*Need a quote for your organization? [Request enterprise pricing โ†’](mailto:research@aliasrobotics.com?subject=CAI%20PRO%20Enterprise%20Inquiry)* - +*Have questions? Contact research@aliasrobotics.com* *Need a quote for your organization? [Request enterprise pricing โ†’](mailto:research@aliasrobotics.com?subject=CAI%20PRO%20Enterprise%20Inquiry)* \ No newline at end of file diff --git a/docs/cai_pro_features.md b/docs/cai_pro_features.md index 6bfe9ce5..95f0d7c3 100644 --- a/docs/cai_pro_features.md +++ b/docs/cai_pro_features.md @@ -14,7 +14,7 @@ |------------|----------|---------| | **๐Ÿค– Alias1 Model** | โŒ | โœ… **Unlimited Tokens** | | **๐Ÿ–ฅ๏ธ Terminal UI (TUI)** | โŒ | โœ… Multi-terminal parallel execution | -| **๐Ÿ“Š Context Monitoring** | โŒ | โœ… Real-time token tracking | +| **๐Ÿ“Š Usage / cost** | โŒ | โœ… `/cost`, TUI cost panels | | **โšก Multi-Agent Swarms** | โŒ | โœ… 100+ parallel agents | | **๐Ÿ’ฌ Professional Support** | โŒ Community | โœ… Priority (48h SLA) | | **๐Ÿ‡ช๐Ÿ‡บ European Hosting** | โœ… GDPR + NIS2 | โœ… GDPR + NIS2 | @@ -59,7 +59,7 @@ #### Keyboard Control - **Vim-style shortcuts**: Navigate without touching your mouse -- **Quick commands**: `/agent`, `/model`, `/context`, `/parallel` +- **Quick commands**: `/agent`, `/model`, `/parallel`, `/cost` - **Terminal switching**: `Ctrl+N`/`Ctrl+B` for rapid navigation #### Real-Time Stats @@ -83,29 +83,7 @@ --- -## 3. Context Monitoring (`/context`) - -### Optimize Your Conversations - -Track token usage and stay within model limits with real-time context monitoring. - -### Features - -- **Real-time tracking**: Monitor context window consumption as you work -- **Category breakdown**: Tokens by system, tools, memory, and messages -- **Visual indicators**: Color-coded utilization levels -- **Optimization insights**: Know when to compact or clear history - -### Use Cases - -- **Long conversations**: Avoid hitting context limits mid-session -- **Cost optimization**: Understand where tokens are consumed -- **Memory management**: Balance RAG memory vs conversation space -- **Multi-terminal coordination**: Track context across parallel agents - ---- - -## 4. Parallel Agent Swarms +## 3. Parallel Agent Swarms ### 100+ Concurrent Agents @@ -148,7 +126,7 @@ Chain agents for complex operations: --- -## 5. Professional Support +## 4. Professional Support ### Priority Technical Assistance @@ -181,7 +159,7 @@ Request tailored solutions: --- -## 6. European Data Sovereignty +## 5. European Data Sovereignty ### GDPR & NIS2 Compliant by Design @@ -207,7 +185,7 @@ Your security testing data never leaves Europe. --- -## 7. Advanced Reporting +## 6. Advanced Reporting ### Professional Security Reports @@ -242,7 +220,7 @@ Generate compliance-ready reports automatically. --- -## 8. Four-Layer Guardrails +## 7. Four-Layer Guardrails ### Advanced Security Protection @@ -274,7 +252,7 @@ CAI PRO includes enterprise-grade guardrails against adversarial attacks. --- -## 9. Commercial Use License +## 8. Commercial Use License ### Unrestricted Business Use @@ -302,7 +280,7 @@ CAI PRO includes full commercial licensing for professional security services. --- -## 10. Custom Extensions +## 9. Custom Extensions ### Tailored Solutions for Your Organization @@ -344,7 +322,7 @@ Work with the CAI team to develop specialized capabilities. | **300+ Models** | โœ… BYO Keys | โœ… BYO Keys | โœ… BYO Keys + Private | | **Alias1 Tokens** | โŒ | โœ… Unlimited | โœ… Unlimited + On-prem | | **TUI** | โŒ | โœ… Yes | โœ… Yes + Custom UI | -| **Context Monitoring** | โŒ | โœ… Yes | โœ… Yes + Analytics | +| **Usage & cost visibility** (`/cost`, TUI) | โŒ | โœ… Yes | โœ… Yes + Analytics | | **Parallel Agents** | โŒ | โœ… 100+ | โœ… Unlimited | | **Support** | Community | โœ… Priority | โœ… Dedicated + Training | | **Reporting** | Basic | โœ… Advanced | โœ… Custom Templates | @@ -368,7 +346,7 @@ Work with the CAI team to develop specialized capabilities. - โœ… Unlimited alias1 tokens - โœ… Terminal UI with parallel agents -- โœ… Context monitoring and optimization +- โœ… Usage and cost visibility (`/cost`, compaction, TUI) - โœ… Professional support (48h SLA) - โœ… European data sovereignty (GDPR + NIS2) - โœ… Commercial use license diff --git a/docs/cai_pro_pricing.md b/docs/cai_pro_pricing.md index 9f261e53..eb874555 100644 --- a/docs/cai_pro_pricing.md +++ b/docs/cai_pro_pricing.md @@ -31,7 +31,7 @@ Free for research purposes. - โŒ No alias1 model access - โŒ No Terminal UI (TUI) - โŒ No parallel agent swarms -- โŒ No context monitoring +- โŒ No PRO usage analytics and reporting - โŒ No commercial license - โš ๏ธ Framework updates ~6 months behind PRO @@ -49,7 +49,7 @@ Leading enterprise framework for AI Security with professional support. - โœ… **Unlimited alias1 tokens** - โœ… **Terminal User Interface (TUI)** - โœ… **Multi-agent parallel execution** (100+ agents) -- โœ… **Context Monitoring** (`/context` command) +- โœ… **Usage visibility** (`/cost`, TUI cost panels) - โœ… **Commercial license** included - โœ… **Professional support** (48h SLA) - โœ… **GDPR & NIS2 compliant** European hosting @@ -112,7 +112,7 @@ Custom deployment options. | **๐Ÿ–ฅ๏ธ User Interfaces** | | | | | Terminal UI (TUI) | โŒ | โœ… Multi-terminal | โœ… Multi-terminal + Custom | | Parallel Agent Execution | โŒ | โœ… 100+ agents | โœ… Unlimited | -| Context Monitoring | โŒ | โœ… `/context` | โœ… + Analytics Dashboard | +| Usage / cost visibility | โŒ | โœ… `/cost`, TUI | โœ… + Analytics Dashboard | | Keyboard Shortcuts | โŒ | โœ… Full Set | โœ… Full Set + Custom | | Team Presets | โŒ | โœ… 11 Teams | โœ… Unlimited Custom | | | | | | diff --git a/docs/cai_pro_quickstart.md b/docs/cai_pro_quickstart.md index 74571a2c..9d21e803 100644 --- a/docs/cai_pro_quickstart.md +++ b/docs/cai_pro_quickstart.md @@ -228,18 +228,12 @@ CAI> Perform recon on https://bugbounty-target.com for a bug bounty program ## Advanced Configuration -### Enable Context Monitoring +### Check usage and costs -Track your token usage in real-time: +Use **`/cost`** for session spend and token stats; use **`/compact`** when histories grow long. ```bash -CAI> /context - -# Shows: -# - Total tokens used/available -# - Breakdown by category (system, tools, memory, messages) -# - Visual grid representation -# - Optimization suggestions +CAI> /cost ``` ### Multi-Agent Parallel Execution @@ -291,10 +285,9 @@ cai --version ### Issue: "Rate limit exceeded" -**This shouldn't happen with CAI PRO** (unlimited tokens). If you see this: +The client will automatically pause until the appropriate time frame has passed and then retry the iteration without interrupting the session. -1. Check for typos in your `ALIAS_API_KEY` -2. Contact support immediately: support@aliasrobotics.com +If this is happening frequently, consider compacting the context with `/compact`. --- @@ -365,7 +358,7 @@ Learn from real-world CAI applications: ### ๐ŸŽฏ Best Practices 1. **Start with clear prompts**: Be specific about your testing scope and objectives -2. **Use context monitoring**: Check `/context` regularly to optimize token usage +2. **Watch costs and thread length**: Use `/cost` and `/compact` as sessions grow 3. **Leverage parallel execution**: Run multiple agents for comprehensive coverage 4. **Save your sessions**: Use `/save` to preserve important conversations 5. **Enable guardrails**: Keep `CAI_GUARDRAILS=true` for safer operations diff --git a/docs/cai_quickstart.md b/docs/cai_quickstart.md index ecdef2ea..c137e008 100644 --- a/docs/cai_quickstart.md +++ b/docs/cai_quickstart.md @@ -106,17 +106,17 @@ CAI_PRICE_LIMIT="0.004" CAI_MODEL="qwen2.5:72b" cai #### 3. Runtime configuration -After running CAI, use `/config` +After running CAI, use **`/env`** (the catalog). ``` - /config set to configure a variable # see `config.py` or type `/help` - + /env set <#|NAME> # set a catalog variable + /env list # numbered catalog + live values + /env default # restore catalog defaults ``` ``` cai - /config # It will display a panel with all the environment variables. - # You must pick its reference NUMBER (1st column left) - # `18` is the corresponding number for CAI_PRICE_LIMIT - /config set 18 "0.004" + /env list + # Pick the catalog index or variable name from the first column + /env set 18 "0.004" ``` diff --git a/docs/cli/advanced_usage.md b/docs/cli/advanced_usage.md index 4072c59c..60458862 100644 --- a/docs/cli/advanced_usage.md +++ b/docs/cli/advanced_usage.md @@ -329,8 +329,8 @@ cai --prompt "/agent redteam_agent ; scan target.com ; /save results.json" ```text # ctf_workflow.txt -/config CTF_NAME=hackableii -/config CTF_CHALLENGE=web_app +/env set CTF_NAME hackableii +/env set CTF_CHALLENGE web_app /agent redteam_agent Analyze the CTF challenge environment Find and exploit vulnerabilities @@ -343,7 +343,7 @@ Extract the flag ```text # bugbounty_recon.txt /agent bug_bounter_agent -/config CAI_PRICE_LIMIT=20.0 +/env set CAI_PRICE_LIMIT 20.0 # Reconnaissance Perform subdomain enumeration on target.com @@ -967,10 +967,10 @@ cai CAI> /cost # Increase limit if needed -CAI> /config CAI_PRICE_LIMIT=20.0 +CAI> /env set CAI_PRICE_LIMIT 20.0 # Check updated limit -CAI> /config | grep PRICE_LIMIT +CAI> /env list | grep PRICE_LIMIT ``` ### Cost Optimization Strategies @@ -1115,11 +1115,11 @@ cai ```bash # Start with base config -CAI> /config +CAI> /env list # Adjust during session -CAI> /config CAI_DEBUG=2 -CAI> /config CAI_PRICE_LIMIT=15.0 +CAI> /env set CAI_DEBUG 2 +CAI> /env set CAI_PRICE_LIMIT 15.0 # Verify changes CAI> /env | grep CAI @@ -1209,7 +1209,7 @@ Common issues and solutions. CAI> /cost # Increase limit -CAI> /config CAI_PRICE_LIMIT=20.0 +CAI> /env set CAI_PRICE_LIMIT 20.0 # Or restart with higher limit exit @@ -1223,7 +1223,7 @@ CAI_PRICE_LIMIT=20.0 cai CAI> /env | grep MAX_INTERACTIONS # Increase limit -CAI> /config CAI_MAX_INTERACTIONS=500 +CAI> /env set CAI_MAX_INTERACTIONS 500 # Or use /flush to start fresh CAI> /flush @@ -1242,14 +1242,14 @@ CAI> /agent CAI> /agent redteam_agent # Check configuration -CAI> /config +CAI> /env list ``` ### Issue: Context Window Full ```bash -# Check context usage (CAI PRO) -CAI> /context +# Review spend / token usage +CAI> /cost # Compact conversation CAI> /compact @@ -1298,7 +1298,7 @@ export CAI_DEBUG=2 cai # Or enable during session -CAI> /config CAI_DEBUG=2 +CAI> /env set CAI_DEBUG 2 ``` --- diff --git a/docs/cli/cli_index.md b/docs/cli/cli_index.md index 887de66e..40b2f769 100644 --- a/docs/cli/cli_index.md +++ b/docs/cli/cli_index.md @@ -92,11 +92,11 @@ See the [Getting Started Guide](getting_started.md) for detailed instructions. Over 30 built-in commands organized by category: -- **Agent Management**: `/agent`, `/parallel`, `/run` -- **Memory & History**: `/memory`, `/history`, `/compact`, `/flush`, `/load`, `/merge` -- **Environment & Config**: `/config`, `/env`, `/workspace`, `/virtualization` -- **Tools & Integration**: `/mcp`, `/platform`, `/shell` -- **Utilities**: `/model`, `/graph`, `/context`, `/cost`, `/help` +- **Agent Management**: `/agent`, `/parallel` +- **Memory & History**: `/memory`, `/history`, `/compact`, `/flush`, `/load`, `/merge`, `/save` +- **Environment**: `/env` (catalog `list` / `get` / `set` / `default`), `/help var` (per-variable help), `/workspace`, `/virtualization` +- **Tools & Integration**: `/mcp`, `/shell` +- **Utilities**: `/model`, `/graph`, `/cost`, `/help` All commands support aliases for faster typing (e.g., `/a` for `/agent`, `/h` for `/help`). @@ -280,7 +280,7 @@ cai --yaml agents.yaml --prompt "full reconnaissance on target.com" | `/agent list` | List all agents | `/agent list` | | `/agent ` | Switch agent | `/agent redteam_agent` | | `/model ` | Change model | `/model alias1` | -| `/config` | View configuration | `/config` | +| `/env list` | Catalog + live values | `/env list` | | `/help` | Show help | `/help agent` | | `/save ` | Save session | `/save session.json` | | `/load ` | Load session | `/load session.json` | @@ -306,7 +306,7 @@ CAI CLI can be configured via: 1. **Environment Variables**: `CAI_MODEL`, `CAI_AGENT_TYPE`, etc. 2. **`.env` File**: Place in your working directory -3. **`/config` Command**: Runtime configuration changes +3. **`/env` command**: Runtime changes via catalog (`/env set โ€ฆ`, `/env default`, โ€ฆ) 4. **YAML Files**: Agent and workflow definitions Example `.env`: diff --git a/docs/cli/commands_reference.md b/docs/cli/commands_reference.md index ea8ec9cf..e7afb1a9 100644 --- a/docs/cli/commands_reference.md +++ b/docs/cli/commands_reference.md @@ -1,1291 +1,833 @@ -# CAI CLI Commands Reference +# CAI CLI and REPL commands reference -This comprehensive guide documents all commands available in the CAI Command Line Interface, organized by category for easy navigation. +This page documents flags accepted by the `cai` binary and slash commands in the **CLI** interactive REPL. For **Textual TUI** shortcuts, multi-terminal routing, and UI-only behavior, see the [TUI commands reference](../tui/commands_reference.md). --- -## Command Categories +## On this page -1. [Agent Management](#agent-management) -2. [Model Management](#model-management) -3. [Memory & History](#memory--history) -4. [Environment & Configuration](#environment--configuration) -5. [Tools & Integration](#tools--integration) -6. [System Management](#system-management) -7. [Parallel Execution](#parallel-execution) -8. [Utilities](#utilities) +1. [Binary `cai` CLI flags](#binary-cai-cli-flags) +2. [REPL syntax](#repl-syntax) +3. [Agents and models](#agents-and-models) +4. [Conversation and context](#conversation-and-context) +5. [Memory](#memory) +6. [Parallel execution and queues](#parallel-execution-and-queues) +7. [Configuration and environment](#configuration-and-environment) +8. [Integrations](#integrations) +9. [System and processes](#system-and-processes) +10. [Utilities](#utilities) +11. [Quick reference table](#quick-reference-table) +12. [Commands registered](#commands-registered) +13. [Next steps](#next-steps) --- -## Agent Management +## Binary `cai` CLI flags -### `/agent` or `/a` +The binary parses known flags and treats **unrecognized tokens as an initial prompt** (positional prompt text), similar to `parse_known_args()` semantics. -Manage and switch between different AI agents. -**Syntax**: +| Flag | Type | Default | Description | +| -------------------- | -------- | --------- | ------------------------------------------------------------------------------------- | +| `--tui` | flag | false | Start CAI in Textual TUI (multi-terminal). Sets `CAI_TUI_MODE=true`. | +| `--yaml FILE` | option | โ€” | Load parallel agent definitions from a YAML file. | +| `--prompt TEXT` | option | โ€” | Initial prompt executed immediately on startup. | +| `--version` | flag | false | Print `cai-framework` version and exit. | +| `--update` | flag | false | Check for updates and install if available. Requires `ALIAS_API_KEY`. | +| `--continue` / `-c` | flag | false | Enable auto-continue mode (`CAI_CONTINUE_MODE=true`). | +| `--resume [SESSION]` | optional | โ€” | Resume a prior session: `last`, `list`, a session id, or path to a `.jsonl` log. | +| `--logpath PATH` | option | โ€” | Custom log directory (often used with `--resume`). | +| `--unrestricted` | flag | false | Enable abliteration steering: `CAI_UNRESTRICTED=true`. | +| `--yolo` | flag | false | Skip confirmation for sensitive commands (`CAI_YOLO=true`). **Insecure.** | +| `--api` | flag | false | Run CAI as an HTTP API backend (FastAPI + uvicorn). See [CAI API Backend](../api.md). | +| `--api-host` | option | 127.0.0.1 | API bind host. Env: `CAI_API_HOST`. | +| `--api-port` | int | 8000 | API bind port. Env: `CAI_API_PORT`. | +| `--api-reload` | flag | false | Uvicorn auto-reload. Env: `CAI_API_RELOAD`. | +| `--api-workers` | int | 1 | Uvicorn workers. Env: `CAI_API_WORKERS`. | + + +**API mode:** operational details, auth headers, and routes are documented in [CAI API Backend](../api.md). For a single list of all binary flags, stay on this page; the API doc focuses on HTTP behavior. + +**Example (non-interactive prompt):** + ```bash -/agent [subcommand] [arguments] -/a [subcommand] [arguments] +cai --prompt "Summarize SSH hardening for Ubuntu 22.04" ``` -**Subcommands**: +--- -#### `list` -List all available agents with their descriptions. +## REPL syntax -```bash -/agent list +```text +/command [subcommand] [arguments ...] ``` -**Output**: Table showing agent names, descriptions, and primary use cases. +Aliases are listed per command. Arguments in `[]` are optional; `|` means alternatives. -#### `` -Switch to a specific agent. +In **Example** sections below, lines starting with `CAI>` are commands you type; other lines are **representative** REPL output (exact text, tables, and colors vary by build and environment). -```bash -/agent redteam_agent -/agent bug_bounter_agent -/a blueteam_agent -``` +--- -#### `info` or `info ` -Display detailed information about the current or specified agent. +## Agents and models -```bash -# Current agent info -/agent info +### `/agent` (`/a`) -# Specific agent info -/agent info redteam_agent -``` +Manage and switch agents. -**Examples**: -```bash -# List all agents +| Subcommand | Arguments | Description | +| ---------- | ----------------------- | ------------------------------------------------------- | +| `list` | โ€” | List available agents and parallel patterns. | +| `select` | name / number / pattern | Switch to the given agent; transfers history. | +| `info` | [name / number] | Detailed info: key, model, tools, handoffs, guardrails. | +| `current` | โ€” | Active agent configuration (in TUI: all terminals). | +| `new` | โ€” | Create a new agent interactively. | + + +- **No arguments:** same as `/agent current`. +- **Shortcut:** `/agent red_teamer` is equivalent to `/agent select red_teamer`. + +**Example:** + +```text CAI> /agent list +โ€ฆ table of agents, models, and ids (layout varies by build) โ€ฆ -# Switch to red team agent -CAI> /agent redteam_agent +CAI> /agent select red_teamer +Switched to agent: red_teamer -# Switch to bug bounty agent (using alias) -CAI> /a bug_bounter_agent - -# Get info about DFIR agent -CAI> /agent info dfir_agent +CAI> /agent +โ€ฆ same as /agent current: active agent, model, tools summary โ€ฆ ``` -**Available Agents**: +### `/model` (`/mod`) -| Agent | Use Case | -|-------|----------| -| `redteam_agent` | Offensive security testing | -| `blueteam_agent` | Defensive security analysis | -| `bug_bounter_agent` | Bug bounty hunting | -| `one_tool_agent` | Single-tool execution | -| `dfir_agent` | Digital forensics | -| `reverse_engineering_agent` | Binary analysis | -| `network_security_analyzer_agent` | Network security | -| `wifi_security_agent` | WiFi security testing | -| `android_sast_agent` | Android security analysis | -| `selection_agent` | Agent recommendation | +View or change the active LLM. The LiteLLM-backed catalog is under the `**show**` subcommand (for example `**/model show**` or `**/mod show**`). -**Notes**: -- Agent changes are immediate -- Conversation history is preserved when switching -- Each agent has specialized tools and instructions ---- +| Usage | Description | +| -------------------------------- | -------------------------------------------------------------------------------------------------- | +| `/model` (no extra args) | Prints the current model and a numbered table of predefined models (with pricing where available). | +| `/model ` | Sets the model by name (typically via `CAI_MODEL`), e.g. `/model gpt-4o`. | +| `/model ` | Selects by number from the last displayed table, e.g. `/model 5`. | +| `/model show` | Lists LiteLLM-backed models (full catalog). Use `/model` / `/model ` to switch after choosing. | +| `/model show supported` | Same catalog filtered to models with function-calling support. | +| `/model show ` | Filter the catalog by substring. | +| `/model show supported ` | Filter to supported models matching a substring. | -## Model Management -### `/model` or `/mod` +**Examples:** -View or change the current LLM model. - -**Syntax**: -```bash -/model [model_name] -/mod [model_name] -``` - -**Examples**: - -```bash -# View current model +```text CAI> /model +Current model: alias1 +โ€ฆ numbered shortcuts / pricing table โ€ฆ -# Change to alias1 -CAI> /model alias1 - -# Change to GPT-4o CAI> /model gpt-4o +Model set to gpt-4o -# Change to Claude -CAI> /model claude-3-5-sonnet-20241022 +CAI> /model show ollama +โ€ฆ LiteLLM rows whose id/name contains "ollama" โ€ฆ + +CAI> /mod show supported +โ€ฆ catalog filtered to function-calling models โ€ฆ ``` -### `/model-show` - -Display all available models from the LiteLLM repository. - -**Syntax**: -```bash -/model-show -``` - -**Output**: Comprehensive list of models by provider (OpenAI, Anthropic, Ollama, etc.) - -**Examples**: - -```bash -# Show all available models -CAI> /model-show - -# Then select one -CAI> /model gpt-4o -``` - -**Commonly Used Models**: - -| Model | Provider | Cost | Best For | -|-------|----------|------|----------| -| `alias1` | Alias Robotics | Medium | Balanced performance โญ | -| `gpt-4o` | OpenAI | High | Complex reasoning | -| `claude-3-5-sonnet-20241022` | Anthropic | High | Fast & accurate | -| `o1-mini` | OpenAI | Medium | Reasoning tasks | - --- -## Memory & History +## Conversation and context -### `/history` or `/his` - -Display conversation history. - -**Syntax**: -```bash -/history [number] [agent_name] -/his [number] -``` - -**Parameters**: -- `number`: Number of recent messages to show (default: 10) -- `agent_name`: Filter by specific agent - -**Examples**: - -```bash -# Show last 10 messages -CAI> /history - -# Show last 20 messages -CAI> /history 20 - -# Show last 5 messages -CAI> /his 5 - -# Show history for specific agent -CAI> /history 10 redteam_agent -``` - -**Output**: Formatted conversation with timestamps, roles (user/agent), and message content. - ---- - -### `/memory` or `/mem` - -Manage persistent memory storage across sessions. - -**Syntax**: -```bash -/memory [arguments] -/mem [arguments] -``` - -**Subcommands**: - -#### `list` -Show all saved memories. - -```bash -/memory list -``` - -#### `save [name]` -Save current conversation as a memory. - -```bash -/memory save "web app pentest findings" -/mem save ctf_techniques -``` - -#### `apply ` -Apply a saved memory to the current session. - -```bash -/memory apply mem_12345 -``` - -#### `show ` -Display the content of a specific memory. - -```bash -/memory show mem_12345 -``` - -#### `delete ` -Remove a memory permanently. - -```bash -/memory delete mem_12345 -``` - -#### `merge [name]` -Combine two memories into one. - -```bash -/memory merge mem_12345 mem_67890 "combined_findings" -``` - -#### `compact` -AI-powered memory summarization. - -```bash -/memory compact -``` - -#### `status` -Show memory system status and statistics. - -```bash -/memory status -``` - -**Examples**: - -```bash -# Save current session insights -CAI> /memory save "SQLi vulnerabilities found" - -# List all memories -CAI> /memory list - -# Apply previous knowledge -CAI> /memory apply mem_12345 - -# Check memory status -CAI> /mem status -``` - -**Notes**: -- Memories persist across sessions -- Stored in `.cai/memory/` directory -- Useful for long-term research projects - ---- - -### `/compact` or `/cmp` - -Compact the current conversation to reduce context size. - -**Syntax**: -```bash -/compact [model_name] -/cmp -``` - -**Parameters**: -- `model_name`: Optional model to use for compaction - -**Examples**: - -```bash -# Compact with current model -CAI> /compact - -# Compact with specific model -CAI> /compact alias1 -``` - -**Use Cases**: -- Approaching token limits -- Long conversations that need summarization -- Maintaining conversation flow with reduced tokens - ---- - -### `/flush` or `/clear` +### `/flush` (`/clear`) Clear conversation history. -**Syntax**: -```bash -/flush [agent_name|all] -/clear -``` -**Parameters**: -- `agent_name`: Flush specific agent history -- `all`: Flush all agent histories +| Subcommand | Arguments | Description | +| ---------- | --------- | ---------------------------------------------------- | +| `all` | โ€” | Clear **all** agents, plus sudo cache and allowlist. | +| `agent` | name | Clear history for one agent. | -**Examples**: -```bash -# Flush current agent -CAI> /flush +- **CLI, no args:** interactive menu of agents that have history. +- **TUI, no args:** clears **only** the current terminal. +- **Shortcut:** `/flush Red Teamer` or `/flush P2` clears by display name or agent id. -# Flush specific agent -CAI> /flush redteam_agent - -# Flush all agents -CAI> /flush all -``` - -**Warning**: This action is irreversible. Consider using `/save` first. - ---- - -### `/load` or `/l` - -Load conversation history from a file. - -**Syntax**: -```bash -/load -/l -``` - -**Supported Formats**: -- JSON (`.json`) -- JSONL (`.jsonl`) -- Markdown (`.md`) - -**Examples**: - -```bash -# Load JSON session -CAI> /load pentest_session.json - -# Load JSONL data -CAI> /load conversation.jsonl - -# Using alias -CAI> /l ~/sessions/previous_work.json -``` - -**Notes**: -- Restores conversation context -- Compatible with `/save` output -- Can load partial histories - ---- - -### `/merge` or `/mrg` - -Merge agent message histories (shortcut for `/parallel merge`). - -**Syntax**: -```bash -/merge [agent1] [agent2] -/mrg -``` - -**Examples**: - -```bash -# Merge all parallel agents -CAI> /merge - -# Merge specific agents -CAI> /merge redteam_agent blueteam_agent -``` - -**Use Cases**: -- Combining parallel execution results -- Integrating different agent perspectives - ---- - -## Environment & Configuration - -### `/config` or `/cfg` - -Display and configure environment variables. - -**Syntax**: -```bash -/config [VARIABLE=value] -/config set -/cfg -``` - -**Examples**: - -```bash -# View all configuration -CAI> /config - -# Set by variable name -CAI> /config CAI_PRICE_LIMIT=10.0 -CAI> /config CAI_MAX_TURNS=50 - -# Set by number (from /config output) -CAI> /config set 18 "5.0" -``` - -**Common Configuration Variables**: - -| Variable | Description | Default | -|----------|-------------|---------| -| `CAI_MODEL` | Default model | `alias1` | -| `CAI_AGENT_TYPE` | Default agent | `redteam_agent` | -| `CAI_DEBUG` | Debug level (0-2) | `1` | -| `CAI_PRICE_LIMIT` | Cost limit (USD) | `1.0` | -| `CAI_MAX_TURNS` | Max conversation turns | `inf` | -| `CAI_MAX_INTERACTIONS` | Max tool calls | `inf` | -| `CAI_TRACING` | Enable tracing | `true` | -| `CAI_GUARDRAILS` | Security guardrails | `false` | - -**Notes**: -- Changes take effect immediately -- Use `/config` without arguments to see all options -- Numbers in first column can be used with `set` subcommand - ---- - -### `/env` or `/e` - -Display current environment variables. - -**Syntax**: -```bash -/env [pattern] -/e -``` - -**Parameters**: -- `pattern`: Optional filter pattern (e.g., "CAI", "CTF") - -**Examples**: - -```bash -# Show all environment variables -CAI> /env - -# Filter CAI-specific variables -CAI> /env CAI - -# Filter CTF variables -CAI> /env CTF -``` - ---- - -### `/workspace` or `/ws` - -Manage workspace directories. - -**Syntax**: -```bash -/workspace [path] -/ws -``` - -**Subcommands**: - -#### `show` or `pwd` -Display current workspace directory. - -```bash -/workspace show -/ws pwd -``` - -#### `set ` -Change workspace directory. - -```bash -/workspace set /path/to/project -/ws set ~/ctf_challenges -``` - -#### `list` or `ls` -List workspace contents. - -```bash -/workspace list -/ws ls -``` - -**Examples**: - -```bash -# Show current workspace -CAI> /workspace show - -# Change workspace -CAI> /workspace set /home/user/pentests - -# List files -CAI> /ws ls -``` - -**Notes**: -- Affects where shell commands execute -- Useful for CTF challenges and projects -- Works with Docker containers - ---- - -### `/virtualization` or `/virt` - -Manage Docker-based virtualization environments. - -**Syntax**: -```bash -/virtualization [arguments] -/virt -``` - -**Subcommands**: - -#### `list` -List available containers. - -```bash -/virtualization list -``` - -#### `set ` -Set active container for command execution. - -```bash -/virtualization set abc123def456 -/virt set mycontainer -``` - -#### `clear` -Return to host environment. - -```bash -/virtualization clear -``` - -#### `info` -Show current virtualization status. - -```bash -/virtualization info -``` - -**Examples**: - -```bash -# List containers -CAI> /virtualization list - -# Execute commands in container -CAI> /virt set ubuntu_ctf - -# Return to host -CAI> /virt clear -``` - -**Notes**: -- Automatically set when CTF challenges start -- Commands execute inside specified container -- Uses `CAI_ACTIVE_CONTAINER` environment variable - ---- - -## Tools & Integration - -### `/mcp` or `/m` - -Manage Model Context Protocol (MCP) servers and their tools. - -**Syntax**: -```bash -/mcp [arguments] -/m -``` - -**Subcommands**: - -#### `load ` -Load an SSE MCP server. - -```bash -/mcp load http://localhost:9876/sse burp -``` - -#### `load stdio ` -Load a STDIO MCP server. - -```bash -/mcp load stdio "npx -y @modelcontextprotocol/server-brave-search" brave -``` - -#### `list` -List active MCP connections. - -```bash -/mcp list -``` - -#### `add ` -Add MCP tools to an agent. - -```bash -/mcp add redteam_agent burp -``` - -#### `remove ` -Remove an MCP server connection. - -```bash -/mcp remove burp -``` - -#### `tools ` -List tools from an MCP server. - -```bash -/mcp tools burp -``` - -#### `status` -Check MCP server connection status. - -```bash -/mcp status -``` - -#### `associations` -Show agent-MCP associations. - -```bash -/mcp associations -``` - -**Examples**: - -```bash -# Load Burp Suite MCP server -CAI> /mcp load http://localhost:9876/sse burp - -# List MCP tools -CAI> /mcp tools burp - -# Add to current agent -CAI> /mcp add redteam_agent burp - -# Check status -CAI> /mcp status -``` - -**Common MCP Servers**: -- **Burp Suite**: Web application testing tools -- **Brave Search**: Web search capabilities -- **Filesystem**: File operations -- **Git**: Repository management -- **Postgres**: Database operations - -**Notes**: -- Extends agent capabilities dynamically -- Supports both SSE and STDIO protocols -- See [MCP Documentation](../cai/getting-started/MCP.md) for details - ---- - -### `/shell` or `/s` or `/$` - -Execute shell commands directly from the CLI. - -**Syntax**: -```bash -/shell -/s -$ -``` - -**Examples**: - -```bash -# Using /shell -CAI> /shell nmap -sV 192.168.1.1 - -# Using /s alias -CAI> /s whoami - -# Using $ shortcut -CAI> $ ls -la - -# Complex commands -CAI> $ nmap -sV -p- 192.168.1.0/24 -oN scan_results.txt -``` - -**Notes**: -- Commands execute in current workspace -- Respects `CAI_ACTIVE_CONTAINER` if set -- Output displayed in real-time -- `Ctrl+C` to interrupt running commands - ---- - -## System Management - -### `/kill` or `/k` - -Terminate active processes or stuck sessions. - -**Syntax**: -```bash -/kill -/k -``` - -**Examples**: - -```bash -# Kill current process -CAI> /kill - -# Alternative: Ctrl+C -``` - -**Use Cases**: -- Stopping stuck tool executions -- Canceling long-running operations -- Interrupting agent loops - ---- - -### `/exit` or `/quit` or `/q` - -Exit the CAI CLI. - -**Syntax**: -```bash -/exit -/quit -/q -``` - -**Examples**: - -```bash -# Exit CAI -CAI> /exit - -# Alternative: Ctrl+D -``` - -**Notes**: -- Performs clean shutdown -- Saves session logs -- Stops background processes - ---- - -### `/quickstart` - -Display setup information and quick start guide. - -**Syntax**: -```bash -/quickstart -``` - -**Examples**: - -```bash -# Show quickstart guide -CAI> /quickstart -``` - -**Notes**: -- Auto-displays on first launch -- Useful for new users -- Shows essential commands and setup - ---- - -## Parallel Execution - -### `/parallel` or `/par` or `/p` - -Manage parallel agent configurations and execution. - -**Syntax**: -```bash -/parallel [arguments] -/par -/p -``` - -**Subcommands**: - -#### `add [model]` -Add an agent to parallel configuration. - -```bash -/parallel add redteam_agent alias1 -/par add bug_bounter_agent gpt-4o -``` - -#### `remove ` -Remove an agent from parallel configuration. - -```bash -/parallel remove P1 -``` - -#### `list` -List all parallel agents. - -```bash -/parallel list -``` - -#### `clear` -Clear all parallel configurations. - -```bash -/parallel clear -``` - -#### `run ` -Execute a prompt across all parallel agents. - -```bash -/parallel run "scan 192.168.1.1 for vulnerabilities" -``` - -#### `merge` -Merge all parallel agent histories. - -```bash -/parallel merge -``` - -**Examples**: - -```bash -# Configure parallel agents -CAI> /parallel add redteam_agent alias1 -CAI> /parallel add blueteam_agent alias1 -CAI> /parallel add bug_bounter_agent gpt-4o - -# List configuration -CAI> /parallel list - -# Execute on all agents -CAI> /parallel run "analyze target.com" - -# Merge results -CAI> /parallel merge - -# Clear configuration -CAI> /parallel clear -``` - -**YAML Configuration**: - -Create `agents.yaml`: - -```yaml -agents: - - name: red1 - agent_type: redteam_agent - model: alias1 - - name: bug1 - agent_type: bug_bounter_agent - model: alias1 -``` - -Launch with YAML: - -```bash -cai --yaml agents.yaml --prompt "scan target.com" -``` - -**Notes**: -- Each agent runs independently -- Results can be merged -- Different models per agent supported -- See [Advanced Usage](advanced_usage.md) for more details - ---- - -### `/run` or `/r` - -Execute queued prompts (works with parallel mode). - -**Syntax**: -```bash -/run -/r -``` - -**Examples**: - -```bash -# Queue and run prompt -CAI> /run "analyze this binary" - -# Alternative -CAI> /r "test for XSS" -``` - -**Notes**: -- Executes immediately if agents are ready -- Queues if agents are busy -- Works with both single and parallel modes - ---- - -**Queue File Format** (`prompts.txt`): +**Example:** ```text -# Comments start with # -/agent redteam_agent -Scan 192.168.1.0/24 for open ports -Test https://target.com for vulnerabilities -$ nmap -sV 192.168.1.1 -Generate security report +CAI> /flush agent red_teamer +Cleared history for red_teamer. + +CAI> /flush all +Cleared all agent histories (and related caches per build). ``` -**Notes**: -- Prompts execute sequentially -- Supports commands and regular prompts -- Can load from files for automation +### `/compact` (`/cmp`) + +Summarize the conversation into memory. + + +| Subcommand | Arguments | Description | +| ---------- | ------------------------- | --------------------------------- | +| `model` | name / number / `default` | Model used for compaction. | +| `prompt` | text / `reset` | Custom summarization prompt. | +| `status` | โ€” | Show current compaction settings. | + + +Inline flags: `--model โ€ฆ`, `--prompt โ€ฆ`. **No args:** in parallel mode compacts all; in single-agent / TUI shows a menu. + +**Example:** + +```text +CAI> /compact status +Compaction model: default | custom prompt: (none) + +CAI> /compact +โ€ฆ summary written to memory / thread shortened (wording varies) โ€ฆ +``` + +### `/history` (`/his`) + +History with optional filtering. + + +| Subcommand | Arguments | Description | +| ---------- | --------- | ---------------------------- | +| `all` | โ€” | Full history for all agents. | +| `agent` | name | History for one agent. | +| `search` | term | Search the history. | +| `index` | โ€” | Message index. | + + +**No arguments:** interactive control panel. + +**Example:** + +```text +CAI> /history search "nmap" +โ€ฆ matching transcript excerpts โ€ฆ + +CAI> /history agent red_teamer +โ€ฆ recent messages for that agent โ€ฆ +``` + +### `/load` (`/l`) + +Load JSONL into context. + + +| Subcommand | Arguments | Description | +| ---------- | --------- | ---------------------------------- | +| `agent` | [path] | Load history for the active agent. | +| `all` | [path] | Load for all agents. | +| `parallel` | [path] | Load into parallel configuration. | +| `load-all` | โ€” | Load all available logs. | + + +**No arguments:** load from `logs/last`. + +**Example:** + +```text +CAI> /load session_2025-04-01.jsonl +Loaded conversation from session_2025-04-01.jsonl +``` + +### `/merge` (`/mrg`) + +Shortcut for `/parallel merge`. Merges parallel contexts into the main thread and exits parallel mode. + +**Example:** + +```text +CAI> /merge +โ€ฆ merged parallel branches into main; returned to single-agent mode โ€ฆ +``` + +--- + +## Memory + +### `/memory` (`/mem`) + +Persistent memory under `~/.cai/memory`. + + +| Subcommand | Arguments | Description | +| -------------- | -------------- | -------------------------------------- | +| `list` | โ€” | List saved memories. | +| `save` | [name] [agent] | Save conversation as memory. | +| `apply` | id / name | Apply memory to context. | +| `show` | id / name | Show one memoryโ€™s content. | +| `delete` | id / name | Delete a memory. | +| `remove` | id / name | Alias of `delete`. | +| `merge` | id1 id2 โ€ฆ | Merge multiple memories. | +| `status` | โ€” | Memory subsystem status. | +| `compact` | [agent] | Compact memory for an agent. | +| `clear` | โ€” | Delete all memories. | +| `list-applied` | โ€” | Memories applied to the current agent. | + + +**No arguments:** control panel. A single id such as `M001` routes to `show`. + +**Example:** + +```text +CAI> /memory list +M001 pentest-notes-20250401 12 messages +M002 ctf-web-flags 8 messages + +CAI> /memory show M001 +โ€ฆ saved memory content โ€ฆ +``` + +--- + +## Parallel execution and queues + +### `/parallel` (`/par`, `/p`) + +Configure and run parallel agents. + + +| Subcommand | Arguments | Description | +| ----------------- | ----------------------- | ------------------------------------------- | +| `add` | agent [`--model` model] | Add an agent to the parallel set. | +| `list` | โ€” | List configured parallel agents. | +| `clear` | โ€” | Remove parallel agents (no merge). | +| `remove` | agent / index | Remove one parallel agent. | +| `override-models` | model | Set a shared model for all parallel agents. | +| `merge` | [`all` / agent] | Merge contexts into the main thread. | +| `prompt` | agent / `all` `"text"` | Enqueue a prompt for agent(s). | +| `run` | โ€” | Run all enqueued prompts in parallel. | + + +**No arguments:** show current parallel configuration. + +**Example:** + +```text +CAI> /parallel list +P1 red_teamer alias1 +P2 blueteam gpt-4o + +CAI> /parallel prompt all "Enumerate TLS on target:443" +โ€ฆ prompts queued โ€ฆ + +CAI> /parallel run +โ€ฆ parallel fan-out; per-terminal output in TUI โ€ฆ +``` + +### `/queue` (`/que`) + +Sequential prompt queue. + + +| Subcommand | Arguments | Description | +| --------------- | --------- | ----------------------------- | +| `show` / `list` | โ€” | Show queued prompts. | +| `add` | `"text"` | Append a prompt. | +| `run` | โ€” | Run all prompts sequentially. | +| `remove` | index | Remove one entry. | +| `clear` | โ€” | Empty the queue. | +| `next` | โ€” | Run only the next prompt. | +| `load` | path | Load prompts from a file. | + + +**Example:** + +```text +CAI> /queue add "Run nmap -sV on 10.0.0.5" +Queued #1 + +CAI> /queue show +#1 Run nmap -sV on 10.0.0.5 + +CAI> /queue run +โ€ฆ runs prompts in order โ€ฆ +``` + +### `/continue` + +Auto-continue mode. + + +| Subcommand | Description | +| ---------- | ----------------------------- | +| `on` | Set `CAI_CONTINUE_MODE=true`. | +| `off` | Disable auto-continue. | +| `status` | Show state. | + + +**No arguments:** turns the mode **on**. + +**Example:** + +```text +CAI> /continue status +CAI_CONTINUE_MODE=false + +CAI> /continue on +Auto-continue enabled. +``` + +--- + +## Configuration and environment + +### `/env` (`/e`) + +Catalog and edit `CAI_*` and `CTF_*` variables; sensitive values are masked in listings. + + +| Subcommand | Arguments | Description | +| ---------- | ------------------------ | ----------------------------------------------------------------------------- | +| `list` | โ€” | Numbered catalog with descriptions and current values (default when helpful). | +| `get` | `VAR` or index | Print one variable's effective value. | +| `set` | `VAR` or index, `valueโ€ฆ` | Set a variable (by name or by catalog number from `list`). | +| `default` | โ€” | Restore catalog defaults where applicable. | + + +**No arguments / bare `/env`:** compact view of live `CAI_`* / `CTF_`* values (not the full numbered catalog). Piping: `/env \| grep VAR` works in supported terminals. + +Alternate assignment style (some builds): `/env set VAR=value` or multiple tokens after `set`. + +**Examples:** + +```text +CAI> /env list +โ€ฆ numbered catalog: CAI_MODEL, CAI_MAX_TURNS, CTF_NAME, โ€ฆ with current values โ€ฆ + +CAI> /env get CAI_MODEL +CAI_MODEL=alias1 + +CAI> /env set CAI_MODEL gpt-4o +Set CAI_MODEL=gpt-4o + +CAI> /env set 18 5.0 +Set variable #18 to 5.0 (index 18 from /env list) + +CAI> /env +CAI_MODEL=gpt-4o +CAI_MAX_TURNS=100 +CTF_NAME= +โ€ฆ other CAI_* / CTF_* keys in this session โ€ฆ + +CAI> /env default +โ€ฆ restored defaults where the catalog defines them โ€ฆ +``` + +### `/settings` (`/set`) + +Interactive settings and FAQ. + + +| Topic | Description | +| ------------------------------- | ------------------------- | +| `faq` / `help` / `troubleshoot` | FAQ and troubleshooting. | +| `validate` / `check` | Validate API keys. | +| `status` / `info` | System status. | +| `lang` / `language` | Language selector. | +| `ollama` / `local` | Ollama / local model FAQ. | + + +**No args:** full-screen interactive UI in CLI; TUI-adapted UI in TUI. + +**Example:** + +```text +CAI> /settings faq +โ€ฆ opens FAQ / troubleshooting flow โ€ฆ +``` + +### `/temperature` (`/temp`) + +Show or set `CAI_TEMPERATURE` (float `0.0`โ€“`2.0`). + +**Example:** + +```text +CAI> /temp +CAI_TEMPERATURE=0.7 + +CAI> /temp 0.2 +CAI_TEMPERATURE=0.2 +``` + +### `/topp` (`/top_p`) + +Show or set nucleus sampling `CAI_TOP_P` (float `0.0`โ€“`1.0`). + +**Example:** + +```text +CAI> /topp +CAI_TOP_P=1.0 + +CAI> /topp 0.9 +CAI_TOP_P=0.9 +``` + +--- + +## Integrations + +### `/mcp` + +Model Context Protocol servers. + + +| Subcommand | Arguments | Description | +| -------------- | ------------ | --------------------------------------------------------------------------- | +| `load` | url name | Load an MCP **SSE** server. | +| `load-stdio` | command name | Load an MCP **stdio** server (some builds use `/mcp load stdio โ€ฆ` instead). | +| `list` | โ€” | Active MCP connections. | +| `add-to-agent` | agent server | Attach MCP tools to an agent. | + + +Many builds also support extra helpers (`tools`, `status`, `remove`, โ€ฆ); use `/mcp help` locally. + +**Example:** + +```text +CAI> /mcp load https://example.com/mcp/sse ctf-tools +Loaded MCP server "ctf-tools" (SSE). + +CAI> /mcp list +ctf-tools SSE connected +``` + +### `/api` (`/apikey`) + +Manage `ALIAS_API_KEY` in the environment / `.env`. + + +| Subcommand | Arguments | Description | +| ---------- | --------- | ------------------------ | +| `show` | โ€” | Display key (masked). | +| `set` | key | Persist `ALIAS_API_KEY`. | + + +**No arguments:** `show`. Shortcut: `/api sk-โ€ฆ` behaves like `/api set sk-โ€ฆ`. + +**Example:** + +```text +CAI> /api +ALIAS_API_KEY=sk-โ€ฆxxxx (masked) + +CAI> /api set sk-proj-โ€ฆ +API key saved to environment / .env (path depends on build). +``` + +### `/auth` + +API users and device pairing. + + +| Subcommand | Arguments | Description | +| ---------- | ----------------- | --------------------------- | +| `add-user` | username password | Add an API user. | +| `add-ip` | ip[:port] | Register an IP for pairing. | + + +**Example:** + +```text +CAI> /auth add-user analyst hunter2 +User "analyst" created. + +CAI> /auth add-ip 203.0.113.10 +Registered pairing for 203.0.113.10 +``` + +--- + +## System and processes + +### `/shell` (`/s`, `$`) + +Run the remainder of the line as a shell command. + +Examples: `/shell ls -la`, `/s whoami`, `$ nmap -sV 10.0.0.1` + +**Example:** + +```text +CAI> $ whoami +alice + +CAI> /shell ls -la /tmp +total 12 +drwxrwxrwt โ€ฆ /tmp +``` + +### `/workspace` (`/ws`) + +Workspace (host or Docker container). + + +| Subcommand | Arguments | Description | +| ---------- | --------- | ---------------------------------- | +| `set` | path | Set working directory / workspace. | +| `get` | โ€” | Show current workspace. | +| `ls` | [path] | List files. | +| `exec` | command | Run a command in the workspace. | +| `copy` | src dst | Copy between host and container. | + + +**No arguments:** same as `get`. + +**Example:** + +```text +CAI> /ws get +Workspace: /home/alice/projects/cai-target + +CAI> /ws ls src +agent.py tools.py โ€ฆ +``` + +### `/virtualization` (`/virt`) + +Docker environments. + + +| Subcommand | Arguments | Description | +| ---------- | --------------- | ---------------- | +| `pull` | image | Pull an image. | +| `run` | image [options] | Run a container. | + + +**No arguments:** Docker status. A single non-subcommand argument can select/activate an image as container context (see `/help virtualization` on your build). + +**Example:** + +```text +CAI> /virt +Docker: running images: 12 active: cai-kali:latest + +CAI> /virt pull kalilinux/kali-rolling +โ€ฆ pull progress โ€ฆ +``` --- ## Utilities -### `/help` or `/h` or `/?` +### `/help` (`/h`, `/?`) -Display help information and command documentation. +Built-in help and topic deep-dives. -**Syntax**: -```bash -/help [command] -/h [command] -/? [command] +Example topics: `agent`, `parallel`, `queue`, `memory`, `history`, `compact`, `flush`, `load`, `merge`, `env`, `workspace`, `virtualization`, `mcp`, `shell`, `model`, `graph`, `aliases`, `commands`, `quick`, `quickstart`, `topics`. + +Examples: `/help`, `/help parallel`, `/? model` + +**Example:** + +```text +CAI> /help env +โ€ฆ environment catalog / usage for /env โ€ฆ ``` -**Examples**: +### `/cost` (`/costs`, `/usage`) -```bash -# General help -CAI> /help -# Help for specific command -CAI> /help agent -CAI> /h parallel -CAI> /? mcp -``` +| Subcommand | Description | +| ---------- | --------------------------------------- | +| `summary` | Session summary (default when no args). | +| `models` | Per-model breakdown. | +| `daily` | Daily costs. | +| `sessions` | Per-session costs. | +| `reset` | Reset counters. | -**Topics**: -- `agent`: Agent management -- `parallel`: Parallel execution -- `memory`: Memory management -- `config`: Configuration -- `mcp`: MCP integration -- `commands`: List all commands ---- +**Example:** -### `/graph` or `/g` - -Visualize agent interaction graphs. - -**Syntax**: -```bash -/graph [agent_name] -/g -``` - -**Examples**: - -```bash -# Show graph for current conversation -CAI> /graph - -# Show graph for specific agent -CAI> /graph redteam_agent -``` - -**Output**: -- Directed graph of conversations -- User and agent interactions -- Tool calls highlighted -- Conversation flow visualization - ---- - -### `/context` or `/ctx` ๐Ÿš€ **CAI PRO Exclusive** - -> **โšก CAI PRO Exclusive Feature** -> The `/context` command is available exclusively in **CAI PRO**. To access this feature and unlock advanced monitoring capabilities, visit [Alias Robotics](https://aliasrobotics.com/cybersecurityai.php) for more information. - -View context usage and token statistics for the current conversation. - -**Syntax**: -```bash -/context [agent_name] -/ctx -``` - -**Examples**: - -```bash -# Show context for current agent -CAI> /context - -# Show context for specific agent -CAI> /ctx redteam_agent -``` - -**Output Includes**: -- Total context usage (used/max tokens) with percentage -- Visual grid representation with CAI logo -- Breakdown by category: - - System prompt tokens - - Tool definitions tokens - - Memory/RAG tokens - - User prompts tokens - - Assistant responses tokens - - Tool calls tokens - - Tool results tokens -- Free space available -- Color-coded visualization - -**Notes**: -- Helps monitor token limits -- Useful for long conversations -- Different models have different context windows - ---- - -### `/cost` - -Display API usage costs and token statistics. - -**Syntax**: -```bash -/cost [agent_name] -``` - -**Examples**: - -```bash -# Show costs for current session +```text CAI> /cost +Session spend: $0.42 tokens in: 120k tokens out: 18k -# Show costs for specific agent -CAI> /cost redteam_agent - -# Show all agents' costs -CAI> /cost all +CAI> /cost models +alias1 $0.30 +gpt-4o $0.12 ``` -**Output Includes**: -- Total cost (USD) -- Input tokens used -- Output tokens used -- Cost per interaction -- Model pricing rates -- Agent breakdown +### `/graph` (`/g`) ---- -### `/save` +| Subcommand | Arguments | Description | +| ---------- | --------- | -------------- | +| `all` | โ€” | Full graph. | +| `timeline` | โ€” | Timeline view. | +| `stats` | โ€” | Statistics. | +| `export` | [path] | Export graph. | -Save current conversation to a file. -**Syntax**: -```bash -/save +**No args:** active agent view. A free argument can select `P1`, `P2`, or an agent name. + +**Example:** + +```text +CAI> /graph +โ€ฆ ASCII or Rich-rendered interaction graph for the active agent โ€ฆ ``` -**Supported Formats**: -- JSON (`.json`) -- Markdown (`.md`) +### `/exit` (`/q`, `/quit`) -**Examples**: +Clean exit: telemetry flush, session end, `sys.exit(0)`. -```bash -# Save as JSON -CAI> /save pentest_session.json +**Example:** -# Save as Markdown -CAI> /save findings_report.md - -# Full path -CAI> /save ~/sessions/project_alpha.json +```text +CAI> /exit +Goodbye. ``` -**Notes**: -- Saves all conversation history -- Includes agent names and timestamps -- Cost information preserved -- Can be loaded with `/load` +### `/quickstart` (`/qs`, `/quick`) ---- +Essential setup instructions and tables (no args). -### `/temperature` or `/temp` +**Example:** -Adjust the model's temperature parameter. - -**Syntax**: -```bash -/temperature -/temp +```text +CAI> /quickstart +โ€ฆ printed checklist: keys, /env list, /model show, agents, โ€ฆ โ€ฆ ``` -**Parameters**: -- `value`: Temperature (0.0 - 2.0) - - Lower = more deterministic - - Higher = more creative +### `/replay` -**Examples**: +Replay a session JSONL. -```bash -# Set to more deterministic -CAI> /temperature 0.2 +- Path to `.jsonl`, or no args โ†’ `logs/last`. +- Optional trailing **numeric** argument: delay in seconds between actions. +- `stop` / `cancel`: stop in-progress replay (TUI). -# Set to more creative -CAI> /temp 1.5 +Sets `CAI_DISABLE_SESSION_RECORDING=true` while replaying. -# View current temperature -CAI> /temperature +**Example:** + +```text +CAI> /replay logs/last.jsonl 0.5 +โ€ฆ replay with 0.5s delay between actions โ€ฆ +``` + +### `/resume` (`/r` when registered) + +Resume a previous session. Optional: + +- `--full` / `-f` โ€” full history. +- Path to `.jsonl`, or session id. +- No args โ€” latest session. + +**Example:** + +```text +CAI> /resume --full ./logs/session_20250401.jsonl +โ€ฆ session restored with full transcript โ€ฆ +``` + +### `/sessions` (`/sess`) + +List recent sessions; optional count limit or session id / label for details. + +**Example:** + +```text +CAI> /sessions 5 +โ€ฆ last five session ids, paths, and labels โ€ฆ +``` + +### `/ctr` + +Cyber threat reasoning / attack graphs. Optional alias form `ctr` (without leading `/`) in some builds. + + +| Subcommand | Description | +| ---------- | --------------------------- | +| `show` | Current CTR analysis. | +| `graph` | Attack graph visualization. | +| `list` | Available analyses. | +| `use` | Select an analysis. | +| `open` | Open dedicated view. | + + +**No arguments:** full CTR analysis output. + +**Example:** + +```text +CAI> /ctr show +โ€ฆ current CTR narrative / indicators โ€ฆ +``` + +### `/metadebug` (`/md`) + +Meta-agent debugging (**TUI**). Requires `CAI_META_AGENT=true`. + +**Example:** + +```text +CAI> /md +โ€ฆ meta-agent trace / routing (TUI only; requires CAI_META_AGENT=true) โ€ฆ ``` --- -### `/api` +## Quick reference table -Manage API keys and authentication. -**Syntax**: -```bash -/api [arguments] -``` +| Command | Aliases | Description | +| ----------------- | ------------------ | ----------------------------------------------------------------- | +| `/agent` | `/a` | Manage and switch agents | +| `/api` | `/apikey` | Show or set `ALIAS_API_KEY` | +| `/auth` | โ€” | API users and device pairing | +| `/compact` | `/cmp` | Compact conversation to memory | +| `/continue` | โ€” | Auto-continue mode | +| `/cost` | `/costs`, `/usage` | Usage cost statistics | +| `/ctr` | `ctr` | CTR analysis / attack graphs | +| `/env` | `/e` | Catalog / get / set / `default` for `CAI_*` and `CTF_*` variables | +| `/exit` | `/q`, `/quit` | Exit the REPL | +| `/flush` | `/clear` | Clear conversation history | +| `/graph` | `/g` | Interaction graph | +| `/help` | `/h`, `/?` | Help and documentation | +| `/history` | `/his` | History with filters | +| `/load` | `/l` | Load JSONL into context | +| `/mcp` | โ€” | MCP servers | +| `/memory` | `/mem` | Persistent memory (`~/.cai/memory`) | +| `/merge` | `/mrg` | Merge parallel contexts | +| `/metadebug` | `/md` | Meta-agent debug (TUI) | +| `/model` | `/mod` | View or change model; `show` subcommand lists LiteLLM catalog | +| `/parallel` | `/par`, `/p` | Parallel agents | +| `/queue` | `/que` | Sequential prompt queue | +| `/quickstart` | `/qs`, `/quick` | Quick start guide | +| `/replay` | โ€” | Replay JSONL session | +| `/resume` | `/r` | Resume session | +| `/sessions` | `/sess` | List recent sessions | +| `/settings` | `/set` | Interactive settings / FAQ | +| `/shell` | `/s`, `$` | Shell escape | +| `/temperature` | `/temp` | Sampling temperature | +| `/topp` | `/top_p` | Top-p sampling | +| `/virtualization` | `/virt` | Docker environments | +| `/workspace` | `/ws` | Workspace management | -**Subcommands**: -- `show`: Display configured API keys (masked) - -**Examples**: - -```bash -# Show API keys -CAI> /api show --- -## Special Features +## Commands registered -### Command Chaining +The following modules are imported in `[src/cai/repl/commands/__init__.py](../../src/cai/repl/commands/__init__.py)` in a typical OSS snapshot: `agent`, `compact`, `cost`, `env`, `exit`, `flush`, `graph`, `help`, `history`, `load`, `mcp`, `memory`, `merge`, `model`, `parallel`, `quickstart`, `shell`, `virtualization`, `workspace`. Your checkout may load extra modules; use `/help` locally for the authoritative list. -Chain multiple commands using semicolons (`;`). - -**Syntax**: -```bash -command1 ; command2 ; command3 -``` - -**Examples**: - -```bash -# Chain commands at launch -cai --prompt "/agent redteam_agent ; scan 192.168.1.1 ; /save results.json" - -# Chain in CLI -CAI> /agent bug_bounter_agent ; test https://target.com ; /cost -``` - -**Use Cases**: -- Automation workflows -- Batch operations -- Quick sequences +Commands such as `/resume`, `/queue`, `/continue`, `/settings`, `/api`, `/auth`, `/replay`, `/sessions`, `/ctr`, and `/metadebug` are listed above for completeness but may ship only in builds that add their modules to the REPL registry. --- -### Autoloading Queue from File +## Next steps -Load and execute prompts automatically on startup. - -**Environment Variable**: -```bash -export CAI_QUEUE_FILE="/path/to/prompts.txt" -``` - -**Launch**: -```bash -CAI_QUEUE_FILE=~/my_prompts.txt cai -``` - -**Notes**: -- Prompts execute automatically -- Returns to interactive mode when done -- Perfect for automation +- [CLI getting started](getting_started.md) +- [CLI advanced usage](advanced_usage.md) +- [CLI overview](cli_index.md) +- [CAI API Backend](../api.md) โ€” HTTP API when using `cai --api` --- -## Quick Reference - -### Most Used Commands - -| Command | Description | Example | -|---------|-------------|---------| -| `/agent ` | Switch agent | `/agent redteam_agent` | -| `/model ` | Change model | `/model alias1` | -| `/config` | View config | `/config` | -| `/help` | Get help | `/help agent` | -| `/save ` | Save session | `/save session.json` | -| `/load ` | Load session | `/load session.json` | -| `/cost` | Show costs | `/cost` | -| `/history` | View history | `/history 20` | -| `$ ` | Shell command | `$ nmap -sV target` | -| `/exit` | Exit CAI | `/exit` | - -### Command Aliases - -| Full Command | Aliases | -|--------------|---------| -| `/agent` | `/a` | -| `/model` | `/mod` | -| `/config` | `/cfg` | -| `/help` | `/h`, `/?` | -| `/history` | `/his` | -| `/memory` | `/mem` | -| `/workspace` | `/ws` | -| `/virtualization` | `/virt` | -| `/parallel` | `/par`, `/p` | -| `/shell` | `/s`, `/$` | -| `/context` | `/ctx` | -| `/compact` | `/cmp` | -| `/temperature` | `/temp` | -| `/load` | `/l` | -| `/merge` | `/mrg` | -| `/run` | `/r` | -| `/kill` | `/k` | -| `/exit` | `/quit`, `/q` | - ---- - -## Next Steps - -- ๐Ÿ“– [Getting Started Guide](getting_started.md) - Learn the basics -- ๐Ÿš€ [Advanced Usage](advanced_usage.md) - Automation and advanced features -- ๐Ÿ  [CLI Overview](cli_index.md) - Return to main CLI documentation - ---- - -*Last updated: November 2025 | CAI CLI v0.6+* - diff --git a/docs/cli/getting_started.md b/docs/cli/getting_started.md index a346db16..06cd4b36 100644 --- a/docs/cli/getting_started.md +++ b/docs/cli/getting_started.md @@ -71,18 +71,18 @@ export ALIAS_API_KEY="ak_live_1234567890abcdef" cai ``` -### Method 3: Runtime Configuration +### Method 3: Runtime configuration -After launching CAI, use the `/config` command: +After launching CAI, use the **`/env`** catalog: ```bash -CAI> /config CAI_MODEL=alias1 +CAI> /env set CAI_MODEL alias1 ``` -To view all current configuration: +To view the catalog with live values: ```bash -CAI> /config +CAI> /env list ``` ## Step 3: Select Your Model @@ -96,7 +96,7 @@ CAI> /model alias1 To see all available models: ```bash -CAI> /model-show +CAI> /model show ``` ### Recommended Models @@ -190,8 +190,8 @@ The agent will: ```bash # Set up CTF environment -CAI> /config CTF_NAME=hackableii -CAI> /config CTF_CHALLENGE=web_challenge +CAI> /env set CTF_NAME hackableii +CAI> /env set CTF_CHALLENGE web_challenge # Start the challenge CAI> Analyze this CTF challenge and find the flag @@ -214,12 +214,15 @@ Here are the most important commands to know: ### Getting Help ```bash -# General help +# General help (quick guide; full environment-variable tables below) CAI> /help # Help for specific command CAI> /help agent +# Long-form help for one environment variable +CAI> /help var CAI_MODEL + # Quick reference guide CAI> /quickstart ``` @@ -246,8 +249,8 @@ CAI> /model # Change model CAI> /model gpt-4o -# List all available models -CAI> /model-show +# List all available models (LiteLLM catalog) +CAI> /model show ``` ### Session Management @@ -319,23 +322,23 @@ CAI> Run a comprehensive port scan on 192.168.1.0/24 ## Step 8: Working with Configuration -### View Current Configuration +### View current configuration ```bash -CAI> /config +CAI> /env list ``` -This displays a panel with all environment variables and their current values. +This shows the environment catalog with numbers and current values. Use bare **`/env`** for a compact view of `CAI_*` / `CTF_*` only. -### Change Configuration at Runtime +### Change configuration at runtime ```bash -# Set a specific variable (use the number from /config output) -CAI> /config set 18 "5.0" +# Set by catalog index (from /env list) +CAI> /env set 18 "5.0" -# Or set by name -CAI> /config CAI_PRICE_LIMIT=5.0 -CAI> /config CAI_MAX_TURNS=50 +# Or set by variable name +CAI> /env set CAI_PRICE_LIMIT 5.0 +CAI> /env set CAI_MAX_TURNS 50 ``` ### Important Configuration Variables @@ -480,7 +483,7 @@ CAI> /help CAI> /cost # Increase limit -CAI> /config CAI_PRICE_LIMIT=20.0 +CAI> /env set CAI_PRICE_LIMIT 20.0 # Or set it before launching CAI_PRICE_LIMIT=20.0 cai @@ -491,7 +494,7 @@ CAI_PRICE_LIMIT=20.0 cai **Solution**: ```bash # Increase turn limit -CAI> /config CAI_MAX_TURNS=100 +CAI> /env set CAI_MAX_TURNS 100 # Or flush history and start fresh CAI> /flush @@ -530,7 +533,8 @@ Congratulations! You've completed the basics of CAI CLI. Here's what to explore /agent list # List all agents /agent # Switch agent /model # Change model -/config # View configuration +/model show # LiteLLM model catalog +/env list # Catalog + live values /help # Get help /save # Save session /load # Load session diff --git a/docs/council.md b/docs/council.md deleted file mode 100644 index 7252b460..00000000 --- a/docs/council.md +++ /dev/null @@ -1,295 +0,0 @@ -# LLM Council - -The LLM Council is a multi-model consensus system that queries multiple AI models, has them evaluate each other's responses, and synthesizes a final answer through a chairman. This approach improves accuracy for complex decisions by leveraging diverse model perspectives. - -## How It Works - -The council operates in three stages: - -``` -User Query: "What's the best approach for this security task?" -โ”‚ -โ”œโ”€ Stage 1: Council Members (parallel) -โ”‚ โ”œโ”€ Agent + gpt-4o โ†’ Text response only -โ”‚ โ”œโ”€ Agent + gpt-5 โ†’ Text response only -โ”‚ โ””โ”€ Agent + claude-sonnet-4-5 โ†’ Text response only -โ”‚ -โ”œโ”€ Stage 2: Rankings (parallel) -โ”‚ โ”œโ”€ Agent + gpt-4o โ†’ Ranks anonymized responses -โ”‚ โ”œโ”€ Agent + gpt-5 โ†’ Ranks anonymized responses -โ”‚ โ””โ”€ Agent + claude-sonnet-4-5 โ†’ Ranks anonymized responses -โ”‚ -โ””โ”€ Stage 3: Chairman - โ””โ”€ Active Agent + TOOLS - โ”œโ”€ Synthesizes best answer - โ””โ”€ Can execute operations if requested -``` - -**Key Points:** - -- **Stage 1 & 2**: Council members provide text-only responses (no tool execution) -- **Stage 3**: The chairman (your active agent) can use all available tools -- All members use the current agent's instructions and context - -## Quick Start - -```bash -# Configure council models -export CAI_COUNCIL="gpt-4o,gpt-5,claude-sonnet-4-20250514" - -# In CAI REPL, load an agent first -CAI> /agent redteam - -# Use the council command -CAI> /council What are the best practices for API security? - -# Or use the short alias -CAI> /c How should I approach this vulnerability assessment? -``` - -## Configuration - -### Environment Variables - -| Variable | Description | Default | -|----------|-------------|---------| -| `CAI_COUNCIL` | Comma-separated list of council member models | `gpt-4o,gpt-4o-mini` | -| `CAI_COUNCIL_AUTO` | Auto-convene setting: `false`, `true`/`1`, or interval number | `false` | -| `CAI_COUNCIL_PROMPT` | Custom prompt for auto-council reviews | See below | -| `CAI_COUNCIL_DEBUG` | Enable debug output (`1`, `true`, `yes`) | `false` | - -```bash -# Example configuration -export CAI_COUNCIL="gpt-4o,gpt-5,claude-sonnet-4-20250514" -export CAI_COUNCIL_AUTO="5" -export CAI_COUNCIL_PROMPT="Review the current progress and recommend the best approach." -export CAI_COUNCIL_DEBUG="1" -``` - -### API Keys - -Ensure you have the appropriate API keys set for your council models: - -```bash -export OPENAI_API_KEY="sk-..." -export ANTHROPIC_API_KEY="sk-ant-..." -export ALIAS_API_KEY="..." -``` - -### Verified Model Names - -Use exact model names as shown in the `/model` command: - -| Provider | Models | -|----------|--------| -| OpenAI | `gpt-5`, `gpt-4o`, `gpt-4o-mini`, `o3-mini` | -| Anthropic | `claude-sonnet-4-20250514`, `claude-3-5-sonnet-20240620` | -| Alias | `alias1` | -| DeepSeek | `deepseek-v3`, `deepseek-r1` | - -## Manual Usage - -The `/council` command (alias `/c`) invokes the council manually: - -```bash -# Load an agent -CAI> /agent redteam - -# Ask the council -CAI> /council What vulnerabilities should I look for in this web application? -``` - -The council uses the active agent's: - -- Instructions/system prompt -- Available tools (chairman only) -- Guardrails - -## Auto-Council Mode - -When `CAI_COUNCIL_AUTO` is enabled, the council convenes automatically at specified intervals during agent execution. - -### Configuration Options - -- `false` - Never auto-convene (use `/council` manually) -- `true` or `1` - Convene at every agent interaction -- `5`, `10`, etc. - Convene every N interactions - -### Example: Every Interaction - -```bash -export CAI_COUNCIL_AUTO="1" - -CAI> run ps aux, then analyze the results, then check for vulnerabilities - -๐Ÿ›๏ธ COUNCIL (auto-invoked at interaction [1]) -[Stage 1, 2, 3 run...] -[1] Agent: "I'll run ps aux" โ†’ executes command - -๐Ÿ›๏ธ COUNCIL (auto-invoked at interaction [2]) -[Stage 1, 2, 3 run...] -[2] Agent: "Analyzing results..." โ†’ analyzes output - -๐Ÿ›๏ธ COUNCIL (auto-invoked at interaction [3]) -[Stage 1, 2, 3 run...] -[3] Agent: "Checking for vulnerabilities..." โ†’ performs check -``` - -### Example: Every 5 Interactions - -```bash -export CAI_COUNCIL_AUTO="5" - -CAI> perform a comprehensive security audit - -[1] Agent executes first task -[2] Agent executes second task -[3] Agent executes third task -[4] Agent executes fourth task - -๐Ÿ›๏ธ COUNCIL (auto-invoked at interaction [5]) -[Stage 1, 2, 3 run...] -[5] Agent executes fifth task - -[6] Agent continues... -[7] Agent continues... -[8] Agent continues... -[9] Agent continues... - -๐Ÿ›๏ธ COUNCIL (auto-invoked at interaction [10]) -[Stage 1, 2, 3 run...] -[10] Agent executes tenth task -``` - -## Programmatic Usage - -You can use the council directly in Python code: - -```python -from cai.council import run_full_council_agents, CouncilAgentConfig -from cai.sdk.agents import Agent - -# With an existing agent -stage1, stage2, stage3, metadata = await run_full_council_agents( - base_agent=my_agent, - user_query="Your question here", -) - -# Access results -print(stage3["response"]) # Final answer -print(metadata["aggregate_rankings"]) # Model rankings -print(metadata["council_cost"]) # Total cost -print(metadata["council_input_tokens"]) # Input tokens -print(metadata["council_output_tokens"]) # Output tokens -``` - -### Return Values - -```python -stage1_results: List[Dict] # Individual responses from each model -stage2_results: List[Dict] # Rankings from each model -stage3_result: Dict # Final synthesized answer -metadata: Dict # Rankings, cost, tokens -``` - -### Metadata Structure - -```python -metadata = { - "aggregate_rankings": [ - {"model": "gpt-4o", "average_rank": 1.33, "rankings_count": 3}, - {"model": "gpt-5", "average_rank": 2.0, "rankings_count": 3}, - ], - "council_cost": 0.032, - "council_input_tokens": 5000, - "council_output_tokens": 2500, -} -``` - -## Visual Display - -During execution, the council shows an animated panel with progress: - -``` -โ•ญโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ Alias Council โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ -โ”‚ โ”‚ -โ”‚ ๐Ÿ‘‘ Chairman: Red Team Agent (gpt-4o) โ”‚ -โ”‚ โ”‚ -โ”‚ โ ‹ Stage 1: Collecting responses from council members โ”‚ -โ”‚ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ 2/3 โ”‚ -โ”‚ โœ“ gpt-4o โ”‚ -โ”‚ โœ“ gpt-5 โ”‚ -โ”‚ โ ‹ alias1 โ”‚ -โ”‚ โ”‚ -โ”‚ โ—‹ Stage 2: Waiting... โ”‚ -โ”‚ โ”‚ -โ”‚ ๐Ÿ’ฐ $0.012 (1.2k in / 800 out) โฑ 15.2s โ”‚ -โ”‚ โ”‚ -โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ -``` - -## Performance Considerations - -| Metric | Single Query | Council (3 models) | -|--------|--------------|-------------------| -| API Calls | 1 | ~7 (2N + 1) | -| Cost | 1x | 3-4x | -| Latency | 1x | 2-3x | -| Accuracy | Base | Improved | - -!!! tip "When to Use Council" - Use the council when accuracy matters more than speed or cost. It's particularly valuable for: - - - Complex security decisions - - Architecture recommendations - - Vulnerability assessments - - Strategic planning tasks - -## Troubleshooting - -### Debug Mode - -Enable detailed logging to diagnose issues: - -```bash -export CAI_COUNCIL_DEBUG=1 -``` - -### Common Issues - -**"All models failed to respond"** - -- Verify API keys are set correctly -- Check model names with `/model` command -- Check for rate limiting - -**Council hangs on Stage 1** - -- Model name might be incorrect (verify with `/model`) -- API key invalid or missing -- Network connectivity issues - -**"Temperature not supported"** - -- Handled automatically for GPT-5/O1/O3 models (temperature set to 1) - -### Test Individual Models - -Before using council, verify each model works independently: - -```bash -CAI> /model gpt-4o -CAI> What is 2+2? -``` - -### Minimal Configuration - -If experiencing issues, try a minimal setup: - -```bash -export CAI_COUNCIL="gpt-4o,gpt-4o-mini" -``` - -## Credits - -Inspired by [llm-council](https://github.com/karpathy/llm-council) by Andrej Karpathy. diff --git a/docs/environment_variables.md b/docs/environment_variables.md index b94a5ded..d145329b 100644 --- a/docs/environment_variables.md +++ b/docs/environment_variables.md @@ -4,39 +4,76 @@ This comprehensive guide documents all environment variables available in CAI, i --- +## ๐Ÿ”Ž Discovering variables in the REPL + +In current CAI releases, you can explore environment variables **from inside the interactive CLI** without leaving the session: + +| What you need | Command | +|---------------|---------| +| **Numbered catalog with live values** (what is set *now*) | `/env list` | +| **Session keys only** (`CAI_*` / `CTF_*` in this process) | `/env` (no arguments) | +| **Full reference tables** (defaults, allowed values, when they apply, extras) | `/help` โ€” scroll past the quick guide; or `/help topics` for the overview first, then the same tables at the end | +| **Long-form help for one variable** (examples, catalog index when listed, notes) | `/help var VARIABLE_NAME` (e.g. `/help var CAI_MODEL`, `/help var CAI_AVOID_SUDO`) | + +Aliases such as `/h` for `/help` work the same way. This page remains the **canonical web reference**; the REPL output tracks the version you have installed. + +--- + +## ๐Ÿ“– Fields explained (same model as `/help var NAME`) + +In the REPL, **`/help var VARIABLE_NAME`** expands each variable with the same ideas used below: + +| Field | Meaning | +|-------|---------| +| **Description** | What the variable controls (see the next table). | +| **Values** | Value *type* or documented range (e.g. `bool`, `int 0โ€“2`, `string`) โ€” same notion as the **Values** column in the large `/help` tables. | +| **When** | **Runtime** โ€” often picked up on each use via `os.getenv`. **Restart** โ€” typically read only at process start (new session recommended). **Mixed** โ€” in `os.environ` but parts of CAI may cache until the next turn, agent switch, or restart. | +| **Default** | Documented default when unset or as shipped. | + +**How to set (matches `/help` copy):** + +- Before launch: `export VAR=value` or a line in `.env`, then start CAI. +- During a session: `/env set <#|NAME> `, `/env default`, or code updating `os.environ`. + +**Types (short):** *bool* โ€” `true`/`false`, `1`/`0`, etc.; *string* โ€” free text; *int* / *float* โ€” numeric; ranges in **Values** are the usual bounds CAI documents; *secret* โ€” treat like a string, never commit real keys. + +For **numbered catalog index**, **extra notes**, and **copy-paste examples** per variable, use **`/help var NAME`** in the REPL โ€” the web page keeps one compact table for browsing. + +--- + ## ๐Ÿ“‹ Complete Reference Table -| Variable | Description | Default | -|----------|-------------|---------| -| CTF_NAME | Name of the CTF challenge to run (e.g. "picoctf_static_flag") | - | -| CTF_CHALLENGE | Specific challenge name within the CTF to test | - | -| CTF_SUBNET | Network subnet for the CTF container | 192.168.3.0/24 | -| CTF_IP | IP address for the CTF container | 192.168.3.100 | -| CTF_INSIDE | Whether to conquer the CTF from within container | true | -| CAI_MODEL | Model to use for agents | alias1 | -| CAI_DEBUG | Set debug output level (0: Only tool outputs, 1: Verbose debug output, 2: CLI debug output) | 1 | -| CAI_BRIEF | Enable/disable brief output mode | false | -| CAI_MAX_TURNS | Maximum number of turns for agent interactions | inf | -| CAI_MAX_INTERACTIONS | Maximum number of interactions (tool calls, agent actions, etc.) allowed in a session. If exceeded, only CLI commands are allowed until increased. If force_until_flag=true, the session will exit | inf | -| CAI_PRICE_LIMIT | Price limit for the conversation in dollars. If exceeded, only CLI commands are allowed until increased. If force_until_flag=true, the session will exit | 1 | -| CAI_TRACING | Enable/disable OpenTelemetry tracing. When enabled, traces execution flow and agent interactions for debugging and analysis | true | -| CAI_AGENT_TYPE | Specify the agents to use (e.g., boot2root, one_tool, redteam_agent). Use "/agent" command in CLI to list all available agents | redteam_agent | -| CAI_STATE | Enable/disable stateful mode. When enabled, the agent will use a state agent to keep track of the state of the network and the flags found | false | -| CAI_MEMORY | Enable/disable memory mode (episodic: use episodic memory, semantic: use semantic memory, all: use both episodic and semantic memory) | false | -| CAI_MEMORY_ONLINE | Enable/disable online memory mode | false | -| CAI_MEMORY_OFFLINE | Enable/disable offline memory | false | -| CAI_ENV_CONTEXT | Add environment context, dirs and current env available | true | -| CAI_MEMORY_ONLINE_INTERVAL | Number of turns between online memory updates | 5 | -| CAI_SUPPORT_MODEL | Model to use for the support agent | o3-mini | -| CAI_SUPPORT_INTERVAL | Number of turns between support agent executions | 5 | -| CAI_STREAM | Enable/disable streaming output in rich panel | false | -| CAI_TELEMETRY | Enable/disable telemetry | true | -| CAI_PARALLEL | Number of parallel agent instances to run. When set to values greater than 1, executes multiple instances of the same agent in parallel and displays all results | 1 | -| CAI_GUARDRAILS | Enable/disable security guardrails for agents. When set to "true", applies security guardrails to prevent potentially dangerous outputs and inputs | false | -| CAI_GCTR_NITERATIONS | Number of tool interactions before triggering GCTR (Generative Cut-The-Rope) analysis in bug_bounter_gctr agent. Only applies when using gctr-enabled agents | 5 | -| CAI_ACTIVE_CONTAINER | Docker container ID where commands should be executed. When set, shell commands and tools execute inside the specified container instead of the host. Automatically set when CTF challenges start (if CTF_INSIDE=true) or when switching containers via /virtualization command | - | -| CAI_TOOL_TIMEOUT | Override the default timeout for tool command executions in seconds. When set, this value overrides all default timeouts for shell commands and tool executions | varies (10s for interactive, 100s for regular) | -| C99_API_KEY | API key for C99.nl subdomain discovery service. Required for using the C99 reconnaissance tool for DNS enumeration and subdomain discovery. Obtain from [C99.nl](https://c99.nl) | - | +| Variable | Description | Values | When | Default | +|----------|-------------|------|------|---------| +| CTF_NAME | Name of the CTF challenge to run (e.g. "picoctf_static_flag") | string | Mixed | - | +| CTF_CHALLENGE | Specific challenge name within the CTF to test | string | Mixed | - | +| CTF_SUBNET | Network subnet for the CTF container | string | Mixed | 192.168.3.0/24 | +| CTF_IP | IP address for the CTF container | string | Mixed | 192.168.3.100 | +| CTF_INSIDE | Whether to conquer the CTF from within container | bool | Mixed | true | +| CAI_MODEL | Model to use for agents | string | Mixed | alias1 | +| CAI_DEBUG | Set debug output level (0: Only tool outputs, 1: Verbose debug output, 2: CLI debug output) | int 0โ€“2 | Mixed | 1 | +| CAI_BRIEF | Enable/disable brief output mode | bool | Mixed | false | +| CAI_MAX_TURNS | Maximum number of turns for agent interactions | int โ‰ฅ1 | Mixed | inf | +| CAI_MAX_INTERACTIONS | Maximum number of interactions (tool calls, agent actions, etc.) allowed in a session. If exceeded, only CLI commands are allowed until increased. If force_until_flag=true, the session will exit | int โ‰ฅ1 | Mixed | inf | +| CAI_PRICE_LIMIT | Price limit for the conversation in dollars. If exceeded, only CLI commands are allowed until increased. If force_until_flag=true, the session will exit | float โ‰ฅ0 | Mixed | 1 | +| CAI_TRACING | Enable/disable OpenTelemetry tracing. When enabled, traces execution flow and agent interactions for debugging and analysis | bool | Restart | true | +| CAI_AGENT_TYPE | Specify the agents to use (e.g., boot2root, one_tool, redteam_agent). Use "/agent" command in CLI to list all available agents | string | Mixed | redteam_agent | +| CAI_STATE | Enable/disable stateful mode. When enabled, the agent will use a state agent to keep track of the state of the network and the flags found | bool | Mixed | false | +| CAI_MEMORY | Enable/disable memory mode (episodic: use episodic memory, semantic: use semantic memory, all: use both episodic and semantic memory) | string | Mixed | false | +| CAI_MEMORY_ONLINE | Enable/disable online memory mode | bool | Mixed | false | +| CAI_MEMORY_OFFLINE | Enable/disable offline memory | bool | Mixed | false | +| CAI_ENV_CONTEXT | Add environment context, dirs and current env available | bool | Mixed | true | +| CAI_MEMORY_ONLINE_INTERVAL | Number of turns between online memory updates | int | Mixed | 5 | +| CAI_SUPPORT_MODEL | Model to use for the support agent | string | Mixed | o3-mini | +| CAI_SUPPORT_INTERVAL | Number of turns between support agent executions | int | Mixed | 5 | +| CAI_STREAM | Enable/disable streaming output in rich panel | bool | Runtime | false | +| CAI_TELEMETRY | Enable/disable telemetry | bool | Restart | true | +| CAI_PARALLEL | Number of parallel agent instances to run. When set to values greater than 1, executes multiple instances of the same agent in parallel and displays all results | int 1โ€“20 | Mixed | 1 | +| CAI_GUARDRAILS | Enable/disable security guardrails for agents. When set to "true", applies security guardrails to prevent potentially dangerous outputs and inputs | bool | Runtime | false | +| CAI_GCTR_NITERATIONS | Number of tool interactions before triggering GCTR (Generative Cut-The-Rope) analysis in bug_bounter_gctr agent. Only applies when using gctr-enabled agents | int | Mixed | 5 | +| CAI_ACTIVE_CONTAINER | Docker container ID where commands should be executed. When set, shell commands and tools execute inside the specified container instead of the host. Automatically set when CTF challenges start (if CTF_INSIDE=true) or when switching containers via /virtualization command | string | Mixed | - | +| CAI_TOOL_TIMEOUT | Override the default timeout for tool command executions in seconds. When set, this value overrides all default timeouts for shell commands and tool executions | int (s) | Runtime | varies (10s for interactive, 100s for regular) | +| C99_API_KEY | API key for C99.nl subdomain discovery service. Required for using the C99 reconnaissance tool for DNS enumeration and subdomain discovery. Obtain from [C99.nl](https://c99.nl) | string | Mixed | - | --- @@ -149,6 +186,9 @@ CAI_GUARDRAILS="true" # Prevent dangerous commands CAI_PRICE_LIMIT="1" # Maximum cost in dollars CAI_MAX_INTERACTIONS="inf" # Maximum allowed interactions +# Shell privilege policy (generic Linux tool) +CAI_AVOID_SUDO="true" # Block sudo/su/pkexec/doas (hard block; see /help var CAI_AVOID_SUDO) + # Debugging & monitoring CAI_DEBUG="1" # 0: minimal, 1: verbose, 2: CLI debug CAI_TRACING="true" # Enable OpenTelemetry tracing @@ -156,6 +196,7 @@ CAI_TRACING="true" # Enable OpenTelemetry tracing **Security Layers:** - **Guardrails**: Prompt injection detection and command validation +- **`CAI_AVOID_SUDO`**: Blocks privilege escalation in the generic Linux shell tool; use `/help var CAI_AVOID_SUDO` for examples and session vs. launch notes - **Cost Limits**: Prevent runaway API usage - **Interaction Limits**: Control agent autonomy @@ -357,5 +398,6 @@ CAI_MODEL="gpt-4o" CAI_PRICE_LIMIT="2" cai ``` **3. Runtime configuration** -Use CLI commands to modify settings during execution. See [Commands Reference](cai/getting-started/commands.md). + +Use slash commands during a session: `/env`, `/env list`, `/env set โ€ฆ`, and the in-session help above (`/help`, `/help var โ€ฆ`). See [Commands Reference](cai/getting-started/commands.md) and [CLI Commands Reference](cli/commands_reference.md). diff --git a/docs/index.md b/docs/index.md index 0146910e..f227506a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -35,7 +35,7 @@ A lightweight, ergonomic framework for building bug bounty-ready Cybersecurity A - โœ… **Unlimited `alias1` tokens** - Our state-of-the-art cybersecurity model that beats GPT-5 in benchmarks - โœ… **Mobile User Interface (iOS)** - Native iOS app for security testing on the go - **[Join TestFlight Beta](https://testflight.apple.com/join/nXZZD4Z5)** - โœ… **Terminal User Interface (TUI)** - Multi-agent parallel execution with visual monitoring *(Deprecated - Use Mobile UI)* -- โœ… **Context Monitoring** - Real-time token tracking and optimization +- โœ… **Usage visibility** - `/cost`, compaction, and TUI cost indicators - โœ… **Zero Refusals** - Unrestricted AI specifically trained for offensive security - โœ… **European Hosting** - GDPR & NIS2 compliant with guaranteed data privacy - โœ… **Professional Support** - Dedicated technical assistance from security experts diff --git a/docs/providers/ollama_cloud.md b/docs/providers/ollama_cloud.md index 6498731e..3204b9da 100644 --- a/docs/providers/ollama_cloud.md +++ b/docs/providers/ollama_cloud.md @@ -25,7 +25,7 @@ cai ## Available Models -View in CAI with `/model-show` under "Ollama Cloud" category: +View in CAI with `/model show` under "Ollama Cloud" category: - `ollama_cloud/gpt-oss:120b` - General purpose 120B model - `ollama_cloud/llama3.3:70b` - Llama 3.3 70B @@ -40,7 +40,7 @@ More models at [ollama.com/library](https://ollama.com/library). # By name CAI> /model ollama_cloud/gpt-oss:120b -# By number (after /model-show) +# By number (after /model show) CAI> /model 3 ``` diff --git a/docs/tui/commands_reference.md b/docs/tui/commands_reference.md index 46defda0..25b71327 100644 --- a/docs/tui/commands_reference.md +++ b/docs/tui/commands_reference.md @@ -5,6 +5,9 @@ --- +!!! tip "Recommended: use the CLI REPL" + The command matrix for every `cai` binary flag and REPL slash command is maintained in the **[CLI commands reference](../cli/commands_reference.md)**. **When in doubtโ€”especially for scripting, copy-paste examples, or comparing subcommandsโ€”use the plain CLI REPL** and the CLI reference. The TUI shares the same underlying engine; this document focuses on **multi-terminal UX**, keyboard shortcuts, palette actions, and behaviors that differ from the CLI. + This comprehensive guide documents all commands available in the CAI Terminal User Interface (TUI), including command palette actions, keyboard shortcuts, and CLI-style commands. --- @@ -23,19 +26,40 @@ CAI TUI commands are organized into the following categories: --- +## CLI parity and TUI-only differences + +The [CLI commands reference](../cli/commands_reference.md) is the **authoritative** list for REPL slash commands. The TUI reuses the same slash commands, but a few interactions differ: + + +| Situation | CLI REPL | TUI | +| ------------------------------------------ | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | +| `/flush` or `/clear` with **no** arguments | Interactive menu of agents that still have history | Clears history for the **focused terminal only** | +| `/agent` with no arguments | Same as `/agent current` | Shows the active agent configuration across terminals where applicable | +| Screen vs history | N/A | **Ctrl+L** / visual โ€œclearโ€ only affects scrollback; it does **not** replace `/flush` for wiping message history | + + +For binary flags such as `--tui`, `--yaml`, or `--api`, see [Binary `cai` CLI flags](../cli/commands_reference.md#binary-cai-cli-flags). + +--- + ## Agent Management ### `/agent` or `/a` Switch between agents or list all available agents. +!!! note "CLI reference vs TUI examples" + The CLI reference documents `/agent` with explicit subcommands (`list`, `select`, `info`, `current`, โ€ฆ). In the TUI you will often see the shorthand `/agent `; on many builds that is equivalent to `/agent select `. For exact syntax and flags, follow the **[CLI commands reference](../cli/commands_reference.md#agent-a)**. + **Syntax**: + ``` /agent [agent_name] /a [agent_name] ``` **Examples**: + ```bash # List all available agents /agent @@ -48,6 +72,7 @@ Switch between agents or list all available agents. ``` **Available Agents**: + - `redteam_agent` - Offensive security testing and penetration testing - `blueteam_agent` - Defensive security analysis and hardening - `bug_bounter_agent` - Bug bounty hunting and vulnerability research @@ -72,6 +97,7 @@ Switch between agents or list all available agents. - `offsec_pattern` - Offensive security pattern orchestration **Notes**: + - Agent changes are immediate and affect only the active terminal - Each terminal can run a different agent simultaneously - Agent context is preserved when switching between terminals @@ -85,6 +111,7 @@ Switch between agents or list all available agents. CAI TUI uses model dropdowns in each terminal header for model management. Models are configured via environment variables and aliases. **Available Models**: + - `alias1` - Cybersecurity focus model [Recommended] - `gpt-4o` - OpenAI GPT-4 Optimized - `gpt-4-turbo` - OpenAI GPT-4 Turbo @@ -93,11 +120,13 @@ CAI TUI uses model dropdowns in each terminal header for model management. Model - `o1-preview` - OpenAI O1 Preview **How to Change Models**: + 1. Click the model dropdown in any terminal header 2. Select desired model from the list 3. Model change takes effect immediately for that terminal **Environment Variables**: + ```bash export CAI_MODEL=gpt-4o # Set default model export CAI_OPENAI_API_KEY=sk-... # OpenAI API key @@ -105,6 +134,7 @@ export CAI_ANTHROPIC_API_KEY=sk-... # Anthropic API key ``` **Notes**: + - Each terminal can use a different model - Model costs are tracked separately per terminal - Switching models mid-conversation preserves history @@ -120,11 +150,13 @@ Send commands to specific terminals using either the prefix notation or the flag #### Method 1: Prefix Notation **Syntax**: + ``` T: ``` **Examples**: + ```bash # Switch agent in Terminal 2 T2:/agent blueteam_agent @@ -138,6 +170,7 @@ T1:/clear # Execute command in Terminal 4 T4:scan target.com for vulnerabilities ``` + #### Method 2: Flag Notation **Syntax**: @@ -148,6 +181,7 @@ T4:scan target.com for vulnerabilities ``` **Examples**: + ```bash # Switch agent in Terminal 2 /agent blueteam_agent t2 @@ -166,6 +200,7 @@ Scan target.com for XSS vulnerabilities t2 ``` **Supported Flags**: + - `t1` - Target Terminal 1 - `t2` - Target Terminal 2 - `t3` - Target Terminal 3 @@ -173,6 +208,7 @@ Scan target.com for XSS vulnerabilities t2 - (Additional terminals if configured: `t5`, `t6`, etc.) **Notes**: + - Both methods achieve the same result - Flag notation is more concise for quick commands - Prefix notation is clearer for complex prompts @@ -183,6 +219,7 @@ Scan target.com for XSS vulnerabilities t2 **Keyboard Shortcut**: Click the `[+]` button in the top bar **Notes**: + - New terminals start with `redteam_agent` by default - Maximum recommended terminals: 4 (for optimal UX) - Terminals beyond 4 use scrollable layout @@ -191,16 +228,18 @@ Scan target.com for XSS vulnerabilities t2 ## History and Memory -### `/history [number] [agent_name]` or `/h` +### `/history [number] [agent_name]` or `/his` -Display conversation history for the current or specified agent. +Display conversation history for the current or specified agent. (Use `/his` โ€” `/h` is reserved for `/help` on builds that follow the documented alias table.) **Syntax**: + ``` /history [number] [agent_name] ``` **Examples**: + ```bash # Show last 10 messages /history @@ -212,24 +251,27 @@ Display conversation history for the current or specified agent. /history 10 redteam_agent # Compact syntax -/h 5 +/his 5 ``` **Notes**: + - Default shows last 10 interactions - History includes both user prompts and agent responses - History is terminal-specific -### `/flush [agent_name|all]` +### `/flush [agent_name|all]` or `/clear` -Clear agent message history. +Clear agent message history (`/clear` is an alias of `/flush` for history, not the same as clearing the screenโ€”see below). **Syntax**: + ``` /flush [agent_name|all] ``` **Examples**: + ```bash # Flush current agent history /flush @@ -242,15 +284,18 @@ Clear agent message history. ``` **Notes**: + - Flushing is irreversible - Agent context window is reset - Useful for starting fresh conversations +- **TUI:** with **no** arguments, `/flush` typically affects only the **focused** terminal (see [CLI parity and TUI-only differences](#cli-parity-and-tui-only-differences)). The CLI may instead show a pickerโ€”confirm with `/help flush` on your build. ### `/memory [subcommand]` or `/mem` Advanced memory management for agents. **Syntax**: + ``` /memory /mem @@ -259,55 +304,72 @@ Advanced memory management for agents. **Subcommands**: #### `list` + Show all saved memories. + ```bash /memory list ``` #### `save [name]` + Save current conversation as a memory. + ```bash /memory save "Authentication bypass research" /mem save pentest_findings ``` #### `apply ` + Apply a saved memory to the current agent. + ```bash /memory apply mem_12345 ``` #### `show ` + Display the content of a specific memory. + ```bash /memory show mem_12345 ``` #### `delete ` + Remove a memory permanently. + ```bash /memory delete mem_12345 ``` #### `merge [name]` + Combine two memories into one. + ```bash /memory merge mem_12345 mem_67890 "Combined pentesting notes" ``` #### `compact` + AI-powered memory summarization. + ```bash /memory compact ``` #### `status` + Show memory system status and statistics. + ```bash /memory status ``` **Notes**: + - Memories persist across sessions - Useful for resuming long-term research projects - AI-powered summarization reduces token usage @@ -321,15 +383,18 @@ Show memory system status and statistics. Save the current conversation to a file. **Syntax**: + ``` /save ``` **Supported Formats**: + - JSON (`.json`) - Markdown (`.md`) **Examples**: + ```bash # Save as JSON /save pentest_session.json @@ -342,6 +407,7 @@ Save the current conversation to a file. ``` **Notes**: + - Saves all terminal conversations - Includes agent names, models, and timestamps - Cost information is preserved @@ -351,12 +417,14 @@ Save the current conversation to a file. Load a previously saved conversation. **Syntax**: + ``` /load /l ``` **Examples**: + ```bash # Load JSON session /load pentest_session.json @@ -369,6 +437,7 @@ Load a previously saved conversation. ``` **Notes**: + - Restores agent context and history - Compatible with both JSON and Markdown formats - Loading does not affect current cost tracking @@ -377,61 +446,20 @@ Load a previously saved conversation. ## Utility Commands -### `/context [agent_name]` or `/ctx` ๐Ÿš€ **CAI PRO Exclusive** - -> **โšก CAI PRO Exclusive Feature** -> The `/context` command is available exclusively in **[CAI PRO](https://aliasrobotics.com/cybersecurityai.php)**. To access this feature and unlock advanced monitoring capabilities, visit [Alias Robotics](https://aliasrobotics.com/cybersecurityai.php) for more information. - -Display context window usage and token statistics for the current conversation. - -**Syntax**: -``` -/context [agent_name] -/ctx [agent_name] -``` - -**Examples**: -```bash -# Show context usage for active terminal -/context - -# Show context usage for specific agent -/context redteam_agent - -# Compact syntax -/ctx -``` - -**Output Includes**: -- Total context usage (used/max tokens) with percentage -- Visual grid representation with CAI logo -- Breakdown by category: - - System prompt tokens - - Tool definitions tokens - - Memory files (RAG) tokens - - User prompts tokens - - Assistant responses tokens - - Tool calls tokens - - Tool results tokens -- Free space available -- Color-coded visualization for easy identification - -**Notes**: -- Context usage helps monitor when you're approaching model limits -- Different models have different context windows (e.g., GPT-4: 128k, Claude: 200k) -- Use `/context` regularly during long conversations to avoid hitting limits -- Context usage is terminal-specific in TUI mode +For spend and token usage use **`/cost`** (and the per-terminal cost UI in the TUI). When threads grow too long, use **`/compact`**. See the [CLI commands reference](../cli/commands_reference.md) for the full command list. ### `/cost [agent_name]` Display API usage costs and token statistics. **Syntax**: + ``` /cost [agent_name] ``` **Examples**: + ```bash # Show costs for active terminal /cost @@ -444,6 +472,7 @@ Display API usage costs and token statistics. ``` **Output Includes**: + - Total cost (USD) - Input tokens used - Output tokens used @@ -456,12 +485,14 @@ Display API usage costs and token statistics. Get help for commands. **Syntax**: + ``` /help [command] /? [command] ``` **Examples**: + ```bash # General help /help @@ -477,11 +508,13 @@ Get help for commands. Display environment variables relevant to CAI. **Syntax**: + ``` /env ``` **Output Includes**: + - `CAI_MODEL` - Default model - `CAI_AGENT_TYPE` - Default agent - `CAI_MAX_TURNS` - Maximum interaction turns @@ -496,12 +529,14 @@ Display environment variables relevant to CAI. Execute shell commands directly from the TUI. **Syntax**: + ``` /shell $ ``` **Examples**: + ```bash # List files /shell ls -la @@ -514,31 +549,21 @@ $nmap -sV 192.168.1.1 ``` **Notes**: + - Commands execute in the system shell - Output is displayed in the terminal - Use with caution - no sandboxing -### `/kill` +### Stopping work in the TUI -Terminate the currently executing agent operation. +Use **Ctrl+C** to cancel the **current agent turn** or tool call in the focused terminal. Partial responses may be discarded depending on the tool; message history is preserved unless you also `/flush`. To signal an external PID, use **`/shell`** or **`$`** with the usual OS tools. + +### `/clear` (scrollback) + +Clear **visual** terminal output (scrollback) in the TUI. **Syntax**: -``` -/kill -``` -**Keyboard Shortcut**: `Ctrl+C` - -**Notes**: -- Stops agent mid-execution -- Partial responses are discarded -- Agent context is preserved - -### `/clear` - -Clear the terminal output. - -**Syntax**: ``` /clear ``` @@ -546,16 +571,21 @@ Clear the terminal output. **Keyboard Shortcut**: `Ctrl+L` **Notes**: + - Clears visual output only -- Conversation history is preserved +- **Does not** wipe conversation historyโ€”use `/flush` / `/clear` in the history sense (see above) - Cost tracking continues +### `/exit` or `/quit` or `/q` -**Keyboard Shortcut**: `Ctrl+Q` +Leave the TUI session cleanly (telemetry flush, session teardown). + +**Keyboard Shortcut**: `Ctrl+Q` (depending on build; confirm in-app shortcuts) **Notes**: -- Unsaved sessions will be lost -- Graceful shutdown of all terminals + +- Unsaved work in buffers may be lostโ€”`/save` or export logs first if needed +- Shuts down all terminals in the layout --- @@ -568,6 +598,7 @@ Access the command palette for quick command search and execution. **Keyboard Shortcut**: `Ctrl+P` **Features**: + - Fuzzy search for commands - Command descriptions - Keyboard navigation (arrow keys, Enter) @@ -582,7 +613,6 @@ Show or hide the sidebar. **Alternative**: Click the `[โ‰ก]` button in the top bar - ### Clear Input Clear the prompt input field. @@ -590,6 +620,7 @@ Clear the prompt input field. **Keyboard Shortcut**: `Ctrl+U` **Use Cases**: + - Parallel agent execution - Comparing agent responses - Team-based workflows @@ -599,6 +630,7 @@ Clear the prompt input field. Cancel running operations. **Keyboard Shortcuts**: + - `Ctrl+C` - Cancel execution in focused terminal - `Escape` - Cancel all running agents (press twice to exit) @@ -606,6 +638,7 @@ Cancel running operations. ## Next Steps +- [CLI commands reference](../cli/commands_reference.md) โ€” recommended for exact REPL syntax - [Terminals Management](terminals_management.md) - Advanced multi-terminal workflows - [Keyboard Shortcuts](keyboard_shortcuts.md) - Complete keyboard reference - [User Interface Guide](user_interface.md) - Visual components and layouts @@ -614,5 +647,4 @@ For questions or issues, visit [CAI GitHub Issues](https://github.com/aliasrobot --- -*Last updated: October 2025 | CAI TUI v0.6+* - +*TUI UX and shortcuts; authoritative slash-command tables: [CLI commands reference](../cli/commands_reference.md).* \ No newline at end of file diff --git a/docs/tui/terminals_management.md b/docs/tui/terminals_management.md index 9f3a695d..c204e6a6 100644 --- a/docs/tui/terminals_management.md +++ b/docs/tui/terminals_management.md @@ -480,8 +480,6 @@ Active โ”€โ”€[Focus Terminal]โ”€โ”€> Focused โ”€โ”€[Focus Other]โ”€โ”€> Active **Method 2**: `Escape` twice (all terminals) -**Method 3**: `/kill` command - #### Clearing Errors **Command**: `/clear` (clears visual errors, preserves history) diff --git a/mkdocs.yml b/mkdocs.yml index 9a1bd9da..1e0c15ac 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -30,6 +30,7 @@ nav: - Welcome: index.md - Installation: cai_installation.md - Quickstart: cai_quickstart.md + - Commands reference: cli/commands_reference.md # ======================================== # CAI PRO (EXPANDIDO - COMERCIAL) โญ @@ -119,7 +120,6 @@ nav: - Tracing & Debugging: tracing.md - Context Management: context.md - Guardrails & Security: guardrails.md - - LLM Council: council.md - Environment Variables: environment_variables.md # ========================================