nkapp env

Manage and synchronize environment variables across local .env files and remote secret providers.


nkapp env <subcommand> [options]

Subcommands

`env sync`

Synchronize environment variables between a local .env file and the remote secret store configured in nanokit.yml. Nanokit compares the local file against the configuration’s secrets: and env: blocks, then displays a diff of what would change. On a live run it merges pulled secrets directly into the .env file.


nkapp env sync [-e <env>] [--direction <direction>] [--dry-run] [--force]

Flag	Type	Default	Description
`-e, --env <env>`	string	`local`	Target environment
`--direction <direction>`	`push` \| `pull` \| `both`	`both`	Sync direction
`--dry-run`	boolean	`false`	Show what would change without applying anything
`--force`	boolean	`false`	Overwrite existing values without prompting

Sync directions

Direction	Behaviour
`pull`	Resolve remote secrets / vault references and write them into the local `.env` file
`push`	Upload local `.env` values to the remote secret provider (requires provider support)
`both` (default)	Runs pull and push together, highlighting any conflicts


# See what would change for staging without touching files
nkapp env sync -e stage --dry-run
 
# Pull resolved secrets from vault into .env.stage
nkapp env sync -e stage --direction pull
 
# Bidirectional sync with force-overwrite
nkapp env sync -e prod --direction both --force

[!NOTE] Push is Vault-only. sync --direction push writes local values back to keys that reference HashiCorp Vault (vault://…). Variables backed by env:// references or brand-new local keys have no remote target and are reported as skipped — they are never uploaded anywhere.

`env list`

Display all environment variables visible to a given environment — from the local .env file, the nanokit.yml secrets: block, and each service’s env: block.


nkapp env list [-e <env>]

Flag	Type	Default	Description
`-e, --env <env>`	string	`local`	Target environment

Secret references (vault://… or env://…) are shown in a distinct colour so you can immediately see which values are resolved locally versus pointing at a remote store.


# Show all variables for the local environment
nkapp env list
 
# Show all variables for the staging environment
nkapp env list -e stage

Relationship to Other Commands

Need	Command
Set a project-level variable in `nanokit.yml`	`nkapp config set env.KEY=VALUE`
Set a service-level variable	`nkapp service set <name> env.KEY=VALUE [-e <env>]`
Manage secret store references	`nkapp secrets`
Show diff before syncing	`nkapp env sync --dry-run`