CLI Configuration

The Terracotta CLI (tc) uses cosmiconfig for configuration discovery, giving you flexible options for where and how you define your settings.

🚀 Overview

Configuration controls how tc authenticates, formats output, and decides which findings fail your CI pipeline. You can define configuration at the project level, the user level, or via environment variables — whatever fits your workflow.

🔍 Configuration Discovery

Cosmiconfig searches for configuration in the following locations, in order. The first match wins, searched from the current working directory upward:

.terracottarc
.terracottarc.json
.terracottarc.yaml
terracotta.config.js
package.json (under the "terracotta" key)

Place a .terracottarc.yaml in your repo root for project-wide settings. For user-specific overrides, place one in your home directory.

🛠️ Configuration Options

Option	Type	Default	Description
`apiKey`	string	required	API key for authentication. Can also be set via the `TERRACOTTA_API_KEY` environment variable.
`apiBaseUrl`	string	`https://api.terracotta.ai`	API endpoint URL. Override for self-hosted or staging environments.
`outputFormat`	string	`text`	Output format: `text`, `json`, or `markdown`.
`failOn`	string	`critical`	Minimum severity level that causes a non-zero exit code: `critical`, `high`, `medium`, `low`, `info`.
`guardrails`	boolean	`true`	Enable guardrail policy checks during reviews.
`excludePatterns`	array	`[]`	Glob patterns for files to exclude from analysis.

Environment variables take precedence over file-based configuration. Set TERRACOTTA_API_KEY in CI to avoid committing secrets.

🔐 Per-Rule Suppression

Add # tc:ignore:<rule-id> comments directly in your Terraform files to suppress specific findings on a per-line basis.

resource "aws_s3_bucket" "logs" {
  bucket = "my-logs-bucket"
  acl    = "private" # tc:ignore:s3-versioning-disabled
}

Suppressed findings still appear in the review output but are marked as ignored and do not affect the exit code.

🛠️ Example Configuration

A typical .terracottarc.yaml for a CI pipeline:

apiKey: ${TERRACOTTA_API_KEY}
apiBaseUrl: https://api.terracotta.ai
outputFormat: json
failOn: high
guardrails: true
excludePatterns:
  - "modules/deprecated/**"
  - "**/*.tftest.hcl"

For local development, a minimal configuration works:

apiKey: tc_dev_abc123
outputFormat: text
failOn: info

📋 TL;DR

tc discovers configuration via cosmiconfig — .terracottarc, .terracottarc.yaml, terracotta.config.js, or package.json
First match wins, searched from current directory upward
Set apiKey via config file or TERRACOTTA_API_KEY environment variable
Control CI behavior with failOn to set the severity threshold for non-zero exits
Suppress individual findings inline with # tc:ignore:<rule-id>
Use excludePatterns to skip files that should not be analyzed