Skip to content

Configs ​

Switch between your dev, staging, and prod databases, and decide what a person or an AI agent may do on each.

A config is a saved database connection. This project has three:

bash
noorm config use staging
noorm config list
Active config set to: staging
Configurations:
  dev — postgres/order_to_cash_dev
  staging (active) — postgres/order_to_cash_staging
  prod — postgres/order_to_cash [user:operator agent:off]

The bracket tag marks a test config, or roles that differ from the default (user:admin agent:viewer). agent:off hides the config from AI agents.

How do I create a config? ​

Use the TUI wizard: run noorm ui, press c for configs, then a. Before it saves, the wizard connects to the server's system database, so the target database does not have to exist yet. MySQL has no system database to fall back to, so on MySQL create the database first.

FieldNotes
Config NameLetters, numbers, hyphens, underscores. A name that matches a stage links the config to it
Database Typepostgres, mysql, sqlite, mssql
Host, PortSQLite has no host. Port defaults to 5432, 3306, or 1433
DatabaseDatabase name, or file path for SQLite
Username, PasswordStored encrypted in .noorm/state/state.enc
User Role, Agent RoleSee Access roles
Test DatabaseSets isTest, read by rules in settings.yml and the SDK's requireTest

Schema and change folders are not config fields. paths in .noorm/settings.yml sets them.

noorm config add and config edit exit 1 and point you at the TUI. To create a config without it, write a JSON file and import it. This staging.json is hidden from agents:

json
{
    "name": "staging",
    "access": { "user": "operator", "agent": false },
    "connection": {
        "dialect": "postgres",
        "host": "staging.db.internal",
        "database": "order_to_cash_staging",
        "user": "deploy"
    }
}
bash
noorm config import ./staging.json
Imported config 'staging'.

How do I switch configs? ​

Commands use the first of these that is set:

ScopeHow
One commandnoorm run build --config prod, with the flag after the subcommand
One shellexport NOORM_CONFIG=prod
Every commandnoorm config use staging, or highlight a config in the TUI and press Enter

How do I override a config in CI? ​

Environment variables override the stored config. Stages shows the full order.

VariableSets
NOORM_CONNECTION_DIALECT, _HOST, _PORT, _DATABASE, _USER, _PASSWORD, _SSLconnection.* on the config
NOORM_PATHS_SQL, NOORM_PATHS_CHANGESpaths.sql, paths.changes. Never written back to settings.yml
NOORM_CONFIGWhich stored config to use
NOORM_YESAny value except empty, 0, or false skips confirm prompts on the user channel
NOORM_CHANNELuser or agent. See Which channel is a process on?

When no config is selected by flag, NOORM_CONFIG, or config use, noorm builds one named __env__ from the variables. It needs NOORM_CONNECTION_DIALECT and NOORM_CONNECTION_DATABASE:

bash
export NOORM_CONNECTION_DIALECT=postgres
export NOORM_CONNECTION_HOST=db.ci.internal
export NOORM_CONNECTION_DATABASE=order_to_cash_ci
export NOORM_CONNECTION_PASSWORD="$DB_PASSWORD"

noorm run build

CI/CD covers the full pipeline.

Access roles ​

Each config has two roles, one per channel. The user channel is you, in the CLI, TUI, or SDK. The agent channel is an AI agent, over MCP or the CLI. Change them in the TUI (config list, e).

RoleMeaning
viewerReads only, no secrets. Default for agent
operatorWrites data. Builds, changes, and db create ask first
adminEverything allowed, but irreversible operations still ask. Default for user
falseagent only. Hides the config: config list omits it and MCP answers as if it does not exist

Every permission has one cell per role, fixed in src/core/policy/matrix.ts:

Permissionvieweroperatoradmin
explore, sql:read (SELECT, EXPLAIN)allowallowallow
sql:write (INSERT, UPDATE, DELETE)denyallowallow
sql:ddl (CREATE, ALTER, DROP)denydenyallow
run:build, run:file, run:dir, change:run, change:ff, change:revert, db:create, db:resetdenyconfirmallow
db:truncate, change:rm, config:rm, config:write, vault:propagate, lock:forcedenyconfirmconfirm
db:destroy (db drop), db:teardowndenydenyconfirm
vault:read, secret:read, transfer:plandenyallowallow
vault:write, secret:writedenyconfirmallow
debug:readallowallowallow
debug:writedenydenyconfirm

A confirm cell never opens for an agent:

--yes and NOORM_YES=1 satisfy a confirm cell. They never open a deny cell.

Which channel is a process on? ​

A process takes the channel from its environment, not from which binary it called:

The harness variables are CLAUDECODE, CLAUDE_CODE, CLAUDE_CODE_ENTRYPOINT, CODEX_SANDBOX, CURSOR_AGENT, GEMINI_CLI, AI_AGENT, and NOORM_AGENT. TERM_PROGRAM, CI, and whether stdout is a terminal are ignored, because they describe the terminal, not the caller.

Roles prevent accidents

Roles stop a wrong-database teardown and an agent that shells out after an MCP refusal. They do not stop someone with the credentials, and an agent can set NOORM_CHANNEL too. Use database permissions for security.

How do I check a config? ​

bash
noorm config validate prod
prod: VALID
  [+] Connection: Connection successful
  [+] Name: prod
  [+] Database: order_to_cash
  [+] Host: db.example.com

Exit 0 when valid, 1 when not. Every check runs, so one report lists all failures. In the TUI, highlight a config, press +, then v.

How do I share a config with a teammate? ​

TUI export (+, then x)noorm config export
File<name>.noorm.enc, encrypted for one recipientJSON to stdout, or --output <file>
ContentsThe config and its local secrets, without user and passwordThe config, with password
NeedsThe recipient's identity known locallyA role that can read secrets
ImportTUI: +, then inoorm config import <file>

config export --output writes the file with 0600 permissions. Treat it as a credential. Importing over an existing name needs --force --yes, because an overwrite rewrites the config's roles.

What bites ​

SymptomCauseFix
noorm -c prod run build fails: --cwd path is not a directoryBefore the subcommand, -c is --cwdnoorm run build --config prod
"db:teardown" is not allowed on config "prod" (role: operator).The role's cell is deny, and no flag opens itChange the role in the TUI, or use a config with admin
"run:build" on config "prod" requires confirmation from a human.A confirm cell is deny on the agent channelRun it in your own terminal, or with NOORM_CHANNEL=user when you script inside an agent session
An imported config is open to adminThe file has no access, so it gets user: admin, agent: viewerPut access in the file

Next ​

  • Stages: defaults and required secrets shared by a team
  • Secrets: keep sensitive values out of SQL
  • Headless reference: every config flag and exit code
  • MCP: the agent side of access roles