Skip to content
breakingthecloudPublic

About

SOFE command-line interface — run FinOps evaluations from your terminal.

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

42 Commits

Folders and files

Repository files navigation

SOFE CLI

Command-line interface for the SOFE Open FinOps Engine
19 commands, interactive TUI, AI-powered remediation.

Quick Start · Commands · v0.3 Features · Ecosystem

License Go Local + Cloud PRs


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/

Install

# 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

Quick Start

Local Mode

# 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

Cloud Mode

# 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 123456789012

With more than one connected account, sofe evaluate --cloud without --account lists them and asks you to choose.

Which AWS account does it evaluate?

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.

Commands

Core

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

AI + Remediation

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)

Account

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

Update connected account stacks

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_COMPLETE

If the automatic mapping is not what you want:

sofe accounts update --profile-map 111111111111=prod,222222222222=dev

The update keeps each stack's External ID (UsePreviousValue=true), so connected accounts keep working and nothing has to be reconnected.

Utilities

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)

New in v0.3.0

Interactive TUI

sofe interactive              # Browse findings with keyboard navigation
sofe interactive abc123-eval-id  # Or specify an evaluation

Navigate with ↑/↓, press Enter for details, e for AI explanation, q to quit.

AI Explain & Remediate

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 interactively

Upgrade & Status

sofe upgrade                    # Connect CLI to SOFE Cloud
sofe upgrade pro                # Upgrade to Pro tier
sofe status                     # Check your status

Evaluate Flags

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)

Configuration

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 format

Config stored at ~/.sofe/config.yaml (permissions 0600).

Environment variables: SOFE_API_KEY, SOFE_CLOUD_URL.

Local vs Cloud

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

CI/CD

# Block deploys with critical findings
sofe evaluate --cloud --api-key $SOFE_API_KEY --fail-on high

Ecosystem

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

License

Apache 2.0 — see LICENSE.


sofe.dev · Engine · finoptix.dev

19 commands. Zero AWS bill surprises.

About

SOFE command-line interface — run FinOps evaluations from your terminal.

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages