Env Sync — Secret Server to .env File

Refreshes a .env file by pulling the latest secret values from Secret Server. Uses a JSON map that defines which secret IDs map to which environment variable names.

When to use

• The user asks to refresh credentials in an env file
• A secret was rotated and env files need to be updated
• Setting up a new environment from Secret Server

Prerequisites

1. Valid Secret Server token (ss-cli token-status --json → "valid": true)
2. A JSON map file defining secret → env var mappings
3. Either configured defaults or explicit paths

Map file format

[
  {
    "secretId": 21908,
    "name": "LDAP credentials",
    "fields": {
      "username": "LDAP_USERNAME",
      "password": "LDAP_PASSWORD"
    }
  },
  {
    "secretId": 21909,
    "name": "InfluxDB",
    "fields": {
      "username": "INFLUXDB_USERNAME",
      "password": "INFLUXDB_PASSWORD",
      "url": "INFLUXDB_URL"
    },
    "transforms": {
      "url": "hostname"
    }
  }
]

Supported transforms: hostname (extracts hostname from URL), dbname (extracts path from URL).

Running the sync

# Use configured defaults
ss-cli refresh-env

# Specify paths explicitly
ss-cli refresh-env --env-file /path/to/global.env --map-file /path/to/env-map.json

One-time config setup

ss-cli config set defaultEnvFile /path/to/global.env
ss-cli config set envMapFile /path/to/env-map.json

Script

./skills/env-sync/scripts/env-sync.sh [--env-file <path>] [--map-file <path>]

Pairing with dotenvx

For encrypted env files that are safe to commit to git:

# Pull secrets
ss-cli refresh-env --env-file .env --map-file env-map.json

# Encrypt the result
dotenvx encrypt .env

# Apps decrypt at runtime
dotenvx run -- docker-compose up -d

After sync

Remind the user to restart any services that load the env file at startup — changes only take effect when services restart.