Features

Secret Promotion

Copy secrets from one environment to another. Useful for preparing a release — promote from development to staging to production with a single command.

CLI Usage

Promote all secrets

secr promote --from development --to staging

Dry run

Preview what would be promoted without making any changes:

secr promote --from development --to staging --dry-run

Overwrite existing secrets

By default, secrets that already exist in the target environment are skipped. Use --overwrite to update them:

secr promote --from staging --to production --overwrite

Promote specific keys

Pass a comma-separated list of keys to promote only a subset:

secr promote --from development --to staging \
  --keys DATABASE_URL,REDIS_URL,API_KEY

Options

OptionTypeRequiredDescription
--fromstringYesSource environment to copy secrets from
--tostringYesTarget environment to copy secrets to
--keysstringNoComma-separated list of keys to promote (default: all)
--overwriteflagNoOverwrite secrets that already exist in the target
--dry-runflagNoPreview changes without applying them

API Usage

Endpoint

POST /secrets/:orgSlug/:projectSlug/promote

Request body

request.json
{
  "fromEnv": "development",
  "toEnv": "staging",
  "keys": ["DATABASE_URL", "REDIS_URL"],
  "overwrite": false
}
OptionTypeRequiredDescription
fromEnvstringYesSource environment name
toEnvstringYesTarget environment name
keysstring[]NoSpecific keys to promote (default: all)
overwritebooleanfalseWhether to overwrite existing secrets

Response

response.json
{
  "promoted": 2,
  "created": 1,
  "updated": 1,
  "skipped": 0
}

Errors

StatusReason
400Source and target environments are the same
403Viewer role or no access to the project
404Organization, project, or environment not found

How It Works

  1. Resolves source and target environments, checks RBAC permissions
  2. Fetches all active secrets from the source environment (filtered by keys if specified)
  3. For each secret:
    • Key does not exist in target → create
    • Key exists and overwrite is false → skip
    • Key exists and overwrite is true → update
  4. An audit log entry is written with the action secret.promote

Secrets are transferred at the encryption layer and are not decrypted or re-encrypted during promotion.

Streamline your deployments

secr promote --from staging --to production

Create Free AccountBack to Docs