SECRETS MANAGEMENT - nself-org/cli GitHub Wiki

Secrets Management

nself CLI version: 0.9.6+ Last updated: January 31, 2026

Overview

nself provides comprehensive secrets management to protect sensitive credentials, API keys, and passwords. This guide covers best practices, command usage, and integrations with external secret managers.

Table of Contents

Quick Start

Generate Secrets for New Project

# During initialization
nself init
# Wizard will prompt for secrets generation

# Or generate manually
nself config secrets generate

This creates .env.secrets with strong random values:

# View generated secrets (masked)
nself config secrets list

# View specific secret (masked)
nself config secrets get POSTGRES_PASSWORD

# View actual value (use carefully!)
nself config secrets get POSTGRES_PASSWORD --reveal

Validate Secrets

# Check secret strength and security
nself config secrets validate

# Output:
# โœ“ POSTGRES_PASSWORD is set (32 chars)
# โœ“ HASURA_GRAPHQL_ADMIN_SECRET is set (64 chars)
# โœ“ JWT_SECRET is set (64 chars)
# โœ“ File permissions are correct (600)
# โœ“ Secrets file is properly ignored by git

Security Best Practices

1. Never Commit Secrets to Git

Automatic Protection:

  • .env.secrets is automatically added to .gitignore
  • nself doctor warns if secrets are tracked by git

Manual Verification:

# Check if secrets are tracked
git ls-files | grep .env.secrets

# Should return nothing
# If found, remove from git:
git rm --cached .env.secrets
git commit -m "Remove secrets from git"

2. Use Strong Secrets

โœ… Good: Generated by nself (32-64 characters, random)

POSTGRES_PASSWORD=aB3kL9mP2xQ7vN4wY8zR1tS5uO6cF0dH

โŒ Bad: Weak, default, or predictable

POSTGRES_PASSWORD=postgres123
POSTGRES_PASSWORD=password
POSTGRES_PASSWORD=admin

Check for Weak Secrets:

nself doctor
# Automatically detects weak/default secrets

3. Secure File Permissions

Correct Permissions: 600 (owner read/write only)

# Set correct permissions
chmod 600 .env.secrets

# Verify
ls -la .env.secrets
# Should show: -rw-------

Security Check:

nself doctor
# Checks file permissions automatically

4. Rotate Secrets Regularly

Single Secret:

# Rotate specific secret
nself config secrets rotate POSTGRES_PASSWORD

# Backup created automatically
# New value generated
# Restart required to apply

All Secrets:

# Rotate everything
nself config secrets rotate --all

# โš ๏ธ Warning: This will generate new values for ALL secrets
# Continue? (y/N) y

After Rotation:

# Restart services to apply new secrets
nself restart

5. Environment Isolation

Development:

# .env.secrets (weak passwords OK)
POSTGRES_PASSWORD=dev-password-123

Production:

# .env.secrets (MUST be strong)
POSTGRES_PASSWORD=$(nself config secrets generate POSTGRES_PASSWORD)
# Or use external secret manager

Command Reference

Generate Secrets

Generate All Secrets

nself config secrets generate

# Output file: .env.secrets (default)
# Generates:
# - POSTGRES_PASSWORD (32 chars, alphanumeric)
# - HASURA_GRAPHQL_ADMIN_SECRET (64 chars, hex)
# - JWT_SECRET (64 chars, hex)
# - COOKIE_SECRET (32 chars, hex)
# - MINIO_ROOT_PASSWORD (32 chars, alphanumeric)
# - REDIS_PASSWORD (32 chars, alphanumeric)
# - GRAFANA_ADMIN_PASSWORD (24 chars, alphanumeric)

Generate Specific Secret

# Generate custom secret
nself config secrets generate MY_API_KEY

# Specify length and type
nself config secrets generate MY_SECRET 64 hex
# Types: hex, base64, alphanumeric

List Secrets

# List all secrets (masked)
nself config secrets list

# Output:
#   POSTGRES_PASSWORD (32 chars)
#   HASURA_GRAPHQL_ADMIN_SECRET (64 chars)
#   JWT_SECRET (64 chars)

