Skip to content

Terminal UI ​

Run builds, apply changes, operate SQL pipelines, and explore the database from the keyboard.

bash
noorm ui

Adding a config, creating the database, building the schema, fast-forwarding changes, and browsing the result

noorm ui takes no flags and opens on Home. Bare noorm prints the command list. See the CLI reference for commands you can run outside the TUI.

How do I get around? ​

Home opens five working screens with one key. Config, changes, run, and database navigation are below; the pipeline screens have their own review and history path:

Home: status, quick actions, and recent activity

Key on HomeOpens
rRun menu
cConfig list
gChanges list
dDatabase menu
pPipeline list
+More: Settings, Vault, Identity, Lock
s, v, i, lSettings, Vault, Identity, Lock, without going through More
uUpdate
1Run build
2Fast-forward changes
3Lock status
qQuit
TaskKeys
Switch configc, ↓ to the config, Enter
Fast-forward all changesg, f
Run the buildr, b
Review and run a pipelinep, ↓ to the pipeline, Enter; see Pipelines in the terminal
Validate a configc, +, v

Which keys work on every screen? ​

KeyAction
EscGo back, or cancel the operation in flight
Ctrl+CQuit
?Help overlay. Any key closes it
Shift+LToggle the log viewer
Shift+QOpen the SQL terminal
DToggle dry-run mode. The status bar shows DRY
FToggle force mode. The status bar shows FORCE

D applies to the run screens, pipeline review, change ff, and the database wipe, teardown, and transfer screens. In pipeline review it selects the next invocation's dry-run mode; a started invocation keeps its captured mode. F applies to the file run screens and change ff, but has no pipeline effect and cannot bypass pipeline policy or single-run protection.

While a text field takes input (a form field in edit mode, a search box, the SQL editor), every key above except Ctrl+C types its character instead. ?, D, and F also stand down inside dialogs.

Lists ​

KeyAction
↑ ↓Move the cursor. Wraps at both ends, except on the changes list
EnterSelect
EscBack
1-9Select by number, on lists that show numbers: Settings and the explorer
SpaceToggle an item, on multi-select lists. Enter then submits

A list fits the window, so a taller terminal shows more rows. It keeps its cursor when you open an item and come back.

Forms ​

A form has two modes. Enter switches between them, so submitting is a place you navigate to:

ModeKeyEffect
Browse↑ ↓, Tab, Shift+TabMove between fields, wrapping through the action row
BrowseEnterOpen the field for editing
BrowsexOn a password field with a value, empty it. Opening a password field starts from its current value, so this replaces it without backspacing
BrowseEscCancel the form
EditEnterCommit and return to browse
EditEscRestore the value the field held when edit opened
EditTab, Shift+TabCommit and move to the next or previous field
Actions← →, EnterPick a button and activate it

A checkbox toggles in place on Enter or Space. A select expands on Enter, moves with ↑ ↓, and takes the highlighted option on a second Enter. A red * marks a required field. Most forms reject an empty required field and put the cursor on it with an error. Pipeline input forms instead require presence: explicitly saving an empty string is valid.

A value longer than the row ends in … instead of wrapping, and an open text field scrolls to keep the cursor in view. On the config edit form, an empty password keeps the stored one, as its placeholder says: clear the field with x and type the replacement.

Mouse ​

On by default. In lists and result grids:

ActionEffect
Click a rowMove the cursor to it
Double-click a rowSame as Enter on that row
WheelMove the cursor one row, or scroll a document

In a form:

ActionEffect
Click a fieldMove the cursor to it. Another field being edited is committed first
Double-click a text, password, or select fieldOpen it for editing
Click a checkboxToggle it
Click [ Submit ] or [ Cancel ]Activate that button
Click an option in an open selectHighlight it. Double-click takes it
WheelMove between fields, or the highlight in an open select

In a confirm dialog, clicking Yes (y) confirms and clicking No (n) cancels.

A [key] Label hint is a button: a footer hint such as [a] Add or [Esc] Back, a Quick Actions entry, a row of Available Actions, or a menu entry on More. A click presses that key, through the same path the keyboard takes, so whatever has focus answers it exactly as it would the key. A double click presses once. Hints that name no single key ([↑↓] Scroll, [any] Back) and sentences that only mention a key ("Press [a] to add one") are plain text; the Home prompts "Press [c] to ..." are the exception and are buttons.

A hint does nothing while a confirmation holds the screen, since the key would answer the confirmation. It never types its letter into a text field that is taking input; Esc and Enter hints still work there.

Also clickableEffect
Earlier breadcrumb crumbsGo back to that screen. Inactive while an overlay is open, a confirmation holds the screen, or an operation is running
The idle / Filter... row of a searchable listEnter search mode
Rows of the file pickerClick moves the cursor and enters select mode; double-click toggles the checkbox
Rows of the log viewer, SQL history and clear lists, known users, result gridsClick moves the cursor; double-click does what Enter does

Moving the pointer over anything a click would act on shades it, so you can see what is clickable. The shade is a step off your terminal's own background (lighter on a dark theme, darker on a light one), asked for when noorm ui starts, and the text keeps its color. A terminal that does not report its background gets ANSI bright black instead. The cursor row keeps its own marker and is not shaded. Nothing shades, or answers a click, in a list that does not hold focus.

TIP

Mouse tracking takes click-drag text selection away from the terminal. Hold Option in macOS Terminal and iTerm2, or Shift in most others.

Hover makes the terminal send a report for every cell the pointer crosses, which is noticeable over a slow SSH link. To turn the mouse off, set ui.mouse in .noorm/settings.yml; ? prints the same hint. If a crashed session leaves the terminal printing characters as the pointer moves, run reset.

yaml
# .noorm/settings.yml
ui:
    mouse: false

What does Esc do while the database is busy? ​

A screen waiting on the database says so and names the key:

Testing connection...  [Esc] Cancel

That covers testing a config (add and edit), the force-release lock check, and the SQL terminal connecting or running a query. Esc returns the screen to a usable state and saves nothing. The client always stops waiting. Whether the server stops depends on the dialect:

DialectEffect on the server
PostgreSQLpg_cancel_backend asks it to stop the statement
MySQLKILL QUERY stops the statement
SQL Server, SQLiteNothing. The statement finishes. The message reads Stopped waiting. The query may still be running on the server.

A connect that answers after you cancelled is closed, not adopted. A connection attempt also ends on its own after 15 seconds. Raise connection.connectTimeoutMs for a link that is slow but working. The SQL terminal guide has the full table.

Pipeline stop uses a different contract: Esc requests that no more steps start, then waits for running SQL, transaction cleanup, and bookkeeping. It does not send the server-cancel requests in the table above. See pipeline stop and shutdown.

Long-Running Files ​

A file that runs past 10 seconds gets a status block under its name, refreshed every 10 seconds. It appears on the run screens (Build, Exec, Dir, File) and the change screens (Run, Revert, Fast Forward, Next, Rewind):

Current:  06_items.sql
Running for 17m05s  pid 4412
CREATE INDEX on items · building index: loading tuples · 4210/9800 (42%)  2 parallel workers
Waiting on pid 4411 (CREATE INDEX items_embedding ..., 17m04s) · Lock: transactionid
LineAppears when
Running for … pid …Always. SQLite shows elapsed time only
Operation progressThe server reports it: index builds, VACUUM, CLUSTER, COPY, ANALYZE on PostgreSQL; percent_complete on SQL Server; stage counters on MySQL
Waiting on pid …The file waits on another session's lock

On Run Build and Run Exec, press Esc once for a warning and again within 2 seconds to cancel. No further file starts. PostgreSQL and MySQL cancel the running statement. SQL Server and SQLite let it finish, and the screen says Stopping after the current file finishes. Leaving the screen does not cancel the run.

What does each screen do? ​

Config List ​

The configuration list

A config shows ● when active and ○ when not, with [user:<role> agent:<role|off>] when its access differs from the default (admin for you, viewer for the agent) and [test] on a test config.

A server config also shows its TLS state, read from the connection the TUI opens for it:

TagMeaning
[tls]SSL is on and the server certificate is validated
[tls unverified]SSL is on and ssl.rejectUnauthorized is false: the connection is encrypted and the certificate is not validated
noneSSL is off, the config is SQLite, the config names an access role the project does not define, or the stored config and its stage do not combine into a valid config

The TUI connects with the stored config over the defaults of the stage with its name, so a config with no ssl of its own on a stage that sets ssl shows [tls]. The TUI applies no config variable (NOORM_CONNECTION_*, NOORM_ACCESS_*) and no flag to a config. Settings variables still apply: NOORM_STAGES_<stage>_DEFAULTS_* changes the stage defaults the TUI merges, as NOORM_PATHS_* changes its paths.

WhenThe TUI shows
The stored config and its stage do not combine into a valid config, for example a pool.min above the default pool.maxHome with the validation message and no active config. The config stays in this list, where e edits it
A certificate file cannot be readThe connection error with its message, such as Cannot read ssl.caFile './certs/corp-ca.pem': ENOENT. Home and the database list do not report the database as missing, whatever the path contains
KeyAction
EnterMake the highlighted config active. On the config that is already active, open its edit form
aAdd
eEdit
dDelete
cCopy
kSecrets of the highlighted config
+More: x export, i import, v validate

Adding a config is interactive only. noorm config add points here, and noorm config import <file.json> is the headless route.

The add-config form

Both forms also carry these SSL fields. The edit form of a SQLite config shows none of them.

FieldSetsNotes
Use SSLsslChecked turns SSL on. Unchecking it stores ssl: false, which also turns off an ssl the stage supplies
Verify Certificatessl.rejectUnauthorizedUnchecked with Use SSL checked, it stores ssl.rejectUnauthorized: false: the connection stays encrypted and the server certificate is not validated. Checking it again removes the false
CA Filessl.caFilePath to the CA certificate. A path replaces inline PEM of the same field. Emptied, it removes the stored path
Client Cert Filessl.certFilePath to the client certificate
Client Key Filessl.keyFilePath to the client key
TLS Server NametlsServerNameHostname the server certificate is issued for

The edit form opens on the state in effect, which is the stored config over its stage. The add form shows no stage state, whatever name you type: Use SSL starts unchecked, Verify Certificate starts checked, and no field shows a stage placeholder.

On the edit formShows
The stored config or the stage turns SSL onUse SSL checked
The ssl in effect has rejectUnauthorized: falseVerify Certificate unchecked
Only the stage supplies a certificate fileAn empty field with the placeholder (stage: <path>)
The stored value is inline PEMAn empty field with the placeholder (inline certificate stored). The PEM stays while the field is empty
The stored config has ssl: falseUse SSL unchecked and no stage placeholder. Checking it stores ssl: true, and the stage's certificate files apply again

A save that changes none of Use SSL, Verify Certificate and the three file fields leaves the stored ssl as it was, and an absent ssl stays absent. The stage keeps supplying its value, and the saved config holds no copy of it. An unchanged TLS Server Name is left as stored in the same way. Typed paths and the server name are trimmed. The edit form keeps every connection field it does not show, such as pool and timeouts, except a SQLite filename, which the Database field replaces.

Submit judges the connection the save would produce over the stage's defaults, on both forms. The message shows on the form and nothing is saved.

Submit refusesWhen
A certificate path you enter or changeSSL would be off in the result
A TLS Server Name on PostgreSQL or MySQLSSL would be off in the result, or Verify Certificate is unchecked

A stage applies by config name, so renaming a config on the edit form can move it to another stage, or to none. The save then stores the TLS state the form shows (ssl: true, ssl: false, or rejectUnauthorized: false) when the new name would give a different one. The old stage's certificate paths stay with the stage: enter them on the config if the renamed config needs them.

A TLS Server Name passes when the stage supplies ssl and you leave Use SSL untouched. MSSQL allows the name in every case. Unchecking Use SSL over stored paths saves ssl: false and drops the paths. The connection test also runs over the stage's defaults, and a path that cannot be read shows its error there. Configs covers the path rules.

KeyAction on the add and edit forms
Enter on the submit buttonTest the server connection, then save
Ctrl+SSave without testing the connection

Ctrl+S works while the cursor moves between fields. While a field is in edit mode it does nothing and types nothing; press Enter or Tab to leave edit mode first. It runs the same field validation as the submit button. The hint row shows it as ctrl+s save without verifying. A failed test prints its error under the hint row, then Press Ctrl+S to save without verifying. on a row of its own, which is hidden while a field is in edit mode. Use it for a database that is unreachable now, such as one behind a tunnel that is down.

Saving a config needs an identity, because the private key encrypts .noorm/state/state.enc. When none exists, Add (a) and Import (i under More) show identity setup first:

Saving a config needs an identity. Set it up once to continue.

Name and email are filled in from git config user.name and git config user.email; the name falls back to the OS username. Machine is filled in from the hostname. Submitting creates the identity and continues to the form you opened. Esc goes back and creates nothing.

Setup never replaces an existing ~/.noorm/identity.key. With a key and no identity.pub, it derives the public key from the private one; with a key and identity.json already there, it asks nothing. When the key file exists but cannot be loaded, the screen shows the reason instead of the form, for example Insecure permissions on private key file (...). Fix with: chmod 600 ....

