Quick Start

Get up and running with C3X in under five minutes. This guide walks you through installation, your first cost estimate, budget guards, what-if analysis, and CI/CD integration.

1. Install C3X

Choose the installation method that works best for your environment.

Homebrew (macOS)

brew install c3xdev/tap/c3x

Docker

docker pull ghcr.io/c3xdev/c3x:latest
# or from Docker Hub:
docker pull c3xdev/c3x:latest

# Run directly
docker run --rm -v $(pwd):/workspace ghcr.io/c3xdev/c3x:latest \
  estimate --path /workspace

Install script (curl)

# Auto-detects your OS and architecture, verifies the checksum
curl -fsSL https://c3x.dev/install.sh | sh

# Or pin a specific version
curl -fsSL https://c3x.dev/install.sh | C3X_VERSION=v0.1.3 sh

# Verify installation
c3x --version

Prefer a manual download? Every release on the GitHub releases page publishes c3x_<version>_<os>_<arch>.tar.gz archives with a checksums.txt.

2. Run Your First Estimate

Point C3X at any directory containing Terraform files. It will automatically parse your configuration, resolve modules, and calculate costs.

c3x estimate --path /path/to/terraform

C3X outputs a table showing each resource, its monthly cost, and the total. Use --format json or --format html for machine-readable or shareable output.

3. Get Recommendations

C3X can analyze your infrastructure and suggest cost optimizations such as right-sizing instances, switching to reserved pricing, or removing unused resources.

c3x recommend --path .

Each recommendation includes an estimated monthly saving and a brief explanation of the change.

4. Set a Budget Guard

Fail the command with a non-zero exit code when the estimated monthly cost exceeds a threshold. This is especially useful in CI/CD pipelines.

c3x estimate --path . --budget 1000

If the estimate exceeds $1,000/month, C3X exits with code 1 and prints a warning. To gate on the change in cost rather than the absolute total, save a baseline and use c3x diff --baseline base.json --budget-delta 200.

5. Try What-If Analysis

Explore cost impacts of infrastructure changes without modifying your Terraform files.

c3x estimate --path . --what-if 'aws_instance.web.instance_type=m6i.xlarge'

You can pass multiple --what-if flags to simulate several changes at once. C3X recalculates the full estimate with your overrides applied.

6. Add to CI

Integrate C3X into your pull request workflow so every change gets a cost estimate automatically. Here is a complete GitHub Actions workflow.

name: Cost Estimation
on: [pull_request]
permissions:
  pull-requests: write
  contents: read
jobs:
  c3x:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: c3xdev/c3x@v0
        with:
          path: .

Two steps. No API key, no secrets. Every PR gets a cost estimate comment automatically. Want it posted as c3x-cloud[bot] instead of the github-actions bot? Install the C3X Cloud GitHub App and set branded-comments: true — see the CI/CD Integration guide, which also covers GitLab, Bitbucket, Azure Pipelines, Atlantis, and Spacelift.

Try the Examples

The C3X repository includes ready-to-run examples for Terraform, Terragrunt, and CloudFormation. Clone and try them:

git clone https://github.com/c3xdev/c3x.git
cd c3x/examples/terraform
c3x estimate --path .

Available examples:

  • examples/terraform/: EC2 instance + Lambda with usage file. Try changing the instance type or region to see cost differences.
  • examples/terragrunt/: Multi-environment Terragrunt setup (dev + prod) with shared modules.
  • examples/cloudformation/: AWS CloudFormation template with usage-based resources.

To estimate with usage data (for Lambda, S3, etc.):

c3x estimate --path examples/terraform --usage examples/terraform/c3x-usage.yml

Next Steps