CLI Guide
Complete reference for the SOFE CLI — install, configure, evaluate locally or via cloud.
Install
Quick install (macOS / Linux)
curl -fsSL https://sofe.dev/install.sh | bash
Go install
go install github.com/breakingthecloud/sofe-cli@latest
Binary download
# Download from GitHub Releases: # https://github.com/breakingthecloud/sofe-cli/releases
Available for: macOS (arm64/amd64), Linux (arm64/amd64), Windows (amd64)
Two Modes
Local Mode (default)
Runs evaluations on your machine using local AWS credentials. No account needed.
sofe serve sofe evaluate --profile default
Cloud Mode
Calls api.sofe.dev — requires API key from platform.sofe.dev.
sofe config set api-key sk_sofe_xxx sofe evaluate --cloud
Configuration
# Show current config sofe config show # Set default mode to cloud sofe config set mode cloud # Set API key (persisted to ~/.sofe/config.yaml) sofe config set api-key sk_sofe_your_key_here # Set custom cloud URL (for enterprise/BYOS) sofe config set cloud-url https://my-sofe-server.company.com # Set AWS profile (for local mode) sofe config set profile production # Set output format sofe config set format json
Config stored at ~/.sofe/config.yaml (file permissions 0600, user-only read).
Environment Variables (override config)
| Variable | Description |
|---|---|
| SOFE_API_KEY | API key for cloud mode |
| SOFE_CLOUD_URL | Override cloud API URL (default: https://api.sofe.dev) |
Commands Reference
sofe evaluate
Run policies against AWS resources.
# Local mode (default) sofe evaluate --profile default --policies ./policies/ # Cloud mode sofe evaluate --cloud --api-key sk_sofe_xxx # With filters sofe evaluate --resource-types aws.ec2,aws.s3 # CI/CD: fail on high severity findings sofe evaluate --fail-on high # Auto-start local server if not running sofe evaluate --auto-serve --profile default # JSON output sofe evaluate --format json > findings.json
Flags
| Flag | Description | Default |
|---|---|---|
| --cloud | Use cloud API | false (local) |
| --api-key | API key for cloud | from config |
| --profile | AWS profile (local) | from config |
| -p, --policies | Policies directory | ./policies |
| --fail-on | Exit 1 if findings ≥ severity | (none) |
| --resource-types | Filter (comma-separated) | all |
| --auto-serve | Auto-start local server | false |
| --format | Output format | table |
sofe serve
Start the local evaluation server.
sofe serve # starts on port 8080 sofe serve --port 9090 # custom port
sofe policies
List available policies.
sofe policies # from local server sofe policies --cloud # from api.sofe.dev
sofe config
Manage CLI configuration.
sofe config show # display all settings sofe config set api-key sk_sofe_xxx # persist API key sofe config set mode cloud # default to cloud sofe config set profile my-aws-profile # AWS profile
New in v0.3.0 Latest
sofe interactive
Launch a terminal UI to browse findings interactively. Navigate with keyboard, view details, get AI explanations.
sofe interactive # uses latest evaluation sofe interactive <eval-id> # specific evaluation # Controls: ↑/↓ navigate, Enter detail, e explain, Esc back, q quit
sofe history
List your past evaluations (cloud mode).
sofe history # shows last 15 evaluations with date, findings, trigger
sofe status
Show account status — mode, tier, last evaluation, AI usage.
sofe status # displays mode, API key, last eval summary, AI calls today
sofe explain
Get an AI explanation for a specific finding.
sofe explain <eval-id> --finding 0 # explain first finding sofe explain <eval-id> -f 3 # explain fourth finding
sofe remediate
Show or execute remediation commands for a finding.
sofe remediate <eval-id> --finding 0 # show commands sofe remediate <eval-id> --finding 0 --execute # run with confirmation
sofe upgrade
Connect your CLI to SOFE Cloud or upgrade to Pro tier.
sofe upgrade # opens signup, saves API key sofe upgrade pro # opens billing page for Pro upgrade
sofe terraform coming soon
Pre-deploy scan of Terraform plans for FinOps violations (Sprint 26).
sofe terraform ./infra/ # scan .tf files (coming soon)
Output Formats
Table (default)
┌──────────┬─────────────────┬──────────┬──────────────────────┬───────────┐ │ Severity │ Policy │ Resource │ Message │ Savings │ ├──────────┼─────────────────┼──────────┼──────────────────────┼───────────┤ │ 🔴 HIGH │ no-idle-ec2 │ i-0abc123│ CPU 2.1% for 30d │ $340/mo │ │ 🟡 MED │ require-tags │ i-0def456│ Missing: CostCenter │ — │ └──────────┴─────────────────┴──────────┴──────────────────────┴───────────┘
JSON (for automation)
sofe evaluate --format json | jq '.findings[] | select(.severity=="high")'
Markdown (for reports)
sofe evaluate --format markdown > report.md
CI/CD Usage
# GitHub Actions example
- name: Install SOFE CLI
run: curl -fsSL https://sofe.dev/install.sh | bash
- name: Evaluate (cloud mode)
env:
SOFE_API_KEY: ${{ secrets.SOFE_API_KEY }}
run: sofe evaluate --cloud --fail-on high