cmd config

nself config

View and manage project configuration.

Synopsis

nself config <subcommand> [flags]

Description

nself config provides a complete interface for reading and writing ɳSelf configuration values. Config is stored in .env files, nself config reads and writes them safely, preserving comments and formatting.

Secret keys (any key containing SECRET, PASS, KEY, TOKEN, CREDENTIAL, WEBHOOK, PRIVATE, DSN or SALT) are masked as *** in output by default, and the credentials inside a URL value are masked (postgres://****@db:5432/app, ?password=****). Pass --reveal to show plaintext values; --reveal is terminal-only and never offered over MCP or the HTTP API, and config export, config secrets get and config secrets decrypt-on-deploy are CLI-only (in v1.5 config secrets decrypt-on-deploy also needs --reveal when stdout is not a terminal, and its --json shows names only). Use --env to target a specific environment file (e.g., --env staging reads .env.staging).

Setting a value: what config set regenerates

nself config set KEY VALUE writes KEY=VALUE into .env (or .env.<name> with --env <name>), keeping comments and every other line. A setting usually feeds generated files: BASE_DOMAIN reaches docker-compose.yml and every nginx site conf. Before anything is written, config set renders the whole build with the new value in memory and compares it with the disk, so it knows exactly which generated files the change touches (the same change plan as nself build --plan, see Safe-On-Live).

• --preview prints that plan and writes nothing, not even the env line. In v1.5 mode --json makes it one v1 envelope (data: key, file, applied: false, plan); in v1.4 mode config set ignores --json, as before.
• v1.5 mode (NSELF_V15=1, the default from v1.5.0): on a dev env the line is written and the change is applied at once through the build pipeline, then one summary line is printed, for example config: BASE_DOMAIN → 7 artifacts changed (compose, env, nginx, state). No container is restarted: run nself start to pick the new files up. On a prod-class env (ENV is prod or staging) every config set that changes the file needs --yes or a y at the terminal prompt, even when nothing generated changes (the env line is a change of its own); without a terminal and without --yes it is refused with E403 (exit 4), the plan is printed on stderr and nothing is written. Changing ENV itself away from prod or staging (for example config set ENV dev on a production box) counts as a prod-class change too; the plan header shows env prod → dev. Overwriting a generated file someone edited by hand needs --force in any env. If the project cannot be built with the new value (it fails validation, for example), nothing is written and the error says why. If the apply fails after the line was written, the env file is put back exactly as it was (atomically, while the project lock is still held) and the command exits non-zero with the error; generated files the build had already rewritten stay rewritten, so review them with nself build --plan. Ctrl-C, SIGTERM and a dropped SSH session (SIGHUP) during the apply are held until the apply finishes, so an interrupt cannot leave the new line behind a half-written tree; Ctrl-C at the confirmation prompt still exits at once.
• v1.4 mode: the line is written exactly as before and nothing is regenerated; the plan summary and a notice go to stderr. Run nself build to apply.

With --json in v1.5 mode an applied change prints the envelope with applied: true (schema schemas/commands/config-set.v1.schema.json).

Rotating a live secret. Put the new value in .env.secrets and let the regeneration carry it: nself config set HASURA_GRAPHQL_ADMIN_SECRET <new> --env secrets --yes on a prod-class env. The generated env and compose files are updated; the running containers keep the old value until they are recreated (nself start). nself secrets rotate is a different tool: it rotates the encrypted secret store (.secrets/<env>.age), which the build does not read, so it does not regenerate anything. Its schedule tracks HASURA_GRAPHQL_ADMIN_SECRET, the name the stack reads.

The validate subcommand runs all registered configuration validators and reports pass/fail per rule. It is automatically run during nself build, but you can run it independently to check config without rebuilding. It also warns, on stderr, about each env-file value whose unquoted or double-quoted $ the loader would expand (.env.secrets:12: KEY holds an unquoted '$' ...): the warning gives the file, line and key only, never the value; a ${NAME} reference is not flagged; and warnings do not change the exit code or the --json document. Single-quote the value if the $ is literal.

JSON output

With NSELF_V15=1 (the default from v1.5.0), config show, config get and config list write one v1 envelope to stdout when given --json (see JSON-Output). Before that, --json is accepted and ignored and the human output is unchanged. Secret keys and URL credentials are masked as *** exactly as in the human output; --reveal shows them in show and get, and list never reveals.

{ "schema_version": "1", "command": "config get", "data": { "key": "POSTGRES_PASSWORD", "value": "***", "masked": true, "file": ".env" } }

Command	data
config get <key>	key, value, masked (true when masking changed the value), file (env file name)
config list	file, keys[] of key, value, source (file, default or unset; a default shows the default value, unset shows "")
config show	object of key to value, sorted by key

config show --format json is the same envelope in v1.5 mode and the bare object before; NSELF_V15=1 NSELF_JSON_LEGACY=1 restores the bare object for one more minor release (removed in v1.6.0). A missing key or env file is an error envelope with exit status 1. Schemas: schemas/commands/config-show.v1.schema.json, config-get, config-list.

Flags

Name	Shorthand	Type	Default	Env	Escalates to	JSON override	Description
--env		string	""	ENV			Target environment (reads .env.{env})
--json		bool	false				JSON output
--reveal		bool	false				Show secret values in plaintext
--help	-h	bool	false				Show help

Subcommands

Name	Description
bundles	Manage and inspect ɳSelf plugin bundles
env	Multi-environment management: switch, list, diff, copy
explain	Explain where a configuration key comes from
export	Export current config to a file or stdout
features	Manage CLI-built-in feature flags
get	Get a single configuration value
import	Import config from a file into .env
list	List all known config keys with current values
oauth	Manage OAuth provider tokens
plugins	Manage ɳSelf plugins
secrets	Manage encrypted project secrets (age encryption)
services	Manage optional services
set	Update a configuration value (writes to .env)
show	Show all config key=value pairs (masked by default)
telemetry	Manage CLI telemetry preferences
trust	Set up local dev trust (DNS, SSL, port forwarding)
validate	Validate configuration against all registered rules

Contract

• Side effect: read
• Output: document
• JSON: envelope (data schema)
• Exit codes: none declared

Examples

# Show all config (secrets masked)
nself config show

# Show config with secrets revealed
nself config show --reveal

# Show config for staging environment
nself config show --env staging

# Get a single value
nself config get BASE_DOMAIN

# Get a secret value
nself config get POSTGRES_PASSWORD --reveal

# Set a value (v1.5 regenerates the dependent files at once)
nself config set BASE_DOMAIN myapp.dev
nself config set REDIS_ENABLED true

# See what a change would regenerate, write nothing
nself config set BASE_DOMAIN myapp.dev --preview
nself config set BASE_DOMAIN myapp.dev --preview --json

# Prod-class env: confirm without a prompt
nself config set BASE_DOMAIN example.com --yes

# Rotate a live secret through .env.secrets
nself config set HASURA_GRAPHQL_ADMIN_SECRET "$(openssl rand -hex 32)" --env secrets --yes

# List all known keys with current values and source
nself config list
nself config list --env staging

# Validate configuration
nself config validate
nself config validate --env prod

# Export config to a file
nself config export backup.env
nself config export /tmp/prod-config.env --env prod

# Import config from a file
nself config import backup.env
nself config import staging.env --env staging --force

See Also

• Commands — full command index
• Core-Services — what a stack is made of

← Commands | Home →