Terraform & OpenTofu Credentials Helper

Use dotsecenv as a credentials helper for Terraform and OpenTofu. Registry and backend tokens (e.g., Terraform Cloud) are encrypted at rest in your vault — no plaintext credentials blocks in your CLI config.

Note

Credentials helpers handle registry and backend authentication only (e.g., Terraform Cloud, private module registries). They are not used for provider-specific credentials like cloud API keys — those are configured separately via provider blocks or environment variables.

How It Works

Terraform and OpenTofu call the credentials helper with three verbs:

Verb	Action	dotsecenv behavior
get <host>	Retrieve credentials for a registry	Returns stored JSON from vault, or {} if none
store <host>	Save credentials (JSON on stdin)	Validates and stores the full JSON object in vault
forget <host>	Remove credentials for a registry	Marks the secret as deleted in vault

Terraform passes the registry hostname (e.g., app.terraform.io) as the key. The helper stores it as a dotsecenv secret under that hostname. The full JSON credentials object is stored as-is, preserving all properties.

Prerequisites

• dotsecenv installed and configured with at least one vault (see Getting Started)
• Terraform >= 0.13 or OpenTofu >= 1.6

Installation

Credentials helpers must be placed in one of Terraform’s default plugin search locations. The most portable location across all platforms is ~/.terraform.d/plugins/.

Note

Terraform does not search your PATH for credentials helpers — only plugin directories. The -plugin-dir argument to terraform init is also ignored for credentials helpers.

Linux (apt/rpm)

The terraform-credentials-dotsecenv helper is included in the deb, rpm, and Arch packages and installed to /usr/share/terraform/plugins/.

Verify it’s available:

ls /usr/share/terraform/plugins/terraform-credentials-dotsecenv

macOS (Homebrew)

After installing dotsecenv via Homebrew, the helper is included in the release archive. Symlink it into a plugin directory:

mkdir -p ~/.terraform.d/plugins
ln -s "$(brew --prefix dotsecenv)/contrib/terraform-credentials-dotsecenv" \
  ~/.terraform.d/plugins/terraform-credentials-dotsecenv

Manual

Download the helper script from the release archive or copy it from contrib/terraform-credentials-dotsecenv:

# Linux / XDG Base Directory fallback
PLUGIN_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/terraform/plugins"
mkdir -p "$PLUGIN_DIR"
curl -fsSL https://raw.githubusercontent.com/dotsecenv/dotsecenv/main/contrib/terraform-credentials-dotsecenv \
  -o "$PLUGIN_DIR/terraform-credentials-dotsecenv"
chmod +x "$PLUGIN_DIR/terraform-credentials-dotsecenv"

Configuration

1. Verify the helper is installed

   Check that the binary exists in a plugin directory and is executable:

   ls -l ~/.terraform.d/plugins/terraform-credentials-dotsecenv

   Quick smoke test:

   ~/.terraform.d/plugins/terraform-credentials-dotsecenv get app.terraform.io
   # Should print: {}

2. Add to CLI config

   Terraform

   Add to ~/.terraformrc:

   credentials_helper "dotsecenv" {
     args = []
   }

   Caution

   Remove any existing credentials blocks for registries you want managed by dotsecenv. Terraform uses credentials blocks first, falling back to the helper only if no block matches.

   OpenTofu

   Add to ~/.tofurc:

   credentials_helper "dotsecenv" {
     args = []
   }

   Caution

   Remove any existing credentials blocks for registries you want managed by dotsecenv. OpenTofu uses credentials blocks first, falling back to the helper only if no block matches.

Usage

terraform login

Log in to a registry (e.g., Terraform Cloud):

terraform login

Terraform generates an API token and calls store to save it through dotsecenv. The token is encrypted and stored in your vault under the registry hostname (e.g., app.terraform.io).

terraform logout

terraform logout

Terraform calls forget to mark the credentials as deleted in your vault.

Manual operations

You can also call the helper directly. Terraform normally does this automatically, but manual calls are useful for debugging or scripting:

# Store
echo '{"token":"my-api-token"}' | terraform-credentials-dotsecenv store app.terraform.io

# Retrieve
terraform-credentials-dotsecenv get app.terraform.io

# Remove
terraform-credentials-dotsecenv forget app.terraform.io

Verifying the setup

After terraform login, confirm the token is stored in your vault:

dotsecenv secret get app.terraform.io --json

{
  "added_at": "2026-01-15T10:30:00Z",
  "value": { "token": "my-api-token" },
  "vault": "~/.secenv.vault"
}

Tip

Notice the value field contains the raw JSON object — not a string-escaped version. This is the smart value marshaling at work.

Troubleshooting

Problem	Cause	Solution
terraform login fails with “credentials helper not found”	Helper not in a plugin directory	Check it exists in ~/.terraform.d/plugins/ and is executable
store fails with “not valid JSON”	Malformed input	Check the JSON is well-formed with echo '...' | python3 -m json.tool
store fails with “must contain a ‘token’ property”	Missing token key	Terraform always sends a token property — check for manual input errors
get returns {} for a stored secret	Secret key case mismatch	dotsecenv normalizes keys to UPPERCASE; check with dotsecenv secret get
GPG passphrase prompt during terraform init	GPG agent not caching	Configure gpg-agent with a longer cache TTL in ~/.gnupg/gpg-agent.conf

---

Next Steps

• Getting Started — Set up dotsecenv and your first vault
• CLI Reference — Full command documentation
• Security Model — How encryption and access control work