secrets-sync-cli

secrets-sync-cli

Sync .env files and GitHub Actions secrets with lightweight drift detection and guardrails built for monorepos and multi-env apps.

Why this tool

• Keep production as the canonical source of truth while highlighting drift in other env files.
• Avoid tedious copy/paste when updating GitHub Actions secrets.
• Preview every change with dry-run and optional confirmation gates.

Prerequisites

• Node.js 18+ (for running the CLI)
• Bun runtime (for development - install from bun.sh)
• GitHub CLI (gh) authenticated if you want to sync to GitHub Secrets
• Env files live in config/env by default (configurable via --dir)

Install

# Add to your project (recommended for pinned version)
bun add -D secrets-sync-cli
# or
npm install -D secrets-sync-cli

# Ad-hoc without installing
bunx secrets-sync --help
# or
npx secrets-sync --help

🚀 Quick start

• Ensure you have a production file at config/env/.env (canonical) and any env-specific files like .env.staging.
• Validate and preview changes:

# Using bunx/npx (no install needed)
bunx secrets-sync --dry-run
bunx secrets-sync --env staging --dry-run

# If installed locally
secrets-sync --dry-run

• Apply changes (writes backups first):

secrets-sync --env staging

• Sync to GitHub Actions when gh is available:

secrets-sync --env production --dry-run

Default directory structure

your-project/
├── config/
│   └── env/
│       ├── .env                # production (canonical)
│       ├── .env.production     # optional overrides
│       ├── .env.staging
│       ├── .env.development
│       └── required-secrets.json (optional)
└── env-config.yml              # optional CLI defaults

What it does

• Discover .env* files under the configured directory (skips templates/examples).
• Treat .env as canonical; compare other envs against it for missing or extra keys.
• Optionally validate against required-secrets.json.
• Show a diff and audit summary; in non-dry runs, write updates and timestamped backups.
• When enabled, push secrets to GitHub Actions using the GitHub CLI (gh secret commands).

✨ Key features

• Drift detection between production and other environments.
• GitHub Actions sync via gh with dry-run safety.
• Optional required-secrets validation.
• Smart skipping for .example, .template, .local, .test env files.
• .gitignore protection with --fix-gitignore.
• Best-effort secret scrubbing in console/log output to reduce accidental leaks.

🔌 Provider support

Currently supported:

• ✅ GitHub Actions (via GitHub CLI)

Planned (see issue #52):

• ⬜ AWS Secrets Manager
• ⬜ Azure Key Vault
• ⬜ GCP Secret Manager
• ⬜ HashiCorp Vault

⚙️ Configuration

Required secrets (optional) config/env/required-secrets.json:

{
  "shared": ["API_KEY", "DATABASE_URL"],
  "production": ["PROD_SECRET"],
  "staging": ["STAGING_SECRET"]
}

CLI defaults env-config.yml (project root):

flags:
  skipUnchanged: true
  backupRetention: 5

skipSecrets:
  - DEBUG
  - LOCAL_ONLY_VAR

Contextual Help

Get detailed help for any flag by adding --help after it:

secrets-sync --force --help
secrets-sync --env --help
secrets-sync --dry-run --help

Each flag shows:

• Description and usage examples
• When to use (and when not to)
• Related flags
• Documentation links

Works with short flags too: secrets-sync -f --help

CLI options

Flag	Description
--env <name>	Target specific environment
--dir <path>	Env files directory (default: config/env)
--dry-run	Preview changes without applying
--overwrite	Apply all changes without prompts
--force, -f	Use prefixes for production files
--skip-unchanged	Skip secrets with matching hashes
--no-confirm	Non-interactive mode
--fix-gitignore	Add missing .gitignore patterns
--verbose	Show detailed output
--help, -h	Show help message
--version, -v	Show version

💡 Examples

# Preview changes
secrets-sync --dry-run

# Sync specific environment
secrets-sync --env staging

# Fix .gitignore patterns
secrets-sync --fix-gitignore

# Non-interactive mode (requires --overwrite)
secrets-sync --overwrite --no-confirm

🔒 Security and data handling

• Scrubbing is best-effort: it hides common secret patterns, but you should still avoid pasting real secrets into terminals or issue trackers.
• Backups are stored locally with timestamps; review before discarding.
• .gitignore checks aim to keep env files out of version control, but verify your ignore rules before committing.

Troubleshooting and docs

• Contributing Guidelines — Development setup and workflows.
• Changelog — Release history.
• Troubleshooting — Common fixes.
• Error Message Patterns — Error handling standards.

License

MIT © Dorsey Creative

Contributing

Issues and PRs welcome. Please read the contributing guidelines first.