CLI design — lexicon & options

Goal: a lexicon a new user understands without a glossary, and options that fix what repo/west users always missed.

Lexicon (canonical since v0.1)

Old spellings (brick, product, bricks, --product, --bricks) parse forever as aliases; serialization and docs use the new words only.

Verbs (commands)

Rule: one guessable verb per action, git-adjacent, no jargon. Old names kept as hidden aliases so nothing breaks.

haw run takes the command positionally (haw run 'git fetch'); -c/--command still works via the forall alias. Running haw with no subcommand opens the dashboard (like htop, k9s).

Rev handling (user-friendly by default)

• One field: rev = "main" | "v6.1.2" | "<40-hex sha>". No type = key; the kind is detected (refs/heads > peeled tag > tag > full SHA).
• Display: SHAs are shown 8 chars everywhere; haw.lock stores the full 40.
• Never detached: branch revs check out on a same-name branch, tags/SHAs on haw/<rev>.

Groups (implemented)

• groups = ["firmware", "ci"] on a repo.
• haw sync --group firmware, haw status --group ci, haw forall --group firmware -c ... (repeatable; empty filter = everything; a filter excludes ungrouped repos).
• Groups are recorded in haw.lock so filtering works offline.

Options grid

TUI keymap

k9s/lazygit-style, keyboard-first. Three mechanisms carry everything:

• digits 1–7 switch views (from any top-level list view),
• a opens the current view’s context actions (a lazygit-style menu),
• : is the command bar for the rest — its verbs mirror the CLI (learn one, know both).

Data loads on a background worker — the UI never blocks. The fleet grid auto-refreshes every ~5s while idle (never while you’re typing, in an overlay, a confirm, or a job is in flight); F5 / ctrl-r refresh on demand.

Global (frozen — these keys mean the same thing in every view)

View jumps (1–7) — from any list view

Digits are inert in the scroll/detail views (repo/PR/CI detail, files, grep) — jump from a list. Sorting (</>/.) applies to the Fleet, PR/MR, and CI tables.

Fleet view

Switch-stack, lock, and git-fetch moved to the command bar: :stack (picker) / :stack NAME, :lock, :fetch. Pinning the lock is p in the Stacks view (or :pin).

Marks persist across the Fleet and Changeset views; with marks set, both s (sync) and r/:run act on just the marked set.

Fleet PR/MR view (3) and CI view (4)

a (actions) and d are also available from within a PR/MR drill-in. Refetch is now just F5 / ctrl-r.

Files view (f from a repo)

A read-only browser: view or pick a file at any ref, on local disk or the forge (GitHub / GitLab / Bitbucket). It never stages/commits — it only reads. Two modes share the same repo / ref / scope context and toggle with T: a flat one-directory list (default) and a navigable expandable tree.

Tree view (T from Files)

The tree fetches every file path of the repo at the active ref once, then expands/collapses client-side. Collapsed dirs show ▸, expanded ▾; files are indented under their parents.

Ref picker (r in either mode)

r opens a popup listing the repo’s branches then tags (j/k + enter to pick), plus an input row to type an arbitrary ref or commit SHA. Selecting a ref reloads the current view AS OF that ref (the flat list re-roots at the repo root; the tree re-fetches its paths). The panel title shows the active ref honestly: @ main, @ v1.0.0, @ a1b2c3d, or @ HEAD (local) / @ default (remote) when none is pinned. Local refs come from git for-each-ref / git ls-tree / git show <ref>:<path>; forge refs and trees come from each forge’s REST API.

e suspends the cockpit, hands the current TTY to $VISUAL/$EDITOR (falling back to nvim/vim/vi) on the file’s absolute path, then resumes and reloads the listing. It is declined on the forge view (R) and on directories; if the repo isn’t on disk it prompts to sync.

Errors view, Plugins view, Governance view

Reach them from a list view (Errors via :errors/:err, Plugins via 7/:plugins, Governance via 6/:governance). In Governance, o opens the cursor plugin’s artifact (SBOM / provenance / …). Refetch is F5 / ctrl-r; b / esc go back.