Export (x under More) writes <name>.noorm.enc, encrypted for one recipient, and import (i) reads it. Config sharing has the file format.

What happens
Export carriesEvery stored connection field that is not a credential, including dialect, host, port, database, tlsServerName, pool, the timeouts, and in ssl the inline ca, rejectUnauthorized and the three file paths. Stage values are not added
Export withholdsuser, password, and the inline ssl.key and ssl.cert. The recipient supplies their own
Import previewSender and secrets count, dialect, database and host, then SSL on or off, certificate verification, the TLS server name and each certificate file path. Roles: user <role>, agent <role|off> shows the roles the import saves. A file that sets isTest adds Test database: every role gets at least admin's permissions
Import savesThe connection fields the config schema accepts, with the user and password typed on the import form

A certificate file path travels as text. The preview says A certificate file path must exist on this machine., and import does not check for the file.

User Role covers a human on the CLI, TUI, or SDK. Agent Role covers an AI agent over MCP and the CLI. They are independent. Configs lists what each role permits.

Changes List ​

The changes list

SymbolMeaning
✓Applied
○Pending
✗Failed
↩Reverted
!Orphaned: recorded in the database, folder gone from disk

Fast-Forward (f) offers to retire pending changes with missing forward SQL. Select the changes, then confirm that all supported databases have caught up and no longer need their rollback SQL. NoORM saves the decision to .noorm/retired.yml and checks the batch again. Press Esc to stop without recording retirement. The Changes list shows Retired alongside any recorded execution status. Retired changes cannot run or be reverted.

KeyAction
EnterRun a pending, failed, or reverted change. Revert an applied one
aAdd
eEdit a change that is neither orphaned nor retired
dDelete a change that is neither orphaned nor retired
rRun. Pending, failed, or reverted only
vRevert. Applied only
nNext: apply the next N pending changes, one by default
fFast-forward all pending changes
wRewind
hHistory

With no changes, the list reads No changes found. Press [a] to create one.

Change history

History lists what ran, when, and under which identity. Enter shows the files, and e shows the full error of a failed change.

Run Menu ​

The run menu

b or 1 Build, e or 2 Exec, f or 3 File, d or 4 Dir, i or 5 Inspect.

A file that already ran with the same content opens File Previously Run and asks Run this file again?. A directory with such files opens Files Previously Run.

Pipelines ​

Pipeline review and history are separate screens; recorded runs remain reachable without opening a definition:

p from Home opens code-owned pipeline definitions. Enter reviews a definition, s switches inputs and steps, and r opens native run or dry-run confirmation against the captured active config. Each input uses a separate form with explicit Save and Cancel; x in review removes its override.

h opens config-scoped history by slug, and i on the pipeline list opens run-ID lookup, even without a local definition. Results distinguish execution status from transaction outcome and show cleanup warnings separately. The screens show elapsed time rather than live SQL or step progress.

See Pipelines in the terminal for typed input presence, review and result keys, protected confirmation, bounded history, and stop/shutdown behavior.

Database Menu ​

The database menu

KeyActionNeeds a connection
cCreate the database. Shows a toast if it is already initializedNo
dDestroyNo
xExploreYes
wWipe: truncateYes
tTeardownYes
rTransferYes

The SQL terminal is not on this menu. Open it with Shift+Q.

Schema Explorer ​

The explorer overview, with object counts by category

Each category opens from the overview by its letter or its number. A category with no objects does nothing.

CategoryKeys
Tablest, 1
Viewsv, 2
Proceduresp, 3
Functionsf, 4
Typesy, 5
Indexesi, 6
Foreign Keysk, 7

The table list

Enter on an object opens its detail. Indexes and foreign keys have none.

Table detail: columns, indexes, and foreign keys

A detail longer than the window scrolls. The footer lists only the keys the screen answers to.

KeyAction
↑ ↓Scroll one line
Ctrl+U, Ctrl+DHalf a page
PageUp, PageDownA full page. On macOS the footer shows fn ↑↓
Home, EndTop, bottom
vFull text: the same rows with nothing truncated
rRead rows. Tables only

Reading Rows ​

r on a table detail reads its rows without leaving the explorer for the SQL terminal.

Peeking at both ends of a table, then opening one row as a document

The peek reads both ends of the table, so the last rows by primary key are as reachable as the first:

First and last rows, side by side

