nself env

Manage multi-environment configuration across .env.dev, .env.staging, and .env.prod.

Quick start

# Switch the active environment to staging
nself env use staging

# List all environments and the currently active one
nself env list

# Compare staging vs prod to catch drift
nself env diff staging prod

Synopsis

nself env use <ENV>
nself env list
nself env show [ENV]
nself env diff <ENV_A> <ENV_B>
nself env copy <FROM> <TO> [FLAGS]

Description

nSelf uses a layered environment cascade: .env.dev holds team-shared defaults, .env.staging and .env.prod hold environment-specific overrides, .env.secrets holds real production secrets (gitignored), and.env.local holds per-machine overrides (gitignored). The CLI merges these layers at startup; later layers override earlier ones.

nself env use switches which environment the CLI targets for subsequent commands like nself start, nself deploy, andnself db. The active environment is stored in .nself/env and survives shell restarts.

The subcommands create, switch, and delete were removed in v1.0.x. Use env use to switch, and manage env files directly for creation and deletion.

Subcommands

nself env use <ENV>

Set the active environment for all subsequent CLI operations. Valid values:local, dev, staging, prod.

nself env use staging
# Switched to environment: staging
# Active: .env.staging + .env.secrets

nself env list

Print all available environments and highlight the currently active one.

nself env list
#   local    (active)
#   staging
#   prod

nself env show [ENV]

Print the merged, resolved configuration for an environment. Secrets are masked by default; use --reveal with caution. Omitting ENV shows the active environment.

nself env show
nself env show staging
nself env show prod --reveal   # shows secret values — handle carefully

nself env diff <ENV_A> <ENV_B>

Compare two environments side-by-side. Highlights variables that differ in value, variables present in one environment but missing in the other, and masked secrets that have different hashes (indicating different values without revealing them).

nself env diff staging prod
# VAR                        STAGING          PROD
# POSTGRES_DB                nself_staging    nself_prod
# HASURA_GRAPHQL_ADMIN_SECRET [differs]        [differs]
# NEW_FEATURE_FLAG            true             <missing>

nself env copy <FROM> <TO>

Copy non-secret variables from one environment file to another. Secrets (any variable matching *_SECRET, *_TOKEN, *_KEY,*_PASSWORD) are skipped unless --include-secrets is passed.

# Copy shared config from dev to staging (no secrets)
nself env copy dev staging

# Also copy secrets (be careful)
nself env copy staging prod --include-secrets

Flags

Examples

Check for config drift before a production deploy

nself env diff staging prod
# Review all differences, especially missing vars in prod

Promote staging config to prod

nself env copy staging prod
# Then manually set prod secrets in .env.secrets

Debug a missing variable

nself env show staging --json | jq 'keys | sort'
nself env show prod --json | jq 'keys | sort'

Switch back to local development

nself env use local
nself start

Inspect the merged effective config (no secrets)

nself env show --json | jq 'to_entries[] | select(.value != "[secret]")'

Environment variables

• NSELF_ENV — override the active environment for one command: NSELF_ENV=prod nself db status

Exit codes

• 0 — success
• 1 — generic error
• 2 — invalid arguments or unknown environment name
• 6 — diff found differences (useful in CI assertions: nself env diff staging prod; [ $? -eq 0 ])

Related

• nself start — start the stack using the active environment
• nself deploy — deploy using the active environment
• nself config — manage non-secret CLI configuration