Changeset view

Actions menu (a)

a opens a bordered actions popup listing the current view’s context actions, each with its sub-key. Pressing a listed sub-key fires that action — write actions keep their y/n confirm gate. esc (or any unlisted key) cancels. Views with no actions report so.

Command bar (:)

Verbs mirror the CLI, and the status line echoes the exact command each one runs, so the TUI doubles as a way to discover the CLI.

Themes / skins

Seven built-in skins: classic, catppuccin (default), dracula, nord, gruvbox, solarized, monochrome. classic is a neutral 16-color-ANSI look that reads on both light and dark terminals. :theme with no argument opens an interactive picker (highlighting the active skin); pressing enter applies the skin live and persists it to [ui].theme in the config. :theme <name> still switches (and persists) directly.

User config — ~/.config/haw/config.toml

Optional. A missing file, a partial table, or an unknown key all fall back to sane defaults (the cockpit never errors on absence). HAW_CONFIG overrides the path.

[ui]
theme = "classic"        # startup theme (a built-in name)
editor = "nvim"          # editor for the `e` key
compact_header = false   # start with the header collapsed
refresh_secs = 5         # idle auto-refresh cadence (clamped 2–60)

[keys]                   # remap a SAFE subset of action keys (single chars)
sync = "s"               # remappable: sync, goto, run, shell, files, problems, watch
goto = "g"

Precedence:

• Theme: NO_COLOR (non-empty) → monochrome; else HAW_THEME (env) if it names a built-in; else [ui].theme; else the default catppuccin.
• Editor: $VISUAL → $EDITOR (env always wins) → [ui].editor → the first of nvim/vim/vi on PATH → vi.

Custom keybindings ([keys])

Each entry maps an action name to a single key char. Only a safe subset is remappable — sync, goto, run, shell, files, problems, watch. The frozen globals (j, k, :, /, ?, q, b, space, g, w, and the digit view-jumps 1–7) can never be the target of a remap; a remap that targets a global, duplicates another remap, collides with a default action key, or isn’t a single char is dropped with a startup warning. When a remap is active, the header hints show the active key so they stay honest. The original default key keeps working too (a remap adds, never removes).

Shipped since this design was written

• haw pin / haw unpin (aliases freeze/unfreeze).
• --label <L> on change start, forwarded to PR/MRs at change request.
• forge = "github" | "gitlab" key on [remote.X] for hosts the URL heuristic misses.
• deps = [...] on a repo — change land merges in stable topological order.
• haw verify, haw sync --locked, --format json on status/tree, exit 3 on drift.
• haw build / haw test (per-repo commands in the manifest), lifecycle hooks in .haw/hooks/, haw hooks install, haw evidence, haw-<name> plugins.
• Lexicon nuance: --slug on repo add accepts --repo as alias; haw run takes the command positionally (forall -c still works).
• TUI g (goto) quits and prints the repo path — cd "$(haw dash)" — instead of spawning a nested shell.
• TUI: live idle auto-refresh (~5s), fuzzy / filter (nucleo), column sorting (</>/.), marks + bulk s/r, drill-ins for repos/PRs/CI runs, the a actions menu (merge / approve / checkout in PR/MR; request-PR / land in Changeset), fleet-wide governance (6) view, the file browser (f) with a navigable tree (T), ref picker (r), and local edit (e), and seven themes including classic (HAW_THEME, NO_COLOR, live :theme with an interactive picker).
• TUI config file ~/.config/haw/config.toml: [ui] startup theme / editor / compact_header / refresh_secs, plus [keys] custom keybindings for a safe subset of action keys. Interactive :theme / :editor pickers persist a choice; :compact toggles the collapsed header.

Planned (not yet implemented)

• Tag conveniences: haw lock --as-of <tag>; haw status marking rev kind (branch/tag/sha).
• haw auth login — OAuth device flow + OS keychain (see ARCHITECTURE DR-14).
• TUI: mouse support.