terraci init

Initialize a TerraCi configuration file.

Synopsis

terraci init [flags]

Description

The init command creates a .terraci.yaml configuration file. By default, it launches an interactive TUI wizard that guides you through configuration choices. Use --ci for non-interactive mode suitable for automation, or pass specific flags to skip the wizard.

Flags

Flag	Short	Type	Default	Description
--force	-f	bool	false	Overwrite existing configuration
--ci		bool	false	Non-interactive mode (skip TUI wizard)
--provider		string		CI provider: gitlab or github
--binary		string		Terraform binary: terraform or tofu
--pattern		string		Directory structure pattern

When any of --provider, --binary, or --pattern is provided, the wizard is automatically skipped and non-interactive mode is used.

Examples

Interactive Mode (Default)

terraci init

This launches a TUI wizard with the following groups:

1. Basics — CI provider (GitLab CI or GitHub Actions), Terraform binary (Terraform or OpenTofu)
2. Structure — directory structure pattern
3. Pipeline Options — configure plan jobs
4. Plugin groups — dynamic groups contributed by enabled plugins (gitlab/github image, summary, cost, policy, tfupdate, etc.)

Non-Interactive Mode

terraci init --ci

Creates .terraci.yaml with default values without prompting.

Provider Selection

# Generate config for GitHub Actions
terraci init --provider github

# Generate config for GitLab CI
terraci init --provider gitlab

When --provider github is used, the generated config will have a github: section (with runs_on, steps_before, etc.) and no gitlab: section. When --provider gitlab is used, the config will have a gitlab: section (with image, tags, etc.) and no github: section.

OpenTofu Setup

terraci init --provider gitlab --binary tofu

This automatically selects the appropriate image (ghcr.io/opentofu/opentofu:1.6) and for GitHub Actions, uses opentofu/setup-opentofu@v1 instead of hashicorp/setup-terraform@v3.

Custom Pattern

terraci init --pattern "{team}/{stack}/{datacenter}/{component}"

Full Non-Interactive Example

terraci init --provider github --binary tofu --pattern "{service}/{environment}/{region}/{module}"

Force Overwrite

terraci init --force

Overwrites existing .terraci.yaml without prompting.

Different Directory

terraci -d /path/to/project init

Creates configuration in specified directory.

Generated Configuration

GitLab Provider

When --provider gitlab (or default), creates:

structure:
  pattern: "{service}/{environment}/{region}/{module}"

execution:
  binary: terraform

extensions:
  gitlab:
    image:
      name: hashicorp/terraform:1.6
    stages_prefix: deploy

GitHub Provider

When --provider github, creates:

structure:
  pattern: "{service}/{environment}/{region}/{module}"

execution:
  binary: terraform

extensions:
  github:
    runs_on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    job_defaults:
      steps_before:
        - uses: actions/checkout@v4
        - uses: hashicorp/setup-terraform@v3

Backend configuration (S3, GCS, etc.) is not generated by terraci init — TerraCi reads existing terraform { backend "..." } blocks from your modules to disambiguate state keys; nothing is added to .terraci.yaml.

What Gets Created

The command creates:

• .terraci.yaml in the current (or specified) directory

It does NOT modify:

• Existing Terraform files
• CI configuration files
• Any other project files

After Initialization

1. Review the configuration

   cat .terraci.yaml

2. Customize for your project

   • Adjust the pattern to match your structure
   • Update the Docker image or runner labels
   • Add exclude patterns
   • Configure backend settings

3. Validate

   terraci validate

4. Generate your first pipeline

   terraci generate --dry-run
   # For GitLab:
   terraci generate -o .gitlab-ci.yml
   # For GitHub:
   terraci generate -o .github/workflows/terraform.yml

Troubleshooting

File Already Exists

Error: config file already exists: .terraci.yaml (use --force to overwrite)

Solution: Use --force or manually edit the existing file.

Permission Denied

Error: permission denied: .terraci.yaml

Solution: Check file permissions and ownership.

See Also

• Configuration Overview -- full configuration reference for .terraci.yaml
• Getting Started -- step-by-step guide to set up TerraCi