CLI Tool (tc)

The Terracotta CLI (tc) brings AI-powered Terraform analysis to your local terminal and CI/CD pipelines. Run code reviews and plan analysis without opening a pull request.

🚀 Installation

Install the CLI globally via npm:

npm install -g @terracotta/cli

Or run via npx without installing:

npx @terracotta/cli review

Requirements: Node.js 18 or later.

🔑 Authentication

tc login

Authenticate with your Terracotta API key. The key is validated against the Terracotta API and stored locally.

tc login
# Prompts for your API key (masked input)
# Validates the key and stores it in ~/.terracotta/config.json

To get an API key: navigate to Settings → API Keys in the Terracotta dashboard and click Create API Key.

tc logout

Clear stored credentials:

tc logout
# Removes ~/.terracotta/config.json

🔍 tc review

Run an AI-powered code review on Terraform files.

# Auto-detect changed .tf files via git (staged + unstaged)
tc review

# Review specific files
tc review main.tf variables.tf

# Review with glob patterns
tc review "modules/**/*.tf"

How auto-detection works

When no files are specified, tc review uses git diff to find all changed .tf, .tf.json, and .cdktf files (both staged and unstaged). This is the most common usage in local development.

Options

Examples

# Quick review with high detail
tc review --detail-level high

# CI pipeline — fail on high+ severity
tc review --ci --fail-on high

# JSON output for downstream tooling
tc review --format json > review-results.json

📋 tc plan

Analyze a Terraform plan for security, cost, blast radius, and best practices.

# Run terraform plan automatically and analyze the result
tc plan

# Analyze an existing plan file (binary .tfplan)
tc plan terraform.tfplan

# Analyze a JSON plan (from terraform show -json)
tc plan plan.json

How it works

1. If no [planfile] argument is given, tc plan runs terraform plan in the current directory (or --working-dir) and captures the output.
2. If a planfile is given, it detects whether it's binary (.tfplan) or JSON and parses accordingly. Binary plans are converted via terraform show -json.
3. Secret scrubbing: Before upload, sensitive attribute values (passwords, tokens, keys, credentials) are replaced with [REDACTED]. Variable values are never sent — only variable names.
4. No-op filtering: Resources with only no-op actions are excluded to reduce noise.
5. The structured payload is sent to the Terracotta API for analysis.

Options

Examples

# Analyze plan with markdown output
tc plan --format markdown

# CI pipeline with custom working directory
tc plan --ci --fail-on high --working-dir infra/prod

# Pass variables
tc plan --var "environment=staging" --var-file secrets.tfvars

⚙️ Configuration

The CLI loads configuration from multiple sources, in order of priority (highest first):

Environment variables

Project config (.terracottarc.json)

Create a .terracottarc.json file in your project root to set defaults for all team members:

{
  "format": "terminal",
  "detailLevel": "high",
  "failOn": "high"
}

🔄 CI/CD Integration

GitHub Actions

- name: Terracotta Review
  run: |
    npx @terracotta/cli review --ci --fail-on high
  env:
    TERRACOTTA_API_KEY: ${{ secrets.TERRACOTTA_API_KEY }}

GitLab CI

terracotta-review:
  script:
    - npx @terracotta/cli review --ci --fail-on high
  variables:
    TERRACOTTA_API_KEY: $TERRACOTTA_API_KEY

Exit Codes

📋 TL;DR

• Install: npm install -g @terracotta/cli
• Authenticate: tc login
• Review local changes: tc review
• Analyze a plan: tc plan
• Use --ci --fail-on <severity> for pipeline integration
• Config priority: env vars > flags > .terracottarc.json > ~/.terracotta/config.json > defaults