Skip to main content

CLI commands

The Infracost CLI is organized into a few focused command groups. Every command supports --help.

  • Setup & integrations — get authenticated and wire Infracost into the tools you use:

  • Analyze infrastructure — derive cost and policy results from your IaC:

  • Organization settings — review what your organization has configured:

  • CLI maintenance:

    • infracost doctor: Diagnose and (optionally) repair your installation
    • infracost update: Update the CLI binary
    • infracost version: Print the version
    • infracost completion: Generate a shell completion script

Global flags​

The following flags are available on every command:

  • --org <slug-or-id>: Run the command against a specific organization (overrides the active org)
  • --json: Output logs and command results as JSON
  • --llm: Output command results in a compact, token-efficient format intended for LLM prompts
  • --no-color: Disable colored output
  • --access-token-use-cache (default true): Read and save access tokens from the local cache. Disable to force a fresh login.
  • --oauth-use-device-flow: Use the OAuth device flow (useful when a browser/localhost is unavailable, e.g. on a remote shell)

Repos and projects​

See this section for details about repos and projects, and how you can customize project names.

Setup​

The fastest way to get started is the interactive setup wizard. It logs you in, picks an organization, and walks through enabling AI coding agent skills, the IDE extension, and CI integration.

infracost setup

If you only want to configure one thing, use the dedicated subcommands described below (infracost auth login, infracost agent setup, infracost ide setup, infracost ci setup).

Auth​

infracost auth login   # browser-based PKCE login (use --oauth-use-device-flow if no browser)
infracost auth whoami  # show the currently authenticated user
infracost auth logout  # clear the cached token

For non-interactive environments such as CI/CD, set the INFRACOST_CLI_AUTHENTICATION_TOKEN environment variable to a service account or personal access token instead of running infracost auth login.

Org​

infracost org list       # list organizations the current user belongs to
infracost org current    # show the active organization
infracost org switch                # interactively pick an org
infracost org switch acme           # switch globally to the "acme" org
infracost org switch acme --repo    # pin the active org for the current repository only

You can also override the org for a single command using the --org global flag.

Agent​

Install or remove Infracost skills for AI coding agents (e.g. Claude Code).

infracost agent setup            # install at the user (global) scope
infracost agent setup --scope project   # install for the current project only
infracost agent setup --scope local     # install for the current shell session only

infracost agent remove           # remove from the user scope
infracost agent remove --scope project

Supported --scope values: user (default), project, local.

IDE​

infracost ide setup

Walks you through installing the Infracost extension for your editor.

CI​

Connect a repository to Infracost so that pull requests are automatically scanned and commented on.

# Connect this repo via the Infracost app integration (recommended)
infracost ci setup

# Generate a GitHub Actions workflow instead
infracost ci setup --ci-pipeline

# Skip confirmation prompts (useful for scripts)
infracost ci setup --yes

Scan​

infracost scan reads IaC from a directory, derives the resources it would create, prices them, and applies your organization's FinOps and tagging policies. The results are cached locally so subsequent infracost inspect queries are instantaneous.

# Scan the current directory
infracost scan

# Scan a specific project path
infracost scan ./terraform

# Run against a different organization's policies & prices
infracost scan --org acme

# Override the display currency (ISO 4217 code)
infracost scan --currency EUR

# Output results to a JSON file
infracost scan --json > infracost.json

The target must be a directory. The CLI auto-detects the IaC type (Terraform, Terragrunt, CloudFormation, etc.) from the directory contents. If your repo has multiple projects or workspaces, define them in an infracost.yml config file and they'll be scanned together.

For local development no extra setup is usually needed. For CI/CD and other special cases, see:

AWS CDK​

note

For full automated CDK support — including automatic synthesis, source mapping of issues back to your original CDK code (rather than the generated CloudFormation JSON), and PR comments — use Infracost Cloud with a VCS integration. See the CDK docs for details.

The CLI does not run cdk synth automatically. Running synthesis can trigger side effects such as network calls to AWS, execution of custom hooks or scripts, and context lookups that assume specific credentials or environment configuration. To scan a CDK project locally, run cdk synth yourself first, then point Infracost at the synthesized CloudFormation output.

Inspect​

infracost inspect queries the cached results of the most recent scan. It is the right command to reach for when you want to answer specific questions like "which resources are missing the team tag?" or "what would I save if every FinOps issue were fixed?"

# Run against the cache for the current directory
infracost inspect

# Or against a specific project
infracost inspect ./terraform

# Export scan results to a JSON file, then inspect from that file
infracost scan --json > infracost.json
infracost inspect --file infracost.json

Selection flags​

