RomanNum3ral
/
cai
mirror of https://github.com/aliasrobotics/cai.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
cai/docs/cli/advanced_usage.md

1405 lines
25 KiB
Markdown
Raw Blame History

# Advanced Usage
This guide covers advanced features, automation, scripting, and power-user techniques for the CAI Command Line Interface.
---
## Table of Contents
1. [CLI Startup Flags](#cli-startup-flags)
2. [Parallel Execution](#parallel-execution)
3. [Queue System](#queue-system)
4. [Automation & Scripting](#automation--scripting)
5. [Memory Management](#memory-management)
6. [Workspace & Virtualization](#workspace--virtualization)
7. [CTF Workflows](#ctf-workflows)
8. [Cost Management](#cost-management)
9. [Configuration Management](#configuration-management)
10. [Integration Patterns](#integration-patterns)
11. [Troubleshooting](#troubleshooting)
---
## CLI Startup Flags
CAI provides powerful command-line flags for session management and autonomous operation.
### Session Resume Flags
Resume previous sessions to continue where you left off:
```bash
# Resume the last session
cai --resume
# Resume with interactive session selector
cai --resume list
# Resume a specific session by ID
cai --resume abc12345
# Resume from a specific log file
cai --resume /path/to/session.jsonl
# Resume from custom logs directory
cai --resume list --logpath ~/custom_logs/
```
### Continue Mode Flag
Enable autonomous operation where the agent continues working without waiting for user input:
```bash
# Start with continue mode
cai --continue --prompt "perform security audit"
# Short form
cai -c --prompt "analyze vulnerabilities"
```
### Combining Resume and Continue
The most powerful combination - resume a session AND continue autonomously:
```bash
# Resume last session and continue working
cai --resume --continue
# Resume specific session and continue
cai --resume abc12345 --continue
# Short form
cai --resume -c
```
This is ideal for:
- Resuming interrupted long-running tasks
- Continuing security audits after a break
- Picking up penetration tests where you left off
### Other Useful Flags
```bash
# Start with initial prompt
cai --prompt "your task here"
cai -p "your task here"
# Use specific agent type
cai --agent redteam_agent
cai -a bug_bounter_agent
# Use specific model
cai --model alias1
cai -m gpt-4o
# Load YAML configuration
cai --yaml config.yaml
# Check version
cai --version
# Update CAI
cai --update
```
For detailed documentation on session resume, see [Session Resume](../session_resume.md).
For continue mode details, see [Continue Mode](../continue_mode.md).
---
## Parallel Execution
Run multiple agents simultaneously to get different perspectives or distribute workload.
### Basic Parallel Setup
#### Method 1: Using Commands
```bash
# Launch CAI
cai
# Add agents to parallel configuration
CAI> /parallel add redteam_agent alias1
CAI> /parallel add blueteam_agent alias1
CAI> /parallel add bug_bounter_agent gpt-4o
# List configured agents
CAI> /parallel list
# Execute on all agents
CAI> /parallel run "analyze the security of target.com"
# Merge results
CAI> /parallel merge
```
#### Method 2: Using YAML Configuration
Create `agents.yaml`:
```yaml
metadata:
description: "Multi-perspective security analysis"
auto_run: true
agents:
- name: offensive
agent_type: redteam_agent
model: alias1
- name: defensive
agent_type: blueteam_agent
model: alias1
- name: bug_hunter
agent_type: bug_bounter_agent
model: gpt-4o
- name: forensics
agent_type: dfir_agent
model: alias1
```
Launch with YAML:
```bash
cai --yaml agents.yaml --prompt "perform comprehensive security assessment of target.com"
```
#### Method 3: Using Environment Variable
```bash
# Set parallel count
export CAI_PARALLEL=3
export CAI_AGENT_TYPE=redteam_agent
export CAI_MODEL=alias1
cai --prompt "scan network 192.168.1.0/24"
```
### Advanced Parallel Patterns
#### Pattern 1: Distributed Reconnaissance
Split reconnaissance across multiple agents:
```yaml
# recon_team.yaml
agents:
- name: subdomain_enum
agent_type: redteam_agent
model: alias1
initial_prompt: "Enumerate subdomains for A-M range"
- name: subdomain_enum2
agent_type: redteam_agent
model: alias1
initial_prompt: "Enumerate subdomains for N-Z range"
- name: port_scanner
agent_type: network_security_analyzer_agent
model: alias1
initial_prompt: "Scan all discovered hosts"
- name: web_analyzer
agent_type: bug_bounter_agent
model: alias1
initial_prompt: "Analyze all web services found"
```
```bash
cai --yaml recon_team.yaml
```
#### Pattern 2: Red vs Blue Analysis
Compare offensive and defensive perspectives:
```bash
# Configure teams
CAI> /parallel add redteam_agent alias1
CAI> /parallel add blueteam_agent alias1
# Execute same analysis from different perspectives
CAI> /parallel run "analyze the security posture of this web application"
# Compare results
CAI> /parallel merge
```
#### Pattern 3: Multi-Model Comparison
Test different models on the same task:
```yaml
# model_comparison.yaml
agents:
- name: alias_test
agent_type: bug_bounter_agent
model: alias1
- name: gpt4o_test
agent_type: bug_bounter_agent
model: gpt-4o
- name: claude_test
agent_type: bug_bounter_agent
model: claude-3-5-sonnet-20241022
```
### Managing Parallel Results
```bash
# View individual agent outputs
CAI> /history 10 offensive
CAI> /history 10 defensive
# Merge all conversations
CAI> /parallel merge
# Save merged results
CAI> /save parallel_assessment_results.json
# Clear parallel configuration
CAI> /parallel clear
```
---
## Queue System
Batch process multiple prompts for automated workflows.
### Creating Queue Files
Create `security_checklist.txt`:
```text
# Security Assessment Checklist
# Comments start with # and are ignored
# Phase 1: Reconnaissance
/agent redteam_agent
Perform passive reconnaissance on target.com
Enumerate subdomains and services
# Phase 2: Vulnerability Scanning
/agent bug_bounter_agent
Test for OWASP Top 10 vulnerabilities
Check for known CVEs in discovered services
# Phase 3: Network Analysis
/agent network_security_analyzer_agent
$ nmap -sV -p- target.com
Analyze the network topology
# Phase 4: Report Generation
/agent reporting_agent
Generate comprehensive security report
/save security_assessment_report.md
# Phase 5: Cleanup
/cost
/history 50
```
### Loading and Executing Queues
#### Method 1: Auto-load on Startup
```bash
# Set environment variable
export CAI_QUEUE_FILE="security_checklist.txt"
cai
# Queue executes automatically
```
#### Method 2: Command Line Queue
```bash
# Use semicolons to chain commands
cai --prompt "/agent redteam_agent ; scan target.com ; /save results.json"
```
### Advanced Queue Patterns
#### Pattern 1: CTF Challenge Queue
```text
# ctf_workflow.txt
/env set CTF_NAME hackableii
/env set CTF_CHALLENGE web_app
/agent redteam_agent
Analyze the CTF challenge environment
Find and exploit vulnerabilities
Extract the flag
/save ctf_solution.md
```
#### Pattern 2: Bug Bounty Workflow
```text
# bugbounty_recon.txt
/agent bug_bounter_agent
/env set CAI_PRICE_LIMIT 20.0
# Reconnaissance
Perform subdomain enumeration on target.com
Identify web technologies and frameworks
Map the attack surface
# Testing
Test authentication mechanisms for bypasses
Check for injection vulnerabilities
Analyze API endpoints for security issues
# Reporting
Compile findings into bug bounty report
/save bugbounty_findings.md
/cost
```
#### Pattern 3: Continuous Security Monitoring
```text
# daily_security_check.txt
/agent network_security_analyzer_agent
# Daily checks
$ nmap -sV 192.168.1.0/24
Analyze changes from previous scan
Identify new services or hosts
Report anomalies
/save daily_scan_$(date +%Y%m%d).json
```
---
## Automation & Scripting
Integrate CAI into scripts and CI/CD pipelines.
### Bash Script Integration
#### Script 1: Automated Security Scan
```bash
#!/bin/bash
# security_scan.sh
TARGET="$1"
OUTPUT_DIR="./scan_results"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
# Configuration
export CAI_MODEL=alias1
export CAI_AGENT_TYPE=redteam_agent
export CAI_PRICE_LIMIT=10.0
export CAI_MAX_TURNS=50
export CAI_TRACING=false
export CAI_DEBUG=0
# Create output directory
mkdir -p "$OUTPUT_DIR"
# Run CAI with automated prompt
cai --prompt "
/agent redteam_agent
Perform comprehensive security scan on $TARGET
Test for common vulnerabilities
/save $OUTPUT_DIR/scan_${TIMESTAMP}.json
/cost
/exit
"
echo "Scan completed. Results saved to $OUTPUT_DIR/scan_${TIMESTAMP}.json"
```
Usage:
```bash
chmod +x security_scan.sh
./security_scan.sh target.com
```
#### Script 2: Multi-Target Batch Scan
```bash
#!/bin/bash
# batch_scan.sh
TARGETS_FILE="$1"
OUTPUT_DIR="./batch_results"
mkdir -p "$OUTPUT_DIR"
while IFS= read -r target; do
echo "Scanning $target..."
CAI_PRICE_LIMIT=5.0 cai --prompt "
/agent bug_bounter_agent
Scan $target for web vulnerabilities
/save $OUTPUT_DIR/${target//\//_}_scan.json
/exit
"
echo "Completed: $target"
sleep 2
done < "$TARGETS_FILE"
echo "All scans completed!"
```
Usage:
```bash
# targets.txt contains one domain per line
./batch_scan.sh targets.txt
```
#### Script 3: CTF Automation
```bash
#!/bin/bash
# ctf_solver.sh
CTF_NAME="$1"
CHALLENGE="$2"
export CTF_NAME="$CTF_NAME"
export CTF_CHALLENGE="$CHALLENGE"
export CTF_INSIDE=true
export CAI_AGENT_TYPE=redteam_agent
export CAI_MODEL=alias1
export CAI_MAX_TURNS=100
# Create queue file
cat > /tmp/ctf_queue.txt << 'EOF'
Analyze the CTF challenge
Identify vulnerabilities
Exploit and find the flag
/save ctf_solution.json
/exit
EOF
# Run with queue
CAI_QUEUE_FILE=/tmp/ctf_queue.txt cai
# Cleanup
rm /tmp/ctf_queue.txt
```
Usage:
```bash
./ctf_solver.sh hackableii web_challenge
```
### CI/CD Integration
#### GitHub Actions Example
```yaml
# .github/workflows/security-scan.yml
name: Security Scan
on:
push:
branches: [ main ]
schedule:
- cron: '0 2 * * *' # Daily at 2 AM
jobs:
security-scan:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v3
- name: Setup Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
- name: Install CAI
run: |
pip install cai
- name: Run Security Scan
env:
ALIAS_API_KEY: ${{ secrets.ALIAS_API_KEY }}
CAI_MODEL: alias1
CAI_PRICE_LIMIT: 10.0
CAI_TRACING: false
run: |
cai --prompt "
/agent bug_bounter_agent
Analyze this repository for security issues
Focus on OWASP Top 10 vulnerabilities
/save security_report.json
/exit
"
- name: Upload Results
uses: actions/upload-artifact@v3
with:
name: security-report
path: security_report.json
```
#### GitLab CI Example
```yaml
# .gitlab-ci.yml
security_scan:
stage: test
image: python:3.11
before_script:
- pip install cai
script:
- |
cai --prompt "
/agent redteam_agent
Scan $CI_PROJECT_URL for vulnerabilities
/save scan_results.json
/exit
"
artifacts:
paths:
- scan_results.json
expire_in: 1 week
only:
- main
- merge_requests
```
### Non-Interactive Mode
```bash
# Single command execution
cai --prompt "scan 192.168.1.1" > output.txt
# Suppress interactive elements
CAI_DEBUG=0 CAI_BRIEF=true cai --prompt "quick scan"
# Pipe output
cai --prompt "analyze" | grep -i "vulnerability"
# JSON output for parsing
cai --prompt "scan target ; /save results.json ; /exit"
```
---
## Memory Management
Advanced persistent memory for long-term context.
### Episodic Memory
Store and recall specific episodes or sessions.
```bash
# Enable episodic memory
export CAI_MEMORY=episodic
cai
# During session
CAI> /memory save "SQLi vulnerability found in login"
CAI> /memory save "XSS in comment section"
# List memories
CAI> /memory list
# Apply memory to new session
CAI> /memory apply mem_12345
```
### Semantic Memory
Store knowledge and facts.
```bash
# Enable semantic memory
export CAI_MEMORY=semantic
cai
# Save semantic knowledge
CAI> /memory save "Target uses Apache 2.4.41 with ModSecurity"
```
### Combined Memory
Use both episodic and semantic memory:
```bash
# Enable all memory types
export CAI_MEMORY=all
export CAI_MEMORY_ONLINE=true
export CAI_MEMORY_ONLINE_INTERVAL=5
cai
```
### Online Memory Mode
Automatically save memory at intervals:
```bash
# Configure online memory
export CAI_MEMORY=episodic
export CAI_MEMORY_ONLINE=true
export CAI_MEMORY_ONLINE_INTERVAL=3 # Save every 3 turns
cai --prompt "long reconnaissance session"
```
### Memory Workflows
#### Workflow 1: Multi-Day Assessment
**Day 1:**
```bash
CAI> /agent bug_bounter_agent
CAI> Perform reconnaissance on target.com
CAI> /memory save "day1_reconnaissance"
CAI> /save day1_session.json
```
**Day 2:**
```bash
CAI> /agent bug_bounter_agent
CAI> /memory apply day1_reconnaissance
CAI> Continue testing based on yesterday's findings
CAI> /memory save "day2_exploitation"
```
#### Workflow 2: Knowledge Base
```bash
# Build security knowledge base
CAI> /memory save "CVE-2024-1234 affects Apache < 2.4.59"
CAI> /memory save "SQL injection bypasses for ModSecurity"
CAI> /memory save "XSS payload variants for WAF bypass"
# Later, in new session
CAI> /memory list
CAI> /memory apply mem_useful_techniques
```
### Memory Compaction
Reduce memory size while preserving important information:
```bash
# Compact current conversation
CAI> /memory compact
# Status and statistics
CAI> /memory status
```
### Memory Management
```bash
# Show specific memory
CAI> /memory show mem_12345
# Merge memories
CAI> /memory merge mem_12345 mem_67890 "combined_findings"
# Delete memory
CAI> /memory delete mem_12345
```
---
## Workspace & Virtualization
Manage execution environments and Docker containers.
### Workspace Management
```bash
# Show current workspace
CAI> /workspace show
# Change workspace
CAI> /workspace set /home/user/pentests/target_corp
# List workspace contents
CAI> /workspace list
# Execute commands in workspace
CAI> $ ls -la
CAI> $ cat target_info.txt
```
### Docker Container Execution
#### Automatic Container Setup (CTF)
```bash
# CTF automatically sets up container
export CTF_NAME=hackableii
export CTF_INSIDE=true
cai
# Commands execute inside container automatically
CAI> $ whoami
CAI> $ ip addr
```
#### Manual Container Management
```bash
# List available containers
CAI> /virtualization list
# Set active container
CAI> /virtualization set ubuntu_pentest
# All commands now execute in container
CAI> $ nmap -sV localhost
# Return to host
CAI> /virtualization clear
```
### Environment Variables for Virtualization
```bash
# CTF Configuration
export CTF_NAME=hackableii
export CTF_CHALLENGE=web_app
export CTF_SUBNET=192.168.3.0/24
export CTF_IP=192.168.3.100
export CTF_INSIDE=true # Execute inside container
# Active Container
export CAI_ACTIVE_CONTAINER=abc123def456
cai
```
### Advanced Virtualization Patterns
#### Pattern 1: Isolated Testing
```bash
#!/bin/bash
# isolated_test.sh
# Create isolated container
CONTAINER_ID=$(docker run -d ubuntu:latest sleep infinity)
# Set container for CAI
export CAI_ACTIVE_CONTAINER=$CONTAINER_ID
# Run tests
cai --prompt "
/virtualization set $CONTAINER_ID
Install and test malware sample
Analyze behavior
/save malware_analysis.json
/exit
"
# Cleanup
docker stop $CONTAINER_ID
docker rm $CONTAINER_ID
```
#### Pattern 2: Multi-Container Testing
```bash
# Test across multiple containers
CAI> /virtualization set web_server_container
CAI> $ curl http://localhost
CAI> /virtualization set db_container
CAI> $ psql -l
CAI> /virtualization set app_container
CAI> $ python test_exploit.py
```
---
## CTF Workflows
Specialized workflows for Capture The Flag challenges.
### Basic CTF Setup
```bash
# Configure CTF environment
export CTF_NAME=hackableii
export CTF_CHALLENGE=binary_exploit
export CAI_AGENT_TYPE=redteam_agent
export CAI_MODEL=alias1
export CAI_MAX_TURNS=inf
cai
```
### CTF Challenge Types
#### Type 1: Web Challenges
```bash
export CTF_NAME=webchallenge
export CTF_INSIDE=true
cai --prompt "
/agent bug_bounter_agent
Analyze this web application
Find and exploit vulnerabilities
Extract the flag
/save web_ctf_solution.md
"
```
#### Type 2: Binary Exploitation
```bash
export CTF_NAME=pwn_challenge
cai --prompt "
/agent reverse_engineering_agent
Analyze the binary
Find buffer overflow vulnerability
Develop exploit
/save exploit.py
"
```
#### Type 3: Forensics
```bash
export CTF_NAME=forensics_challenge
cai --prompt "
/agent dfir_agent
Analyze the memory dump
Extract hidden data
Find the flag
/save forensics_analysis.md
"
```
### Automated CTF Solver
```bash
#!/bin/bash
# auto_ctf.sh
CHALLENGES=(
"web_app:bug_bounter_agent"
"binary_exploit:reverse_engineering_agent"
"network_forensics:dfir_agent"
"crypto:redteam_agent"
)
for challenge in "${CHALLENGES[@]}"; do
IFS=':' read -r name agent <<< "$challenge"
echo "Solving $name..."
CTF_NAME="ctf_event" \
CTF_CHALLENGE="$name" \
CAI_AGENT_TYPE="$agent" \
cai --prompt "
Analyze and solve the challenge
Find the flag
/save ${name}_solution.json
/exit
"
done
```
### CTF with Time Limits
```bash
# Set strict limits for CTF
export CAI_MAX_TURNS=50
export CAI_MAX_INTERACTIONS=200
export CAI_PRICE_LIMIT=5.0
# Force exit if flag not found
# (requires force_until_flag mode)
cai --prompt "solve the CTF challenge"
```
---
## Cost Management
Control and optimize API usage costs.
### Setting Cost Limits
```bash
# Set price limit
export CAI_PRICE_LIMIT=10.0
# Set interaction limit
export CAI_MAX_INTERACTIONS=100
# Set turn limit
export CAI_MAX_TURNS=50
cai
```
### Runtime Cost Adjustment
```bash
# Check current costs
CAI> /cost
# Increase limit if needed
CAI> /env set CAI_PRICE_LIMIT 20.0
# Check updated limit
CAI> /env list | grep PRICE_LIMIT
```
### Cost Optimization Strategies
#### Strategy 1: Model Selection
```bash
# Use cheaper models for reconnaissance
CAI> /agent redteam_agent
CAI> /model alias1 # Balanced cost/performance
# Use powerful models for complex analysis
CAI> /model gpt-4o
CAI> Analyze complex vulnerability chain
```
#### Strategy 2: Conversation Compaction
```bash
# When approaching token limits
CAI> /compact
# Or set automatic compaction
export CAI_AUTO_COMPACT=true
```
#### Strategy 3: Targeted Prompts
```bash
# Be specific to reduce back-and-forth
CAI> Scan 192.168.1.1 ports 80,443,8080 with nmap -sV
# Instead of:
CAI> Scan 192.168.1.1
# (agent asks which ports)
# (multiple turns = higher cost)
```
### Cost Monitoring
```bash
# View detailed cost breakdown
CAI> /cost
# Per-agent costs
CAI> /cost redteam_agent
CAI> /cost bug_bounter_agent
# Session statistics
CAI> /history
CAI> /cost all
```
### Budget-Constrained Workflows
```bash
#!/bin/bash
# budget_scan.sh
# Set strict budget
export CAI_PRICE_LIMIT=2.0
export CAI_MODEL=alias1 # Cost-effective model
cai --prompt "
/agent redteam_agent
Quick vulnerability scan on $TARGET
Focus on critical issues only
/cost
/save budget_scan.json
/exit
"
# Check if limit was hit
if grep -q "price limit" budget_scan.json; then
echo "Warning: Price limit reached"
fi
```
---
## Configuration Management
Advanced configuration patterns.
### Configuration Profiles
#### Profile 1: Development
```bash
# dev_profile.env
export CAI_MODEL=alias1
export CAI_DEBUG=2
export CAI_PRICE_LIMIT=5.0
export CAI_TRACING=true
export CAI_MAX_TURNS=20
```
Usage:
```bash
source dev_profile.env
cai
```
#### Profile 2: Production
```bash
# prod_profile.env
export CAI_MODEL=alias1
export CAI_DEBUG=0
export CAI_BRIEF=true
export CAI_PRICE_LIMIT=50.0
export CAI_TRACING=false
export CAI_GUARDRAILS=true
```
#### Profile 3: CTF
```bash
# ctf_profile.env
export CAI_MODEL=alias1
export CAI_AGENT_TYPE=redteam_agent
export CAI_MAX_TURNS=inf
export CAI_PRICE_LIMIT=20.0
export CAI_DEBUG=1
```
### Per-Agent Model Override
```bash
# Set different models for different agents
export CAI_REDTEAM_AGENT_MODEL=gpt-4o
export CAI_BUG_BOUNTER_AGENT_MODEL=alias1
export CAI_DFIR_AGENT_MODEL=claude-3-5-sonnet-20241022
# Default model for others
export CAI_MODEL=alias1
cai
```
### Dynamic Configuration
```bash
# Start with base config
CAI> /env list
# Adjust during session
CAI> /env set CAI_DEBUG 2
CAI> /env set CAI_PRICE_LIMIT 15.0
# Verify changes
CAI> /env | grep CAI
```
---
## Integration Patterns
Integrate CAI with other tools and services.
### MCP Integration
#### Pattern 1: Burp Suite Integration
```bash
# Start Burp Suite MCP server
# (in separate terminal)
burp-mcp-server --port 9876
# In CAI
CAI> /mcp load http://localhost:9876/sse burp
CAI> /mcp tools burp
CAI> /mcp add redteam_agent burp
# Use Burp tools
CAI> Use Burp to scan https://target.com
```
#### Pattern 2: Custom Tool Integration
```bash
# Load custom MCP server
CAI> /mcp load stdio "python my_custom_tools.py" custom
# Add to agent
CAI> /mcp add bug_bounter_agent custom
# Use custom tools
CAI> Use custom scanner on target
```
### API Integration
```bash
#!/bin/bash
# api_integration.sh
# Get CAI results
RESULT=$(cai --prompt "scan $TARGET ; /save -" 2>/dev/null)
# Send to external API
curl -X POST https://api.security-platform.com/scans \
-H "Content-Type: application/json" \
-d "$RESULT"
```
### Webhook Integration
```bash
#!/bin/bash
# webhook_notify.sh
# Run scan
cai --prompt "security scan on $TARGET ; /save results.json"
# Send webhook notification
curl -X POST $WEBHOOK_URL \
-H "Content-Type: application/json" \
-d '{
"target": "'$TARGET'",
"status": "complete",
"results": "'$(cat results.json)'"
}'
```
---
## Troubleshooting
Common issues and solutions.
### Issue: Price Limit Reached
```bash
# Check current cost
CAI> /cost
# Increase limit
CAI> /env set CAI_PRICE_LIMIT 20.0
# Or restart with higher limit
exit
CAI_PRICE_LIMIT=20.0 cai
```
### Issue: Max Interactions Exceeded
```bash
# Check current count
CAI> /env | grep MAX_INTERACTIONS
# Increase limit
CAI> /env set CAI_MAX_INTERACTIONS 500
# Or use /flush to start fresh
CAI> /flush
```
### Issue: Agent Not Responding
```bash
# Interrupt current operation
Ctrl+C
# Check agent status
CAI> /agent
# Switch to different agent
CAI> /agent redteam_agent
# Check configuration
CAI> /env list
```
### Issue: Context Window Full
```bash
# Review spend / token usage
CAI> /cost
# Compact conversation
CAI> /compact
# Or flush and start fresh
CAI> /flush
```
### Issue: Container Execution Problems
```bash
# Check virtualization status
CAI> /virtualization info
# List containers
CAI> /virtualization list
# Clear container setting
CAI> /virtualization clear
# Verify workspace
CAI> /workspace show
```
### Issue: Memory Loading Fails
```bash
# Check memory status
CAI> /memory status
# List available memories
CAI> /memory list
# Clear corrupted memory
CAI> /memory delete mem_problematic
# Check storage directory
$ ls -la ~/.cai/memory/
```
### Debug Mode
```bash
# Enable maximum debugging
export CAI_DEBUG=2
cai
# Or enable during session
CAI> /env set CAI_DEBUG 2
```
---
## Best Practices
### 1. Session Management
```bash
# Always save important sessions
CAI> /save project_name_$(date +%Y%m%d).json
# Use descriptive filenames
CAI> /save pentest_target_corp_phase1.json
```
### 2. Cost Control
```bash
# Set reasonable limits
export CAI_PRICE_LIMIT=10.0
export CAI_MAX_TURNS=50
# Monitor regularly
CAI> /cost
```
### 3. Agent Selection
```bash
# Use specialized agents
# ✅ Good: /agent bug_bounter_agent for web apps
# ❌ Bad: /agent one_tool_agent for complex tasks
# Let selection_agent help
CAI> /agent selection_agent
CAI> I need to test a mobile application
```
### 4. Parallel Execution
```bash
# Use YAML for complex setups
# ✅ Good: cai --yaml team_config.yaml
# ❌ Bad: Manual /parallel add for many agents
```
### 5. Memory Usage
```bash
# Save important findings
CAI> /memory save "critical vulnerability in auth system"
# Use descriptive names
# ✅ Good: "SQLi in admin panel - bypasses WAF"
# ❌ Bad: "bug1"
```
---
## Quick Reference
### Environment Variables
| Variable | Purpose | Example |
|----------|---------|---------|
| `CAI_MODEL` | Default model | `alias1` |
| `CAI_AGENT_TYPE` | Default agent | `redteam_agent` |
| `CAI_PARALLEL` | Parallel count | `3` |
| `CAI_QUEUE_FILE` | Auto-load queue | `prompts.txt` |
| `CAI_MEMORY` | Memory mode | `episodic` |
| `CAI_MEMORY_ONLINE` | Auto-save memory | `true` |
| `CAI_PRICE_LIMIT` | Cost limit | `10.0` |
| `CAI_MAX_TURNS` | Turn limit | `50` |
| `CAI_ACTIVE_CONTAINER` | Docker container | `abc123` |
### Command Patterns
```bash
# Automation
cai --prompt "command ; command ; command"
CAI_QUEUE_FILE=file.txt cai
# Parallel
cai --yaml agents.yaml --prompt "task"
CAI_PARALLEL=3 cai
# CTF
CTF_NAME=challenge cai
```
---
## Next Steps
- 📖 [Getting Started](getting_started.md) - Basic usage
- 📚 [Commands Reference](commands_reference.md) - All commands
- 🏠 [CLI Overview](cli_index.md) - Main documentation
---
*Last updated: November 2025 | CAI CLI v0.6+*
Reference in New Issue View Git Blame Copy Permalink