nself config

Read and write your project's .env configuration. Provides type validation, safe in-place editing, and import/export — so you never have to hand-edit env files for common changes.

Quick start

# Show all config values for the current environment
nself config show

# Get a specific value
nself config get POSTGRES_PASSWORD

# Set a value (with validation)
nself config set PROJECT_NAME myapp

# Validate the entire config
nself config validate

Synopsis

nself config <SUBCOMMAND> [FLAGS]

Description

nself config is a safe interface to your project's .env files. It reads the full environment cascade (.env.dev → .env.local → .env.staging/.env.prod → .env.secrets → .env.computed) and resolves the effective value for every key, taking into account which cascade layer wins.

When you use nself config set, the CLI writes to the appropriate cascade layer (typically .env.local for developer overrides, or .env.secrets for secrets) rather than modifying the shared base files. This keeps team defaults intact while allowing per-machine customization.

All keys are validated against the nSelf config schema on read and write. Type mismatches, missing required keys, and port conflicts are caught before they become runtime errors.

Subcommands

nself config show

Print all resolved configuration values, indicating which cascade layer each value comes from. Sensitive values (passwords, tokens, secrets) are masked by default.

nself config show

# Show including sensitive values (use with care)
nself config show --reveal-secrets

# Filter to a category of keys
nself config show --filter postgres

# Output as JSON
nself config show --json

nself config get

Get the resolved value of a single configuration key. Returns just the value (no key name), making it safe to use in shell scripts.

# Get a value
nself config get PROJECT_NAME
# → myapp

# Use in a shell script
export DB_HOST=$(nself config get POSTGRES_HOST)

# Show which file the value comes from
nself config get POSTGRES_PASSWORD --show-source
# → .env.secrets  (masked: ****)

nself config set

Set a configuration key. The CLI automatically writes to the correct cascade layer and runs type validation before writing.

# Set a non-secret value (written to .env.local)
nself config set PROJECT_NAME myapp

# Set a secret value (written to .env.secrets)
nself config set POSTGRES_PASSWORD "$(openssl rand -base64 32)"

# Force writing to a specific file
nself config set CUSTOM_VAR value --file .env.dev

# Set without validation (emergency use only)
nself config set MY_KEY value --no-validate

nself config list

List all known configuration keys with their types, default values, and whether they are required. Useful for discovering available configuration options.

# List all known keys with types and defaults
nself config list

# Filter to a category
nself config list --filter hasura

# Show only required keys that have no value set
nself config list --missing

nself config validate

Validate the entire resolved config against the nSelf schema. Checks required keys, value types, port conflicts, URL formats, and cross-key constraints.

nself config validate

# Example output:
# ✓ PROJECT_NAME       string  "myapp"
# ✓ POSTGRES_PORT      port    5432 (no conflict)
# ✗ HASURA_GRAPHQL_ADMIN_SECRET  required, not set
# ✗ CUSTOM_SERVICE_PORT  port conflict with POSTGRES_PORT (both 5432)
#
# 2 errors found. Fix before running nself build.

# Validate a specific environment
nself config validate --env staging

# Exit code 0 = valid, 1 = errors found (CI-safe)
nself config validate && echo "Config OK"

nself config export

Export the resolved configuration to a file. Useful for sharing non-secret config with teammates or for creating environment snapshots.

# Export non-secret config values
nself config export --output config-snapshot.env

# Export all values including secrets (use with care)
nself config export --include-secrets --output full-config.env

# Export as JSON
nself config export --json --output config.json

# Export for a specific environment
nself config export --env staging --output staging-config.env

nself config import

Import configuration values from a file. The CLI validates each key before writing and merges with the existing cascade rather than replacing it wholesale.

# Import from a .env file
nself config import config-snapshot.env

# Import and validate before writing
nself config import config-snapshot.env --validate

# Dry run to see what would change
nself config import config-snapshot.env --dry-run

# Import to a specific cascade layer
nself config import secrets.env --file .env.secrets

Configuration cascade

nSelf reads config in this order (later files win):

.env.dev          # team defaults, committed
.env.local        # local developer overrides, gitignored
.env.staging      # staging env, committed
.env.prod         # production env, committed
.env.secrets      # real secrets, gitignored
.env.computed     # generated by orchestration.sh, never hand-edit

Key naming conventions

See also

• nself build — build after config changes
• nself env — switch between environments
• nself secrets — manage encrypted secrets (age encryption)
• nself init — scaffold a new .env from a template