CLI: Secrets Management

Overview

Secrets are environment variables stored in WindKeep. Each secret can hold different values for development, staging, and production — so the same key works across every environment.

Understanding Secrets

Use secrets for connection strings, API tokens, OAuth credentials, encryption keys, and any other sensitive configuration.

Each secret supports per-environment values:

Important: Secret commands require an active project. Run windkeep projects switch first, or pass -p to windkeep run and windkeep pull.

  • DEVELOPMENT: Local development values (default for windkeep run).
  • STAGING: Test and QA environments.
  • PRODUCTION: Live application values.

Command: List Secrets

List all secrets in the active project, including which environments have values and when each secret was last updated.

Example & Output:

windkeep secrets list
Project: My Project

KEY            ENVIRONMENTS                     DESCRIPTION          UPDATED
DATABASE_URL   DEVELOPMENT, STAGING, PRODUCTION  Database connection  2d ago
API_KEY        PRODUCTION                        Third-party API key  5m ago

2 secret(s) total

Command: Get Secret

Show decrypted values and metadata for a single secret key.

Example & Output:

windkeep secrets get DATABASE_URL
Key:     DATABASE_URL
Desc:    Database connection string
Updated: 2d ago

ENVIRONMENT  VALUE
DEVELOPMENT  postgres://localhost:5432/dev
STAGING      postgres://staging-db:5432/app
PRODUCTION   postgres://prod-db:5432/app

Arguments:

  • KEY: Secret key name (required).

Command: Create Secret

Create a new secret in the active project. Set values per environment with --dev, --staging, and --prod.

# Set values for all environments at once
windkeep secrets create DATABASE_URL \
  --description "Database connection string" \
  --dev "postgres://localhost:5432/dev" \
  --staging "postgres://staging-db:5432/app" \
  --prod "postgres://prod-db:5432/app"

# Or create a secret with only the environments you need
windkeep secrets create API_KEY --description "Production API key" --prod "sk_live_abc123"

Arguments:

  • KEY: Secret key (required; uppercase recommended).

Flags:

  • -d, --description: Optional description.
  • --dev, --staging, --prod: Environment values.

Command: Set Secret

Update values for an existing secret. Only the environments you specify are changed — all others keep their current values.

windkeep secrets set DATABASE_URL --prod "postgres://new-prod-db:5432/app"

windkeep secrets set API_KEY --staging "sk_test_xyz789" --prod "sk_live_xyz789"

windkeep secrets set JWT_SECRET -d "Updated signing secret" --dev "new_dev_secret"

Arguments:

  • KEY: Secret key (required).

Flags:

  • -d, --description: Update the description.
  • --dev, --staging, --prod: Environment values to update.

Command: Secret History

View the audit trail for a secret — who changed each value and when.

Example & Output:

windkeep secrets history DATABASE_URL -e prod
History for: DATABASE_URL

[PRODUCTION]  current: postgres://prod-db:5432/app
VALUE                          CHANGED BY  WHEN
postgres://old-prod-db:5432/app  Alice Smith  3d ago

Arguments:

  • KEY: Secret key (required).

Flags:

  • -e, --env: Filter by environment (dev, staging, or prod).

Command: Delete Secret

Permanently delete a secret and all of its environment values. This cannot be undone.

windkeep secrets delete OLD_API_KEY --confirm

Arguments:

  • KEY: Secret key to delete (required).

Flags:

  • --confirm: Skip the confirmation prompt.

Injecting Secrets at Runtime

windkeep run fetches secrets from WindKeep and injects them as environment variables into your process — no .env file required.

WindKeep flags must come before the command you want to run. Use -- to separate flags when your command also uses -- flags.

# Run with development secrets (default)
windkeep run npm run dev

# Run with production secrets
windkeep run --env prod python app.py

# Override project and environment
windkeep run -p api-service -e staging node server.js

# Pass through flags to the child command
windkeep run -e prod -- node --inspect server.js

Flags:

  • -e, --env: Environment (dev, staging, or prod — defaults to development).
  • -p, --project: Override the active project by slug.
  • -v, --verbose: Print injected secret keys before running (values are never shown).

Syncing with Local .env Files

Prefer working with .env files locally? Use pull and push to sync secrets between WindKeep and your filesystem.

Command: Pull Secrets

Export secrets from a project to a local .env file. Defaults to .env.{slug}.{env} if no output path is given.

# Pull development secrets to the default file
windkeep pull

# Pull production secrets to a specific file
windkeep pull prod.env -e production

# Pull from a different project
windkeep pull .env.staging -e staging -p my-api

Arguments:

  • OUTPUT_FILE: Output file path (optional).

Flags:

  • -e, --env: Environment to pull (defaults to development).
  • -p, --project: Override the active project by slug.

Command: Push Secrets

Import secrets from a local .env file into the active project. Existing keys are skipped unless you pass --overwrite.

# Push from the default .env file
windkeep push

# Push production secrets and overwrite existing keys
windkeep push prod.env -e production --overwrite

Arguments:

  • INPUT_FILE: Input file path (defaults to .env).

Flags:

  • -e, --env: Environment to push to (defaults to development).
  • --overwrite: Update secrets that already exist.