Pick the view you want. These compose with the filter flags below.

  • --summary: Headline numbers — totals, per-policy counts, etc.
  • --top N: The N most expensive resources by monthly cost
  • --top-savings N: The N FinOps issues with the largest monthly savings
  • --total-savings: Scalar sum of monthly savings across every FinOps issue
  • --missing-tag <key>: Resources missing the given tag entirely
  • --invalid-tag <key>: Resources where the tag is set but the value is outside the policy's allowed list
  • --policy <name-or-slug>: Drill into a specific policy
  • --budget <name-or-id>: Drill into a specific budget
  • --guardrail <name-or-id>: Drill into a specific guardrail

Filter flags​

Narrow any view. All filters are AND'd together.

  • --filter "key=value,key=value": Composable expression. Supported keys: policy, project, provider, tag.<key>=missing. Example: --filter "tag.team=missing,provider=aws"
  • --provider aws|google|azurerm
  • --project <name>
  • --resource <address>
  • --min-cost N / --max-cost N: Monthly cost bounds
  • --costs-only: Hide free resources
  • --failing: Only show failing policies

Output shaping​

  • --fields a,b,c: Tabular column projection. Available columns depend on the view. Example: --top-savings 10 --fields address,monthly_savings,policy
  • --addresses-only: Strip everything except the resource address (one per line). Composes with the selection flags. Equivalent to --fields=address.
  • --group-by type|provider|project|resource|file|policy|guardrail|budget: Group results (comma-separated or repeated)
  • --llm: Compact, token-efficient output for piping into an LLM
  • --json: Machine-readable JSON

Examples​

# Headline numbers (totals + per-policy counts)
infracost inspect --summary

# Single scalar from the summary, e.g. for shell scripting
infracost inspect --summary --fields failing_policies

# Top 10 most expensive resources
infracost inspect --top 10

# Total potential monthly savings if every FinOps issue were fixed
infracost inspect --total-savings

# Top 5 FinOps issues, just the addresses
infracost inspect --top-savings 5 --fields address

# Top 5 FinOps issues with custom column projection
infracost inspect --top-savings 5 --fields address,monthly_savings,policy

# Every resource missing the 'team' tag
infracost inspect --missing-tag team

# Resources whose 'environment' tag is set but uses a disallowed value
infracost inspect --invalid-tag environment

# Resources with monthly cost > $100
infracost inspect --min-cost 100

# Composable filter: missing 'team' tag AND on AWS
infracost inspect --filter "tag.team=missing,provider=aws"

# All addresses failing a specific policy (full list, no truncation)
infracost inspect --policy "Required Tags" --addresses-only

# Machine-readable, token-efficient output for LLM pipelines
infracost inspect --summary --llm

Example outputs​

Project: examples/terraform

Monthly cost                   $742.64
FinOps savings available       $187.12
Failing policies                     3
Resources missing required tags      5

Price​

infracost price reads IaC from stdin, scans it, and prints the cost estimate. Useful for quick what-if comparisons and for generating sample pricing without committing files.

# Pipe a Terraform snippet from a file
cat snippet.tf | infracost price

# Pipe a heredoc directly
infracost price <<'EOF'
resource "aws_instance" "web" {
  ami           = "ami-0abcd1234"
  instance_type = "m5.4xlarge"
}
EOF

# Override the display currency
infracost price --currency GBP < snippet.tf

Policies​

List the FinOps and tagging policies your organization has enabled.

infracost policies
infracost policies --finops-only            # only FinOps policies (-f)
infracost policies --tagging-only           # only tagging policies (-t)
infracost policies --providers aws,azure    # limit to specific providers (-p)

Limiting providers also reduces which provider plugins are downloaded.

Budgets​

List cost budgets configured for the current organization.

infracost budgets

Use infracost inspect --budget <name-or-id> to drill into a specific budget's results.

Guardrails​

List cost guardrails for the current repository.

infracost guardrails              # current directory's repo
infracost guardrails ./some/path  # a different working directory

Use infracost inspect --guardrail <name-or-id> to see which resources are tripping a guardrail.

Doctor​

infracost doctor runs diagnostic checks against your installation: auth, plugins, agent/IDE/CI integrations, and so on. Use it any time something feels off.

# Run the standard checks
infracost doctor

# Show the full diagnostic detail for every check
infracost doctor --verbose

# Attempt to auto-remediate failing checks
infracost doctor --fix

# Restrict the fix scope (default "user")
infracost doctor --fix --scope project

# Include AI coding agent / IDE checks
infracost doctor --check-agents
infracost doctor --check-ide

# Generate a support bundle to share with the Infracost team
infracost doctor --bundle

Supported --scope values for --fix: user (global), project, local.

Update​

Update the CLI binary in place to the latest released version.

infracost update

Plugins are versioned and updated separately from the CLI; see the environment variables page for the variables that pin or disable plugin auto-updates.