sops-setup

SOPS + age Setup Wizard

Interactive setup for SOPS + age encryption. Detects current state and guides through configuration.

Important: This skill uses YAML format for encrypted files (not dotenv) because SOPS has a known bug (#1435) where the dotenv store corrupts backslash and \n sequences on decrypt. A helper script handles dotenv↔YAML conversion transparently.

Pre-flight

Run the detection script to understand current state:

python3 ${CLAUDE_SKILL_DIR}/scripts/detect_sops.py <project-root>

Two-Phase Workflow

Phase 1: Detect

1. Run the detector on the project root:

``bash python3 ${CLAUDE_SKILL_DIR}/scripts/detect_sops.py <project-root> ``

1. Summarize findings — show a status table:

| Component | Status | Detail | |-----------|--------|--------| | sops binary | installed/missing | version, path | | age binary | installed/missing | version, path | | age key | exists/missing | public key (truncated) | | .sops.yaml | exists/missing | # of authorized keys | | .env files | N found | list of filenames | | encrypted files | N found | list of *.enc.yaml files | | .gitignore | ok/needs update | env ignored, enc.yaml not ignored |

Phase 2: Configure

Walk through each missing component. Skip steps where detection shows everything is already configured.

1. Install tools (if tools.sops.installed or tools.age.installed is false):
2. Show install commands based on os field:
3. macOS: brew install sops age
4. Linux: Show download URLs for latest binaries from GitHub releases
5. After user confirms installation, re-run detector to verify

1. Generate age key (if age_key.exists is false):
2. Create directory: mkdir -p ~/.config/sops/age
3. Generate key: age-keygen -o ~/.config/sops/age/keys.txt
4. Set permissions: chmod 600 ~/.config/sops/age/keys.txt
5. Display the public key and tell user to save it somewhere safe (password manager, secure note)

1. Generate backup key (recommended):
2. Use AskUserQuestion — offer to create an offline backup key for disaster recovery
3. If yes:

``bash age-keygen 2>&1 | tee /dev/stderr | grep "public key:" | awk '{print $NF}' `` Display BOTH the public key AND the full output (which includes the private key). Tell user: Copy the entire output (including the private key line starting with AGE-SECRET-KEY-) to a password manager or secure offline storage. This is your recovery key.

• The backup public key will be added to .sops.yaml alongside the machine key

1. Create .sops.yaml (if project.sops_yaml.exists is false):
2. Write .sops.yaml with machine key + backup key (if generated):

```yaml creation_rules:

• path_regex: (^|/)\.env\.[^/]+\.enc\.yaml$

age: >- <machine-public-key>, <backup-public-key> ```

• If .sops.yaml already exists but is missing this machine's key, offer to add it

1. Set up .gitattributes for diff-friendly encrypted files:
2. Add to .gitattributes:

`` *.enc.yaml diff=sopsdiffer ``

• Configure git:

``bash git config diff.sopsdiffer.textconv "sops decrypt" ``

• This makes git diff show decrypted content for encrypted files

1. Update .gitignore (if needed):
2. Ensure .env* patterns are ignored (secrets must not be committed in plaintext)
3. Ensure *.enc.yaml is NOT ignored (encrypted files should be committed)
4. Show proposed changes and confirm with user before writing

1. Encrypt files (if project.env_files is non-empty):
2. Use AskUserQuestion (multiSelect: true) — show detected .env* files
3. For each selected file, convert dotenv→YAML then encrypt:

``bash python3 ${CLAUDE_SKILL_DIR}/scripts/dotenv_yaml.py to-yaml <file> > <file>.enc.yaml.tmp sops --encrypt <file>.enc.yaml.tmp > <file>.enc.yaml rm <file>.enc.yaml.tmp ` Example: .env.local → .env.local.enc.yaml`

• Verify each encrypted file was created successfully

1. Confirmation summary — show table of all actions taken:

``` | Step | Action | Result | |------|--------|--------| | Tools | sops 3.9.4, age 1.2.0 | installed | | Key | Machine key generated | age1abc...def | | Key | Backup key generated | age1xyz...uvw (save offline!) | | Permissions | chmod 600 keys.txt | done | | Config | .sops.yaml created | 2 keys authorized | | Git | .gitattributes updated | sopsdiffer configured | | Git | .gitignore updated | .env* ignored | | Encrypt | .env.local → .env.local.enc.yaml | done |

## Next Steps

• Commit .sops.yaml, .gitattributes, and *.enc.yaml files to git
• On another machine: clone, install sops+age, place age key, run /devtools:sops-decrypt
• To add another machine: /devtools:sops-add-key
• To encrypt after editing .env: /devtools:sops-encrypt
• To decrypt after pulling: /devtools:sops-decrypt

```

Key Rules

• Never overwrite existing files without asking. Always offer merge/replace/skip.
• Detect first — skip steps that are already configured.
• Use AskUserQuestion for every decision. Do not assume user preferences.
• YAML format only — never use --input-type dotenv. Use the dotenv_yaml.py helper for conversion.
• chmod 600 on age key files immediately after creation.
• Display public keys after generation — user needs them for multi-machine setup.
• Verify after each step — re-run relevant checks to confirm success.

References

• Workflow: See [WORKFLOW.md](WORKFLOW.md) for detailed per-step flows
• Examples: See [EXAMPLES.md](EXAMPLES.md) for example setup sessions
• Troubleshooting: See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues
• Detection Script: See [scripts/detect_sops.py](scripts/detect_sops.py) for detection logic
• Converter: See [scripts/dotenv_yaml.py](scripts/dotenv_yaml.py) for dotenv↔YAML conversion
• Best Practices: See [references/sops-best-practices.md](references/sops-best-practices.md) for research