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:

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

2. 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):
   • Show install commands based on

     os

     field:
     • macOS:

       brew install sops age

     • Linux: Show download URLs for latest binaries from GitHub releases
   • After user confirms installation, re-run detector to verify

2. Generate age key (if

   age_key.exists

   is false):
   • Create directory:

     mkdir -p ~/.config/sops/age

   • Generate key:

     age-keygen -o ~/.config/sops/age/keys.txt

   • Set permissions:

     chmod 600 ~/.config/sops/age/keys.txt

   • Display the public key and tell user to save it somewhere safe (password manager, secure note)

3. Generate backup key (recommended):

   • Use

     AskUserQuestion

     — offer to create an offline backup key for disaster recovery
   • If yes:

     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

4. Create

   .sops.yaml

   (if

   project.sops_yaml.exists

   is false):
   • Write

     .sops.yaml

     with machine key + backup key (if generated):

     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

5. Set up

   .gitattributes

   for diff-friendly encrypted files:
   • Add to

     .gitattributes

     :

     *.enc.yaml diff=sopsdiffer
     

   • Configure git:

     git config diff.sopsdiffer.textconv "sops decrypt"
     

   • This makes

     git diff

     show decrypted content for encrypted files

6. Update

   .gitignore

   (if needed):
   • Ensure

     .env*

     patterns are ignored (secrets must not be committed in plaintext)
   • Ensure

     *.enc.yaml

     is NOT ignored (encrypted files should be committed)
   • Show proposed changes and confirm with user before writing

7. Encrypt files (if

   project.env_files

   is non-empty):
   • Use

     AskUserQuestion

     (multiSelect: true) — show detected

     .env*

     files
   • For each selected file, convert dotenv→YAML then encrypt:

     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

8. 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 for detailed per-step flows
• Examples: See EXAMPLES.md for example setup sessions
• Troubleshooting: See TROUBLESHOOTING.md for common issues
• Detection Script: See scripts/detect_sops.py for detection logic
• Converter: See scripts/dotenv_yaml.py for dotenv↔YAML conversion
• Best Practices: See references/sops-best-practices.md for research