# List for specific environment
nself config secrets list --env staging

Get Secret Value

# Get masked value (safe)
nself config secrets get POSTGRES_PASSWORD
# Output: ********

# Get actual value (use carefully!)
nself config secrets get POSTGRES_PASSWORD --reveal
# Output: aB3kL9mP2xQ7vN4wY8zR1tS5uO6cF0dH

Set Secret

# Set manually (not recommended - use generate instead)
nself config secrets set API_KEY "your-api-key-here"

# โš ๏ธ Better: Generate random value
nself config secrets generate API_KEY

Delete Secret

# Remove secret from file
nself config secrets delete OLD_API_KEY

# Confirm deletion
nself config secrets list

Rotate Secrets

# Rotate single secret
nself config secrets rotate POSTGRES_PASSWORD

# Backup created: .env.secrets.backup-20260131-120000
# New value generated and replaced
# Restart services: nself restart

# Rotate all secrets (with confirmation)
nself config secrets rotate --all

# โš ๏ธ Warning shown
# Requires confirmation
# Creates backup automatically

Validate Secrets

# Run comprehensive validation
nself config secrets validate

# Checks:
# โœ“ Required secrets present
# โœ“ Secret length sufficient (16+ chars)
# โœ“ No weak/default values
# โœ“ File permissions (600)
# โœ“ Git ignore status
# โœ“ Not tracked in git

Encrypt/Decrypt Secrets

# Encrypt secrets file
nself config secrets encrypt .env.secrets
# Enter encryption password: ****
# Creates: .env.secrets.enc

# Decrypt when needed
nself config secrets decrypt .env.secrets.enc
# Enter decryption password: ****
# Restores: .env.secrets

Use Cases:

  • Store encrypted backup in cloud storage
  • Share with team members securely
  • Archive old secrets safely

External Integrations

HashiCorp Vault

Prerequisites

# Install Vault CLI
brew install vault
# or: https://www.vaultproject.io/downloads

Import from Vault

# Import secrets from Vault
nself config secrets import vault secret/nself

# Reads from: secret/nself
# Writes to: .env.secrets

Export to Vault

# Export secrets to Vault
nself config secrets export vault secret/nself

# Reads from: .env.secrets
# Writes to: secret/nself

Vault Configuration:

# Set Vault address
export VAULT_ADDR='http://127.0.0.1:8200'

# Authenticate
vault login

# Then use nself commands
nself config secrets import vault

AWS Secrets Manager

Prerequisites

# Install AWS CLI
brew install awscli
# or: https://aws.amazon.com/cli/

# Configure credentials
aws configure

Import from AWS

# Import secrets from AWS Secrets Manager
nself config secrets import aws nself/production

# Secret ID: nself/production
# Writes to: .env.secrets

Export to AWS

# Export secrets to AWS Secrets Manager
nself config secrets export aws nself/production

# Creates/updates secret: nself/production
# Source: .env.secrets

AWS IAM Permissions Required:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:CreateSecret",
        "secretsmanager:UpdateSecret"
      ],
      "Resource": "arn:aws:secretsmanager:*:*:secret:nself/*"
    }
  ]
}

Environment Variables

# Import from environment variables
export NSELF_SECRET_POSTGRES_PASSWORD="secure-password"
export NSELF_SECRET_REDIS_PASSWORD="another-secure-password"

nself config secrets import env

# Imports all NSELF_SECRET_* variables
# Strips prefix and writes to .env.secrets

Custom Prefix:

export MY_APP_POSTGRES_PASSWORD="password"
export MY_APP_REDIS_PASSWORD="password"

nself config secrets import env MY_APP_

Troubleshooting

Secrets File Not Found

Problem:

nself config secrets list
# No secrets file found: .env.secrets

Solution:

# Generate secrets
nself config secrets generate

Weak Secrets Detected

Problem:

nself doctor
# โŒ Detected 3 weak or default secret(s)

Solution:

# Rotate all weak secrets
nself config secrets rotate --all

