Quick Reference

A quick overview of the most commonly used CLI commands.

Global Options

These options work with any command:

Option	Description
--json	Output results as JSON
--quiet	Suppress non-essential output
--no-color	Disable colored output
-v, --version	Show CLI version
-h, --help	Show help

Authentication

controlinfra login              # Browser-based login
controlinfra login --token XXX  # Token-based login
controlinfra logout             # Clear credentials
controlinfra whoami             # Show current user

Repositories

controlinfra repos list                    # List all repositories
controlinfra repos add owner/repo          # Add a repository
controlinfra repos remove <id>             # Remove a repository
controlinfra repos info <id>               # Show repository details
controlinfra repos stats <id>              # Show repository statistics

# Add with AWS credentials
controlinfra repos add owner/repo --access-key AKIA... --secret-key ...

# Add with self-hosted runner (instance profile)
controlinfra repos add owner/repo --runner-type self-hosted --runner-id <id> --auth-method instance_profile

# Add with self-hosted runner (assume role)
controlinfra repos add owner/repo --runner-type self-hosted --runner-id <id> --auth-method assume_role --role-arn arn:aws:iam::123456789012:role/Role

Scans

controlinfra scan run owner/repo           # Trigger a scan
controlinfra scan run owner/repo --wait    # Trigger and wait for completion
controlinfra scan list                     # List recent scans
controlinfra scan status <scan-id>         # Check scan status
controlinfra scan logs <scan-id>           # Show scan logs
controlinfra scan cancel <scan-id>         # Cancel a running scan

# CI/CD Drift Gate Options
controlinfra scan run owner/repo --wait --fail-on-drift              # Fail if any drift
controlinfra scan run owner/repo --wait --fail-on-severity high      # Fail on high+ severity
controlinfra scan run owner/repo --wait --fail-on-drift --fail-on-new-only  # Only new drifts

Drifts

controlinfra drifts list                   # List all drifts
controlinfra drifts list --severity high   # Filter by severity
controlinfra drifts show <drift-id>        # Show drift details
controlinfra drifts fix <drift-id>         # Generate AI fix
controlinfra drifts pr <drift-id>          # Create pull request
controlinfra drifts ignore <drift-id>      # Mark as ignored
controlinfra drifts resolve <drift-id>     # Mark as resolved
controlinfra drifts stats                  # Show drift statistics

Runners (Self-Hosted)

controlinfra runners list                  # List all runners
controlinfra runners add --name my-runner  # Create a runner
controlinfra runners setup <runner-id>     # Get install script
controlinfra runners status <runner-id>    # Check runner status
controlinfra runners remove <runner-id>    # Delete a runner
controlinfra runners token <runner-id>     # Regenerate token

Integrations

Slack

controlinfra slack setup                   # Configure webhook
controlinfra slack test                    # Send test message
controlinfra slack status                  # Show status
controlinfra slack remove                  # Remove integration

AWS

controlinfra aws setup                     # Configure credentials
controlinfra aws status                    # Show status
controlinfra aws test                      # Validate credentials
controlinfra aws remove                    # Remove credentials

AI Provider (BYOK)

controlinfra ai status                     # Show current provider
controlinfra ai use anthropic --key XXX    # Use Anthropic
controlinfra ai use openai --key XXX       # Use OpenAI
controlinfra ai verify                     # Verify API key
controlinfra ai remove                     # Use default AI

Examples

Complete Workflow

# 1. Login
controlinfra login

# 2. Add a repository
controlinfra repos add myorg/infrastructure

# 3. Run a scan and wait
controlinfra scan run myorg/infrastructure --wait

# 4. Check for drifts
controlinfra drifts list --repo myorg/infrastructure

# 5. Fix a drift with AI
controlinfra drifts fix abc123

# 6. Create a PR
controlinfra drifts pr abc123

CI/CD Integration

# Set token from environment
export CONTROLINFRA_TOKEN=your-token

# Fail pipeline if any drift detected
controlinfra scan run myorg/infrastructure --wait --fail-on-drift

# Fail only on critical or high severity
controlinfra scan run myorg/infrastructure --wait --fail-on-severity high

# Use environment variables for defaults
export CONTROLINFRA_FAIL_ON_DRIFT=true
export CONTROLINFRA_FAIL_ON_SEVERITY=critical
controlinfra scan run myorg/infrastructure --wait

# JSON output for custom processing
controlinfra scan run myorg/infrastructure --wait --json

Exit Codes:

• 0 = Success (no drift or within threshold)
• 1 = Drift detected (threshold exceeded)
• 2 = Error (scan failed, timeout)

JSON Output

# Get repositories as JSON
controlinfra repos list --json

# Get drift details as JSON
controlinfra drifts show abc123 --json | jq '.drift.changes'

Next Steps

• Repositories - Repository management
• Scans - Running and managing scans
• Drifts - Working with drifts