Command-line interface for the SOFE Open FinOps Engine
19 commands, interactive TUI, AI-powered remediation.
Quick Start · Commands · v0.3 Features · Ecosystem
Evaluate FinOps policies, browse findings in an interactive TUI, get AI-powered remediation commands — all from your terminal.
# Quick install (macOS/Linux)
curl -fsSL https://sofe.dev/install.sh | bash
# Evaluate your AWS account
sofe evaluate --profile default --policies ./policies/# Quick install (macOS/Linux)
curl -fsSL https://sofe.dev/install.sh | bash
# Go install
go install github.com/breakingthecloud/sofe-cli@latest
# Or download binary from GitHub Releases
# https://github.com/breakingthecloud/sofe-cli/releases# Start the local evaluation server
sofe serve
# Evaluate policies against your AWS account
sofe evaluate --profile default --policies ./policies/
# With auto-start server
sofe evaluate --auto-serve --profile default# Set your API key (get one at platform.sofe.dev)
sofe config set api-key sk_sofe_your_key_here
# Evaluate via cloud
sofe evaluate --cloud
# Or pass key directly
sofe evaluate --cloud --api-key sk_sofe_xxx
# Several AWS accounts connected? Choose which one to evaluate
sofe evaluate --cloud --account 123456789012With more than one connected account, sofe evaluate --cloud without --account lists them and asks you to choose.
| Mode | How you pick it | AWS account evaluated | --account |
|---|---|---|---|
| Local / self-hosted (default) | sofe evaluate |
The one your own credentials point to: --profile / aws_profile, or the default AWS credential chain (environment variables, ~/.aws, instance role). Nothing is sent to SOFE Cloud and no account ID is sent to the server. |
Rejected with a clear message |
| Cloud | sofe evaluate --cloud (or mode: cloud) |
An account you connected at platform.sofe.dev/accounts | Required only when two or more accounts are connected; without it the CLI lists them |
sofe history, sofe watch, sofe top and sofe interactive only read evaluations that already exist. With several accounts:
history lists them all with an Account column; watch, top and interactive use the account of your most recent
evaluation and tell you which one (and which others exist). Pass --account <id> to any of them to choose.
sofe diff refuses to compare two evaluations of different accounts.
| Command | Description |
|---|---|
sofe evaluate |
Run policies against AWS resources (spinner + summary card) |
sofe interactive |
Split-panel TUI (findings + detail + AI) |
sofe history |
List past evaluations (cloud mode) |
sofe watch |
Monitor with live sparkline + change detection |
| Command | Description |
|---|---|
sofe explain |
AI explanation for a specific finding |
sofe remediate |
Show/execute remediation CLI commands |
sofe top |
Findings ranked by frequency |
sofe diff |
Compare two evaluations (new/fixed/unchanged) |
| Command | Description |
|---|---|
sofe login |
Authenticate via browser (device flow) |
sofe upgrade |
Connect to SOFE Cloud or upgrade to Pro |
sofe status |
Show account status (tier, evals, AI usage) |
sofe config |
Manage configuration (set/show) |
sofe accounts list |
Connected accounts and their stack TemplateVersion (cloud mode) |
sofe accounts update |
Update the SOFE role stack in every connected account |
The SaaS cannot update your CloudFormation stack: the SOFE role is read-only by design. In cloud mode the CLI
does it locally with your own credentials, mapping each connected account to an AWS profile
(aws configure list-profiles + sts get-caller-identity) and skipping stacks already on the current template:
sofe accounts list # shows the real TemplateVersion per account (v2.3, v2.2, ...)
sofe accounts update --dry-run # prints the profile mapping and the exact aws commands
sofe accounts update # asks once, then updates each stack and waits for UPDATE_COMPLETEIf the automatic mapping is not what you want:
sofe accounts update --profile-map 111111111111=prod,222222222222=devThe update keeps each stack's External ID (UsePreviousValue=true), so connected accounts keep working and
nothing has to be reconnected.
| Command | Description |
|---|---|
sofe serve |
Start local evaluation server (port 8080) |
sofe policies |
List available policies |
sofe changelog |
Show release notes |
sofe version |
Build info (commit, date, Go, OS) |
sofe terraform |
Scan Terraform plans |
sofe completion |
Shell autocompletion (bash/zsh/fish) |
sofe interactive # Browse findings with keyboard navigation
sofe interactive abc123-eval-id # Or specify an evaluationNavigate with ↑/↓, press Enter for details, e for AI explanation, q to quit.
sofe explain abc123-eval-id --finding 2 # AI explanation
sofe remediate abc123-eval-id --finding 2 # Show remediation commands
sofe remediate abc123-eval-id --finding 2 --execute # Execute interactivelysofe upgrade # Connect CLI to SOFE Cloud
sofe upgrade pro # Upgrade to Pro tier
sofe status # Check your status| Flag | Description |
|---|---|
--cloud |
Use cloud API instead of local server |
--api-key |
API key for cloud mode |
--account |
AWS account ID (12 digits) to evaluate in cloud mode. Required when several accounts are connected |
--profile |
AWS profile (local mode) |
--policies |
Policies directory |
--fail-on |
Exit 1 if findings at/above severity |
--resource-types |
Filter resource types (comma-separated) |
--auto-serve |
Auto-start local server if not running |
--format |
Output format (table|json|markdown) |
sofe config show # Show current config
sofe config set mode cloud # Default to cloud mode
sofe config set api-key sk_sofe_xxx # Persist API key
sofe config set profile my-profile # AWS profile for local mode
sofe config set format json # Output formatConfig stored at ~/.sofe/config.yaml (permissions 0600).
Environment variables: SOFE_API_KEY, SOFE_CLOUD_URL.
| Local | Cloud | |
|---|---|---|
| Needs | sofe-server running locally | API key from platform.sofe.dev |
| Auth | None (localhost) | X-API-Key header |
| AWS access | Your local credentials | Connected account (IAM role) |
| Rate limit | None | 10/day (free), 1000/day (pro) |
| History | None | Stored in platform |
# Block deploys with critical findings
sofe evaluate --cloud --api-key $SOFE_API_KEY --fail-on high| Project | Description |
|---|---|
| sofe | Python engine (collectors + policies) |
| sofe-server | REST API server |
| sofe-action | GitHub Action |
| platform.sofe.dev | SaaS dashboard (free tier) |
| sofe.dev/docs | Documentation |
Apache 2.0 — see LICENSE.
sofe.dev · Engine · finoptix.dev
19 commands. Zero AWS bill surprises.