Skip to content

secretzero sync (Example Integration)

Generate and synchronize secrets to targets.

This is an example page

This page demonstrates how to integrate auto-generated CLI documentation with your existing manual content.

Overview

The sync command is the workhorse of SecretZero. It reads your Secretfile, generates secrets according to configured generators, and deploys them to all specified targets.

Key Features

  • ✅ Idempotent - Safe to run multiple times without regenerating secrets
  • ✅ Dry-run mode - Preview changes before applying
  • ✅ Selective sync - Sync only specific secrets with --secret flag
  • ✅ Variable files - Override variables with .szvar files
  • ✅ Clean mode - Remove orphaned lockfile entries (new!)

Command Reference (Auto-Generated)

secretzero sync

Generate and synchronize secrets to targets.

When the global --non-interactive flag is set, interactive prompts are automatically disabled (equivalent to --no-prompt).

This command generates secret values according to your Secretfile configuration and stores them in the specified targets (local files, cloud providers, etc.).

By default, syncs all secrets. Use --secret to sync specific secrets only.

Variable files (.szvar) can be used to override variables defined in the Secretfile. Multiple variable files can be specified, and they are merged in order with later files taking precedence.

Examples:

Text Only
# Sync all secrets
secretzero sync

# Sync with variable file override
secretzero sync --var-file dev.szvar

# Sync with multiple variable files
secretzero sync --var-file base.szvar --var-file dev.szvar

# Sync only specific secrets
secretzero sync --secret db_password --secret api_key

# Short form
secretzero sync -s db_password -s api_key

# Re-push to one target when several exist and others are already synced
secretzero sync -s api_key --force-target local/file/.env.production

# Preview plan before applying
secretzero sync --plan

# Machine-readable plan output
secretzero sync --plan --format json

# Opt out of automatic pre-sync refresh
secretzero sync --no-refresh

Usage:

Text Only
secretzero sync [OPTIONS]

Options:

Name Type Description Default
--file, -f path Path to Secretfile Secretfile.yml
--lockfile, -l path Path to lockfile .gitsecrets.lock
--var-file, -v path Path to .szvar variable file(s) to merge (can be specified multiple times) Sentinel.UNSET
--environment, -e text Named environment profile from Secretfile.environments.profiles None
--dry-run boolean Show what would be done without making changes False
--plan boolean Show detailed execution plan (created/updated/unchanged/skipped) without applying False
--show-input boolean Show secret input as plain text when prompting (default: masked) False
--no-prompt boolean Disable interactive prompts (fail if values are missing) - useful for CI/CD False
--secret, -s text Sync only specific secrets by name (can be specified multiple times) Sentinel.UNSET
--format choice (text | json) Output format (text or json) text
--clean boolean Remove lockfile entries that have no corresponding secret in the Secretfile False
--refresh / --no-refresh boolean Refresh lockfile target validity right before sync (default: enabled; use --no-refresh to opt out) True
--force-target text Re-push the current secret value to these target IDs only (repeatable). Target IDs match the lockfile (e.g. local/file/.env, github/github_secret/…). Requires exactly one --secret. Use when multiple targets exist and at least one is already synced. Sentinel.UNSET
--help, -h boolean Show this message and exit. False

The above reference is automatically generated from the source code and always reflects the current CLI options.

Examples

Basic Usage

Generate and sync all secrets:

Bash
secretzero sync

Output:

Text Only
Synchronizing secrets...

Summary
✓ Success: 3 secret(s) stored
⊙ Skipped: 1 secret(s) skipped

✓ Lockfile saved: .gitsecrets.lock

Dry Run

Preview what would be generated without making changes:

Bash
secretzero sync --dry-run

Sync Specific Secrets

Sync only certain secrets:

Bash
# Single secret
secretzero sync --secret database_password

# Multiple secrets
secretzero sync --secret database_password --secret api_key

# Short form
secretzero sync -s database_password -s api_key

Custom Secretfile and Lockfile

Use specific files:

Bash
secretzero sync --file Secretfile.prod.yml --lockfile .production.lock

# Short form
secretzero sync -f Secretfile.prod.yml -l .production.lock

Variable File Overrides

Override variables for different environments:

Bash
# Single variable file
secretzero sync --var-file prod.szvar

# Multiple variable files (merged in order)
secretzero sync --var-file base.szvar --var-file prod.szvar

# Short form
secretzero sync -v base.szvar -v prod.szvar

Clean Orphaned Entries

Remove lockfile entries that no longer have a corresponding secret in the Secretfile:

Bash
# Clean during sync
secretzero sync --clean

# Preview what would be cleaned
secretzero sync --clean --dry-run

Output:

Text Only
Summary
✓ Success: 2 secret(s) stored
🗑 Cleaned: 3 orphaned lockfile entries

