HUD types
Layer 2. Core. Core
The per-type contract for shc hud: for every type, how you reach it, what
columns it shows, which keys act on it and where it leads. Spec for
SHC-909.
Status. Proposed. CURRENT facts were read out of shc corp main at
dda96d1cf, x9s at 6ccdf607 (the X9S_REF the Makefile pins), ce main at
82dedb29 and the retired bubbletea HUD at 5deaa5b4b:modules/hud. Everything
marked target is not built. Section 3’s column lists are newer: they were
reread from ce core/tableview at ce next dbcf866a3 (SHC-1881). Paths
without a repo prefix are shc. x9s: paths
are the x9s repo (a bare x9s.go is x9s:_k9s/internal/view/x9s.go), k9s:
paths are upstream k9s as staged under .x9s/.k9s, ce: paths are ce.
Per MPO LC-210.
1. The HUD
Section titled “1. The HUD”shc hud is x9s (a k9s fork whose data plane is a pluggable provider) with the
SHC provider pkg/x9sprov compiled in (cli/hud.go:63-105). Every row comes
off the daemon’s public API.
Navigation spine
Section titled “Navigation spine”tenant → environment → stack → deployment → service → container.
| Level | How you get there | State |
|---|---|---|
| tenant | :tenants, then Enter (switch the session and open its deployments), u (switch without moving) or v d (its deployments without switching). The header’s Tenant row shows the active one. | live |
| environment | 0-9 from any view: 0 is all, 1-9 are the recent environments, default always first (pkg/x9sprov/facet.go:77-93,131-133, x9s:…/view/x9s.go:457-483). :environments lists them all. | live |
| stack | :stacks, then Enter (deployments at that stack, every environment) or u (narrow without moving). A stack is a projection of deployments, not a stored thing (facet.go:5-32). | live |
| deployment | :deployments, or Enter from any of the three above, or Enter on a :nodes row. | live |
| service | Enter on a deployment (catalog.go:316, the Drill relation). | live |
| container | Enter on a service (catalog.go:589). | live |
| deployment → container in one hop | v c on a deployment. | live (SHC-912) |
esc walks back up. [ and ] step through history, - flips to the last
view. Launch lands on the shc ctx environment but drops the shc ctx tenant
and stack (cli/hud.go:133 reads only the environment). Target: all three
(G9).
The legend rule
Section titled “The legend rule”Per MPO Axiom 6 (DG-ST-03), LC-118, LC-103.
- Per MPO LC-26, LC-168, Axiom 7.
- Per MPO LC-211.
- Per MPO LC-210.
Today the legend shows the stream keys and the generic ones (l, s,
Shift-F, e, ctrl-n, v, a, ctrl-j, sorts, digits: x9s.go:529-617) and
none of the verbs. Every verb sits behind a. ctrl-d binds only when the verb
is literally named delete/rm/remove/del (x9s.go:663-670), so
uninstall, umount, leave and forget get no key at all.
Target (the legend contract, G1). proto.Action gains Key and When
(x9s:proto/proto.go:314); proto.Relation gains Key (its letter in the
v picker); proto.Param.Type gains secret. The host binds each declared
key to “ask params, then confirm”, exactly the path a takes today
(x9s.go:715-731), and drops the deleteish/kill name guessing.
Rules every type obeys
Section titled “Rules every type obeys”- Per MPO LC-210.
- CLI first. A HUD mutation is a CLI verb with the row filled in, and its
confirm dialog prints that command. A verb the CLI lacks is added to the
CLI first (the provider already enforces this for containers,
actions.go:1510-1519). - Per MPO LC-186.
- Per MPO LC-98, Axiom 9.
2. Global key table
Section titled “2. Global key table”One row per key. The Kind column says who owns it: k9s = bound by k9s on every provider view, untouchable; k9s verb = a k9s key whose k9s meaning SHC keeps; x9s = added by the x9s overlay; SHC = assigned here.
Navigation and view keys (never a verb)
Section titled “Navigation and view keys (never a verb)”| Key | Does | Kind |
|---|---|---|
: | command bar (:deployments, :secrets, …) | k9s |
/ | filter the table | k9s |
? | help: every key live on this view | k9s |
| esc | back | k9s |
| Enter | drill into the Drill relation, else describe | k9s, x9s drill |
[ ] - | history back, forward, last view | k9s |
j k h g G | down, up, left, top, bottom (tview table.go:1218-1229) | k9s |
| ctrl-f ctrl-b | page down, page up | k9s |
| space, ctrl-space, ctrl-\ | mark, mark range, clear marks | k9s |
| ctrl-a | list every : noun | k9s |
| ctrl-c | quit | k9s |
| ctrl-e, ctrl-g | toggle header, toggle crumbs | k9s |
| ctrl-p | persist view config | k9s |
| ctrl-q, ctrl-u | clear filter | k9s |
| ctrl-r | refresh | k9s |
| ctrl-s | save table to file | k9s |
| ctrl-w | toggle wide columns | k9s |
| ctrl-z | toggle faults (rows in a bad state) | k9s |
| Shift-N Shift-A Shift-S | sort by the column that claims name / age / status (catalog.go:186) | k9s, x9s roles |
| Shift-O | sort by the selected column | k9s |
u | use: make this tenant / environment / stack the session’s | k9s (ns) → x9s |
0-9 | environment: 0 all, 1-9 recents | k9s (ns favourites) → x9s |
v | views: picker of this row’s relations, each with a letter | x9s |
| ctrl-j | follow a linked column to the row it names | x9s |
a | actions menu: every verb, its doc and its key | x9s (k9s: attach) |
q | never bound. Operators reach for it to quit. | reserved |
ctrl-h, ctrl-i, ctrl-m and ctrl-[ are backspace, tab, Enter and esc to a terminal and are never assigned.
Verb keys
Section titled “Verb keys”| Key | Verb | Types | Kind |
|---|---|---|---|
d | describe (the detail document) | all | k9s verb |
y | YAML of the detail document | all | k9s verb |
c | copy the type’s copy value (secret value, config value, URL, path; row id otherwise) | all | k9s verb |
e | edit: the row’s writable settings, through a typed form where one exists | deployments, repos, config, secrets, quotas, users, nodes, storage, schedules, retention, cluster, branding, certificates | k9s verb |
l | logs | deployments, services, containers, nodes, events, storage | k9s verb |
s | shell | deployments, services, containers | k9s verb (pods) |
| Shift-F | port-forward | deployments, services, containers | k9s verb |
f | show this row’s active port-forwards (:forwards filtered) | deployments, services, containers | k9s verb (pods) |
x | reveal a secret value in place (toggle); on serviceclients and ldapbinds the one just minted, once | secrets, serviceclients, ldapbinds | k9s verb (secrets: decode) |
r | restart | deployments, services, containers | k9s verb (deployments) |
t | run now: trigger, sync, scan, test, diagnose, apply, reconcile | schedules, jobs, repos, quotas, notifications, diagnoses, retention, license, cluster | k9s verb (cronjobs: trigger) |
| ctrl-n | new | deployments, backups, tenants, repos, users, usergroups, serviceclients, ldapbinds, branding, certificates, schedules, secrets, storage, config, connections, grants, integrations, license | x9s |
| ctrl-d | delete: remove the row (uninstall, delete, umount, leave, unset, reset, delink) | most | k9s verb |
| ctrl-k | kill: stop now with no grace (stop --force, cancel, logout, forget) | deployments, services, tasks, runs, users, nodes | k9s verb |
| ctrl-l | rollback | deployments | k9s verb (replicasets) |
b | backup now (a volume’s provider snapshot on :volumes) | deployments, volumes | SHC (Clay) |
i | install | apps, addons | SHC |
m | Per MPO LC-210. | ||
n | rotate (new key material) | backupkeys, vault, certificates, serviceclients, ldapbinds | SHC |
o | open in the browser | deployments, ingress | SHC |
p | protect ⇄ unprotect | deployments | SHC |
w | export to an archive | deployments, backups, vault | SHC |
| Shift-C | clone | deployments | SHC |
| Shift-D | drain ⇄ undrain | nodes | SHC |
| Shift-E | enable ⇄ disable | schedules, storage | SHC |
| Shift-K | cordon ⇄ uncordon | nodes | SHC |
| Shift-L | lease: renew with a TTL, or clear it | deployments | SHC |
| Shift-M | move (volume binding, vault cold-start) | volumes, vault | SHC |
| Shift-P | repoint the recorded source app | deployments | SHC |
| Shift-R | restore (backup, volume snapshot, export, vault bundle) | backups, volumes, exports, vault | SHC |
| Shift-U | unlock | vault | SHC |
| Shift-V | verify | backups | SHC |
| Shift-W | start (“wake”, the retired HUD’s key) | deployments, services | SHC |
| Shift-X | stop (the retired HUD’s key) | deployments, services | SHC |
Where SHC departs from k9s
Section titled “Where SHC departs from k9s”k9s binds some of these letters on its Kubernetes views only. None of those views exist under x9s, so nothing is shadowed, but the muscle memory differs:
| Key | k9s means | SHC means | Why |
|---|---|---|---|
s on a deployment | scale (k9s:view/scale_extender.go:48) | shell | SHC’s everyday need on a deployment is a shell; shc hud --help and the README already teach s = shell. Replicas change in e’s scale field (shc update --scale). |
p | previous container’s logs (k9s:view/logs_extender.go:37) | protect ⇄ unprotect | SHC has no previous-container log. |
i | set image (k9s:view/image_extender.go:64) | install | SHC-743 named i for install. A version change is e. |
c on a node | cordon (k9s:view/node.go:45) | copy | c is copy on every other k9s table (k9s:view/browser.go:614). Cordon is Shift-K. |
o | show the pod’s node (k9s:view/pod.go:133) | open in browser | Jumping to a node is ctrl-j on the NODE column. |
b | benchmark (k9s:view/svc.go:54) | backup | Clay’s key. |
a | attach | actions menu | x9s already made this change. |
v | vulnerabilities / values | views picker | x9s already made this change. |
Collision proof
Section titled “Collision proof”Assigned lowercase: a b c d e f g h i j k l m n o p r s t u v w x y z, each
once. Assigned uppercase: A C D E F G K L M N O P R S U V W X, each once.
Assigned ctrl: a b c d e f g j k l n p q r s u w z, space, \, each once.
Free for later: q stays unbound on purpose; uppercase B H I J Q T Y Z (k9s uses Shift-J for jump-to-owner on Kubernetes views only);
ctrl-o t v x y.
Per MPO LC-211.
Per MPO LC-210.
3. Types
Section titled “3. Types”Each section: what it is, how you reach it, columns (narrow always shown,
wide on ctrl-w) with the API field behind each, keys, relations, and
CURRENT versus target. In the key tables Now is one of: live (the
key works today), a (works only through the actions menu), target
(not built), blocked (needs something else first, named in the gap).
Every mutating key confirms, so “Prompts” lists only what the form asks
before the confirm.
A type with a CLI list takes its columns from that list’s View in ce
core/tableview (SHC-1881), so the two cannot drift. The narrow view is the
list’s default columns in the list’s order. A column only the HUD shows is
wide. ctrl-w shows every column where the View puts it, so a wide column can
sit between two narrow ones. A header is the View’s label in capitals with
its spaces kept (SIZE BYTES). The sections below give each such type’s
columns as its View has them, narrow first. The only columns the HUD adds
after the View’s are the wide link columns of SHC-919: DEPLOYMENT on a
per-deployment type, and ID on :deployments for those links to land on.
Twelve types have no CLI list and keep columns of their own: :services,
:containers, :groups, :aliases, :events, :audit, :mounts,
:vault, :cluster, :retention, :license and :placement.
Type nouns follow SHC-742: one canonical noun per type, no aliases.
3.1 Host views (x9s, not provider types)
Section titled “3.1 Host views (x9s, not provider types)”| View | What | Keys | Source |
|---|---|---|---|
:types | home: every type as a row, Enter opens it. Launch lands here. | Enter | x9s:…/view/x9s.go:113, x9s_header.go |
:contexts | configured daemons. Enter or u switches the session. | u, ctrl-n, ctrl-d | x9s.go:133-137 |
:environments | the environment facet. Enter lands on its deployments, u selects. | Enter, u | x9s.go:381-440, facet.go:85-91 |
:stacks | the stack facet. Same keys. | Enter, u | facet.go:79-84 |
:forwards | this session’s live port-forwards. | ctrl-d stop; space-mark then ctrl-d stops several | x9s.go:995-1007 |
:mutations | what this session wrote, newest first. d/y show the diff and the command. | d, y | x9s.go:88-93 |
Target: launch opens :deployments scoped to the shc ctx tenant,
environment and stack instead of :types (G9).
3.2 :deployments
Section titled “3.2 :deployments”A running app at one (tenant, stack, environment). The headline type.
catalog.go:282.
Reach. :deployments; Enter on a :stacks, :environments, :tenants
or :nodes row; ctrl-j on any DEPLOYMENT column (live, SHC-919: a wide ID
column carries the row id the link filters on).
Columns (DeploymentList → StackResponse, catalog.go:380-446)
- Narrow, what
shc lsprints:STACKstack_name ·TENANTtenant_name ·ENVenvironment ·APPapp_name ·STATUSstatus (stoppedwhen stopped is true) ·NODEnode ·LEASEtime left on lease_expires_at ·ACCESSeffective_access ·EXPOSUREeffective_exposure ·REASONstatus_reason. - Wide:
READYservices_healthy/services_total fromshc.status.get?all_stacks=true, its unknown and empty readings per MPO Axiom 6 and spec Meter invariants ·AGEcreated_at ·VERSIONapp_version ·RUNTIMEruntime ·ADDONaddon ·DISKdisk_bytes ·PROTECTEDprotected ·MESSAGEerror_message ·LATESTthe versionshc.catalog.updatesoffers (the catalogue head when the deployment’s pin is ahead of it,ambiguouson a repo tie, blank when current) ·HOSTSthe routes fromHostMapping/<id>·URLthe first route ashttps://host[/path], the columnccopies andoopens ·IDthe row id, added by the HUD so a link from another type’s row lands here. LATEST and HOSTS are read at most once a minute (deploy_columns.go).
Keys
| Key | Verb | CLI | Prompts | Now |
|---|---|---|---|---|
| Enter | services | live | ||
l | logs, every service interleaved | shc logs -s <stack> (stream.go:569) | live | |
s | shell in the first running container | shc shell <stack> (stream.go:778-796) | live | |
| Shift-F | port-forward | shc forward <stack> <spec> (forward.go:56) | remote port or service, local address | live; a remote session tunnels through shc.stack.forward at stack:manage (G5) |
f | its forwards | target | ||
d / y | detail (DeploymentGet) with the shc inspect bundle (rendered compose, vars, plugs, jobs, backup manifest, masked by the daemon) under inspect | shc inspect <stack> | live (SHC-913) | |
e | update through the guided form: version (catalogue versions), variables, hosts, ports, access, exposure, gate, HA, scale, resources, integrations, protect | shc update <stack> … | the app’s typed variable form, prefilled with current values | live as YAML of 9 fields (update.go:96-110), no variables, hosts, ports or integrations; target (G3) |
| ctrl-n | install through the guided form: pick an app, then its variables | shc install <app> … | app, stack, environment, node, version, then one field per variable | live as a YAML template (create.go:165); target (G3) |
c | copy the primary URL (URL), else the row id | live (SHC-913) | ||
o | open the primary URL (URL) | live (SHC-913) | ||
r | restart | shc restart <stack> | service (optional) | live (SHC-2701) |
| Shift-W | start | shc start <stack> | service (optional) | live (SHC-2701) |
| Shift-X | stop | shc stop <stack> | service (optional) | live (SHC-2701) |
| ctrl-k | kill | shc stop <stack> --force | service (optional) | live (SHC-2701), danger |
b | backup now | shc backup create <stack> | name, with dependants | live (SHC-2701) |
p | protect ⇄ unprotect | shc protect / shc unprotect <stack> | live (SHC-2701): one verb, the row’s state picks the spelling | |
| Shift-L | lease | shc lease renew <stack> --ttl or shc lease clear <stack> | TTL (blank pins it permanent), force | live (SHC-2701): one verb |
| ctrl-l | rollback to the pre-update snapshot | none today: shc rollback does not exist (G8) | rollback point, with dependants | a, and its confirm prints a command that does not exist (G8) |
| Shift-C | clone to a new coordinate | shc clone <src> <dst> [--target-environment] [--target-tenant] [-a] -y | stack, environment, tenant, all connections, each starting at the source | live (SHC-913) |
| Shift-P | repoint the recorded source; renders nothing | shc repoint <stack> <app>[@<ver>] [-r <repo>] or shc repoint <stack> --back | app (catalogue picker, starting at the recorded source), version, repo, back | live (SHC-913) |
w | run an exporter into an archive | shc -e <env> export <exporter> -s <stack> [--output-dir] [-p k=v] | exporter, output dir (daemon host), params | live (SHC-913) |
| ctrl-d | uninstall | shc uninstall <stack> -y | skip safety backup | a, no key (G1) |
Relations. Enter → :services. v picker letters:
s services, c containers, m groups and l aliases (SHC-2471), b
backups, h schedules, j jobs, v volumes, k secrets, g config, i
integrations, n ingress, e events, a audit, w exports, r retention,
p placement (SHC-1079). Live with their letters (SHC-912):
services, containers, backups, schedules, events, integrations
(stacksResource, relations.go); exports and retention (SHC-921); jobs
(SHC-916); volumes, secrets, config, ingress and audit (SHC-919,
relations_pass.go). ctrl-j: TENANT → :tenants, NODE
→ :nodes. f → :forwards.
3.3 :services
Section titled “3.3 :services”One compose service of one deployment. Hidden: reached by Enter only.
catalog.go:572.
Columns (StackResponse.services[] → ServiceState, catalog.go:622-657)
- Narrow:
SERVICEname ·STACK·ENV·STATUSstatus ·HEALTHhealth ·REPLICASactual_replicas/desired_replicas ·CPUcpu_usage_millicores ·MEMmemory_usage_bytes (k9s shows both on pods). - Wide:
TENANT·IMAGEimage ·RESTART-POLICYrestart_policy ·NODESnodes ·OOMoom_kills ·EXITexit_cause.
Live since SHC-912. The Deployment list route fills all five per service on a
recorded deployment, from one container-table read per page
(enrichServiceColumnsPage, ce modules/app/service_columns_wire.go): nodes,
oom_kills and exit_cause from the recorder’s rows, and CPU and MEM from the
daemon’s stats cache. Their missing, stopped and idle readings are per MPO
Axiom 6 and spec Meter invariants.
Keys
| Key | Verb | CLI | Prompts | Now |
|---|---|---|---|---|
| Enter | containers | live | ||
l | this service’s logs | shc logs <service> -s <stack> | live | |
s | shell in this service | shc shell <stack> -S <service> | live | |
| Shift-F | port-forward to this service | shc forward <stack> <service>:<port> | port (a service half must be this row’s) | live; a remote session tunnels through shc.stack.forward at stack:manage (G5) |
f | its forwards | target | ||
r | restart | shc restart <stack> -S <service> | live (SHC-743) | |
| Shift-W | start | shc start <stack> -S <service> | live (SHC-743) | |
| Shift-X | stop | shc stop <stack> -S <service> | live (SHC-743) | |
| ctrl-k | kill | shc stop <stack> -S <service> --force | live (SHC-743), danger |
d/y fall back to the row as JSON (no detailFn). e refuses with
update.go:307-308: a service’s settings live on its deployment’s e.
Relations. Enter → :containers. ctrl-j TENANT, and DEPLOYMENT back
up (live, SHC-919).
3.4 :containers
Section titled “3.4 :containers”One container of a service. The leaf. Hidden, and lists only when anchored
(one shc.stack.inspect per deployment). catalog.go:671.
Columns (StackInspect → StackContainerView, catalog.go:702-757)
- Narrow:
NAMEName ·SERVICEService ·STACK·ENV·STATEState ·HEALTHHealth. - Wide:
IMAGEImage ·STATUSStatus ·IDID.
Keys
| Key | Verb | CLI | Prompts | Now |
|---|---|---|---|---|
| Enter | describe | live | ||
l | this container’s logs | shc logs <service> -s <stack> (the public stream takes service, not a container id) | target (G4) | |
s | shell in this container | shc shell <stack> -S <service> reaches a replica; the HUD sends the row’s container_id (ce:modules/shell/router.go:274) | live | |
| Shift-F | port-forward to this container | shc forward | port | target (G4) |
r | restart this container | shc container restart <id> | live | |
m | copy its filesystem to a directory on the daemon host, bound read-only over itself and leased (1h). The container’s later writes never reach the copy. No writable variant here: a write to the copy never reaches the container, and the CLI’s --read-write covers the rare need (SHC-994) | shc container mount <id>, released early with shc volume umount <handle> (deletes the copy); listed on :volumemounts | live |
Today r and m are its verbs (g6_verbs.go), and a mount’s path and handle land in :mutations; s is its one stream. Both verbs get the CLI’s five-minute ceiling on a call the HUD’s 15 s request ceiling cannot cancel: once 15 s pass the confirm says the call is still running, and a mount that lands after that logs its path and handle.
3.5 :apps
Section titled “3.5 :apps”The catalogue you install from. catalog.go:931.
Columns (AppList → AppResponse, catalog.go:964-990)
- Narrow, what
shc catalog lsprints:NAMEname ·KINDapp or vapp ·VERSIONversion ·REPOrepo_name ·NODES·DESCRIPTIONdescription. - Wide:
CATEGORYcategory ·VAPPvapp ·HIDDEN·HIDDEN-REASON·PARENTparent_app ·TAGStags ·HOMEPAGEhomepage ·SOURCEsource. NODES,HIDDENandHIDDEN-REASONareshc catalog lscolumns theAppListroute does not carry, so they read-here.
Keys
| Key | Verb | CLI | Prompts | Now |
|---|---|---|---|---|
i | install through the guided form, then land on the new deployment’s services | shc install <app> [--repo] | stack, environment (the CLI’s default, InstallFormEnvironment), node, version, then one typed field per variable | a with 4 free-text params (catalog.go:944-957); target (G3) |
d | detail plus the compiled install plan (shc catalog compile) | live (catalog.go:993-1027) | ||
| Enter | :addons of this app (v a) | live (SHC-921) |
Per MPO LC-64.
3.6 :addons
Section titled “3.6 :addons”What an app publishes as add-ons (shc addon ls <app>, show, versions).
Reached by Enter on an :apps row. type_addons.go, live (SHC-921).
shc addon ls reads the package on disk and has no route, so the daemon’s
copy is read instead: shc.catalog.list kinds addon and vaddon, hidden
ones included, which is shc catalog ls --kind addon --include-hidden.
- Narrow:
ADDONname ·VERSIONdefault_version ·VERSIONS(count) ·DESCRIPTION. Wide:APPwraps_ref ·REPO·KIND. - Keys:
iinstall through the wrapped app’s guided form with the add-on’s version first, confirmingshc install <app>/<addon>[@<version> <app version>] -r <repo>. The app version moves to the second positional when the add-on is pinned, because the CLI reads a lone@as the app version. A vapp add-on (vaddon) refuses and namesshc install <app>/<vapp>/<addon> -s <host>/<instance>: it installs under a host. dis the catalog row plus its compiled install (shc.catalog.compile). No route servesshc addon show’s resolved vars.
3.7 :repos
Section titled “3.7 :repos”App catalogues this platform syncs from. catalog.go:1486.
Columns (RepoList → RepoResponse, catalog.go:1523-1561)
- Narrow:
NAMEname ·URLurl ·ADAPTERadapter ·APP COUNTapp_count ·PRIORITYpriority ·TENANT NAMEtenant_name. - Wide:
ENVIRONMENTenvironment ·SYNCED ATsynced_at ·INTERVALsync_interval ·AGEcreated_at. Target wide:ERRORsync_error.
| Key | Verb | CLI | Prompts | Now |
|---|---|---|---|---|
| Enter | its apps | live | ||
t | sync now | shc repo sync <name> --tenant <t> --environment <e> | force | live (SHC-743) |
e | edit | shc repo update <name> --tenant <t> --environment <e> | YAML | live |
| ctrl-n | add | shc repo add <name> <url> | YAML template | live |
| ctrl-d | delete | shc repo rm <name> --tenant <t> --environment <e> -y | live |
A row’s id is <tenant>/<environment>/<name> (SHC-987). Two tenants may
each own a repo of one name and a tenant’s view lists the system rows
beside its own, and the daemon refuses a write whose scope matches more
than one repo, so every verb names the row’s own pair in the query.
3.8 :backups
Section titled “3.8 :backups”Backup archives. catalog.go:1152.
Columns (BackupList → BackupInfo, catalog.go:1209-1257)
- Narrow:
IDid ·STATUSstatus ·CAUSEerror, elserepository gone,not recordedon a failure with no error,stack stopped <n>sordegraded·TYPEtype ·SIZE BYTESsize ·APPARENT BYTESapparent_size ·TIMESTAMPtimestamp ·POINT IN TIMEpoint_in_time ·ENCRYPTIONencryption ·NODEnode. - Wide:
NAMEname ·TENANTtenant_name ·STACKstack_name ·ENVenvironment ·GROUPconsistency_id ·DEGRADEDdegraded ·DATA SCOPEdata_scope ·LOCATIONlocation ·AGEtimestamp ·DURATIONduration_seconds ·COMPLETEDcompleted_at ·ERRORerror ·DEPLOYMENTlink (SHC-919).
| Key | Verb | CLI | Prompts | Now |
|---|---|---|---|---|
| ctrl-n | take a backup | shc backup create <stack> | target: deployment picker instead of YAML | live (YAML) |
| Shift-R | restore over the deployment | shc backup restore <id> | strategy, create rollback (default on), keep running, force | live (SHC-743) |
| Shift-V | verify against its manifest | shc backup verify <id> | live (SHC-743) | |
m | mount read-only on the daemon host | shc backup mount --id <id> | mountpoint | live (SHC-743) |
w | export to a file on this machine | shc backup export <id> --file <path> | file (a directory or a full path) | live (SHC-913) |
| ctrl-d | delete | shc backup rm <id> -y | live |
Relations. v: m mounts of this backup (live, SHC-919). ctrl-j
TENANT, and DEPLOYMENT for its deployment (SHC-919).
3.9 :mounts
Section titled “3.9 :mounts”FUSE trees m left on the daemon host. catalog.go:1267.
- Narrow:
IDid ·BACKUPbackup_id ·PATHmount_path ·STATUSstatus ·NODEnode_id ·TENANTtenant_name. - Wide:
SNAPSHOTsnapshot_id ·REPOrepo ·PIDpid ·STARTEDstarted_at.
| Key | Verb | CLI | Now |
|---|---|---|---|
| ctrl-d | umount | shc backup umount <id> | live (SHC-743) |
c | copy the path | target (G2) |
ctrl-j BACKUP, NODE, TENANT (live). SHC-744’s mount/umount pair is on
main (catalog.go:1194,1290).
3.10 :volumes
Section titled “3.10 :volumes”Provider volumes bound to deployments. catalog.go:2353.
- Narrow:
IDid ·TENANTtenant ·STACKstack ·MOUNTmount ·PROVIDERprovider ·ACCESSaccess_mode ·SIZEsize_bytes ·NODEcurrent_node ·STATEstate. - Wide:
ENVenvironment ·HANDLEhandle ·LEASE-GENlease_generation ·DEPLOYMENTlink (SHC-919). Target wide:REASONstate_reason.
| Key | Verb | CLI | Prompts | Now |
|---|---|---|---|---|
b | provider snapshot now | shc volume snapshot <id> | name | live (SHC-2701) |
| Shift-R | restore a snapshot | shc volume restore-snapshot <id> <snap> -y | snapshot, confirm | live (SHC-743) |
| Shift-M | move the binding to another node | shc volume rebind <id> <from> <to> -y | to node (picker), confirm | live (SHC-743); the node is typed, a picker is target |
m | bind its data read-only at a path under the daemon’s state directory, leased (1h), whether the volume is on the daemon’s node or another (SHC-994) | shc volume mount <id>, released early with shc volume umount <handle> (never touches the data); listed on :volumemounts | live | |
| none | Per MPO LC-210. | |||
| ctrl-d | delete volume and data | shc volume rm <id> | force | live |
ctrl-j TENANT, NODE, PROVIDER (live). Enter from :storage or v from
:nodes (live).
3.11 :storage
Section titled “3.11 :storage”Storage providers. catalog.go:2266.
- Narrow:
NAMEname ·TYPEprovider_type ·FILESYSTEM·MANAGEDmanaged ·QUOTAquota_support ·SNAPSHOTsnapshot_support ·NODESnodes ·PATHpath. - Wide:
QUOTA-METHOD·SNAPSHOT-METHOD·ID.
| Key | Verb | CLI | Prompts | Now |
|---|---|---|---|---|
| Enter | its volumes | live | ||
e | edit the node set: each added node is a link, each removed one an unlink; adds run first | shc storage link/unlink <name> <node> | node checklist | live (SHC-919, type_storage_nodes.go); the managed providers are refused: the nfs is one export host every node mounts (nfs join -n MOVES it, the data staying behind), the cephfs nodes are OSDs that take a device or an OSD id |
| Shift-E | enable ⇄ disable managed storage | shc storage <cephfs|nfs> enable/disable | target (G15) | |
l | the managed provider’s service journal | shc storage logs <nfs|cephfs> | live (the managed nfs and cephfs rows) | |
| ctrl-n | add | shc storage add | YAML template | live |
| ctrl-d | delete | shc storage rm <name> | force | live |
The retired HUD had enable, disable and logs here
(5deaa5b4b:modules/hud/actionbar_items.go:101-107).
3.12 :exports
Section titled “3.12 :exports”Archives written by exporters (shc export ls, import, mount, umount).
ExportList → name, size_bytes, created_at. type_exports.go, live
(SHC-921).
The route answers for one deployment, so :exports is that call for each
deployment of the browsed tenant and v w on a deployment is the one call.
- Narrow:
NAME·SIZE·AGE. Wide:STACK·ENV·TENANT·DEPLOYMENTlink (SHC-919). - Per MPO LC-168.
mis blocked:shc export mounttakes the archive’s path on the daemon host and the listing carries only its name.
3.13 :backupkeys
Section titled “3.13 :backupkeys”Keys that open the backup repository (shc backup key ls, rotate, rm).
BackupKeyLs → id, current, userName, hostName, created.
type_backupkeys.go, live (SHC-921). Platform-wide: the repository is the
cluster’s.
- Narrow:
ID·CURRENT·AGE·HOST·USER. No wide columns. - Keys:
nrotate (shc backup key rotate -y, the daemon generates the key); ctrl-d retire (shc backup key rm <id> -y), refused on the current key. - No key material reaches the HUD: the row is its own detail and rotate sends none.
3.14 :retention
Section titled “3.14 :retention”The resolved backup retention for the tenant, or a stack with v r from a
deployment (shc retention ls/set/reset/apply/preview). One row per tier,
the shape :quotas uses. BackupRetentionGet → daily, weekly, monthly,
yearly. type_retention.go, live (SHC-921).
- Narrow:
TIER·KEEP·SCOPE. Wide:TENANT·STACK. - Per MPO LC-168.
3.15 :secrets
Section titled “3.15 :secrets”The vault’s keys. catalog.go:1923.
Columns (SecretList all=true → SecretResponse, catalog.go:1974-2004)
- Narrow, what
shc vault lsprints:KEYkey ·SCOPEscope. - Wide:
VALUE,••••••untilxon that row, fetched on demand, never held in the list (G2) ·TENANTtenant_name ·STACKstack_name ·ENVenvironment ·UPDATEDupdated_at ·APPapp_name ·DEPLOYMENTdeployment, the SHC-919 link ·CREATEDcreated_at. VALUEis wide becauseshc vault lshas no value column (SHC-1881). A valuexreveals shows with ctrl-w on.
| Key | Verb | CLI | Prompts | Now |
|---|---|---|---|---|
x | reveal the value in the VALUE cell; again hides it; one row at a time | shc vault get <key> --scope (SecretGet, pkg/apiclient/vault_gen.go:149) | target (G2) | |
c | copy the value to the clipboard (OSC 52, then the native helper) | shc vault get <key> | target (G2). Today c copies the row id. | |
e | set a new value | shc vault set <key> | value, masked | live (SHC-743) |
| ctrl-n | new key | shc vault set <key> | key, value (masked), scope, stack, environment | live, but the value is typed into a YAML file in $EDITOR (create.go:947-959); target form (G2) |
| ctrl-d | delete | shc vault rm <key> | live |
Masking, one-at-a-time reveal and copy are per MPO LC-186.
ctrl-j TENANT, DEPLOYMENT (live, SHC-919).
3.16 :vault (new)
Section titled “3.16 :vault (new)”The vault itself: one row (shc vault status, coldstart, unlock,
rotate, replant, export, import). VaultStatus → initialized,
locked; VaultColdstartStatus → holder node.
- Narrow:
INITIALIZED·LOCKED·COLDSTART-NODE. - Keys: Shift-U unlock (
shc vault unlock, masked password);nrotate the master password (shc vault rotate, masked old and new); Shift-M move the cold-start capability (shc vault coldstart replant, node name);wexport (shc vault export <file>); Shift-R import (shc vault import <file>). Per MPO LC-161, LC-166.
3.17 :config
Section titled “3.17 :config”Scoped configuration. catalog.go:2461. SHC-742 reshapes this view
(ORIGIN column, effective rows, drill to the stored rows).
- Narrow:
PATHpath ·VALUEvalue ·SCOPEscope. - Wide:
ORIGINset/effective ·TENANT·STACK·ENV·UPDATEDupdated_at ·CREATEDcreated_at ·DEPLOYMENTlink (SHC-919).
| Key | Verb | CLI | Prompts | Now |
|---|---|---|---|---|
e | set at this row’s scope | shc config set <path> <value> | value (YAML edit or form) | live (edit); the one-field set stays behind a, on no key |
| ctrl-n | set a new path | shc config set | path, scope, value | target (G15) |
c | copy the value | target (G2) | ||
| ctrl-d | unset at exactly this scope | shc config unset <path> | live |
3.18 :quotas
Section titled “3.18 :quotas”One row per quota axis for the tenant. catalog.go:2024.
- Narrow, what
shc quota statusprints:SCOPEscope_name ·AXIS·LIMITquota.* ·USED*_used ·AVAILABLE*_available ·USED%*_percent_used ·BASISwhat the used figure is:reservedfor cpu and memory,measuredorunmeasuredfor disk,countedfor the rest. - Wide:
TENANT·MEASUREDdisk_measured_at.
| Key | Verb | CLI | Prompts | Now |
|---|---|---|---|---|
e | set this axis’s limit | shc quota set --scope tenant --<axis> <value> | value | live (SHC-746) |
| ctrl-d | remove this axis’s limit | shc quota unset --scope tenant --<axis> | live (SHC-746), danger | |
t | measure disk now | shc quota scan | live (SHC-743); the scan fails (SHC-733) |
3.19 :tenants
Section titled “3.19 :tenants”Isolation boundaries, and the session’s scope. catalog.go:1409.
- Narrow:
ACTIVEactive ·NAMEname ·STACKSdeployment_count. - Wide:
DATA-DIRdata_dir ·CONFIG-DIRconfig_dir.
| Key | Verb | CLI | Now |
|---|---|---|---|
u | make it the session’s tenant | shc ctx -t <name> | live |
| Enter | make it the session’s tenant and open its deployments | shc ctx -t <name> | live |
v d | its deployments, the session’s tenant unchanged | live | |
| ctrl-n | add | shc tenant add <name> | live |
| ctrl-d | delete | shc tenant rm <name> -y (force) | live |
v: d deployments, u users, q quotas, k secrets, g config, c
connections, r retention (live, SHC-919), p rules (live, SHC-1079).
3.20 :users
Section titled “3.20 :users”Keycloak users of the active tenant. catalog.go:1635.
- Narrow:
USERNAMEusername ·EMAILemail ·ENABLEDenabled ·ROLESroles ·DIRECT ROLESdirect_roles. - Wide:
TENANT·FIRSTfirstName ·LASTlastName ·VERIFIEDemailVerified ·UIDid.
| Key | Verb | CLI | Prompts | Now |
|---|---|---|---|---|
e | edit roles, groups and password: each role added is a grant, each removed a revoke; each group ticked a join, each cleared a leave; a password set is a reset | shc user grant, shc user join, shc user reset-password, shc user revoke, shc user leave, in that order | role checklist (baseline roles, the tenant’s direct roles, the user’s own), group checklist (the realm’s groups, the user’s own), other roles, new password (masked), temporary | live (SHC-919, groups gap L5.20, type_users_edit.go) |
| ctrl-k | end the user’s sessions and tokens | shc user logout <user> | live (SHC-743) | |
| ctrl-n | create | shc user create <username> "<name>" <email> | YAML template | live |
| ctrl-d | delete | shc user rm <user> -y | live |
3.21 :connections
Section titled “3.21 :connections”Credentials to outside systems (DNS, S3, CA signer, registry, …).
catalog.go:2675. SHC-742 ruled providers are not server-side objects, so
there is no providers drill.
- Narrow, what
shc connection lsprints:NAME·TYPE·TENANT·SCOPE·DNS·PURPOSE·LOCATION. - Wide:
CAPABILITIES, the HUD’s one-cell summary of the flags ·LOCAL-DNS·PROXY·CA-SIGNER·RESTIC·VOLUME·REGISTRY·ZONES(all fromshc.provider.list).
| Key | Verb | CLI | Prompts | Now |
|---|---|---|---|---|
| Enter | its grants | live (SHC-919) | ||
| ctrl-n | connect | shc connection connect <name> | type, then that type’s fields (secrets masked) | target (G15) |
| ctrl-d | delete | shc connection rm <name> -y | live |
grant and revoke-grant move from a here to ctrl-n and ctrl-d on
:grants.
3.22 :grants (new)
Section titled “3.22 :grants (new)”What a connection may mint, for whom (shc connection grants). Hidden,
reached by Enter on a connection.
- Narrow:
CONNECTION·TENANT·CAPABILITY·GRANTEE·BOUNDARY. No wide columns. - Keys: ctrl-n grant (
shc connection grant <c> --capability --grantee [--boundary]); ctrl-d revoke (shc connection revoke-grant). Live (SHC-919,type_grants.go).
3.23 :integrations
Section titled “3.23 :integrations”Plug/socket wiring between deployments. catalog.go:1736.
- Narrow:
CONSUMERconsumer_stack_name ·PLUGconsumer_plug ·PROVIDERprovider_stack_name ·SOCKETprovider_socket ·STATUSstatus ·IDid. - Wide:
ENVthe consumer’s environment ·TENANTthe consumer’s tenant ·PROVIDER-TENANT·PROVIDER-ENV·DEPLOYMENTandPROVIDER-DEPLOYMENTlinks (SHC-919). - Listed once per (tenant, environment) the scope’s deployments occupy, because a route row names its consumer by stack alone (SHC-973).
| Key | Verb | CLI | Now |
|---|---|---|---|
| ctrl-n | wire a plug to a socket | shc update <consumer> -i <plug>=<provider>[@env] | live (SHC-919): consumer picked from the tenant’s deployments |
| ctrl-d | unwire, which runs the edge’s teardown | shc update <consumer> -i <plug>! | live (SHC-919), Danger |
Both are shc update on the consumer (type_integrations_wire.go). ctrl-j
DEPLOYMENT lands on the consumer and PROVIDER-DEPLOYMENT on the provider
(SHC-919).
3.24 :ingress
Section titled “3.24 :ingress”Every materialised Traefik router (shc ingress ls, cat). IngressLs →
routers[]: file, router, host, rule, service, upstream, middlewares,
priority, target. type_ingress.go, live (SHC-921).
- Narrow:
FILE·ROUTER·HOST·UPSTREAM·MIDDLEWARES·TARGET.TARGETisfront doorfor a hostname exposed bare, which follows the app’s front door, andpinnedfor one exposed with its service (SHC-2474). - Wide:
SERVICE·RULE·PRIORITY. - Keys:
ccopies the host;dshows the route document (shc ingress cat <file>). ois blocked: the host has no open-in-browser path, and a provider verb must be anshccommand.
3.25 :dns (read-only)
Section titled “3.25 :dns (read-only)”The A, AAAA and CNAME records SHC published through its DNS connections,
one row per record (shc dns ls, GET /api/dns/inventory, tenant:read).
type_dns.go, live (SHC-928). Read-only (Decision 6): a record is published
and released with the deployment that declares its host.
- Narrow:
NAME·TYPE·VALUE·ZONE·CONNECTION·TENANT(the connection’s) ·DEPLOYMENT(tenant/environment/stack). - Wide:
TTL·CLAIM·DESIRED·PINNED. - A record lists under the tenant that owns its connection or its
deployment; a platform admin’s
shc dns lswithout-tlists them all.
| Key | Verb | CLI | Now |
|---|---|---|---|
| Enter | its owner: the deployment whose ingress declares the host, else the connection it was written through (v d, v c) | live (x9s Relation.When) | |
c | copy the name | live |
Per MPO Axiom 6, LC-84.
3.26 :schedules
Section titled “3.26 :schedules”Cron schedules on deployments, and the backup schedules (shc backup schedule ls) beside them: one table for “what fires on this deployment”.
schedulesResource in catalog.go, backup rows in
type_schedules_backup.go. A backup row’s JOB is backup and its
SOURCE names its scope (backup:stack, backup:tenant, backup:global,
…). A backup row’s id carries its scope and its --all-connected /
--with-dependants flags, so t and e send what the cron sends. A schedule
the scheduler refuses follows MPO Axiom 6.
e send what the cron sends.
- Narrow:
JOBjob ·CRONcron ·ENABLEDenabled ·LAST RUN ATlast_run_at ·NEXT RUN ATnext_run_at ·STACK. - Wide:
TENANT·ENV·SOURCEsource ·WARNINGwarning ·AGEcreated_at ·LAST-RESULTlast_fire_result (backup rows) ·DEPLOYMENTlink (SHC-919).
| Key | Verb | CLI | Prompts | Now |
|---|---|---|---|---|
t | fire now | shc job run <job> -s <stack>; backup rows shc backup schedule run --scope … | live | |
| Shift-E | enable ⇄ disable | shc schedule enable/disable <job> -s; refused on backup rows (a backup schedule has no disable) | live (SHC-743): one verb, the row’s state picks the spelling | |
e | change the cron | shc schedule edit <job> <cron> -s <stack>; backup rows shc backup schedule set <cron> --scope … | cron, prefilled | live |
| ctrl-n | add | shc schedule add <job> <cron> | YAML template | live |
| ctrl-d | delete | shc schedule rm <job>; backup rows shc backup schedule unset --scope … | live |
v h on a deployment keeps the rows whose STACK and ENV are the
deployment’s, so its stack- and deployment-scope backup schedules show;
tenant-, environment- and estate-wide ones are on the bare :schedules.
3.27 :jobs
Section titled “3.27 :jobs”Jobs a deployment declares (shc job ls, run, show). type_jobs.go.
The daemon lists jobs per deployment, so the bare table asks
shc.job.list once per deployment in the tenant (eight at a time) and
v j on a deployment asks once. d is shc job show.
- Narrow:
JOB·CONTEXT·SOURCE·PHASE·TIMEOUT. - Wide:
STACK·ENV·SERVICE·COMMAND·IMAGE·GROUP·URL·DEPLOYMENTlink (SHC-919). - Keys:
trun (shc job run <job> -s <stack>, prompts--varvalues asKEY=VALUE, …); Enter →:runsof this job;v hits schedules. Live.tdoes not wait: the run shows on Enter while it goes.
The retired HUD had T trigger and L logs on job rows
(actionbar_items.go:60-63).
3.28 :runs
Section titled “3.28 :runs”Job runs, running and finished (shc job ps, history, status,
cancel). type_runs.go. /api/resource/JobRun → id, job_name,
stack_name, environment, tenant_name, status, exit_code, error,
elapsed_seconds, started_at, completed_at, task_id. The bare table is the
newest page (100); Enter on a job asks the daemon for that job’s runs.
- Narrow, what
shc job psprints:ID·JOB·STACK·STATUS·ELAPSED·STARTED. - Wide:
CONTAINER·ENV·EXIT·AGE·COMPLETED·TASK(linked to:tasks) ·ERROR·DEPLOYMENTlink (SHC-919). - Keys: ctrl-k cancel (
shc job cancel <run-id> -y, reason), pending runs only: the daemon refuses a running one (X409067JRNRUN);dstatus (shc job status). Live.
3.29 :crons (read-only)
Section titled “3.29 :crons (read-only)”The daemon’s own maintenance crons (shc cron ls). CronList → name,
module, schedule, class, timeout, leader_gated, next_run_at. Narrow: NAME ·
MODULE · SCHEDULE · CLASS · TIMEOUT · LEADER · NEXT-RUN. No wide
columns. No verbs: the CLI has none; a schedule is the crons.<name> config
key.
type_crons.go, live (SHC-921).
3.30 :tasks
Section titled “3.30 :tasks”The daemon’s operations queue. catalog.go:1334.
- Narrow:
ID·NAME·STATUS·NODE·TRIGGER·ELAPSED. - Wide:
ATTEMPTSattempts/max_attempts ·STARTED·ERROR.
| Key | Verb | CLI | Prompts | Now |
|---|---|---|---|---|
| ctrl-k | cancel | shc task cancel <id> | reason | live (SHC-743) |
ctrl-j NODE. Reached by v from :nodes (live).
3.31 :events
Section titled “3.31 :events”The live typed-event feed. catalog.go:767. Read-only by design
(actions.go:1504-1505).
- Narrow:
SEQ·TIME·LEVEL·CODE·TENANT·STACK·MESSAGE. - Wide:
ENV·ACTOR·NODE·KIND·TRACE. - Keys:
ltails the feed (live). ctrl-jTENANT,NODE,DEPLOYMENT(SHC-919). SHC-745 fixes the row ids and the heartbeat row.
3.32 :audit
Section titled “3.32 :audit”The hash-chained audit trail. catalog.go:861. Read-only by design.
- Narrow:
TIMEcreated_at ·CODE·ACTOR·TENANT·STACK·MESSAGE. - Wide:
ENV·TRACE·ID. - SHC-756: the view renders the newest 100 platform-wide rows and filters
them afterwards. ctrl-j
DEPLOYMENT(live, SHC-919).
3.33 :nodes
Section titled “3.33 :nodes”Cluster members. catalog.go:1032.
- Narrow, what
shc node lsprints:NAMEname ·STATEcluster_state ·CONDITIONcondition, read off the node’s lease ·AVAILavailability ·CLOUDcloud ·LOCATIONthe cloud and location as one path ·ROOMok, orover:and the axes it is over-committed on ·LEADERis_leader ·VOTERis_voter. - Wide:
IDid ·HOSThostname ·INTERNALinternal_address ·UNDERLAYunderlay_address ·RUNTIME·COREScpu_cores ·MEMORYmemory_bytes ·FREE CORESfree_cpu_millicores ·FREE MEMORYfree_memory_bytes ·ROLE·HEALTHhealth_status ·AGE·PUBLICpublic_address ·ARCH·OS·TENANT. - Per MPO Axiom 6.
| Key | Verb | CLI | Prompts | Now |
|---|---|---|---|---|
| Enter | deployments on it | live | ||
l | the shcd log on that node | shc cluster logs <node> | live (stream.go:606) | |
e | set the public address | shc node update <node> --public-address | address | live (SHC-743) |
| Shift-K | cordon ⇄ uncordon | shc node cordon/uncordon <node> | live (SHC-743): one verb, the row’s state picks the spelling | |
| Shift-D | drain ⇄ undrain | shc node drain/undrain <node> | timeout, force | live (SHC-743): one verb, the row’s state picks the spelling |
| ctrl-d | leave gracefully | shc node leave <node> -y | force | live (SHC-743) |
| ctrl-k | forget (evict) | shc node forget <node> | live (SHC-743) |
v: d deployments, v volumes, t tasks, w workers (live, letters
SHC-919), f fences (live, SHC-1079), p pressure (live, SHC-1208).
3.34 :workers
Section titled “3.34 :workers”Task workers, one per shcd. catalog.go:1579. Read-only by design
(actions.go:1508-1509).
- Narrow:
ID·NODE·LEADERis_leader ·HEARTBEATheartbeat_ago ·STARTED. - Wide:
HEARTBEAT-AT.
3.35 :certificates
Section titled “3.35 :certificates”Certificates the CA machinery issued. catalog.go:2173.
- Narrow:
NAME·KIND(root / intermediate / leaf, SHC-742) ·FINGERPRINT·EXPIRESnot_after. - Wide:
PROVENANCE·ISSUER·NOT-AFTER. - Per MPO LC-168.
A tenant CA is the row named for its tenant (gap L5.20,
type_certificates_ca.go):
| Key | Verb | CLI | Prompts | Now |
|---|---|---|---|---|
| ctrl-n | a tenant’s first CA, from a ca-signer connection or a PEM chain | shc ca provision -t <tenant> --signer <conn>, or shc ca import -t <tenant> --root <f> --intermediate <f> --key <f> | tenant, then the signer or the three file paths | live |
e | swap the tenant CA for one from a new source; every served leaf is re-signed (Danger) | shc ca reprovision -t <tenant> (--signer <conn> | --root <f> --intermediate <f> --key <f>) -y | the signer or the three file paths | live |
Per MPO LC-186.
3.36 :cluster (new)
Section titled “3.36 :cluster (new)”The cluster as one row: the facts shc cluster status, shc leader status,
shc cluster mesh status, shc cluster fabric status,
and shc cluster host show answer today, one screen instead of five
commands.
- Narrow:
LEADERleader_node_id ·VOTERSlive voters against the control-plane fence’s automatic target ·HOST·MESHmesh0 up ·FABRIC. - Keys:
eedit host (shc cluster host set);treconcile (shc cluster reconcile). mesh0 has no on/off. It is up from the first join. ctrl-jLEADER→:nodes.v:nnodes,ccertificates,wworkers (SHC-919). Live (SHC-917).tstarts the missing installs and refuses a plan where one has to wait for another, namingshc cluster reconcile: the HUD cannot wait out an install.
3.38 :license (new)
Section titled “3.38 :license (new)”The estate’s vendor identity: the license row (shc license status,
install, activate, trial start, refresh, delink) and the portal
registration row (shc portal status, register, deregister).
LicenseStatus → state, type, holder, domains, expires_at, trial_ends_at,
source, last_check_ok.
- Narrow:
KIND(license / portal) ·STATE·TYPE·HOLDER·EXPIRES. - Wide:
DOMAINS·SOURCE·LAST-CHECK. - Keys: ctrl-n install (token or file; online code and trial are target);
trefresh (shc license refresh); ctrl-d delink. The portal row is read-only: the daemon serves no register or deregister route, soshc portal deregisterruns on the estate. The header’sWarningrow names the license state when it is notkeyedordev, and the portal channel when a registered estate’s is notup. Live (SHC-917).
3.39 :notifications
Section titled “3.39 :notifications”shc notification ls and test. NotificationList → name, channel, on,
destination, provider, connection, cooldown, debounce, retries, timeout.
Per MPO LC-165.
Per MPO LC-186.
- Narrow:
NAME·CHANNEL·ON(event patterns) ·DESTINATION·PROVIDER. Wide:CONNECTION·COOLDOWN·DEBOUNCE·RETRIES·TIMEOUT. - Keys:
ttest (shc notification test <rule>). The daemon prefixes the message[TEST], setstest: truein the payload and refuses a rule tested less than 30 seconds ago (X429707NTFTST). The retired HUD also edited and deleted rules (actionbar_items.go:246-250); rules stay anotificationsconfig edit.
3.40 :diagnoses
Section titled “3.40 :diagnoses”shc doctor ls and run. DoctorDiagnoses → name, description, category,
fix, remedy. type_diagnoses.go, live (SHC-921).
- Narrow:
NAME·CATEGORY·FIX·DESCRIPTION. Wide:REMEDY(the remedy’s effect). - Keys:
trun this row’s category (shc doctor run -c <c> [--fix], prompts fix yes/no; a destructive prescription is never applied from here). What the run found for a row is that row’sd.
3.41 CLI-only by design
Section titled “3.41 CLI-only by design”These are one-shot bootstrap, local-machine or break-glass commands. None is a browsable thing, so none gets a type (Decision 7):
shc init, shc cluster init/join/leave/rm/repair/ping,
shc node join/token, shc ctx login/logout, shc auth login/logout/token,
shc mcp serve, shc completion, shc test run, shc support bundle,
shc purge and shc db, shc adapter load/migrate, shc deploy -f,
shc validate, shc search, shc recover, shc clone reclaim/interrupted/ finish-forward, shc backup group/ungroup/sync/prune/relocate/ clear-unusable/clear-restore-seal/inspect/import,
shc system keycloak reset-admin-password.
Gap L5.20 took service clients, LDAP binds (shc auth …-service-client,
…-ldap-bind) and brands (shc branding …) off this list: each is a
layer-5 object the CLI manages, so each has a page (3.50 to 3.52).
3.42 :volumemounts
Section titled “3.42 :volumemounts”The volume binds and container snapshots m on :volumes and :containers
left on the daemon host, each held under a lease the daemon’s reaper ends
(SHC-994). shc volume mounts → VolumeMounts. type_volumemounts.go,
live. Scoped: a tenant’s view sends its X-SHC-Tenant, the bare view
all_tenants=1.
- Narrow:
IDid ·TENANTtenant_name ·SOURCEsource (a container’s iscontainer <id>) ·TARGETmount_path ·MODEread_only (ro/rw) ·OWNERowner ·EXPIRESexpires_in_seconds (the daemon’s own count, never this host’s clock). - Wide:
KINDkind ·STACKstack_name ·ENVenvironment ·NODEnode_id ·STARTEDstarted_at.
| Key | Verb | CLI | Now |
|---|---|---|---|
| ctrl-d | umount before the lease runs out | shc volume umount <id> | live |
ctrl-j TENANT, NODE (live).
3.43 :labels
Section titled “3.43 :labels”Every label value, what shc label ls --all lists
(SHC-1079, scheduler design 5.3). type_fences.go, live. Platform-wide:
the label index reads no tenant.
- Narrow:
LABELkey=value ·SOURCE(derived, operator, system) ·NODESmembers ·READY·RESERVED·CONSTRAINTS·DEPLOYMENTSdeployment_count. - Wide:
MEMBERSmember names ·BACKUP-REPO·DESCRIPTION·AGEcreated_at. disshc label show <key>=<value> -o json. The listing’s warnings (an unlocated node, a thin control-plane) ride a note.
| Key | Verb | CLI | Prompts | Now |
|---|---|---|---|---|
| Enter | member nodes | live | ||
e | edit | shc label set <key>=<value> | description; reserved on an operator label, location, cloud and control-plane; backup repo on location | live |
Putting a label on a node is shc node label. This view lists label values and edits the attributes shc label set takes. It never adds a label to a node.
v: n member nodes (Enter), r constraints naming it (active tenant and
cluster), d deployments it shapes (live).
3.44 :constraints
Section titled “3.44 :constraints”Placement constraints on the active tenant and the cluster, shc constraint ls
(SHC-1355). type_constraints.go, live. Scoped: every call sends the tenant’s
X-SHC-Tenant; a cluster constraint shows in every tenant with SCOPE
cluster, and the daemon refuses a tenant admin’s ctrl-d on it.
- Narrow:
ID·SCOPE·TARGET·FORMwhere or prefer ·EXPRESSION·REASON·SET-BY·CREATEDcreated_at. No wide columns.
| Key | Verb | CLI | Prompts | Now |
|---|---|---|---|---|
| ctrl-n | set | shc constraint set [--where '<selector>'] [--prefer '<selector>'] --scope cluster|tenant|deployment with -t, -e, -s as the scope needs | scope, stack, environment, where, prefer, reason | live; a form given replaces that form’s row; both may be set |
| ctrl-d | clear | shc constraint clear --scope <scope> --where|--prefer | live; on a cluster constraint the confirm notes that only platform:manage may clear it |
v: f the label values its key=value terms name (none for a key!=value
term), d the tenant’s deployments it binds: cluster, tenant and deployment
at once.
3.45 :placement
Section titled “3.45 :placement”Why a deployment runs where it runs, shc constraint explain (SHC-1079).
type_placement.go, live. Hidden, drill-only, read-only: v p on a
:deployments row.
- Rows are explain’s lines:
STEP(replica, rule, condition) ·SOURCE·OBJECT·RULE·FENCE·NODE·LEFTnodes remaining ·VERDICT(chosen, pending, refused, kept, removed). A step that removes nodes gets one more row per node it removed. disshc constraint explain -s <stack> -t -e -o json. What placement does not enforce yet rides a note.- Until the engine’s explain (SHC-1058 B2) the rows are SHC-1050’s shorter explain; the capacity, spread, score, failover and history steps come with it.
ctrl-j FENCE → :labels, NODE → :nodes (live).
Not built with F1: the wide PLACEMENT column on :deployments waits for
the engine’s assignment state. :nodes has its CONDITION column, read off
the node’s lease by shc node ls.
3.46 :pressure (read-only)
Section titled “3.46 :pressure (read-only)”Every queue on every node, the pressure lines of shc status (SHC-1208).
StatusGetGet → one row per node per queue. type_pressure.go, live.
- Narrow:
NODE(links to:nodes) ·QUEUE·LEVELgreen, amber or red, marked(stale)when the node stopped refreshing it ·DEPTHdepth/capacity and unit ·OLDESTage of the oldest waiting item ·REASONwhy it is not green, or why the queue could not be read ·IN/S·OUT/S·DROPPEDdropped or refused, total ·RETIREDthe retired total and why, when there is one ·AMBERandRED, the depth and age each level starts at. - Wide:
SINCEhow long the level has held.
No verbs: a pressure line is a measurement a node takes of itself, and a
threshold is declared by the queue’s owner in the daemon. Reached from
:nodes with v p, filtered to that node.
3.47 :groups (read-only)
Section titled “3.47 :groups (read-only)”A deployment’s groups, one row a member (SHC-2471). type_groups.go.
Per MPO LC-84, LC-92.
Columns (StatusGetGet?stack_name=… → groups[] → GroupStanding)
- Narrow:
GROUPgroup ·MEMBERmembers[].member ·LOCATIONmembers[].location, where the member runs,-when it was given none, and<location>, moving to <moving_to>while it is on its way (SHC-2480), as the CLI prints it ·READYreadywhen every replica the member runs as reads ready, elsenot ready·SERVICESmembers[].services. - Wide:
STACK·ENV·TENANT·DEPLOYMENT.
The rows are the groups of shc.status.get for the one deployment, the
answer shc status -s <deployment> prints as its Groups section (SHC-2469).
The CLI and the HUD read one source, and one test feeds one answer to both
(TestTheGroupsRowsAndTheCLIGroupsSectionReadOneAnswer). There is no
shc group command and no list of groups across deployments.
Keys
| Key | Verb | CLI | Prompts | Now |
|---|---|---|---|---|
| Enter | the services this member runs | live |
No verbs: a member is scaled with its group (e on the deployment), and
start, stop, restart, logs and shell are on its services, one Enter away.
d/y fall back to the row as JSON.
Relations. Enter → :services, filtered to the member’s services in its
own deployment. ctrl-j TENANT, and DEPLOYMENT back up.
3.48 :aliases (read-only)
Section titled “3.48 :aliases (read-only)”A deployment’s aliases (x-shc-aliases, SHC-2459), one row an alias, with
the replicas it points at now (SHC-2471). type_aliases.go. Hidden, and
lists only when anchored: v l on a :deployments row. A bare :aliases
lists nothing and says why.
Columns (StatusGetGet?stack_name=… → aliases[] → AliasStatus)
- Narrow:
ALIASalias ·SELECTSselects, the selector as the app wrote it, its:1count included ·REPLICASreplicas, the replicas it points at now,-when none ·REASONreason, why it has no backend,-while it has one. - Wide:
STACK·ENV·TENANT·DEPLOYMENT.
The rows are the aliases of shc.status.get for the one deployment, the
answer shc status -s <deployment> prints as its Aliases section, and one
test feeds one answer to both
(TestTheAliasesRowsAndTheCLIAliasesSectionReadOneAnswer).
No keys and no Enter: an alias changes when the labels of its replicas do,
or when the app’s x-shc-aliases does. d/y fall back to the row as
JSON. ctrl-j TENANT, and DEPLOYMENT back up.
3.49 :usergroups
Section titled “3.49 :usergroups”The groups of a tenant’s realm (shc user group ls, add, rm). :groups
is a deployment’s groups, so these take the user’s noun.
type_usergroups.go, gap L5.20. Tenant-scoped. SHC makes shc-app-access,
shc-admins and shc-users itself, and the daemon refuses to make or
remove them.
- Narrow:
NAMEname. Wide:TENANT.
| Key | Verb | CLI | Prompts | Now |
|---|---|---|---|---|
| Enter | the group’s members: the tenant’s users whose GROUPS name it | live | ||
| ctrl-n | add | shc user group add <group> -t <tenant> | name | live |
| ctrl-d | remove; one that leaves the tenant with no manager is refused | shc user group rm <group> -t <tenant> -y | live |
A user joins and leaves a group from e on :users (3.20).
3.50 :serviceclients
Section titled “3.50 :serviceclients”The master realm’s confidential clients (shc auth list-service-clients,
create-service-client, delete-service-client), what terraform and CI log
in with. type_serviceclients.go, gap L5.20. Platform-wide, platform:manage.
- Narrow:
CLIENT IDclient_id ·TOKEN LIFESPANtoken_lifespan. - Wide:
SECRET, masked.
| Key | Verb | CLI | Prompts | Now |
|---|---|---|---|---|
| ctrl-n | mint a client | shc auth create-service-client <name> [--token-lifespan N] | name, token lifespan | live |
n | mint it a new secret; the old one stops working | shc auth create-service-client <name> --rotate-secret | live | |
x/c | reveal or copy the secret just minted, once | live | ||
| ctrl-d | delete | shc auth delete-service-client <name> | live |
Per MPO LC-186.
3.51 :ldapbinds
Section titled “3.51 :ldapbinds”A tenant realm’s LDAP binds (shc auth list-ldap-binds, create-ldap-bind,
delete-ldap-bind), for consumers SHC does not run, and the ones installed
apps hold through their ldap plug. type_ldapbinds.go, gap L5.20.
Tenant-scoped, platform:manage.
- Narrow:
TENANTtenant ·NAMEname. Wide:PASSWORD, masked.
| Key | Verb | CLI | Prompts | Now |
|---|---|---|---|---|
| ctrl-n | make a bind | shc auth create-ldap-bind <name> -t <tenant> | name | live |
n | a new password; the old one is refused from then on | shc auth create-ldap-bind <name> -t <tenant> --rotate-secret | live | |
x/c | reveal or copy the password just minted, once | live | ||
| ctrl-d | remove; a bind an app holds is refused and goes with the app | shc auth delete-ldap-bind <name> -t <tenant> | live |
The password is held for one reveal the way a service client’s secret is (3.50).
3.52 :branding
Section titled “3.52 :branding”The estate’s brand bundles (shc branding list, set, delete), the
logos the sign-in pages and the launcher read through the branding socket.
type_branding.go, gap L5.20. Platform-wide: the store is the estate’s.
- Narrow:
NAMEname ·FILESfiles ·HASHhash.
| Key | Verb | CLI | Prompts | Now |
|---|---|---|---|---|
| ctrl-n | set a brand | shc branding set <name> --logo <file>... | name, svg path, png path | live |
e | replace its logos | shc branding set <name> --logo <file>... | svg path, png path | live |
| ctrl-d | delete | shc branding delete <name> -y | live |
The logos are files on the operator’s machine, read and checked (extension,
1 MiB) before the confirm, as --logo reads them.
Per MPO LC-165.
4. Gap list
Section titled “4. Gap list”Each gap names the ticket that closes it.
| # | Gap | Ticket |
|---|---|---|
| G1 | Every declared verb has a key and is in the legend; ctrl-d/ctrl-k come from declared keys, not verb-name guessing. Built: the deployments slice in SHC-2701, every other type in SHC-743, held by TestEveryDeclaredVerbIsOnAKey. | SHC-743, SHC-2701 |
| G2 | Secrets: x reveal, c copy value, masked VALUE column, masked input for every secret param, c copies a declared copy column over OSC 52. | SHC-910 |
| G3 | Guided install and update forms from the app’s variable schema. | SHC-911 |
| G4 | Shell, logs and port-forward at service and container level; service CPU/MEM columns. | SHC-912 |
| G5 | Port-forward from a remote session. | SHC-926 |
| G6 | Container restart, container mount, volume mount and storage logs have API routes and no CLI verbs. | SHC-927 |
| G7 | Deployment verbs and columns: clone, repoint, export, open, detail folds inspect; LATEST, HOSTS, LEASE; backup export (move removed by SHC-1230). | SHC-913 |
| G8 | Three HUD strings name CLI spellings that do not exist: shc rollback (actions.go:269, no such command in ce or shc), shc cluster forget (actions.go:615, the verb is shc node forget) and --unintegrate (actions.go:1521, removed; a disconnect is -i <plug>!). | SHC-914 |
| G9 | Launch honours the shc ctx tenant and stack, not only the environment (cli/hud.go:133), and opens on :deployments. | SHC-915 |
| G10 | Quota set and unset. | SHC-746 (scan failure: SHC-733) |
| G11 | Aliases, cert kinds, config twice; events ids; audit paging; backup umount. | SHC-742, SHC-745, SHC-756, SHC-744 (on main) |
| G12 | :jobs, :runs; backup schedules on :schedules; t and e on schedules. Closed: e on a job schedule is shc schedule edit over shc.schedule.update. | SHC-916, SHC-985 |
| G13 | :cluster, :vault, :license; cert rotate on :certificates. | SHC-917 |
| G14 | :ingress, :addons, :exports, :backupkeys, :retention, :diagnoses, :crons. | SHC-921 |
| G15 | Relations pass: DEPLOYMENT link on every per-deployment type; the deployment and tenant v lists above; v c deployment → containers; connections → :grants; integrations wire/unwire; storage and users edit forms; picker letters. | SHC-919 |
| G16 | :dns read-only view. Built, with shc dns ls. | SHC-928 |
| G17 | :notifications needs a rule-list route in ce. | SHC-920 |
| G18 | Every layer-5 object has a page (LAYERAUDIT L5.20): :usergroups, :serviceclients, :ldapbinds, :branding, joins and leaves on e of :users, and the tenant CA’s provision, import and reprovision on :certificates. Built. | pending (HUDPAGES) |
Gap tickets
Section titled “Gap tickets”G2 (SHC-910). HUD secrets: x reveals, c copies, every secret field is masked
- On
:secrets,xshows the focused key’s value in aVALUEcell andxagain hides it;ccopies the value; both fetch throughSecretGeton demand and nothing stores the value in the list, the mutation history or an Explain. proto.Paramhas asecrettype rendered as a masked field;vault set,user password,vault unlockand secret-typed app variables use it, and ctrl-n on:secretsno longer puts the value in a YAML file.cworks over SSH on an estate node (OSC 52 first, then pbcopy / wl-copy / xclip), proven by pasting a copied value on the operator’s laptop.
G3 (SHC-911). HUD install and update walk the app’s variables in a typed form
ion:appsand ctrl-n on:deploymentsopen one field per variable fromshc.app.detail(secret masked, bool toggle, int/port validated, select for enums), prefilled with the package default, and the confirm prints the sameshc installthe CLI would run.eon a deployment opens the same form prefilled with current values and can change variables, version, hosts, ports and integrations, printing oneshc update.- After an install confirms, the HUD lands on the new deployment’s
:servicesand the rows go live as containers start.
G4 (SHC-912). Shell, logs and port-forward on services and containers
s,land Shift-F on a:servicesrow target that service; on a:containersrow,stargets that container (container_id).v con a deployment lists its containers across services in one hop.:servicesshowsCPUandMEMnarrow andNODES,OOM,EXITwide.
G5 (SHC-926). Port-forward from a HUD pointed at a remote daemon
- Shift-F works from a laptop session (
--url), through an authenticated tunnel gated atstack:manage, with the same service/port inference asshc forward. shc forwardfrom a remote context works the same way.- A caller without
stack:manageis refused before any socket opens.
G6 (SHC-927). CLI verbs for container restart, container mount, volume mount and storage logs
shc container restart,shc container mount,shc volume mountandshc storage logsexist and call the routes the retired HUD used.randmon:containers,mon:volumesandlon:storagerun them, each confirm printing the new command.
G7 (SHC-913). Deployment verbs and columns the HUD is missing
- Shift-C clone, Shift-P repoint and
wexport run their CLI verbs from a:deploymentsrow with a typed prompt. Relocation isshc update --where(core/placement/relocate_hint.go). oopens andccopies the deployment’s primary URL;LATEST,HOSTSandLEASEare wide columns;dincludes theshc inspectbundle.won:backupsexports the archive.
G8 (SHC-914). The HUD prints three shc spellings that do not exist
rollbackon a deployment either has a realshc rollbackCLI verb or its confirm prints the verb that does exist;cli_verb_reference_test.gocovers action Explains.forgeton a node printsshc node forget <node>, and the:integrationsrefusal names-i <plug>!instead of--unintegrate.
G9 (SHC-915). shc hud opens where shc ctx points
- Launch passes the context’s tenant, environment and stack; the header shows
all three and the first table is
:deploymentsnarrowed to them. - An explicit
--tenant/--environmentflag or$SHC_*still wins.
G12 (SHC-916, SHC-985). Jobs, job runs and one schedules table in the HUD
:jobslists a deployment’s jobs;truns one; Enter shows its runs.:runslists running and finished runs; ctrl-k cancels one.:schedulescarries backup schedules beside job schedules, andt,e, ctrl-d map to the right CLI verb per row.eopens a form prefilled with the row’s cron; on a job row it runsshc schedule edit, which keeps the schedule’s id and last run (SHC-985).
G13 (SHC-917). Cluster, vault and license as HUD types
:clustershows leader, voters, host, mesh0 and fabric on one row witheandt.:vaultunlocks (masked), rotates, replants, exports and imports.:licenseshows license and portal state and installs, refreshes and delinks; the header warns when either is not healthy.
G14 (SHC-921). Browse views for ingress, add-ons, exports, backup keys, retention, diagnoses and crons
- Each type lists what its
shc … lslists, with the columns in this document. - Each verb in its section runs from its key with the CLI command in the confirm.
G15 (SHC-919). HUD relations pass
- Every per-deployment type has a
DEPLOYMENTlink column, so ctrl-j lands on the deployment from any backup, secret, event, schedule, volume, job or config row. von a deployment and on a tenant lists the relations in this document, each with its picker letter, and each opens filtered to the row.:grantsunder connections, wire/unwire on:integrations, the node checklist on:storageand the roles form on:usersreplace the free-text params they have today.- Live (SHC-919). Three keys the tables tag G15 stay target: Shift-E on
:storage, ctrl-n on:configand ctrl-n connect on:connections.
G17 (SHC-920). Notification rules as a HUD type
- ce serves a rule list route and
shc notification lsprints it. :notificationslists rules;tsends a synthetic notification through the focused rule.
5. Decisions
Section titled “5. Decisions”Taken 2026-09-25 on Clay’s go-ahead, each as this spec recommended. Any of them can still be reopened.
- Per MPO LC-210.
- Three k9s letters change meaning:
sis shell (k9s: scale),pis protect (k9s: previous logs),iis install (k9s: set image). Replicas change ine’s scale field (shc update --scale). - Per MPO LC-98.
- Remote port-forward is served on the authenticated public listener,
gated at
stack:manage(SHC-926). - API-only verbs get their CLI commands first; the HUD follows the CLI (SHC-927).
:dnsships read-only without waiting for a CLI verb (SHC-928).- The CLI-only list in 3.41 stands.