Skip to content

Secrets ​

Keep API keys and other sensitive values out of committed SQL, and still use them when a template runs.

The template names the secret. The value never appears in the file:

sql
-- db/sql/09_seeds/02_gateway.sql.tmpl
INSERT INTO app_setting (name, value)
VALUES ('payment_gateway_key', {%~ $.quote($.secrets.PAYMENT_GATEWAY_KEY) %});

Set the value once per config. --stdin keeps it out of shell history and the process table:

bash
printf %s "$KEY" | noorm secret set PAYMENT_GATEWAY_KEY --stdin --config prod
noorm secret list --config prod
Secret "PAYMENT_GATEWAY_KEY" set for config "prod".
Secrets for "prod" (1):
  PAYMENT_GATEWAY_KEY

Secrets are for values a template writes into your database. Database connection credentials belong to the config.

Which value does a template get? ​

The first tier that holds the key wins, so a local value overrides the team's:

TierStored inSet withSeen by
Config-local.noorm/state/state.enc, per confignoorm secret set, or the TUIYou
Global-localstate.enc, all your configsNo CLI or TUI command writes oneYou
VaultThe database, encryptednoorm vault setThe team

$.secrets merges all three tiers. $.globalSecrets holds only the global tier. A missing key throws Secret "PAYMENT_GATEWAY_KEY" not found (searched: config-local, global-local, vault) instead of rendering undefined.

How do I set a secret? ​

CLITUI
Setnoorm secret set <KEY> [value] [--stdin] [--config <name>]noorm ui, c, highlight a config, k, then a
List keysnoorm secret list, which never prints valuesThe same screen. Values show masked, with their first characters visible
Removenoorm secret rm <KEY> --yesThe same screen, d

Keys start with a letter and contain only letters, numbers, and underscores. The TUI masks password and api_key input and checks that a connection_string parses as a URI. A viewer role cannot read or write secrets, and an operator needs --yes to write one.

Stages declares which secrets a config must have. The TUI lists those first, marked set or missing.

The rendered SQL holds the plain value

The database receives the secret as text, and so does anything that logs the rendered SQL. Render a secret only into the column that needs it.

What bites ​

SymptomCauseFix
Secret "PAYMENT_GATEWAY_KEY" not found (searched: ...)No tier has the key. The vault tier is skipped without vault accessSet it locally, or ask a teammate to run noorm vault propagate
Failed to set secret: Secret key "payment-gateway-key" is invalidA hyphen or leading digit in the keyUse PAYMENT_GATEWAY_KEY
A secret set locally is missing in CIA CI runner has no state.encPut it in the vault, or run noorm ci secrets --file <env file> after noorm ci init
secret set says it requires confirmationThe config's role for your channel is operatorPass --yes
The TUI refuses to delete a secretThe stage requires it, and no vault copy existsRemove the requirement from settings.yml. noorm secret rm does not check
A teammate's build fails where yours passesYour local value hides a missing vault valueRun noorm vault list, then noorm vault set
Someone committed state.encIt holds your credentials and secrets. noorm init ignores .noorm/state/, so the ignore line was removed or init never ranRestore .noorm/state/ in .gitignore and remove the file from the repo. Your identity key encrypts it, so another machine cannot read it

Next ​