Cleaned Lockfile Entries (3 orphaned)
╭──────────┬───────────────┬─────────╮
│  Status  │ Secret Name   │ Result  │
├──────────┼───────────────┼─────────┤
│    🗑     │ old_secret_1  │ Removed │
│    🗑     │ old_secret_2  │ Removed │
│    🗑     │ old_secret_3  │ Removed │
╰──────────┴───────────────┴─────────╯

Execution Plan

Show detailed plan without applying changes:

Bash
secretzero sync --plan

Output:

Text Only
PLAN: Showing execution plan without applying changes

Execution Plan
╭────────┬─────────────────┬─────────────────┬──────────╮
│ Action │ Secret Name     │ Type            │ Targets  │
├────────┼─────────────────┼─────────────────┼──────────┤
│ create │ database_password│ random_password│ aws/ssm  │
│ update │ api_key         │ static          │ local/file│
│ skip   │ master_key      │ random_password │ local/file│
╰────────┴─────────────────┴─────────────────┴──────────╯

Plan summary: 2 create/update, 1 skip

Run 'secretzero sync' to apply this plan.

JSON Output

Get machine-readable output:

Bash
secretzero sync --format json

How Sync Works

1. Load Configuration

Reads and validates the Secretfile:

Text Only
Loading: Secretfile.yml
Validating configuration...

2. Load Lockfile

Reads existing lockfile (if any):

Text Only
Loading lockfile: .gitsecrets.lock

3. Clean Orphans (if --clean)

If --clean flag is used, removes lockfile entries that don't have a corresponding secret in the Secretfile.

4. Check Each Secret

For each secret in the Secretfile:

  • Check if already generated (exists in lockfile)
  • Check if one_time flag is set
  • Determine if generation is needed

5. Generate Secrets

Generate new secret values for secrets that need them:

  • Random passwords
  • Random strings
  • Static values
  • Script outputs
  • API responses

6. Store in Targets

Store generated secrets in configured targets:

  • Local files (.env, JSON, YAML, TOML)
  • AWS SSM Parameter Store
  • AWS Secrets Manager
  • HashiCorp Vault
  • Azure Key Vault
  • Kubernetes Secrets
  • GitHub Actions Secrets
  • GitLab CI/CD Variables
  • Jenkins Credentials

7. Update Lockfile

Update lockfile with:

  • SHA-256 hashes of generated values
  • Creation and update timestamps
  • Secretfile hash for change detection
  • Metadata about secrets

Behavior

Idempotent Operation

Sync is idempotent - running it multiple times won't regenerate secrets unnecessarily:

Bash
# First run - generates all secrets
secretzero sync
# Output: Generated: 3

# Second run - skips existing secrets
secretzero sync
# Output: Generated: 0, Skipped: 3

One-Time Secrets

Secrets marked as one_time are never regenerated:

YAML
secrets:
  - name: master_key
    kind: random_password
    one_time: true  # Generated once, never again
    config:
      length: 64
Bash
secretzero sync
# First run: generates master_key

secretzero sync
# Subsequent runs: always skips master_key

Adding New Secrets

When you add new secrets to your Secretfile, only the new secrets are generated:

YAML
# Original Secretfile.yml
secrets:
  - name: existing_secret
    kind: random_password

  # Add new secret
  - name: new_secret
    kind: random_password
Bash
secretzero sync
# Only generates: new_secret
# Skips: existing_secret

Best Practices

1. Always Test with --dry-run First

Before running sync in production, preview changes:

Bash
# Preview first
secretzero sync --dry-run

# Or use plan for detailed view
secretzero sync --plan

# Then apply
secretzero sync

2. Use Variable Files for Environments

Keep environment-specific configuration in .szvar files:

Bash
# Development
secretzero sync --var-file dev.szvar

# Production
secretzero sync --var-file prod.szvar

3. Commit Lockfiles

Always commit lockfiles to version control:

Bash
git add .gitsecrets.lock
git commit -m "Update secrets lockfile"

This provides: - Audit trail of secret changes - Change detection via diffs - Rollback capability

4. Clean Periodically

Remove orphaned entries when refactoring:

Bash
# After removing secrets from Secretfile
secretzero sync --clean

5. Use Selective Sync in CI/CD

Only sync secrets needed for specific jobs:

Bash
# GitHub Actions
secretzero sync --secret github_token --no-prompt

# Only sync API secrets
secretzero sync -s api_key -s api_secret

Troubleshooting

Secret Not Generated

If a secret isn't generated:

  1. Check if it exists in lockfile (use secretzero status)
  2. Check if one_time: true is set
  3. Use --dry-run to see why it's skipped

Provider Connection Errors

If you see "No accessible targets":

Bash
# Test provider connectivity first
secretzero test

# Check specific provider
secretzero test --provider aws

Lockfile Conflicts

If lockfile has merge conflicts:

  1. Don't manually edit lockfile during conflicts
  2. Run secretzero sync after resolving merge
  3. The lockfile will be regenerated correctly

See Also