KeyAction
↑ ↓Move the cursor within a set
TabSwap between the first set and the last
EnterOpen the highlighted row as a document
/Filter. Tab cycles the column, Enter applies, Esc clears
sSort. ← → pick the column, a ascending, d descending
cClear filter and sort
EscClose the peek
ConditionResult
The table has no primary keyOnly the first rows appear: No primary key, so there is no last set — rows are in storage order.
Both ends meetOne table, headed All N rows

The grid fits as many whole columns as the terminal holds and marks the rest … N more columns. Enter on a row shows them all:

One row as a YAML document

KeyAction
← →Previous row, next row, in the order the table showed
↑ ↓Scroll a document taller than the window
fSwap YAML and JSON. The choice holds for the session
EscBack to the peek, on the row you were reading

SQL Terminal ​

Shift+Q opens the SQL terminal against the active config from any screen.

The SQL terminal

KeyAction
EnterRun the query
Shift+EnterNew line
Shift+TabToggle edit mode, where Enter inserts a new line
↑ ↓Walk query history, when the box is empty or already browsing
hOpen the history list, when the box is empty
TabSwitch between the query and the results, once there are rows
EscIn results: back to the query. With text in the box: clear it. Empty: go back. While a query runs: cancel it

In the results grid, /, s, and c filter, sort, and clear as in the row peek, and Enter opens a row as a document. A result wider than the terminal keeps whole columns and marks the remainder … N more columns.

The history list takes ↑ ↓, Enter to view a result, r to re-run a query, and c to clear.

Log Viewer ​

Shift+L toggles an overlay that tails events as they happen, newest first.

The log viewer overlay

KeyAction
/Search. Enter leaves search, Esc clears it
g, GNewest, oldest
↑ ↓, PageUp, PageDownMove
SpacePause or resume the tail
rRefresh
EnterOpen one entry in full. Esc returns to the list
Shift+L, EscClose

More ​

The More menu

+ from Home opens Settings (s), Vault (v), Identity (i), and Lock (l). Each also has its direct key on Home.

Settings ​

The settings screen

Eight groups: Build, Paths, Stages, Rules, Strict, Logging, Secrets, and Access Roles. Enter or a number opens one, and edits write to .noorm/settings.yml. i creates that file when the project has none. See SQL file organization and Configs.

Identity ​

The identity screen

e edit, x export your public key, r regenerate, u known users. Regenerating makes existing state on the machine unreadable, so it first copies the identity files to <file>.bak-<timestamp> in ~/.noorm/ and shows the paths; see the warning on identity init. The identity lives in ~/.noorm/ and names who ran each change in the history. The CLI equivalent is noorm identity.

Vault ​

The vault screen before initialization

The vault holds team-shared encrypted secrets in the database. It starts uninitialized: i creates it. After that, a adds a secret, Enter edits the highlighted one, and p propagates access to teammates. See Vault.

Secrets ​

The secrets screen for a config

k on the config list opens the highlighted config's secrets: a add, e or Enter edit, d delete. See Secrets.

Lock ​

The lock screen

noorm locks the database around writes, so two people building one environment do not interleave. On the lock menu, s or 1 shows status, a or 2 acquires, r or 3 releases, and f or 4 force-breaks a stale lock. The status screen also has x to extend. See Locking.

Acquire and release need the lock:acquire permission, and force needs lock:force. A role the permission denies sees the policy refusal, and the screen opens no connection. Where the role's cell is confirm, the screen asks you to type yes-<config> before it acts.

Update ​

u from Home checks GitHub releases for a newer noorm. i installs it, r checks again, and Esc goes back.

A binary install reports its download as 42.0 / 73.0 MB (57%) with a progress bar. Without a Content-Length it shows 9.0 MB received and no bar. A stalled download resumes from the bytes on disk and shows download stalled — no data for 30s — resuming (attempt N/5).... An npm install runs the package manager and shows none of this.

What does a role that cannot write see? ​

Opening a screen as a role that can write creates noorm's tracking tables, or migrates older ones. A role denied every command that records to them, such as viewer, creates and migrates nothing. Activating a config follows the same rule, and registers no identity in the database for such a role. Its screens show:

ScreenOn a database with no tracking tables
HomeConnected, every change on disk counted as pending, lock free, no recent activity
Changes, change historyEvery change pending, no history
Lock status, lock listUnlocked
Lock acquire, release, forceThe policy refusal. No connection is opened
Pipeline history, run lookupNo runs
VaultThe policy refusal, on the list, add and delete screens. No connection is opened

When the tables need a migration, such a role sees the error the CLI prints: tracking tables are at schema version <n> and this version needs <m>. The role on config "<name>" cannot migrate them: a role that can write must run a command once first.

Next ​