# Or rotate individually
nself config secrets rotate POSTGRES_PASSWORD
nself config secrets rotate HASURA_GRAPHQL_ADMIN_SECRET

Secrets Tracked by Git

Problem:

nself doctor
# โŒ .env.secrets IS TRACKED BY GIT - CRITICAL SECURITY ISSUE!

Solution:

# Remove from git immediately
git rm --cached .env.secrets

# Ensure it's in .gitignore
echo ".env.secrets" >> .gitignore

# Commit the fix
git commit -m "Remove secrets from git and add to .gitignore"

# โš ๏ธ IMPORTANT: Rotate ALL secrets immediately
nself config secrets rotate --all
# Because they were exposed in git history

Insecure File Permissions

Problem:

nself doctor
# โŒ .env.secrets has insecure permissions: 644 (should be 600)

Solution:

# Fix permissions
chmod 600 .env.secrets

# Verify
ls -la .env.secrets
# -rw------- (owner read/write only)

Secret Too Short

Problem:

nself config secrets validate
# โš ๏ธ POSTGRES_PASSWORD is too short (12 chars)

Solution:

# Rotate to generate longer secret
nself config secrets rotate POSTGRES_PASSWORD

# Or manually set strong value
nself config secrets generate POSTGRES_PASSWORD 32 alphanumeric

Lost Secrets File

Problem: Accidentally deleted .env.secrets

Solution:

# Check for backup
ls -la .env.secrets.backup-*

# If backup exists, restore it
cp .env.secrets.backup-20260131-120000 .env.secrets
chmod 600 .env.secrets

# If no backup, regenerate (โš ๏ธ will lose access to data)
nself config secrets generate

# You'll need to:
# 1. Update database password
# 2. Restart all services
# 3. May lose access to encrypted data

Prevention: Always backup .env.secrets securely:

# Encrypted backup to safe location
nself config secrets encrypt .env.secrets
# Store .env.secrets.enc in secure backup location

Advanced Topics

Secret Rotation Strategy

Development:

  • Rotate when compromised
  • No regular rotation needed

Staging:

  • Rotate monthly
  • After team member changes

Production:

  • Rotate quarterly (minimum)
  • After security incidents
  • When team members leave
  • After 3rd party breaches

Zero-Downtime Secret Rotation

# 1. Generate new secret value
NEW_PASSWORD=$(nself config secrets generate POSTGRES_PASSWORD)

# 2. Update database to accept both old and new
# (implementation depends on service)

# 3. Update .env.secrets with new value
nself config secrets set POSTGRES_PASSWORD "$NEW_PASSWORD"

# 4. Rolling restart of services
nself restart --rolling

# 5. Remove old password from database
# (after confirming all services using new password)

Multi-Environment Secrets

# Development
.env.secrets  # Weak passwords OK

# Staging
.environments/staging/.env.secrets

# Production
.environments/production/.env.secrets

# Generate for each environment
nself config secrets generate --env staging
nself config secrets generate --env production

Audit Logging

# Check who rotated secrets
cat .env.secrets.backup-* | head -5
# Shows generation date and user

# Git log for secret rotation commits
git log --all --grep="rotate.*secret" --oneline

Security Checklist

Before deploying to production:

  • All secrets generated with nself config secrets generate
  • No weak or default passwords (nself doctor passes)
  • File permissions set to 600 (ls -la .env.secrets)
  • File in .gitignore (grep .env.secrets .gitignore)
  • Not tracked by git (git ls-files | grep secrets returns nothing)
  • Backup created and stored securely
  • Secret rotation schedule defined
  • Access limited to necessary team members
  • Encrypted backups in secure storage
  • Integration with secret manager (Vault/AWS) configured

Related Documentation

Last Updated: January 31, 2026 nself Version: 0.9.6+ Maintainers: nself Core Team

ษณSelf CLI v1.0.9. MIT licensed. Docs CC BY 4.0.

GitHub ยท Issues ยท Discussions ยท nself.org ยท docs.nself.org

โš ๏ธ **GitHub.com Fallback** โš ๏ธ