Secrets Management

Secrets Management

Manage environment secrets across local and VPS environments. strut provides tools to generate, sync, diff, and validate .env files without manual SCP or copy-paste.

Since: v0.25.0 (init-secrets), v0.26.0 (secrets push/pull/diff/validate)

Overview

The secrets workflow has two complementary tools:

Command	Purpose
init-secrets	Generate a populated .env from a .env.template
secrets push	Upload local .env to VPS (secure SCP, mode 600)
secrets pull	Download .env from VPS to local
secrets diff	Compare local vs remote keys (values redacted)
secrets validate	Check all required_vars are present and non-empty

Generating Secrets (init-secrets)

Start from a stack's .env.template and auto-generate cryptographic secrets for password, token, and key variables:

strut my-app init-secrets --env prod
strut my-app init-secrets --env prod --dry-run   # preview without writing
strut my-app init-secrets --env staging --force  # overwrite existing values

How It Works

1. Reads stacks/<stack>/.env.template
2. Detects placeholder values (changeme, xxxx, empty, etc.)
3. Auto-generates secrets based on key name patterns:
   • *SECRET*, *JWT* → 32-byte hex
   • *PASSWORD* → 16-byte hex
   • *SALT* → 16-byte hex
   • *TOKEN*, *KEY* (generic) → 24-byte hex
   • *ENCRYPTION* → 32-byte hex
4. Respects generation hints in comments:

   # Generate with: openssl rand -hex 64
   MY_SECRET=changeme

5. Leaves API keys, domains, and URLs as-is (user must fill manually)

Safety

• Never overwrites existing non-placeholder values (unless --force)
• Safe to re-run — only fills in missing/placeholder values
• Variables needing manual input (API keys, external URLs) are left untouched

Placeholder Detection

These patterns are recognized as placeholders:

• Empty values
• changeme, CHANGEME, Change-Me
• your-*, YOUR_*
• xxxx, XXXX
• replace-*, REPLACE_*
• todo, TODO, fixme, FIXME
• example, placeholder

Syncing Secrets to VPS

Push

Upload local .env to the VPS:

strut my-app secrets push --env prod
strut my-app secrets push --env prod --force     # overwrite existing remote
strut my-app secrets push --env prod --dry-run

Before pushing, strut automatically validates required_vars (if the file exists). If any required variables are missing, the push aborts.

Pull

Download the remote .env to local:

strut my-app secrets pull --env prod
strut my-app secrets pull --env prod --force     # overwrite local file

Diff

Compare local and remote env files without exposing values:

strut my-app secrets diff --env prod

Output shows:

• Changed — keys present in both but with different values
• Only in local — keys you have locally but not on VPS
• Only on remote — keys on VPS you don't have locally

Values are never displayed — only key names.

Validate

Check that all variables in required_vars are present and non-empty:

strut my-app secrets validate --env prod

Typical Workflow

# 1. Create .env from template with generated secrets
strut my-app init-secrets --env prod

# 2. Fill in remaining values manually (API keys, domains)
nano .prod.env

# 3. Validate everything is set
strut my-app secrets validate --env prod

# 4. Push to VPS
strut my-app secrets push --env prod

# 5. Deploy
strut my-app release --env prod

File Resolution

strut looks for env files in this order:

1. stacks/<stack>/.<env>.env (stack-level)
2. <project_root>/.<env>.env (project-level)

Remote path: <deploy_dir>/.<env>.env

Relationship to Other Tools

Tool	Purpose
init-secrets	Generate initial .env from template
secrets push/pull	Sync .env between local and VPS
secrets diff	Compare local vs remote
keys env:*	Rotate/validate individual env vars
drift detect	Detect config file drift (broader than just secrets)