Appearance

Quick Reference ​

A quick overview of the most commonly used CLI commands.

Global Options ​

These options work with any command:

OptionDescription
--jsonOutput results as JSON
--quietSuppress non-essential output
--no-colorDisable colored output
-v, --versionShow CLI version
-h, --helpShow help

Authentication ​

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

Repositories ​

bash
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 ​

bash
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 ​

bash
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
controlinfra drifts reanalyze <drift-id>   # Reanalyze with AI
controlinfra drifts export                 # Export drifts to JSON
controlinfra drifts export --output f.json # Export to file

Runners (Self-Hosted) ​

bash
controlinfra runners list                  # List all runners
controlinfra runners add 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
controlinfra runners update <runner-id> --name new-name  # Update runner
controlinfra runners offline <runner-id>   # Mark offline

Integrations ​

Slack ​

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

AWS ​

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

AI Provider (BYOK) ​

bash
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

Azure ​

bash
controlinfra azure setup                   # Configure credentials
controlinfra azure status                  # Show status
controlinfra azure test                    # Validate credentials
controlinfra azure remove                  # Remove credentials

GCP ​

bash
controlinfra gcp setup                     # Configure credentials
controlinfra gcp status                    # Show status
controlinfra gcp test                      # Validate credentials
controlinfra gcp remove                    # Remove credentials

Organizations ​

bash
controlinfra orgs list                     # List organizations
controlinfra orgs create <name>            # Create an organization
controlinfra orgs info <id>                # Show organization details
controlinfra orgs update <id> --name new-name  # Update organization
controlinfra orgs delete <id> --force      # Delete organization
controlinfra orgs members <orgId>          # List members
controlinfra orgs invite <orgId> email@example.com  # Invite member
controlinfra orgs invite-link <orgId>      # Generate invite link

Projects ​

bash
controlinfra projects list                 # List projects
controlinfra projects create <name> --provider aws  # Create project
controlinfra projects info <id>            # Show project details
controlinfra projects update <id> --name new-name   # Update project
controlinfra projects delete <id> --force  # Delete project
controlinfra projects default <id>         # Set default project

Tokens ​

bash
controlinfra tokens list                   # List API tokens
controlinfra tokens create my-token --scopes scans:read,drifts:read  # Create token
controlinfra tokens revoke <id>            # Revoke a token

Configuration ​

bash
controlinfra config path                   # Show config file path
controlinfra config get apiUrl             # Get a config value
controlinfra config set orgId <org-id>     # Set a config value
controlinfra config reset                  # Reset all config

Examples ​

Complete Workflow ​

bash
# 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 ​

bash
# 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 ​

bash
# Get repositories as JSON
controlinfra repos list --json

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

Next Steps ​