CLI reference
Every omniglass command, generated from the binary’s own command tree. The data commands
are generated from the API (make gen), so this reference is a faithful mirror of
what the server exposes. For the narrative, connecting, authenticating, and the generated-versus-
hand-written split, see the CLI guide.
Global flags
Section titled “Global flags”Every command accepts these, each with an environment-variable default:
| Flag | Type | Default | Description |
|---|---|---|---|
--server | string | http://localhost:8080 | Omniglass server base URL (env OMNIGLASS_SERVER) |
--token | string | (none) | bearer token (env OMNIGLASS_TOKEN) |
omniglass audit-log
Section titled “omniglass audit-log”Commands for the audit-log resource
omniglass audit-log list
Section titled “omniglass audit-log list”List audit-trail events
omniglass audit-log list [flags]Recent audit-trail events, newest first, each with the actor and, for an impersonated action, the real actor behind it. Read-only; gated by audit:read:admin (admin/owner only, since the audit trail is admin-sensitive).
| Flag | Type | Default | Description |
|---|---|---|---|
--before | string | (none) | Only events strictly older than this RFC3339 timestamp (paging backward) |
--limit | int | 0 | Max rows to return, newest first (default 100, capped at 500) |
--resource | string | (none) | Filter to one resource kind (e.g. auth, principal_grant) |
--verb | string | (none) | Filter to one verb (e.g. login, create) |
Example:
omniglass audit-log listomniglass auth
Section titled “omniglass auth”Commands for the auth resource
omniglass auth avatar
Section titled “omniglass auth avatar”Get your own profile picture
omniglass auth avatarReturns the caller’s profile picture as a base64-encoded JPEG. Requires authentication; self-scoped. No picture is a 404.
Example:
omniglass auth avataromniglass auth change-password
Section titled “omniglass auth change-password”Change your own password
omniglass auth change-password [flags]Verifies the current password and sets a new one. Requires authentication; self-scoped.
| Flag | Type | Default | Description |
|---|---|---|---|
--current-password | string | (none) | Your current password |
--new-password | string | (none) | The new password (at least 12 characters, not a common password, not containing the username) |
Example:
omniglass auth change-password --current-password current_password --new-password new_passwordomniglass auth create-token
Section titled “omniglass auth create-token”Create one of your own API tokens
omniglass auth create-token [flags]Mints a CLI/API token for the caller and returns it once (store it now; it cannot be retrieved again). A description is required (what the token is for); an optional ttl_days bounds its lifetime (default 90, maximum 365). Requires authentication; self-scoped (always issued for you). The token is stamped with the device and address that created it.
| Flag | Type | Default | Description |
|---|---|---|---|
--description | string | (none) | What the token is for (required) |
--ttl-days | int | 0 | Days until the token expires (default 90, maximum 365) |
Example:
omniglass auth create-token --description descriptionomniglass auth login
Section titled “omniglass auth login”Log in with a username and password
omniglass auth login [flags]Verifies a human’s password and sets an httpOnly session cookie. Public; a bad credential is a flat 401, and a correct password against a disabled account is a distinct 403 so the screen can explain it.
| Flag | Type | Default | Description |
|---|---|---|---|
--password | string | (none) | The account password; exchanged for a session cookie, never stored |
--username | string | (none) | The sign-in username |
Example:
omniglass auth login --password password --username usernameomniglass auth logout
Section titled “omniglass auth logout”Log out the current session
omniglass auth logoutRevokes the session token and clears the cookie. Public.
Example:
omniglass auth logoutomniglass auth me
Section titled “omniglass auth me”The authenticated principal, its permissions, and grants
omniglass auth meReturns the caller’s principal, flattened permissions (a UI hint and the fast-reject set), the permissions held on an all-scope grant (fleet_permissions), and grants. Requires authentication.
Example:
omniglass auth meomniglass auth remove-avatar
Section titled “omniglass auth remove-avatar”Remove your own profile picture
omniglass auth remove-avatarClears the caller’s profile picture. Requires authentication; self-scoped.
Example:
omniglass auth remove-avataromniglass auth set-avatar
Section titled “omniglass auth set-avatar”Set your own profile picture
omniglass auth set-avatar [flags]Sets the caller’s profile picture (JPEG, PNG, or WebP, base64-encoded), normalized server-side to a 256x256 JPEG. Requires authentication; self-scoped. A bad or oversize image is a 422.
| Flag | Type | Default | Description |
|---|---|---|---|
--image-base64 | string | (none) | The image (JPEG, PNG, or WebP), base64-encoded; normalized server-side to a 256x256 JPEG |
Example:
omniglass auth set-avatar --image-base64 image_base64omniglass auth status
Section titled “omniglass auth status”Commands for the status resource
omniglass auth status list
Section titled “omniglass auth status list”Whether the system has an owner yet
omniglass auth status listPublic: reports whether any owner has been bootstrapped, so the login screen can hide the bootstrap hint.
Example:
omniglass auth status listomniglass auth stop-impersonation
Section titled “omniglass auth stop-impersonation”Stop the current impersonation session
omniglass auth stop-impersonationRevokes the impersonation session presented by the request token, ending the view-as / act-as. Requires authentication with an impersonation token; self-scoped (ends only the session the token names).
Example:
omniglass auth stop-impersonationomniglass auth update-profile
Section titled “omniglass auth update-profile”Update your own profile
omniglass auth update-profile [flags]Updates the caller’s own label (email is administrator-set). Requires authentication; self-scoped (edits only your own principal).
| Flag | Type | Default | Description |
|---|---|---|---|
--label | string | (none) | Your label; empty clears it |
Example:
omniglass auth update-profileomniglass bootstrap
Section titled “omniglass bootstrap”Create the first owner (idempotent per username) and mint its bearer token
omniglass bootstrap <username> [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--email | string | (none) | owner email (optional) |
--label | string | (none) | owner label (optional) |
--password | string | (none) | owner password, so the owner can sign in to the console (optional) |
--ttl | duration | 2160h0m0s | how long the bootstrap token is valid before it expires (max 365 days) |
omniglass calc-rule
Section titled “omniglass calc-rule”Commands for the calc-rule resource
omniglass calc-rule create
Section titled “omniglass calc-rule create”Create a calc rule
omniglass calc-rule create [flags]Authors a rule that derives its output key on each owner (each component its selector picks, or each system) from its aliased inputs, reduced by an expression over the aliases, each bound as the list of its current values (one per instance on a component, every member’s on a system, with members records beside it). Every input key must be registered (by name or uuid; the rule holds it by uuid) and health may not be one; each alias is an identifier of at most 64, not a keyword, a builtin or list function’s name, or a site binding (component, has, members, system, value), and unique; the reduce must compile and yield the output key’s type (a 422 placed at body.reduce.expr with its line and column, and the name when it is one no alias binds); the output must be a registered key that is not health and that no collection writes (a native probe’s key, or one a driver declares among its emits); an enabled rule may not close a cycle in the graph from every enabled rule’s input keys to its output key (a 422 naming the chain of keys), nor write a key another enabled rule writes (a 422 naming that rule). A list or get carries calc_error when a stored reduce no longer compiles. A name already taken is a 409. Returns the rule with its uuid. Audited. Gated by rule:create, with an all-scope grant.
| Flag | Type | Default | Description |
|---|---|---|---|
--description | string | (none) | What the rule derives and why |
--enabled | bool | false | Defaults to true |
--inputs | string | (none) | The keys the rule reads, each by a unique alias its reduce uses; health may not be one |
--label | string | (none) | A human label |
--name | string | (none) | The rule’s name (lowercase letters, digits, hyphens) |
--output-key | string | (none) | The property or metric the rule writes: its type pins the reduce’s result. Not a reserved key (a native probe key, health), not a key a driver’s emits or a command type write, and not one another enabled rule writes |
--owner-kind | string | (none) | What the rule derives a value on: each component its selector picks, or each system its selector picks (read from the system’s role-bound members). Fixed at create |
--reduce | string | (none) | An expression over the inputs by alias |
--selector | string | (none) | The owners the rule derives for: a component rule’s component_types and components, or a system rule’s system_types and systems; absent is every owner of its kind |
Example:
omniglass calc-rule create --inputs <json> --name name --output-key output_key --owner-kind owner_kind --reduce <json>omniglass calc-rule delete
Section titled “omniglass calc-rule delete”Delete a calc rule
omniglass calc-rule delete <name>Removes an operator rule; an official rule is read-only (409). Audited. Gated by rule:delete, with an all-scope grant.
Example:
omniglass calc-rule delete <name>omniglass calc-rule get
Section titled “omniglass calc-rule get”Get a calc rule
omniglass calc-rule get <name>Returns one calc rule by name (or uuid). Gated by rule:read.
Example:
omniglass calc-rule get <name>omniglass calc-rule list
Section titled “omniglass calc-rule list”List calc rules
omniglass calc-rule listLists the calc rules, by name: the authored config that derives an output key on each owner from aliased inputs, each with its live state as counts (owners_computed, owners_pending, owners_unsupported, owners_failed) over the owners the caller may read. Rules read like a registry, so every rule is listed whatever the caller’s scope. Gated by rule:read.
Example:
omniglass calc-rule listomniglass calc-rule preview
Section titled “omniglass calc-rule preview”Preview a calc rule
omniglass calc-rule preview [flags]Computes a candidate calc rule now, on each owner it selects that the caller may read, with the reduce the tick runs, and writes nothing (a read-only transaction). For each owner it answers the value the rule would write, the output’s current value and whether they differ, the inputs with no value, the members skipped and the instances left out as stale (named when the caller may read the component, else counted). An expression that reads one member’s value by position (members[1].value.t, or an element of an input’s list) over a system with a member the caller may not read is withheld on that system, its error counting the members out of scope; one that folds each input’s list whole (avg(t), max(t)) shows the aggregate. A component rule previews the selected components holding one of its inputs, as the tick would mark them. The owners holding a current value of the output are computed first, so the cap never hides one, and the answer lists the owners holding a value or that the rule would write one on first, each by name. At most owner_cap owners are computed, and a bound on total input reads stops a preview over large systems early, a whole owner at a time (owners_judged of owners_total, truncated past either). The candidate is checked as a save would check it: a reduce that does not compile, a cycle in the key graph, an output another enabled rule or a collection writes, or health are each a 422, so the author learns before saving; given a saved rule’s name it is judged as an edit of that rule. The selector’s names resolve in the caller’s read scope: a name that does not exist and one the caller may not read are the same 422, and a name shared in and out of scope means the one in scope. A preview takes no lock a save waits on. Gated by rule:read.
| Flag | Type | Default | Description |
|---|---|---|---|
--inputs | string | (none) | The keys the rule reads, each by a unique alias its reduce uses |
--name | string | (none) | A saved rule’s name, to preview an edit of it (its stored version is then not a second writer of its key); absent for a new rule |
--output-key | string | (none) | The property or metric the rule would write |
--owner-kind | string | (none) | What the rule derives a value on |
--reduce | string | (none) | An expression over the inputs by alias |
--selector | string | (none) | The owners the rule derives for; absent is every owner of its kind |
Example:
omniglass calc-rule preview --inputs <json> --output-key output_key --owner-kind owner_kind --reduce <json>omniglass calc-rule rename
Section titled “omniglass calc-rule rename”Rename a calc rule
omniglass calc-rule rename <name> [flags]Moves an operator rule’s name, the address an operator types. A separate act from an update, because it breaks bookmarks and integration config outside this system; inside it nothing breaks, since the audit rows hold the rule’s uuid and the key graph is of keys, not rule names. Not a material change: no version bump. An official rule keeps its name (409), a taken name is a 409, an illegal or uuid-shaped one a 422. Returns the rule with its uuid. Audited. Gated by rule:update, with an all-scope grant.
| Flag | Type | Default | Description |
|---|---|---|---|
--name | string | (none) | The rule’s new name, unique among calc rules (lowercase letters, digits, hyphens) |
Example:
omniglass calc-rule rename <name> --name nameomniglass calc-rule state
Section titled “omniglass calc-rule state”Commands for the state resource
omniglass calc-rule state list
Section titled “omniglass calc-rule state list”Get a calc rule’s live state
omniglass calc-rule state list <name> [flags]What a calc rule last did on each owner the caller may read (components by the component read scope, systems by the system read scope), each owner named now: the value it computed, when and at which version, the inputs it found no value of, a system’s members that held none and the instances it left out as stale (named when the caller may read the component, else counted), an error, since when a system has had no members, and whether the owner is pending (with when a deferred mark is due). Ordered on the server, failing owners first, then pending, then those it wrote nothing for, then those holding a value, each by name, and at most limit of them; total and the pending depth count every owner the caller may read, listed or not. Gated by rule:read.
| Flag | Type | Default | Description |
|---|---|---|---|
--limit | int | 0 | The most owners to list, in state order: failing, pending, missing an input (or with no members), valued, each by name |
Example:
omniglass calc-rule state list <name>omniglass calc-rule update
Section titled “omniglass calc-rule update”Update a calc rule
omniglass calc-rule update <name> [flags]Patches a rule (an absent field is unchanged), bumping its version; a patch that changes nothing writes nothing. What changed is checked as on create: changed inputs, reduce or output recompile, a changed output must be one no collection writes, and an enabled rule may not close a cycle or share its output with another enabled rule. Enabling a disabled rule recompiles it and checks both, so a rule carrying calc_error cannot be enabled (422). The owner kind is fixed at create. Official rules are read-only (409). Audited. Gated by rule:update, with an all-scope grant.
| Flag | Type | Default | Description |
|---|---|---|---|
--description | string | (none) | What the rule derives and why |
--enabled | bool | false | Whether the rule runs; an enabled rule is part of the key graph |
--inputs | string | (none) | Replace the keys the rule reads |
--label | string | (none) | A human label |
--output-key | string | (none) | The property or metric the rule writes |
--reduce | string | (none) | Replace the reduce’s expression |
--selector | string | (none) | Replace the owners the rule derives for; an empty selector is every owner of its kind |
Example:
omniglass calc-rule update <name>omniglass command-type
Section titled “omniglass command-type”Commands for the command-type resource
omniglass command-type create
Section titled “omniglass command-type create”Create a command type
omniglass command-type create [flags]Registers a custom command type (official=false). The name must be a single kebab token; a target, when set, must be a registered property or metric type. Gated by command_type:create.
| Flag | Type | Default | Description |
|---|---|---|---|
--description | string | (none) | What the command does |
--label | string | (none) | A human label |
--name | string | (none) | The command type name (lowercase kebab) |
--params-schema | string | (none) | A JSON Schema fragment for the params |
--settle-window-seconds | int | 0 | The actuation window in seconds: how long the device is given to actuate before a mismatch is a failed command. 0 means settle immediately (a fire-and-forget command, or a settleable one judged at the moment of issue). A duration has no negative, so the schema floors it at 0 rather than accepting a value that behaves as 0 with no refusal to say so. |
--target-metric-type | string | (none) | The metric this command sets, for settlement (at most one target arm) |
--target-property-type | string | (none) | The property this command sets, for settlement (at most one target arm) |
Example:
omniglass command-type create --name nameomniglass command-type delete
Section titled “omniglass command-type delete”Delete a command type
omniglass command-type delete <name>Removes a custom command type by name. Official types are read-only. Gated by command_type:delete.
Example:
omniglass command-type delete <name>omniglass command-type get
Section titled “omniglass command-type get”Get a command type
omniglass command-type get <name>Returns one command type by name. Gated by command_type:read.
Example:
omniglass command-type get <name>omniglass command-type list
Section titled “omniglass command-type list”List command types
omniglass command-type listLists every registered command type (official and custom). Fleet-wide reference data. Gated by command_type:read.
Example:
omniglass command-type listomniglass command-type update
Section titled “omniglass command-type update”Update a command type
omniglass command-type update <name> [flags]Patches a custom command type’s label, description, params schema, settle window, or target on either arm (a nil field is unchanged; an empty target clears it; a non-empty arm clears the other). The name is fixed at creation. Official types are read-only. Gated by command_type:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--description | string | (none) | What the command does |
--label | string | (none) | A human label |
--params-schema | string | (none) | A JSON Schema fragment (replaces wholesale) |
--settle-window-seconds | int | 0 | The actuation window in seconds, floored at 0 (a duration has no negative; 0 means settle immediately) |
--target-metric-type | string | (none) | The metric this command sets (empty clears it; a non-empty arm clears the other) |
--target-property-type | string | (none) | The property this command sets (empty clears it; a non-empty arm clears the other) |
Example:
omniglass command-type update <name>omniglass component
Section titled “omniglass component”Commands for the component resource
omniglass component alarm
Section titled “omniglass component alarm”Commands for the alarm resource
omniglass component alarm acknowledge
Section titled “omniglass component alarm acknowledge”Acknowledge an alarm
omniglass component alarm acknowledge <name> <id>Records that a human has seen this alarm, and changes nothing else. The alarm stays exactly as raised as it was: acknowledging is not fixing, so health is NOT recomputed and cleared_at is untouched. Acknowledging is orthogonal to clearing in both directions, so a cleared alarm can still be acknowledged by whoever reviews the history, and clearing never acknowledges on an operator’s behalf. Acknowledging twice is idempotent: the first person and the first time stay, and the no-op writes no second audit row. Gated by alarm:acknowledge, whose scope is resolved on the component tier from that permission (not from component:update); a component outside the caller’s component:read is a non-disclosing 404, and one it can read but not acknowledge on is a 403.
Example:
omniglass component alarm acknowledge <name> <id>omniglass component alarm create
Section titled “omniglass component alarm create”Raise an alarm on a component
omniglass component alarm create <name> [flags]Records a condition on this component, then recomputes health in the same transaction: the component’s own verdict moves, and if it is now outage (an alarm at or above the high level), any role it occupies loses it as an occupant while the alarm is active, which can move its system and location verdicts with it; a lesser alarm degrades the component but leaves it occupying its roles. Gated by component:update; read and update scopes drive the 404 versus 403 split.
| Flag | Type | Default | Description |
|---|---|---|---|
--dedup-key | string | (none) | The condition identity; defaults to the message. Raising an already-open (component, dedup_key) returns the existing open alarm instead of a duplicate. A key (or, without one, a message) beginning rule: is refused (422): that namespace names a rule’s condition |
--message | string | (none) | What is wrong, for the operator reading it later |
--severity | string | (none) | How bad it is: a severity level by name (see /severity-levels); a level at or above high puts the component itself in outage |
Example:
omniglass component alarm create <name> --severity severityomniglass component alarm delete
Section titled “omniglass component alarm delete”Clear an alarm
omniglass component alarm delete <name> <id>Marks the alarm cleared and recomputes health in the same transaction, so the recovery is recorded as a transition at the moment it happened. The row is kept: what was wrong and when outlives the fix. Clearing an alarm that is already cleared or does not exist is a 404. Gated by component:update; read and update scopes drive the 404 versus 403 split.
Example:
omniglass component alarm delete <name> <id>omniglass component alarm list
Section titled “omniglass component alarm list”List a component’s alarms
omniglass component alarm list <name> [flags]What is currently wrong with this component, newest first, with the component’s own verdict those alarms make. Pass include_cleared for the history rather than the active set. Gated by component:read; an out-of-scope component is a non-disclosing 404.
| Flag | Type | Default | Description |
|---|---|---|---|
--include-cleared | bool | false | Include cleared alarms, so the list is the history rather than what is wrong now |
--unacknowledged | bool | false | Only the alarms nobody has looked at. On its own this is the queue an operator works (raised and unacknowledged); with include_cleared it also returns the incidents that came and went unattended |
Example:
omniglass component alarm list <name>omniglass component alarm timeline
Section titled “omniglass component alarm timeline”Read an alarm’s timeline
omniglass component alarm timeline <name> <id>The alarm’s history in one list, oldest first: the events that carry it (an event rule’s fire event, which opened it, and its clear event, which resolved it) merged by time with its audit rows (the raise, each acknowledgement, the clear, and a rule edit that opened or resolved it, naming the editor). At one instant an event comes before the audit row it caused. Gated by alarm:read; a component outside the caller’s component read scope, and an alarm not on the component, are a non-disclosing 404.
Example:
omniglass component alarm timeline <name> <id>omniglass component checkName
Section titled “omniglass component checkName”Check a component name
omniglass component checkName [flags]Reports whether a proposed name is a valid slug and currently free within the given placement (parent wins over location; neither means the unplaced/root bucket). Advisory (Save is still gated by the unique constraint). Gated by component:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--location | string | (none) | The location (by name or uuid) the entity would be placed at, if any and if unparented; ignored by the locations check |
--name | string | (none) | The proposed name to check |
--parent | string | (none) | The parent (by name or uuid) the entity would be created under, if any; omit for a root/unplaced check |
Example:
omniglass component checkName --name nameomniglass component command
Section titled “omniglass component command”Commands for the command resource
omniglass component command issue
Section titled “omniglass component command issue”Issue a command to a component
omniglass component command issue <name> [flags]Records a command invocation, writes a caused event, and (for a settleable command) opens an intended value the observed value settles against. Returns the computed settlement verdict. Gated by command:issue, whose scope is resolved on the component tier from that permission (not from component:read); a component outside the caller’s component:read is a non-disclosing 404, and one it can read but not command is a 403.
| Flag | Type | Default | Description |
|---|---|---|---|
--command-type | string | (none) | The command_type to invoke |
--instance | string | (none) | The series discriminator (e.g. an endpoint), when the target is instanced |
--params | string | (none) | The invocation params, stored on the command and the caused event |
--value | string | (none) | The intended value for the target property (a settleable command) |
Example:
omniglass component command issue <name> --command-type command_typeomniglass component create
Section titled “omniglass component create”Create a component
omniglass component create [flags]Creates a component, optionally under a parent (a root needs an all-scoped grant), bound to a system and a location, and classified by a product (required; naming a generic is fine until a real product is modeled). Gated by component:create. The location reference resolves within the caller’s location:read scope, because the label this stores is rendered from it, and one outside that scope is refused (422) exactly as :renderLabel refuses to preview it. Naming a system additionally requires system:update, and resolves within that scope, because the component’s primary membership is inserted from it: it is the same row the membership route writes, so the two paths cost the same permission. A system outside that scope is refused with a 403 naming it when the caller may read the system (denying its existence to someone who can GET it would be a lie) and with the non-disclosing 422 when the caller may not.
| Flag | Type | Default | Description |
|---|---|---|---|
--expected-name | string | (none) | The name a create form previewed (POST /components:renderLabel returns it). The create is refused with a 409 naming what it would produce instead, rather than silently landing a different name, if the number was taken or the type’s stem moved while the form was open. It does not name the row (the platform still does, and the row is still name_generated): it only asserts what that name will be. Applies only when the platform names the row: sending it beside a name is a 422. |
--label | string | (none) | What an operator reads; the name is the address |
--location | string | (none) | Location name this component is placed at |
--name | string | (none) | Name, unique within its placement (the address; lowercase letters, digits, hyphens). Omit to have the platform generate one from the product’s type. |
--parent | string | (none) | Parent component name; omit for a root component |
--product | string | (none) | Product (catalog SKU) this component is an instance of, by name or uuid. Required: use a generic (generic-device, generic-app, generic-service) until a real product is modeled. |
--system | string | (none) | Primary system name this component belongs to. Naming one writes that system’s membership, so it costs the system:update permission and resolves in that scope; omitted, the create costs component:create alone. |
Example:
omniglass component createomniglass component delete
Section titled “omniglass component delete”Delete a component
omniglass component delete <name>Deletes a component, refused (409) while it still has child components or is still referenced elsewhere, such as by a system role it staffs. Gated by component:delete; read and delete scopes drive the 404 versus 403 split.
Example:
omniglass component delete <name>omniglass component effective-secret
Section titled “omniglass component effective-secret”Commands for the effective-secret resource
omniglass component effective-secret list
Section titled “omniglass component effective-secret list”Effective secrets for a component
omniglass component effective-secret list <name>Resolves the secrets that cascade onto a component (platform -> location -> component), with the winner and the shadowed candidates it overrode. There is NO system band: a secret is device-facing, and the room a component happens to serve is the wrong owner for a credential the device itself answers with. Fields are masked, as in the directory; plaintext is only ever the audited reveal. Gated by secret:read, which the viewer floor does not carry, and admin-sensitive secrets appear only to the admin tier.
Example:
omniglass component effective-secret list <name>omniglass component effective-tag
Section titled “omniglass component effective-tag”Commands for the effective-tag resource
omniglass component effective-tag list
Section titled “omniglass component effective-tag list”Effective tags for a component
omniglass component effective-tag list <name> [flags]Resolves the tags that cascade onto a component (platform -> location -> system -> component): keys union, values override most-specific-wins, with the winner and shadowed candidates. A non-propagating key resolves only from a binding on the component itself. The system band comes from MEMBERSHIP: pass ?system= (a name or a uuid, ADR-0062) to resolve against one the component belongs to (a shared device answers differently for each), or omit it to resolve against its primary membership. Gated by component:read; the component must be in the caller’s component read scope.
| Flag | Type | Default | Description |
|---|---|---|---|
--system | string | (none) | Resolve against this system, name or uuid (ADR-0062), which the component must be a member of. Omit to resolve against its primary membership, the default for a caller with no system in hand. |
Example:
omniglass component effective-tag list <name>omniglass component effective-variable
Section titled “omniglass component effective-variable”Commands for the effective-variable resource
omniglass component effective-variable list
Section titled “omniglass component effective-variable list”Effective variables for a component
omniglass component effective-variable list <name>Resolves the variables that cascade onto a component (platform -> location -> system -> component): names union, values override most-specific-wins, with the winner and the shadowed candidates it overrode. The system band comes from the component’s PRIMARY membership; resolving against a named system is not offered here yet, unlike effective-tags. Gated by variable:read; the component must be in the caller’s component read scope.
Example:
omniglass component effective-variable list <name>omniglass component event
Section titled “omniglass component event”Commands for the event resource
omniglass component event list
Section titled “omniglass component event list”List a component’s recent events
omniglass component event list <name>Returns the component’s recent log occurrences (the log-kind sink), newest first, bounded to the last 24 hours. Gated by component:read; an out-of-scope component is a non-disclosing 404.
Example:
omniglass component event list <name>omniglass component get
Section titled “omniglass component get”Get a component
omniglass component get <name>Fetches a component by name within the caller’s read scope. Out of scope is a non-disclosing 404. Gated by component:read.
Example:
omniglass component get <name>omniglass component impairment
Section titled “omniglass component impairment”Commands for the impairment resource
omniglass component impairment get
Section titled “omniglass component impairment get”Get what is broken on a simulated device
omniglass component impairment get <name>The impairment an operator set on a simulated component (unplugged, or a degraded link), applied by the simulator beside its node when that simulator runs with impairments and NET_ADMIN. A healthy device reads all zero. Gated by simulation:read; the component resolves within the caller’s component read scope.
Example:
omniglass component impairment get <name>omniglass component impairment set
Section titled “omniglass component impairment set”Break or repair a simulated device
omniglass component impairment set <name> [flags]Sets what is broken on a simulated component: unplugged, or a link with added latency, jitter, loss or a rate limit. It replaces the whole impairment, so a field left out reads as zero (setting a latency on an unplugged device plugs it back in); an empty body repairs it. Returns the impairment as stored, loss rounded to hundredths. Audited. The simulator beside the component’s node applies it on its next pull. Gated by simulation:update, whose scope is resolved on the component tier; a component outside the caller’s component:read is a non-disclosing 404, and one it can read but not impair is a 403. Jitter above latency, or a value outside its range, is a 422.
| Flag | Type | Default | Description |
|---|---|---|---|
--jitter-ms | int | 0 | Variation on the delay, in milliseconds; at most the latency |
--latency-ms | int | 0 | Delay added to traffic toward the device, in milliseconds |
--loss-pct | float64 | 0 | Share of packets toward the device dropped, in percent, to hundredths |
--rate-kbit | int | 0 | Bandwidth limit on the device’s link, both ways, in kilobits per second; 0 is unlimited |
--unplugged | bool | false | Dark on every protocol: connects time out, datagrams and pings go unanswered |
Example:
omniglass component impairment set <name>omniglass component list
Section titled “omniglass component list”List components in scope
omniglass component listLists the components the caller may read, each filtered to its scope subtree. Gated by component:read.
Example:
omniglass component listomniglass component listTags
Section titled “omniglass component listTags”List tags on a component
omniglass component listTags <name>Lists the tags bound directly on a component (not the resolved cascade). Gated by component:read.
Example:
omniglass component listTags <name>omniglass component log
Section titled “omniglass component log”Commands for the log resource
omniglass component log list
Section titled “omniglass component log list”List a component’s recent log lines
omniglass component log list <name>Returns the component’s recent raw log lines (the ingest lane of ADR-0066, distinct from typed events), newest first, bounded to the last 24 hours. Gated by component:read; an out-of-scope component is a non-disclosing 404.
Example:
omniglass component log list <name>omniglass component membership
Section titled “omniglass component membership”Commands for the membership resource
omniglass component membership list
Section titled “omniglass component membership list”List the systems a component is in
omniglass component membership list <name>The systems this component is bound into, ordered by name. A component may belong to several: a rack DSP serving three rooms is a member of all three, and each of them depends on it. Exactly one membership may be marked primary, the default for a question asked without a system in hand. Gated by component:read; an out-of-scope component is a non-disclosing 404.
Example:
omniglass component membership list <name>omniglass component metric
Section titled “omniglass component metric”Commands for the metric resource
omniglass component metric list
Section titled “omniglass component metric list”List a component’s effective metrics
omniglass component metric list <name>Every metric the component’s product declares, resolved to the series’ latest observed or calculated sample or the contract default until one arrives (is_sampled marks a live series), plus any metric sampled directly on the component (from_contract false). Gated by component:read; an out-of-scope component is a non-disclosing 404.
Example:
omniglass component metric list <name>omniglass component metric sample
Section titled “omniglass component metric sample”Commands for the sample resource
omniglass component metric sample list
Section titled “omniglass component metric sample list”Read one metric series’ raw samples
omniglass component metric sample list <name> <metric> [flags]The samples behind the effective read’s latest value for one series, newest first, windowed (hours) and capped (limit, newest kept). Gated by component:read; an out-of-scope owner is a non-disclosing 404.
| Flag | Type | Default | Description |
|---|---|---|---|
--hours | int | 0 | The window in hours, counted back from now; 24 when unset |
--limit | int | 0 | The row cap, newest kept; 500 when unset |
Example:
omniglass component metric sample list <name> <metric>omniglass component move
Section titled “omniglass component move”Move a component
omniglass component move <name> [flags]Relocates and/or re-parents a component: at least one of location or parent is required (422 otherwise). Both follow the three-state convention (an omitted field is unchanged, an explicit empty string clears, a name sets). A reparent is cycle-guarded and scope-injected; clearing parent to root requires an all-scoped move grant, the same authorization a root create already requires. A separate act from update, and a separately grantable one (component:move), because a placement change is an authorization act, not a label edit: it moves a row out from under one grant’s subtree and under another’s. Recorded under its own audit verb, move, distinct from update. Does not recompute health: a component’s own verdict is purely its active alarms, unaffected by where it sits. A taken name at the destination is a 409. Gated by component:move; read and move scopes drive the 404 versus 403 split, and the destination location resolves within the caller’s location:read scope, because the move restamps the label from it: a destination outside that scope is refused (422).
| Flag | Type | Default | Description |
|---|---|---|---|
--location | string | (none) | Relocates the component to this location name. An empty string clears its placement. |
--parent | string | (none) | Re-parents the component within the component tree to this component name; cycle-guarded and scope-injected. An empty string makes it a root component (requires an all-scoped move grant). |
Example:
omniglass component move <name>omniglass component previewLabels
Section titled “omniglass component previewLabels”Preview a component label recompute
omniglass component previewLabelsLists exactly the rows a recompute would change, and leaves the fleet as it found it. Use it before :recomputeLabels to see the blast radius of a rule edit. Every generated label in the caller’s read and update scope is re-rendered from its current rules and compared with what is stored; a label an operator typed by hand is never a candidate. Bounded by the same two scopes the apply is, so it never lists a row the apply would then refuse to touch. A location preview also lists the components and systems placed at every location whose label would move, because those go stale the moment it does. Gated by component:update, the same permission the apply needs: a preview is half of an edit rather than a report, and an operator who cannot apply has no use for it.
Example:
omniglass component previewLabelsomniglass component property
Section titled “omniglass component property”Commands for the property resource
omniglass component property delete
Section titled “omniglass component property delete”Clear a property on a component
omniglass component property delete <name> <property>Removes the component’s declared value, so the property falls back to the product contract’s default (or leaves the effective read entirely when it was off-contract). Clearing a property the component never set is a 404. Gated by component:update; read and update scopes drive the 404 versus 403 split.
Example:
omniglass component property delete <name> <property>omniglass component property list
Section titled “omniglass component property list”List a component’s effective properties
omniglass component property list <name>Every property the component’s product declares, resolved to the component’s own value or the contract default (is_set marks the override), plus any property set directly on the component (from_contract false). Gated by component:read; an out-of-scope component is a non-disclosing 404.
Example:
omniglass component property list <name>omniglass component property sample
Section titled “omniglass component property sample”Commands for the sample resource
omniglass component property sample list
Section titled “omniglass component property sample list”Read one property series’ change history
omniglass component property sample list <name> <property> [flags]The change history behind the effective value for one property series, newest first, windowed (hours) and capped (limit, newest kept). Gated by component:read; an out-of-scope owner is a non-disclosing 404.
| Flag | Type | Default | Description |
|---|---|---|---|
--hours | int | 0 | The window in hours, counted back from now; 24 when unset |
--limit | int | 0 | The row cap, newest kept; 500 when unset |
Example:
omniglass component property sample list <name> <property>omniglass component property update
Section titled “omniglass component property update”Set a property on a component
omniglass component property update <name> <property> [flags]Declares a value for the property on this component, overriding the product contract’s default. Idempotent: the first set stores the value, a later set replaces it. The property need not be on the contract, but it must exist in the catalog (422 otherwise). Gated by component:update; read and update scopes drive the 404 versus 403 split.
| Flag | Type | Default | Description |
|---|---|---|---|
--value | string | (none) | The value to declare, shape given by the property’s data_type |
Example:
omniglass component property update <name> <property> --value <json>omniglass component reachability
Section titled “omniglass component reachability”Commands for the reachability resource
omniglass component reachability list
Section titled “omniglass component reachability list”Read a component’s per-endpoint reachability
omniglass component reachability list <name>Composes, per endpoint, the latest reachability verdict, the probe-layer signals that compose it, and the recent verdict transitions for the availability strip. Gated by component:read; an out-of-scope component is a non-disclosing 404.
Example:
omniglass component reachability list <name>omniglass component recomputeLabels
Section titled “omniglass component recomputeLabels”Recompute component labels
omniglass component recomputeLabelsApplies what :previewLabels describes, over the rows in the caller’s read and update scope, and returns exactly what it changed. Idempotent: a second call changes nothing. A label an operator typed by hand is left alone, and clearing that label by hand is how it is handed back to the platform. Recorded as ONE audit row for the operation, naming the rule tier and the affected count, rather than one row per changed entity. Gated by component:update.
Example:
omniglass component recomputeLabelsomniglass component reconciliation
Section titled “omniglass component reconciliation”Commands for the reconciliation resource
omniglass component reconciliation list
Section titled “omniglass component reconciliation list”Read a component’s property reconciliation (want/told/is)
omniglass component reconciliation list <name>Pivots, per declared property, the declared value (want, resolved live from the cascade), the intended value (told), and the observed value (is), with config-drift computed on read. Gated by component:read; an out-of-scope component is a non-disclosing 404.
Example:
omniglass component reconciliation list <name>omniglass component removeTag
Section titled “omniglass component removeTag”Remove a tag value from a component
omniglass component removeTag <name> [flags]Removes a key’s value from a component. Gated by component:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--key | string | (none) | The tag key to remove |
Example:
omniglass component removeTag <name> --key keyomniglass component rename
Section titled “omniglass component rename”Rename a component
omniglass component rename <name> [flags]Moves the component’s name, the address an operator types and every external reference stores. A separate act from an update, and a separately grantable one, because it breaks bookmarks, runbooks, and integration config outside this system; inside it nothing breaks, since every reference holds the uuid. A taken name is a 409, an illegal or uuid-shaped one a 422. Gated by component:rename; read and rename scopes drive the 404 versus 403 split.
| Flag | Type | Default | Description |
|---|---|---|---|
--name | string | (none) | The new name, unique within its placement (lowercase letters, digits, hyphens) |
Example:
omniglass component rename <name> --name nameomniglass component renderLabel
Section titled “omniglass component renderLabel”Draft the name and label a component create would store
omniglass component renderLabel [flags]Drafts the name and the label a component create would stamp, for the classification and placement a create form already holds, without creating anything. It allocates no ordinal, opens no write transaction and takes no advisory lock, which is what separates it from a preview that mints: the ordinal is READ (the lowest free number among the live siblings in the placement bucket) rather than allocated. That answer is provisional, so a form posts the NAME back as expected_name on the create and is refused (409) rather than silently renamed if another create takes the number or the type’s stem moves first. Omitting name drafts the name the platform would mint, and refuses (422) exactly where a nameless create would. Gated by component:create, the permission the create it precedes needs; the parent resolves within the caller’s component:create scope and the location ref within location:read, because the rendered string can carry that label. Naming a system additionally requires system:update and resolves within that scope, the same as the create, because the create binds that system’s membership: a preview is never served for a bind the create would refuse. Omitting parent is the parentless bucket, which a create refuses without an all-scoped grant, so the draft refuses it too (403): a form must not preview a bucket its create declines, and the previewed ordinal reports which names that bucket already holds.
| Flag | Type | Default | Description |
|---|---|---|---|
--location | string | (none) | The location this component will sit at, by name or uuid. Resolved within the caller’s location:read scope: a location out of scope is refused, never rendered. |
--name | string | (none) | The name the row will carry. Omit it to draft the name and label the platform would produce; supply it to draft the label an operator-named row would carry, which has no ordinal at all. |
--parent | string | (none) | The parent component, by name or uuid. Part of the placement bucket a generated name’s ordinal is read from, so a draft that omits it previews the wrong bucket. Resolved within the caller’s component:create scope, the same set the create resolves it in. |
--product | string | (none) | The product this component is an instance of, by name or uuid; the classification both a label rule and a generated name are resolved from |
--system | string | (none) | The system this component will belong to, by name or uuid. Naming it requires system:update, exactly as the create does, because the create inserts that system’s membership; it resolves within that scope, and system:read decides only whether the refusal may name the system. |
Example:
omniglass component renderLabel --product productomniglass component resetName
Section titled “omniglass component resetName”Regenerate a component’s name
omniglass component resetName <name>Hands the pen back to the platform: regenerates the name from the component’s current type and placement (the same ”
Example:
omniglass component resetName <name>omniglass component setTag
Section titled “omniglass component setTag”Set a tag value on a component
omniglass component setTag <name> [flags]Binds a value for a key on a component. The key must exist and apply to this entity kind. Setting a value is the ordinary entity write, gated by component:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--key | string | (none) | The tag key (must exist and apply to this kind) |
--value | string | (none) | The bound value |
Example:
omniglass component setTag <name> --key key --value valueomniglass component simulation
Section titled “omniglass component simulation”Commands for the simulation resource
omniglass component simulation fire
Section titled “omniglass component simulation fire”Fire an operation at a simulated component
omniglass component simulation fire <name> [flags]Asks the simulator beside the component’s node to run one operation against the simulated component, on one of its protocol surfaces: an HTTP call, a command line (SSH, Telnet, TCP) or an SNMP get, and returns its answer. The simulator answers from the component’s live state in process, as its listeners would, so a command’s change sticks and the collector sees it; an impairment does not stop it. Audited. Gated by simulation:update, resolved on the component tier. A component that is not simulated is a 409, a surface it does not serve a 422, and no simulator answering a 503.
| Flag | Type | Default | Description |
|---|---|---|---|
--body | string | (none) | HTTP: the request body |
--command | string | (none) | SSH, Telnet or TCP: the command line |
--method | string | (none) | HTTP: the method; GET when empty |
--oid | string | (none) | SNMP: the OID to get |
--path | string | (none) | HTTP: the request path |
--surface | string | (none) | The surface to fire on, by its name in the component’s surface list |
Example:
omniglass component simulation fire <name> --surface surfaceomniglass component simulation get
Section titled “omniglass component simulation get”Get a component’s simulation
omniglass component simulation get <name>Whether a component is simulated (it has an endpoint on a node and a product a simulator profile simulates) and, when it is, its node, address, live hits and impairment, the products its profile simulates, and its full API surface: every protocol surface, with its HTTP routes, commands and SNMP OIDs. A component that is not simulated reads simulated false. Gated by simulation:read; the component resolves within the caller’s component read scope.
Example:
omniglass component simulation get <name>omniglass component update
Section titled “omniglass component update”Update a component
omniglass component update <name> [flags]Patches a component’s label or product. The name is not patchable: renaming is the :rename custom method. Placement is not patchable either: relocating or re-parenting is the :move custom method, gated separately, because a placement change is an authorization act. Product is required, so it is unchanged when omitted and reclassified when named, but an explicit empty string is refused (422), not a clear. Gated by component:update; read and update scopes drive the 404 versus 403 split.
| Flag | Type | Default | Description |
|---|---|---|---|
--label | string | (none) | A new operator-facing label |
--product | string | (none) | Re-classifies the component to this product (catalog SKU), by name or uuid. Required once set: an empty string is refused (422), not a clear. Explicitly-set property values persist; the new product’s contract defaults follow. |
Example:
omniglass component update <name>omniglass component-type
Section titled “omniglass component-type”Commands for the component-type resource
omniglass component-type create
Section titled “omniglass component-type create”Create a component type
omniglass component-type create [flags]Creates a custom (non-official) component_type, optionally under a parent. Gated by component_type:create.
| Flag | Type | Default | Description |
|---|---|---|---|
--abbrev | string | (none) | A compact form of label; omit to inherit the parent’s |
--default-tags | string | (none) | Tags every instance of this type starts with |
--icon | string | (none) | A glyph key; omit to inherit the parent’s |
--label | string | (none) | What an operator reads in pickers and lists |
--label-rule | string | (none) | A Go text/template rendering the label of every instance of this type, over a closed map of that component’s facts (Name, Ordinal, TypeName, TypeAbbrev, Stem, ProductName, VendorName, LocationLabel, SystemTypeLabel) and the functions title, upper, lower, slug and words (words turns a kebab or snake name into the words in it, so {{title (words .Name)}} reads north-wing as North Wing). Omit to inherit the parent’s, then the global component rule. A template that does not parse is refused here, 422. |
--name | string | (none) | The globally unique name |
--parent-id | string | (none) | The parent component_type, by name or uuid; omit for a root type |
--stem | string | (none) | The auto-generated component name’s prefix; omit to inherit the parent’s. Lowercase letters, digits, and hyphens. |
Example:
omniglass component-type create --label label --name nameomniglass component-type delete
Section titled “omniglass component-type delete”Delete a component type
omniglass component-type delete <id>Deletes a custom component_type, refused if official (422, forked or not: a fork is an overlay, not ownership) or still a parent of another component_type (409). :restore is the only removal a shipped row admits, and it removes your fork, not the row. Gated by component_type:delete.
Example:
omniglass component-type delete displayomniglass component-type list
Section titled “omniglass component-type list”List component types
omniglass component-type listLists the component_type registry (the taxonomy a product is classified under: mic, camera, wireless-mic under mic), ordered alphabetically by label. Each row carries its parent link, so the console reconstructs the tree client-side. Gated by component_type:read.
Example:
omniglass component-type listomniglass component-type restore
Section titled “omniglass component-type restore”Restore a component type’s shipped values
omniglass component-type restore <id>Discards your fork of a shipped component_type, so reads return the values this release ships and later releases can improve them again. 409 when the row carries no fork of yours. Gated by component_type:update, the same permission that took the fork: restoring is undoing your own edit, not deleting a row.
Example:
omniglass component-type restore displayomniglass component-type update
Section titled “omniglass component-type update”Update a component type
omniglass component-type update <id> [flags]Patches a component_type’s label, stem, icon, abbrev, label_rule, or default_tags. A shipped (official) row is never written: the patch FORKS it, storing your version over the shipped one, and the response comes back with forked=true under the same id. :restore discards the fork. Gated by component_type:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--abbrev | string | (none) | A new compact form; an empty string clears it, so this type inherits the nearest ancestor’s again |
--default-tags | string | (none) | Replaces the default-tag set; omit to leave unchanged |
--icon | string | (none) | A new glyph key; an empty string clears it, so this type inherits the nearest ancestor’s again |
--label | string | (none) | A new operator-facing label |
--label-rule | string | (none) | A new label template; an empty string clears it, so instances fall back to the nearest ancestor’s rule and then the global component rule. Refused with 422 if it does not parse. |
--stem | string | (none) | A new name prefix (lowercase letters, digits, and hyphens); an empty string CLEARS it, so this type inherits the nearest ancestor’s again. A root type has no ancestor to inherit from and is refused (422). |
Example:
omniglass component-type update displayomniglass driver
Section titled “omniglass driver”Commands for the driver resource
omniglass driver create
Section titled “omniglass driver create”Create a driver
omniglass driver create [flags]Creates a custom (non-official) driver. Gated by driver:create.
| Flag | Type | Default | Description |
|---|---|---|---|
--label | string | (none) | What an operator reads in pickers and lists |
--name | string | (none) | The globally unique name; renameable |
--spec | string | (none) | The declarative spec body; validated against the catalogs, and a spec that fails validation refuses the write (422) |
--version | string | (none) | A free-form version string, e.g. 1.0.0 |
Example:
omniglass driver create --label label --name nameomniglass driver delete
Section titled “omniglass driver delete”Delete a driver
omniglass driver delete <id>Deletes a custom driver, refused if official (422). Gated by driver:delete.
Example:
omniglass driver delete snmp-genericomniglass driver get
Section titled “omniglass driver get”Get a driver
omniglass driver get <id>Fetches a driver by id. Gated by driver:read.
Example:
omniglass driver get snmp-genericomniglass driver list
Section titled “omniglass driver list”List drivers
omniglass driver listLists the driver registry, ordered alphabetically by label. Populates the driver picker on the product form. Gated by driver:read.
Example:
omniglass driver listomniglass driver update
Section titled “omniglass driver update”Update a driver
omniglass driver update <id> [flags]Patches a custom driver’s label or version. Official drivers are read-only (422). Gated by driver:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--label | string | (none) | A new operator-facing label |
--spec | string | (none) | A replacement spec body; validated like the create’s, refused with a 422 when it cannot be interpreted |
--version | string | (none) | A new version string, e.g. 1.0.1 |
Example:
omniglass driver update snmp-genericomniglass endpoint
Section titled “omniglass endpoint”Commands for the endpoint resource
omniglass endpoint create
Section titled “omniglass endpoint create”Create an endpoint
omniglass endpoint create [flags]Creates an endpoint owned by a component (or a server-hosted one, which needs an all-scoped grant), named by its transport; the optional label is the only identity string an operator types, and is where what the connection is FOR goes. The create scope cascades through the owning component. Gated by endpoint:create.
| Flag | Type | Default | Description |
|---|---|---|---|
--component | string | (none) | Owning component, by name or id; omit for a server-hosted endpoint (needs an all-scoped grant) |
--driver | string | (none) | Attach this driver (by name or id): the spec derives the transport and params, and the endpoint’s tasks derive from the spec’s functions |
--inputs | string | (none) | The inputs the driver’s spec declares (host, port, credentials as secret reference names); required ones must be supplied, defaults fill the rest |
--label | string | (none) | What an operator reads in lists (Control processor). Settable here because the name is derived from the transport, so it says how the device is reached and never what the connection is for |
--node | string | (none) | Node placement, by name or id |
--params | string | (none) | Address/target settings (jsonb); an attach derives them from the inputs instead |
--transport | string | (none) | A transport name from the code registry (GET /transports); the endpoint is named by it, unique within the component. Exactly one of transport (a bare probe endpoint) or driver (an attach) is set |
Example:
omniglass endpoint createomniglass endpoint delete
Section titled “omniglass endpoint delete”Delete an endpoint
omniglass endpoint delete <endpoint>Deletes an endpoint, refused while a task still references it. Gated by endpoint:delete; read and delete scopes (through the component) drive the 404 versus 403 split.
Example:
omniglass endpoint delete 'boi.17c.415a.$comp.display-1/https'omniglass endpoint get
Section titled “omniglass endpoint get”Get an endpoint
omniglass endpoint get <endpoint>Fetches an endpoint by its address (
Example:
omniglass endpoint get 'boi.17c.415a.$comp.display-1/https'omniglass endpoint list
Section titled “omniglass endpoint list”List endpoints in scope
omniglass endpoint listLists the endpoints whose owning component the caller may read (the component cascade). Gated by endpoint:read.
Example:
omniglass endpoint listomniglass endpoint retry
Section titled “omniglass endpoint retry”Retry an endpoint’s gated connections
omniglass endpoint retry <endpoint> [flags]Moves the endpoint’s retry counter, which is part of its connection fingerprint: a gate a refusal retrying cannot fix holds (a wrong credential, a changed host key or certificate, a reply its driver declares terminal) lifts, the node recycles the endpoint’s held session, and every connection to it is attempted again. Fixing the secret, the address, the transport, the tls mode or the driver’s login needs no retry: the change moves the fingerprint itself. An unrelated edit (a label) moves nothing. host_key names a key to trust, the one the endpoint’s transport pins (the offered key a key refusal names): an ssh host key, or a tls or https endpoint’s certificate public key, which such an endpoint also takes as certificate. It becomes the declared pin and recycles the session onto it whatever its state, an audited acceptance of the change. While the endpoint’s gate names an offered key, the key must be that key, so a trust confirmed against a refusal the record has since moved past is a 409 and changes nothing. Audited, a trusted key with the pin it replaced (old) and the pin it set (new). Gated by endpoint:retry; read and retry scopes (through the component) drive the 404 versus 403 split.
| Flag | Type | Default | Description |
|---|---|---|---|
--certificate | string | (none) | A tls or https endpoint only: the same as host_key, named for the certificate (the offered_key a certificate refusal names). It becomes the endpoint’s declared tls-certificate pin, held to the same rule (the exact offered key while a key refusal holds), and the session redials onto it. Omit to retry with the pin unchanged |
--host-key | string | (none) | The SHA256 fingerprint of a changed key the operator now trusts, the key the endpoint’s transport pins (the offered_key a key refusal names on the component’s reachability read): an ssh endpoint’s host key, which becomes its declared ssh-host-key, or a tls or https endpoint’s certificate public key, which becomes its declared tls-certificate. The session redials onto it. While a key refusal holds, it must be that exact offered key: any other is a 409 that changes nothing (the refusal on record is the node’s last word, so to trust a key the component presents since, retry without a key first). With no key refusal held it declares a pin ahead of time. Omit to retry with the pin unchanged |
Example:
omniglass endpoint retry 'boi.17c.415a.$comp.display-1/https'omniglass endpoint update
Section titled “omniglass endpoint update”Update an endpoint
omniglass endpoint update <endpoint> [flags]Patches an endpoint’s node placement, params, label, or (driver-attached) its connection inputs in place: the host, port and attached secret references, validated against the driver’s declared inputs, the endpoint’s tasks re-derived in the same transaction. A value the driver refuses is a 400 naming the field. An empty label clears it and the surface falls back to the derived name. Gated by endpoint:update; read and update scopes (through the component) drive the 404 versus 403 split.
| Flag | Type | Default | Description |
|---|---|---|---|
--inputs | string | (none) | A driver-attached endpoint’s inputs, edited in place (#1061): the host, the port, an attached secret’s reference name, any input the driver declares. Merged over the stored inputs and validated against the driver; a value it refuses is a 400 naming the input. Changing where a credential is sent needs the caller to be able to use that credential |
--label | string | (none) | A new label; an empty string clears it, and the surface falls back to the derived name. Omit to leave it alone |
--node | string | (none) | Reassign the node placement, by name or id |
--params | string | (none) | Replace the address/target settings (jsonb). On a driver-attached endpoint only the timeout is set here: its address derives from its host and port inputs |
--transport | string | (none) | The transport: a driver-attached endpoint takes only one its driver speaks |
Example:
omniglass endpoint update 'boi.17c.415a.$comp.display-1/https'omniglass event-rule
Section titled “omniglass event-rule”Commands for the event-rule resource
omniglass event-rule create
Section titled “omniglass event-rule create”Create an event rule
omniglass event-rule create [flags]Authors a rule whose condition starts on each component it watches when its sample key meets the fire criteria for the fire sustain, and ends when the clear criteria (or the negation of fire) holds for the clear sustain. It names the event type it writes when the condition starts (required) and, optionally, when it ends; with a severity it also raises an alarm while the condition holds, and without one it is informational. Criteria are expressions over the sample (value, key, instance, component.name, component.type) yielding true or false; a body may give {expr} or the short form {op, value}, and the answer is always {expr}. The key must be a registered property or metric, the criteria must compile against its lane (an unknown name or a result that is not a bool is a 422 naming the criteria, line and column), the event types registered and the severity, when given, a level that exists (else 422); a name already taken is a 409. Audited. Gated by rule:create, with an all-scope grant.
| Flag | Type | Default | Description |
|---|---|---|---|
--clear-criteria | string | (none) | The criteria that ends it: {expr} or {op, value}; absent clears on the negation of fire_criteria, !(fire) |
--clear-event-type | string | (none) | The event type the rule writes when its condition ends, by name (condition-ended is the generic one); absent, it writes none |
--clear-sustain | string | (none) | A Go duration; empty is 0s |
--description | string | (none) | What the rule watches for and why |
--enabled | bool | false | Defaults to true |
--fire-criteria | string | (none) | The criteria that starts the condition: {expr}, or the short form {op, value} |
--fire-event-type | string | (none) | The event type the rule writes when its condition starts, by name (condition-started is the generic one) |
--fire-sustain | string | (none) | A Go duration; empty is 0s |
--label | string | (none) | A human label; also the alarm message when message is empty |
--message | string | (none) | The alarm message; empty uses the label or the name |
--name | string | (none) | The rule’s name (lowercase kebab) |
--sample-key | string | (none) | The property or metric the rule reads |
--selector | string | (none) | The components the rule watches (component types and components); absent is every component |
--severity | string | (none) | The severity level the alarm is raised at, by name; absent or empty, the rule is informational and raises no alarm |
Example:
omniglass event-rule create --fire-criteria <json> --fire-event-type fire_event_type --name name --sample-key sample_keyomniglass event-rule delete
Section titled “omniglass event-rule delete”Delete an event rule
omniglass event-rule delete <name>Removes an operator rule; an official rule is read-only (409). Audited. Gated by rule:delete, with an all-scope grant.
Example:
omniglass event-rule delete <name>omniglass event-rule get
Section titled “omniglass event-rule get”Get an event rule
omniglass event-rule get <name>Returns one event rule by name, with its live state as counts over the components the caller may read. Gated by rule:read.
Example:
omniglass event-rule get <name>omniglass event-rule list
Section titled “omniglass event-rule list”List event rules
omniglass event-rule listLists the event rules, the authored config that raises alarms, each with its live state as counts (conditions_in_force, open_alarms, pending_streaks) read in the same query. Rules read like a registry: every rule is listed whatever the caller’s scope, while the counts cover only components the caller may read. Gated by rule:read.
Example:
omniglass event-rule listomniglass event-rule preview
Section titled “omniglass event-rule preview”Preview an event rule
omniglass event-rule preview [flags]Judges a candidate rule (sample key, selector, criteria) without writing anything, as the ingest would have with no sustains (the answer says they are ignored): over each series it selects on components the caller may read, from the state its newest deciding sample in the 7 days before the window set (state_unknown when there is none), through every sample in the last 24 hours that the ingest would have judged (a late sample older than one before it decides nothing). Answers the edges it would have written and the series it would hold in force now. Its reads are index probes per series, capped at row_cap window samples taken a whole series at a time: series_judged of series_total, and truncated when the cap stopped it. A selector naming a component the caller cannot read is the same 422 as one that does not exist. Criteria take {expr} or {op, value}; one that does not compile is a 422 naming the criteria, line and column. Gated by rule:read.
| Flag | Type | Default | Description |
|---|---|---|---|
--clear-criteria | string | (none) | The criteria it ends on; absent, the negation of fire_criteria |
--clear-sustain | string | (none) | Accepted and ignored, like fire_sustain |
--fire-criteria | string | (none) | The criteria its condition starts on: {expr}, or the short form {op, value} |
--fire-sustain | string | (none) | Accepted so a rule body previews as it is, and ignored: a preview judges each sample alone |
--sample-key | string | (none) | The property or metric the candidate rule reads |
--selector | string | (none) | The components it watches; absent or empty, every component |
Example:
omniglass event-rule preview --fire-criteria <json> --sample-key sample_keyomniglass event-rule rename
Section titled “omniglass event-rule rename”Rename an event rule
omniglass event-rule rename <name> [flags]Moves an operator rule’s name, the address an operator types. A separate act from an update, because it breaks bookmarks and integration config outside this system; inside it nothing breaks, since every reference holds the rule’s uuid (an alarm’s raised_by_rule_id and dedup key, a condition, a streak, an event’s derived_by_rule_id). Not a material change: no version bump, streaks keep running and conditions stay in force. An event keeps the name it was written under (derived_by_rule); the rule’s next events carry the new one. An official rule keeps its name (409), a taken name is a 409, an illegal or uuid-shaped one a 422. Returns the rule with its uuid. Audited. Gated by rule:update, with an all-scope grant.
| Flag | Type | Default | Description |
|---|---|---|---|
--name | string | (none) | The rule’s new name, unique among rules (lowercase letters, digits, hyphens) |
Example:
omniglass event-rule rename <name> --name nameomniglass event-rule state
Section titled “omniglass event-rule state”Commands for the state resource
omniglass event-rule state list
Section titled “omniglass event-rule state list”Get an event rule’s live state
omniglass event-rule state list <name>What a rule holds right now: the conditions it holds in force (one per component and instance, whether or not it raises an alarm), the alarms it raised that are still open, each on a component and instance, its streaks waiting out a sustain, and when it last judged an ingested sample. Only conditions, alarms and streaks on components the caller may read are listed. Gated by rule:read.
Example:
omniglass event-rule state list <name>omniglass event-rule update
Section titled “omniglass event-rule update”Update an event rule
omniglass event-rule update <name> [flags]Patches a rule (an absent field is unchanged), bumping its version; disabling it stops new opens. Criteria take {expr} or the short form {op, value}, compiled as on create (a 422 names the criteria, line and column). An empty severity makes the rule informational and an empty clear_event_type drops its clear event; the fire event type cannot be emptied (422). Official rules are read-only (409). Audited. Gated by rule:update, with an all-scope grant.
| Flag | Type | Default | Description |
|---|---|---|---|
--clear-criteria | string | (none) | The criteria that ends it: {expr} or {op, value}; absent clears on the negation of fire_criteria, !(fire) |
--clear-event-type | string | (none) | The event type the rule writes when its condition ends, by name; empty writes none |
--clear-negates | bool | false | Drop the clear criteria, so the rule clears on the negation of its fire criteria |
--clear-sustain | string | (none) | How long the clear criteria must hold, a Go duration; empty is 0s |
--description | string | (none) | What the rule watches for and why |
--enabled | bool | false | Whether the rule evaluates; defaults to true on create |
--fire-criteria | string | (none) | The criteria that starts the condition: {expr}, or the short form {op, value} |
--fire-event-type | string | (none) | The event type the rule writes when its condition starts, by name; it cannot be emptied |
--fire-sustain | string | (none) | How long the fire criteria must hold, a Go duration (e.g. 30s); empty is 0s |
--label | string | (none) | A human label; also the alarm message when message is empty |
--message | string | (none) | The alarm message; empty uses the label or the name |
--sample-key | string | (none) | The property or metric the rule reads |
--selector | string | (none) | Replace the components the rule watches; absent leaves them unchanged, and an empty selector watches every component |
--severity | string | (none) | The severity level the alarm is raised at, by name; empty makes the rule informational (no alarm) |
Example:
omniglass event-rule update <name>omniglass event-type
Section titled “omniglass event-type”Commands for the event-type resource
omniglass event-type create
Section titled “omniglass event-type create”Create an event type
omniglass event-type create [flags]Registers a custom event type (official=false). The name must be a single kebab token, e.g. call-started. Gated by event_type:create.
| Flag | Type | Default | Description |
|---|---|---|---|
--description | string | (none) | What the occurrence means |
--label | string | (none) | A human label |
--name | string | (none) | The event type name (lowercase kebab) |
--payload-schema | string | (none) | A JSON Schema fragment for the payload |
Example:
omniglass event-type create --name nameomniglass event-type delete
Section titled “omniglass event-type delete”Delete an event type
omniglass event-type delete <name>Removes a custom event type by name. Official event types are read-only (409), and so is a type still in use: one that recorded events or an event rule’s fire or clear event type names is a 409 until nothing names it. Gated by event_type:delete.
Example:
omniglass event-type delete <name>omniglass event-type get
Section titled “omniglass event-type get”Get an event type
omniglass event-type get <name>Returns one event type by name. Gated by event_type:read.
Example:
omniglass event-type get <name>omniglass event-type list
Section titled “omniglass event-type list”List event types
omniglass event-type listLists every registered event type (official and custom). The catalog is fleet-wide reference data. Gated by event_type:read.
Example:
omniglass event-type listomniglass event-type update
Section titled “omniglass event-type update”Update an event type
omniglass event-type update <name> [flags]Patches a custom event type’s label, description, or payload schema (a nil field is unchanged). The name is fixed at creation. Official event types are read-only. Gated by event_type:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--description | string | (none) | What the occurrence means |
--label | string | (none) | A human label |
--payload-schema | string | (none) | A JSON Schema fragment (replaces wholesale) |
Example:
omniglass event-type update <name>omniglass expression
Section titled “omniglass expression”Commands for the expression resource
omniglass expression validate
Section titled “omniglass expression validate”Validate an expression
omniglass expression validate [flags]Compiles an expression against a registered site’s environment and answers whether it compiles, with positioned diagnostics, and the site’s bindings, admitted builtins and run budget, all generated from the site’s declaration. For criteria a sample key is required, and types the value (a metric is a number; a property is text, or a bool for a bool property). For calc the key is the rule’s output key, typing the result, and the rule’s inputs (and owner_kind, component by default) give the bindings, each input’s alias bound to the list of its key’s type (a system also binds members, one record per member); an input that is unknown, or an alias that is not an identifier, is reserved or repeats, is a 422; a name the expression uses that no alias binds is a diagnostic carrying that name (unbound); the answer’s value_type so reveals a key’s lane and data type to a rule:read holder, as the rule list already does. Compiles without the engine’s program cache and stores and runs nothing. An unknown site, a missing or unknown key is a 422. Gated by rule:read.
| Flag | Type | Default | Description |
|---|---|---|---|
--inputs | string | (none) | For calc (required there), the rule’s inputs: each bound by its alias, typed by its key (by name or uuid) |
--key | string | (none) | The sample key that types the expression (required at both sites). For criteria, the key the rule reads: its lane and data type type the value (a metric is a number; a property is text, or a bool for a bool property). For calc, the rule’s output key: its type is the result the reduce must yield |
--owner-kind | string | (none) | For calc, what the rule derives on: each input binds by its alias as the list of its current values (one per instance on a component, every member’s on a system); a system also binds members, one record per role-bound member with value. |
--site | string | (none) | Where the expression is written: calc, a calc rule’s reduce; criteria, an event rule’s fire_criteria or clear_criteria |
--source | string | (none) | The expression |
Example:
omniglass expression validate --site site --source sourceomniglass file
Section titled “omniglass file”Commands for the file resource
omniglass file create
Section titled “omniglass file create”Create a file from an upload
omniglass file create [flags]Stores the uploaded bytes as a content-addressed blob (identical bytes dedup to one blob) and writes the file handle pointing at it. Gated by file:create; a sensitive file additionally needs the admin tier (file:create:admin).
| Flag | Type | Default | Description |
|---|---|---|---|
--content | string | (none) | The file bytes, base64-encoded |
--content-type | string | (none) | The MIME type used to serve the file |
--name | string | (none) | The file’s filename, which is already the label an operator reads (no path separators) |
--sensitive | bool | false | Admin-only visibility; defaults false. Setting true requires the admin tier |
Example:
omniglass file create --content content --content-type content_type --name nameomniglass file delete
Section titled “omniglass file delete”Delete a file
omniglass file delete <file>Removes a file handle. The underlying blob is left in place (garbage collection is a later slice). A sensitive file is a non-disclosing 404 without the admin tier. Gated by file:delete.
Example:
omniglass file delete codec-firmware-2.1.4.txtomniglass file download
Section titled “omniglass file download”Download a file’s bytes
omniglass file download <file>Returns a file’s bytes (base64-encoded) read from the blob it points at, the hash verified on read. A sensitive file is a non-disclosing 404 without the admin tier. Gated by file:read.
Example:
omniglass file download codec-firmware-2.1.4.txtomniglass file get
Section titled “omniglass file get”Get a file’s metadata
omniglass file get <file>Returns one file handle’s searchable metadata (no bytes). A sensitive file is a non-disclosing 404 without the admin tier. Gated by file:read.
Example:
omniglass file get codec-firmware-2.1.4.txtomniglass file list
Section titled “omniglass file list”List files
omniglass file listLists the file handles the caller may see (searchable metadata, no bytes). Sensitive files appear only to the admin tier. Gated by file:read.
Example:
omniglass file listomniglass healthz
Section titled “omniglass healthz”Liveness and database-reachability probe
omniglass healthzReports process health and the database leg, pinged through the Storage Gateway. Public: the liveness probe carries no operator data.
Example:
omniglass healthzomniglass location
Section titled “omniglass location”Commands for the location resource
omniglass location checkName
Section titled “omniglass location checkName”Check a location name
omniglass location checkName [flags]Reports whether a proposed name is a valid slug and currently free within the given placement (under the given parent, or among roots when no parent is given). Advisory (Save is still gated by the unique constraint). Gated by location:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--location | string | (none) | The location (by name or uuid) the entity would be placed at, if any and if unparented; ignored by the locations check |
--name | string | (none) | The proposed name to check |
--parent | string | (none) | The parent (by name or uuid) the entity would be created under, if any; omit for a root/unplaced check |
Example:
omniglass location checkName --name nameomniglass location create
Section titled “omniglass location create”Create a location
omniglass location create [flags]Creates a location, optionally under a parent (a root needs an all-scoped grant). Omit name and the platform generates one from the location_type’s name rule, taking the lowest free ordinal among the siblings in that placement; a type carrying no name rule refuses (422), since a building’s real name is not something the platform can know. Gated by location:create.
| Flag | Type | Default | Description |
|---|---|---|---|
--expected-name | string | (none) | The name a create form previewed (POST /locations:renderLabel returns it). The create is refused with a 409 naming what it would produce instead, rather than silently landing a different name, if the number was taken or the location_type’s name rule moved while the form was open. It does not name the row (the platform still does, and the row is still name_generated): it only asserts what that name will be. Applies only when the platform names the row: sending it beside a name is a 422. |
--label | string | (none) | What an operator reads; the name is the address |
--location-type | string | (none) | The location_type, by name or uuid (campus, building, …) |
--name | string | (none) | Name, unique within its placement (the address; lowercase letters, digits, hyphens). Omit to have the platform generate one from the location_type’s name rule. |
--parent | string | (none) | Parent location name; omit for a root location |
Example:
omniglass location create --location-type location_typeomniglass location delete
Section titled “omniglass location delete”Delete a location
omniglass location delete <name>Deletes a location, refused (409) while it still has child locations or is still referenced elsewhere. Gated by location:delete; read and delete scopes drive the 404 versus 403 split.
Example:
omniglass location delete <name>omniglass location get
Section titled “omniglass location get”Get a location
omniglass location get <name>Fetches a location by name within the caller’s read scope. Out of scope is a non-disclosing 404. Gated by location:read.
Example:
omniglass location get <name>omniglass location health
Section titled “omniglass location health”Commands for the health resource
omniglass location health list
Section titled “omniglass location health list”Read a location’s health
omniglass location health list <name>The location’s current verdict, worst-wins over every system placed anywhere beneath it, with those systems and their verdicts as the drill-down (the system health read names the role, which occupant is down, and the alarm). Transitions are the recorded edges over the last 30 days. Gated by location:read; an out-of-scope location is a non-disclosing 404.
Example:
omniglass location health list <name>omniglass location list
Section titled “omniglass location list”List locations in scope
omniglass location listLists the locations the caller may read, each filtered to its scope subtree. Gated by location:read.
Example:
omniglass location listomniglass location listTags
Section titled “omniglass location listTags”List tags on a location
omniglass location listTags <name>Lists the tags bound directly on a location (not the resolved cascade). Gated by location:read.
Example:
omniglass location listTags <name>omniglass location metric
Section titled “omniglass location metric”Commands for the metric resource
omniglass location metric list
Section titled “omniglass location metric list”List a location’s effective metrics
omniglass location metric list <name>Every metric the location’s type declares, resolved to the series’ latest observed or calculated sample or the contract default until one arrives (is_sampled marks a live series), plus any metric sampled directly on the location (from_contract false). Gated by location:read; an out-of-scope location is a non-disclosing 404.
Example:
omniglass location metric list <name>omniglass location move
Section titled “omniglass location move”Move a location
omniglass location move <name> [flags]Re-parents a location (a tree move): parent is required (422 if omitted), cycle-guarded, and placement-validated against the resolved location_type. Moving to root is not supported (422): MoveLocation gains no clear-to-root capability locations have never had. A separate act from update, and a separately grantable one (location:move), because a placement change is an authorization act, not a label edit. Recorded under its own audit verb, move, distinct from update. Does not recompute health. A taken name at the destination is a 409. A move can RENAME the location: a platform-generated name is scoped to its parent bucket, so a move that changes the parent re-mints the name and the ordinal under the new parent, from the same location_type name rule. A move that re-states the current parent leaves the name alone, and an operator-typed name is never touched. Gated by location:move; the read and move scopes drive the 404 versus 403 split.
| Flag | Type | Default | Description |
|---|---|---|---|
--parent | string | (none) | Re-parents the location (a tree move) to this location name; cycle-guarded and placement-validated. Moving to root is not supported. |
Example:
omniglass location move <name>omniglass location previewLabels
Section titled “omniglass location previewLabels”Preview a location label recompute
omniglass location previewLabelsLists exactly the rows a recompute would change, and leaves the fleet as it found it. Use it before :recomputeLabels to see the blast radius of a rule edit. Every generated label in the caller’s read and update scope is re-rendered from its current rules and compared with what is stored; a label an operator typed by hand is never a candidate. Bounded by the same two scopes the apply is, so it never lists a row the apply would then refuse to touch. A location preview also lists the components and systems placed at every location whose label would move, because those go stale the moment it does. Gated by location:update, the same permission the apply needs: a preview is half of an edit rather than a report, and an operator who cannot apply has no use for it.
Example:
omniglass location previewLabelsomniglass location property
Section titled “omniglass location property”Commands for the property resource
omniglass location property delete
Section titled “omniglass location property delete”Clear a property on a location
omniglass location property delete <name> <property>Removes the location’s declared value, so the property falls back to the location type contract’s default (or leaves the effective read entirely when it was off-contract). Clearing a property the location never set is a 404. Gated by location:update; read and update scopes drive the 404 versus 403 split.
Example:
omniglass location property delete <name> <property>omniglass location property list
Section titled “omniglass location property list”List a location’s effective properties
omniglass location property list <name>Every property the location’s type declares, resolved to the location’s own value or the contract default (is_set marks the override), plus any property set directly on the location (from_contract false). Gated by location:read; an out-of-scope location is a non-disclosing 404.
Example:
omniglass location property list <name>omniglass location property update
Section titled “omniglass location property update”Set a property on a location
omniglass location property update <name> <property> [flags]Declares a value for the property on this location, overriding the location type contract’s default. Idempotent: the first set stores the value, a later set replaces it. The property need not be on the contract, but it must exist in the catalog (422 otherwise). Gated by location:update; read and update scopes drive the 404 versus 403 split.
| Flag | Type | Default | Description |
|---|---|---|---|
--value | string | (none) | The value to declare, shape given by the property’s data_type |
Example:
omniglass location property update <name> <property> --value <json>omniglass location recomputeLabels
Section titled “omniglass location recomputeLabels”Recompute location labels
omniglass location recomputeLabelsApplies what :previewLabels describes, over the rows in the caller’s read and update scope, and returns exactly what it changed. Idempotent: a second call changes nothing. A label an operator typed by hand is left alone, and clearing that label by hand is how it is handed back to the platform. Recorded as ONE audit row for the operation, naming the rule tier and the affected count, rather than one row per changed entity. Gated by location:update.
Example:
omniglass location recomputeLabelsomniglass location removeTag
Section titled “omniglass location removeTag”Remove a tag value from a location
omniglass location removeTag <name> [flags]Removes a key’s value from a location. Gated by location:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--key | string | (none) | The tag key to remove |
Example:
omniglass location removeTag <name> --key keyomniglass location rename
Section titled “omniglass location rename”Rename a location
omniglass location rename <name> [flags]Moves the location’s name, the address an operator types and every external reference stores. A separate act from an update, and a separately grantable one, because it breaks bookmarks, runbooks, and integration config outside this system; inside it nothing breaks, since every reference holds the uuid. A taken name is a 409, an illegal or uuid-shaped one a 422. Gated by location:rename; the read and rename scopes drive the 404 versus 403 split.
| Flag | Type | Default | Description |
|---|---|---|---|
--name | string | (none) | The new name, unique within its placement (lowercase letters, digits, hyphens) |
Example:
omniglass location rename <name> --name nameomniglass location renderLabel
Section titled “omniglass location renderLabel”Draft the name and label a location create would store
omniglass location renderLabel [flags]The location tier of :renderLabel on components. Drafts the name and the label a location create would stamp, allocating nothing. A shipped fleet answers from the global location rule, which reads the location’s own name as words and titles it, so a location named north-wing drafts as North Wing; an empty label means no rule resolves at any tier, and the surface falls back to the name. Omitting name refuses (422) a location_type with no name rule, the same refusal a nameless create gives. Gated by location:create; the parent resolves within the caller’s location:create scope, because a location’s two placement buckets are under a parent or at the root and that is where the ordinal is read from. Omitting parent is the ROOT bucket, which a create refuses without an all-scoped grant, so the draft refuses it too (403) rather than reporting which names the fleet root already holds.
| Flag | Type | Default | Description |
|---|---|---|---|
--location-type | string | (none) | The location_type this location is classified by, by name or uuid |
--name | string | (none) | The name the row will carry. Omit it to draft the name and label the platform would produce, which a location_type with no name rule refuses; supply it to draft the label an operator-named location would carry. |
--parent | string | (none) | The parent location, by name or uuid. A location has two placement buckets, under a parent or at the root, and this is which one a generated name’s ordinal is read from. Resolved within the caller’s location:create scope. |
Example:
omniglass location renderLabel --location-type location_typeomniglass location resetName
Section titled “omniglass location resetName”Regenerate a location’s name
omniglass location resetName <name>Hands the pen back to the platform, the same verb components and systems carry: the name is re-minted from the location_type’s name rule and the lowest free ordinal in this placement, and name_generated goes back to true. A location_type carrying no name rule refuses (422), which is every type a shipped fleet has: only a positional kind of place, one whose number is an arbitrary disambiguator rather than a designation read off the signage (a parking deck, a rack row), has a name the platform can generate, and an operator declares such a type themselves. Gated by location:rename, the same token :rename uses.
Example:
omniglass location resetName <name>omniglass location setTag
Section titled “omniglass location setTag”Set a tag value on a location
omniglass location setTag <name> [flags]Binds a value for a key on a location. The key must exist and apply to this entity kind. Setting a value is the ordinary entity write, gated by location:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--key | string | (none) | The tag key (must exist and apply to this kind) |
--value | string | (none) | The bound value |
Example:
omniglass location setTag <name> --key key --value valueomniglass location update
Section titled “omniglass location update”Update a location
omniglass location update <name> [flags]Patches a location’s label or location_type. The name is not patchable: renaming is the :rename custom method. Placement is not patchable either: re-parenting is the :move custom method, gated separately, because a placement change is an authorization act. Changing the location_type of a location the PLATFORM named re-mints the name from the new type’s name rule, and is refused (422) when the new type carries none, which is every shipped type: :rename the location first to claim its name, then reclassify it. A location an operator named is never renamed by a reclassify. Gated by location:update; the read and update scopes drive the 404 versus 403 split.
| Flag | Type | Default | Description |
|---|---|---|---|
--label | string | (none) | A new operator-facing label |
--location-type | string | (none) | Re-types the location: a location_type, by name or uuid |
Example:
omniglass location update <name>omniglass location-type
Section titled “omniglass location-type”Commands for the location-type resource
omniglass location-type create
Section titled “omniglass location-type create”Create a location type
omniglass location-type create [flags]Creates a custom (non-official) location_type, optionally with the label_rule locations of that type get. An unparseable rule is a 422. Gated by location_type:create.
| Flag | Type | Default | Description |
|---|---|---|---|
--allowed-parent-types | string | (none) | location_type names and/or the reserved root sentinel this type may be placed under; empty means unconstrained |
--icon | string | (none) | A glyph key; the console falls back to map-pin when empty |
--label | string | (none) | What an operator reads in pickers and lists |
--label-rule | string | (none) | The label template locations of this type get, a Go text/template over the location data map; omit to fall back to the global rule. Refused (422) if it does not compile |
--name | string | (none) | The globally unique name (e.g. wing); “root” is reserved |
--name-rule | string | (none) | How the platform NAMES locations of this type; omit to have an operator name every one of them. Refused (422) if it cannot mint a legal name |
Example:
omniglass location-type create --label label --name nameomniglass location-type delete
Section titled “omniglass location-type delete”Delete a location type
omniglass location-type delete <id>Deletes a custom location_type, refused if official (422) or still referenced by a location (409). Gated by location_type:delete.
Example:
omniglass location-type delete roomomniglass location-type list
Section titled “omniglass location-type list”List location types
omniglass location-type listLists the location_type registry (the shape-definers a location is classified by), ordered alphabetically by label. Populates the type picker on the location form. Gated by location_type:read.
Example:
omniglass location-type listomniglass location-type metric
Section titled “omniglass location-type metric”Commands for the metric resource
omniglass location-type metric delete
Section titled “omniglass location-type metric delete”Withdraw a metric from a location type
omniglass location-type metric delete <id> <metric>Removes one line from a location type’s contract, a shipped (official) type’s included, since nothing seeds a contract line; locations of the type keep any samples the series already holds, now off-contract. A metric the type does not declare is a 404, and so is an unknown type. Gated by location_type:delete.
Example:
omniglass location-type metric delete room <metric>omniglass location-type metric list
Section titled “omniglass location-type metric list”List a location type’s declared metrics
omniglass location-type metric list <id>Lists the location type’s declared-metric contract (which metrics every location of the type carries), ordered by metric name, each with its optional default and required flag. Gated by location_type:read.
Example:
omniglass location-type metric list roomomniglass location-type metric update
Section titled “omniglass location-type metric update”Declare a metric on a location type
omniglass location-type metric update <id> <metric> [flags]Declares a catalog metric on a location type, or revises the declaration in place (the line is addressed by name, so the write is idempotent). A shipped (official) type’s contract is writable too: a contract line is a row in its own table and nothing seeds one, so every line is an operator’s. An unknown type is a 404 and a metric the catalog does not know is a 422. Gated by location_type:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--default-value | string | (none) | The contract default, validated against the metric’s data_type; omit for no default |
--required | bool | false | Whether every location of this type must carry the metric; defaults to false |
Example:
omniglass location-type metric update room <metric>omniglass location-type property
Section titled “omniglass location-type property”Commands for the property resource
omniglass location-type property delete
Section titled “omniglass location-type property delete”Withdraw a property from a location type
omniglass location-type property delete <id> <property>Removes one line from a location type’s contract, a shipped (official) type’s included, since nothing seeds a contract line; locations of the type keep any value they set for it, now off-contract. A property the type does not declare is a 404, and so is an unknown type. Gated by location_type:delete.
Example:
omniglass location-type property delete room <property>omniglass location-type property list
Section titled “omniglass location-type property list”List a location type’s declared properties
omniglass location-type property list <id>Lists the location type’s declared-property contract (what every location of the type exposes), ordered by property name, each with its optional default and required flag. Gated by location_type:read.
Example:
omniglass location-type property list roomomniglass location-type property update
Section titled “omniglass location-type property update”Declare a property on a location type
omniglass location-type property update <id> <property> [flags]Declares a catalog property on a location type, or revises the declaration in place (the line is addressed by name, so the write is idempotent). A shipped (official) type’s contract is writable too: a contract line is a row in its own table and nothing seeds one, so every line is an operator’s. An unknown type is a 404 and a property the catalog does not know is a 422. Gated by location_type:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--default-value | string | (none) | The contract default, validated against the property’s data_type; omit for no default |
--required | bool | false | Whether every location of this type must set the property; defaults to false |
Example:
omniglass location-type property update room <property>omniglass location-type restore
Section titled “omniglass location-type restore”Restore a location type’s shipped values
omniglass location-type restore <id>Discards your fork of a shipped location_type, so reads return the values this release ships, including a rule a later release WITHDREW. 409 when the row carries no fork of yours. Gated by location_type:update, the same permission that took the fork: restoring is undoing your own edit, not deleting a row.
Example:
omniglass location-type restore roomomniglass location-type update
Section titled “omniglass location-type update”Update a location type
omniglass location-type update <id> [flags]Patches a location_type’s label, icon, allowed parents, label_rule or name_rule. An unparseable label_rule (or a name_rule that cannot mint a legal name) is a 422 at rule-edit time, never a broken row at create time, and setting a label rule restamps nothing on its own: apply it with /locations:recomputeLabels after seeing the blast radius with :previewLabels. A shipped (official) row is never written: the patch FORKS it, storing your version over the shipped one, and the response comes back with forked=true under the same id. :restore discards the fork. Gated by location_type:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--allowed-parent-types | string | (none) | Replaces the allowed-parent set; omit to leave unchanged, [] to clear back to unconstrained |
--icon | string | (none) | A new glyph key; the console falls back to map-pin when empty |
--label | string | (none) | A new operator-facing label |
--label-rule | string | (none) | A new label template for locations of this type; omit to leave unchanged, "" to clear back to the global rule. Refused (422) if it does not compile. Editing it does not restamp anything: apply it with /locations:recomputeLabels, having seen the blast radius with :previewLabels |
--name-rule | string | (none) | A new name rule for locations of this type; omit to leave unchanged, or name name_rule in update_mask with no rule here to CLEAR it back to operator-named. Refused (422) if it cannot mint a legal name. Setting it renames nothing that already exists: it decides how the NEXT nameless create, :resetName, move or reclassify names a row |
--update-mask | string | (none) | Which fields this write changes (AIP-134). Omit it and the fields present in the body change and nothing else; name a field here and it is written even when the body leaves it empty, which is how a field is CLEARED (name_rule back to operator-named); send [”*”] for full replacement. A field this resource does not patch is a 422 naming it |
Example:
omniglass location-type update roomomniglass metric-type
Section titled “omniglass metric-type”Commands for the metric-type resource
omniglass metric-type create
Section titled “omniglass metric-type create”Create a metric type
omniglass metric-type create [flags]Registers a custom metric type (official=false). The name must be a valid metric key. Gated by metric_type:create.
| Flag | Type | Default | Description |
|---|---|---|---|
--data-type | string | (none) | The value type; a metric is always a number |
--description | string | (none) | What the series measures |
--label | string | (none) | A human label |
--name | string | (none) | The metric type name (lowercase kebab) |
--precision | int | 0 | Decimal places a rendered value keeps |
--unit | string | (none) | The display unit of the series (ms, dB, percent) |
Example:
omniglass metric-type create --data-type data_type --name nameomniglass metric-type delete
Section titled “omniglass metric-type delete”Delete a metric type
omniglass metric-type delete <name>Removes a custom metric type by name. Official metric types are read-only. A metric type a calc rule writes is a 409 naming the rule. Gated by metric_type:delete.
Example:
omniglass metric-type delete <name>omniglass metric-type get
Section titled “omniglass metric-type get”Get a metric type
omniglass metric-type get <name>Returns one metric type by name. Gated by metric_type:read.
Example:
omniglass metric-type get <name>omniglass metric-type list
Section titled “omniglass metric-type list”List metric types
omniglass metric-type listLists every registered metric type (official and custom). The catalog is fleet-wide reference data. Gated by metric_type:read.
Example:
omniglass metric-type listomniglass metric-type update
Section titled “omniglass metric-type update”Update a metric type
omniglass metric-type update <name> [flags]Patches a custom metric type’s label, description, unit, or precision (a nil field is unchanged). Data type is fixed at creation. Official metric types are read-only. Gated by metric_type:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--description | string | (none) | What the series measures |
--label | string | (none) | A human label |
--precision | int | 0 | Decimal places a rendered value keeps |
--unit | string | (none) | The display unit of the series |
Example:
omniglass metric-type update <name>omniglass migrate
Section titled “omniglass migrate”Apply embedded database migrations (dbmate)
omniglass migrateomniglass node
Section titled “omniglass node”Commands for the node resource
omniglass node claim
Section titled “omniglass node claim”Claim a node identity in exchange for its NATS credential
omniglass node claim [flags]The node-facing exchange: a node presents its enrollment token and receives its NATS credential (url, username, password). Public (the token is the authentication); an invalid token is a 401.
| Flag | Type | Default | Description |
|---|---|---|---|
--name | string | (none) | The node name the enrollment was minted for |
--token | string | (none) | The one-time enrollment token from node create, exchanged here for the node’s NATS credential |
Example:
omniglass node claim --name name --token tokenomniglass node create
Section titled “omniglass node create”Create a node
omniglass node create [flags]Registers an edge node server-side (day-one enrollment: create, then :enroll to mint its token). Gated by node:create.
| Flag | Type | Default | Description |
|---|---|---|---|
--description | string | (none) | Free-form operator notes about the node |
--label | string | (none) | Operator label; falls back to the name when empty |
--location | string | (none) | Optional location the node sits in, by name or id (descriptive placement, not scope) |
--name | string | (none) | Globally unique node name (lowercase letters, digits, and hyphens); it is also the node’s NATS subject token, which is why the rule forbids a dot |
Example:
omniglass node create --name nameomniglass node delete
Section titled “omniglass node delete”Delete a node
omniglass node delete <name>Decommissions a node: a hard delete that cascades its endpoints, their derived tasks, its node-owned tags and self-telemetry, and its enrollment credential. Component telemetry it collected is unaffected. Requires an all-scope action. Gated by node:delete.
Example:
omniglass node delete <name>omniglass node enroll
Section titled “omniglass node enroll”Mint a node’s enrollment token
omniglass node enroll <name>Mints (or re-mints) the node’s enrollment token and returns it once. The token is stored only as a hash; it is never logged. Gated by node:enroll.
Example:
omniglass node enroll <name>omniglass node get
Section titled “omniglass node get”Get a node
omniglass node get <name>Fetches a node by name. Requires an all-scope read. Gated by node:read.
Example:
omniglass node get <name>omniglass node list
Section titled “omniglass node list”List nodes
omniglass node listLists the edge nodes. A node is fleet-wide, so listing requires an all-scope read. Gated by node:read.
Example:
omniglass node listomniglass node listTags
Section titled “omniglass node listTags”List tags on a node
omniglass node listTags <name>Lists the tags bound directly on a node (not the resolved cascade). Gated by node:read.
Example:
omniglass node listTags <name>omniglass node log
Section titled “omniglass node log”Commands for the log resource
omniglass node log list
Section titled “omniglass node log list”List a node’s recent self-logs
omniglass node log list <name>Returns the node’s own recent operational log lines (the raw ingest lane of ADR-0066, owner-bound to the node), newest first, bounded to the last 24 hours. Gated by node:read; an out-of-scope node is a non-disclosing 404.
Example:
omniglass node log list <name>omniglass node removeTag
Section titled “omniglass node removeTag”Remove a tag value from a node
omniglass node removeTag <name> [flags]Removes a key’s value from a node. Gated by node:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--key | string | (none) | The tag key to remove |
Example:
omniglass node removeTag <name> --key keyomniglass node run
Section titled “omniglass node run”Run the edge node: claim, pull the worklist, and heartbeat over NATS
omniglass node run [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--heartbeat | duration | 30s | heartbeat interval |
--name | string | (none) | this node’s registered name (env OMNIGLASS_NODE_NAME) |
--once | bool | false | run a single claim + pull + heartbeat cycle and exit |
--server | string | (none) | Omniglass server base URL (env OMNIGLASS_SERVER) |
--token | string | (none) | enrollment token from POST /nodes/{name}:enroll (env OMNIGLASS_NODE_TOKEN) |
omniglass node setTag
Section titled “omniglass node setTag”Set a tag value on a node
omniglass node setTag <name> [flags]Binds a value for a key on a node. The key must exist and apply to this entity kind. Setting a value is the ordinary entity write, gated by node:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--key | string | (none) | The tag key (must exist and apply to this kind) |
--value | string | (none) | The bound value |
Example:
omniglass node setTag <name> --key key --value valueomniglass node simulation
Section titled “omniglass node simulation”Get a node’s simulator
omniglass node simulation <name>The devices a simulator beside the node serves (each component with an endpoint placed on the node, within the caller’s component read scope), joined to the hits the server has seen and the simulator’s capabilities. Hits are live and per server process, not stored. Requires an all-scope node read. Gated by node:read.
Example:
omniglass node simulation <name>omniglass node update
Section titled “omniglass node update”Update a node
omniglass node update <name> [flags]Patches a node’s label, description, and location (a nil field is unchanged; a location of "" clears it). The name is immutable. Requires an all-scope action. Gated by node:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--description | string | (none) | New free-form operator notes |
--label | string | (none) | A new operator-facing label |
--location | string | (none) | Set the node’s location by name or id, or "" to clear it |
Example:
omniglass node update <name>omniglass principal
Section titled “omniglass principal”Commands for the principal resource
omniglass principal archive
Section titled “omniglass principal archive”Archive a principal
omniglass principal archive <id>Soft-deletes a principal: it is hidden from the directory, can no longer authenticate, and its rows stay intact, reversibly (restore) until purged. Gated by principal:archive (all-scope). The last active owner cannot be archived.
Example:
omniglass principal archive <id>omniglass principal avatar
Section titled “omniglass principal avatar”Commands for the avatar resource
omniglass principal avatar list
Section titled “omniglass principal avatar list”Get a principal’s profile picture
omniglass principal avatar list <id>Returns the principal’s profile picture as a base64-encoded JPEG. Gated by principal:read:admin. A principal without a picture is a 404.
Example:
omniglass principal avatar list <id>omniglass principal create
Section titled “omniglass principal create”Create a human principal
omniglass principal create [flags]Creates a human principal with an optional initial password. Gated by principal:create (all-scope). The new principal holds no grants; assign roles separately.
| Flag | Type | Default | Description |
|---|---|---|---|
--email | string | (none) | Contact email for the account |
--label | string | (none) | What an operator reads in lists; falls back to the username |
--password | string | (none) | Optional initial password (at least 12 characters, not a common password, not containing the username); the user changes it after signing in |
--username | string | (none) | Unique sign-in name (lowercase letters, digits, and . _ -) |
Example:
omniglass principal create --username usernameomniglass principal disable
Section titled “omniglass principal disable”Disable a principal
omniglass principal disable <id>Soft-disables a principal so it can no longer authenticate; its audit trail is kept. Gated by principal:update (all-scope). The last active owner cannot be disabled.
Example:
omniglass principal disable <id>omniglass principal enable
Section titled “omniglass principal enable”Enable a principal
omniglass principal enable <id>Re-enables a disabled principal, restoring its ability to authenticate. Gated by principal:update (all-scope).
Example:
omniglass principal enable <id>omniglass principal get
Section titled “omniglass principal get”Get a principal
omniglass principal get <id>Fetches one principal by id with its profile and grants. Gated by principal:read:admin.
Example:
omniglass principal get <id>omniglass principal grant
Section titled “omniglass principal grant”Commands for the grant resource
omniglass principal grant create
Section titled “omniglass principal grant create”Grant a role to a principal
omniglass principal grant create <id> [flags]Assigns a role at a scope to a principal. Gated by principal_grant:create (all-scope). Refused (403) when the granted role’s capabilities exceed the granter’s own (no promoting anyone, including yourself, to a higher tier such as owner). A duplicate is 409, an unknown role or bad scope 422.
| Flag | Type | Default | Description |
|---|---|---|---|
--role | string | (none) | A role id (viewer, operator, admin, owner, or a custom role) |
--scope-id | string | (none) | The scope root, the location, system or component the scope kind names, by name, dotted address or uuid (stored as its uuid); omit for the all scope |
--scope-kind | string | (none) | The scope kind; ‘all’ confers the whole fleet (group-as-scope is unbuilt and not offered) |
--scope-op | string | (none) | How the scope root matches the tree: subtree (root + descendants, the default), subtree_excl_root (descendants only for update/delete, root kept for read/create), or self (the root row only). Moot for the all scope. |
Example:
omniglass principal grant create <id> --role role --scope-kind scope_kindomniglass principal grant delete
Section titled “omniglass principal grant delete”Revoke a grant
omniglass principal grant delete <id> <grantId>Removes one grant from a principal. Gated by principal_grant:delete (all-scope). The last owner grant cannot be revoked.
Example:
omniglass principal grant delete <id> <grantId>omniglass principal impersonate
Section titled “omniglass principal impersonate”Impersonate a principal (view-as or act-as)
omniglass principal impersonate <id> [flags]Mints a bounded, revocable token to view as (read-only) or act as (full) the target. Gated by principal:impersonate (all-scope). Refused on self, on an owner target (owners are un-impersonatable by anyone), when it would grant a capability the caller lacks (the escalation guard), or from within an existing impersonation.
| Flag | Type | Default | Description |
|---|---|---|---|
--duration-minutes | int | 0 | Session lifetime in minutes (default 30, max 1440) |
--mode | string | (none) | view_as is read-only; act_as is full, with mutations attributed to both the real actor and the impersonated principal |
Example:
omniglass principal impersonate <id> --mode modeomniglass principal list
Section titled “omniglass principal list”List principals
omniglass principal list [flags]Lists all principals (humans and service accounts) with their grants. Gated by principal:read:admin.
| Flag | Type | Default | Description |
|---|---|---|---|
--include-archived | bool | false | Include archived (soft-deleted) principals, hidden by default |
--kind | string | (none) | Optionally filter by principal kind |
Example:
omniglass principal listomniglass principal purge
Section titled “omniglass principal purge”Purge a principal
omniglass principal purge <id>Hard-deletes an archived principal and its owned rows (profile, credentials, grants, memberships); the audit trail is preserved. Irreversible. Gated by principal:purge:admin (admin-sensitive, all-scope), and the principal must be archived first.
Example:
omniglass principal purge <id>omniglass principal removeAvatar
Section titled “omniglass principal removeAvatar”Remove a principal’s profile picture
omniglass principal removeAvatar <id>Clears another human principal’s profile picture. Gated by principal:set-avatar (all-scope). Removing an absent picture is a no-op. Audited with the administrator as the actor.
Example:
omniglass principal removeAvatar <id>omniglass principal resetPassword
Section titled “omniglass principal resetPassword”Reset a principal’s password
omniglass principal resetPassword <id> [flags]Sets a new password for another human principal (an administrator action; the target’s current password is not required). Gated by principal:reset-password (all-scope). The new password must meet the password policy; a violation is a 422. Refused on yourself (change your own password from your profile, which verifies your current one), on an owner (owners cannot be reset by anyone), or when it would exceed the caller’s own capabilities (the takeover guard, shared with impersonation). The action is audited with the administrator as the actor.
| Flag | Type | Default | Description |
|---|---|---|---|
--password | string | (none) | The new password (at least 12 characters, not a common password, not containing the username) |
Example:
omniglass principal resetPassword <id> --password passwordomniglass principal restore
Section titled “omniglass principal restore”Restore a principal
omniglass principal restore <id>Reverses an archive: the account is restored to active and can authenticate again. Gated by principal:archive (all-scope).
Example:
omniglass principal restore <id>omniglass principal session
Section titled “omniglass principal session”Commands for the session resource
omniglass principal session list
Section titled “omniglass principal session list”List a principal’s sessions
omniglass principal session list <id>Lists another principal’s active bearer credentials (login sessions and API tokens) with their non-secret metadata, newest first, so an administrator can see where an account is signed in and revoke a session that should not be. Gated by principal:revoke-session (all-scope). The token secret is never returned, and current is always false (there is no “this request’s own session” when viewing another principal).
Example:
omniglass principal session list <id>omniglass principal session revoke
Section titled “omniglass principal session revoke”Revoke a principal’s session
omniglass principal session revoke <id> <sid>Revokes one of another principal’s sessions or tokens by id (an administrator action; the target is immediately signed out of that credential). Gated by principal:revoke-session (all-scope). Bounded to the target, so a credential id that is not theirs is a non-disclosing 404, never a cross-principal revoke. Refused (403) on an owner (an owner’s sessions cannot be revoked by anyone, the takeover guard shared with impersonation and password reset) or when it would exceed the caller’s own capabilities. Audited with the administrator as the actor.
Example:
omniglass principal session revoke <id> <sid>omniglass principal session revokeAll
Section titled “omniglass principal session revokeAll”Revoke all of a principal’s sessions or tokens
omniglass principal session revokeAll <id> [flags]Revokes every one of another principal’s web-login sessions, or every one of its CLI/API tokens (chosen by purpose), in a single administrator action, returning how many were ended. Gated by principal:revoke-session (all-scope). Bounded to the target and never crosses purpose (revoking sessions leaves tokens, and vice versa). Refused (403) on an owner (the takeover guard shared with impersonation and the password reset) or when it would exceed the caller’s own capabilities. Audited with the administrator as the actor.
| Flag | Type | Default | Description |
|---|---|---|---|
--purpose | string | (none) | Which credentials to revoke: all of the principal’s web-login sessions, or all its CLI/API tokens |
Example:
omniglass principal session revokeAll <id> --purpose purposeomniglass principal setAvatar
Section titled “omniglass principal setAvatar”Set a principal’s profile picture
omniglass principal setAvatar <id> [flags]Sets another human principal’s profile picture (an administrator action). Gated by principal:set-avatar (all-scope). The image (JPEG, PNG, or WebP, base64-encoded) is normalized server-side to a 256x256 JPEG; a bad or oversize image is a 422. Audited with the administrator as the actor.
| Flag | Type | Default | Description |
|---|---|---|---|
--image-base64 | string | (none) | The image (JPEG, PNG, or WebP), base64-encoded; normalized server-side to a 256x256 JPEG |
Example:
omniglass principal setAvatar <id> --image-base64 image_base64omniglass principal update
Section titled “omniglass principal update”Update a principal
omniglass principal update <id> [flags]Updates a human principal’s label, email, and username. Gated by principal:update (all-scope). A username is not an entity name and is patchable here rather than through a :rename method: it is the sign-in identifier, on its own rule, and nothing keys on it.
| Flag | Type | Default | Description |
|---|---|---|---|
--email | string | (none) | Email; empty clears it |
--label | string | (none) | Label; empty clears it |
--username | string | (none) | Sign-in name (lowercase letters, digits, and . _ -); renaming is safe |
Example:
omniglass principal update <id>omniglass principal-group
Section titled “omniglass principal-group”Commands for the principal-group resource
omniglass principal-group create
Section titled “omniglass principal-group create”Create a principal group
omniglass principal-group create [flags]Creates a principal group. Gated by principal_group:create (all-scope). A duplicate name is 409.
| Flag | Type | Default | Description |
|---|---|---|---|
--description | string | (none) | Free-form notes on what the group is for |
--label | string | (none) | What an operator reads in lists |
--name | string | (none) | Unique group name (lowercase letters, digits, and hyphens) |
Example:
omniglass principal-group create --name nameomniglass principal-group delete
Section titled “omniglass principal-group delete”Delete a principal group
omniglass principal-group delete <group>Removes a group and, by cascade, its memberships and grants. Gated by principal_group:delete (all-scope).
Example:
omniglass principal-group delete night-shiftomniglass principal-group get
Section titled “omniglass principal-group get”Get a principal group
omniglass principal-group get <group>One principal group, by name or uuid. Gated by principal_group:read:admin.
Example:
omniglass principal-group get night-shiftomniglass principal-group grant
Section titled “omniglass principal-group grant”Commands for the grant resource
omniglass principal-group grant create
Section titled “omniglass principal-group grant create”Grant a role to a group
omniglass principal-group grant create <group> [flags]Assigns a role at a scope to a group; its members inherit it. Gated by principal_grant:create (all-scope). Refused (403) when the granted role’s capabilities exceed the granter’s own, exactly as for a direct grant. A duplicate is 409.
| Flag | Type | Default | Description |
|---|---|---|---|
--role | string | (none) | A role id (viewer, operator, admin, owner, or a custom role) |
--scope-id | string | (none) | The scope root, the location, system or component the scope kind names, by name, dotted address or uuid (stored as its uuid); omit for the all scope |
--scope-kind | string | (none) | The scope kind; ‘all’ confers the whole fleet (group-as-scope is unbuilt and not offered) |
--scope-op | string | (none) | How the scope root matches the tree; moot for the all scope |
Example:
omniglass principal-group grant create night-shift --role role --scope-kind scope_kindomniglass principal-group grant delete
Section titled “omniglass principal-group grant delete”Revoke a group grant
omniglass principal-group grant delete <group> <grantId>Removes one grant from a group. Gated by principal_grant:delete (all-scope).
Example:
omniglass principal-group grant delete night-shift <grantId>omniglass principal-group grant list
Section titled “omniglass principal-group grant list”List a group’s grants
omniglass principal-group grant list <group>The role x scope grants a group confers on its members. Gated by principal_group:read:admin.
Example:
omniglass principal-group grant list night-shiftomniglass principal-group list
Section titled “omniglass principal-group list”List principal groups
omniglass principal-group listEvery principal group. Gated by principal_group:read:admin.
Example:
omniglass principal-group listomniglass principal-group member
Section titled “omniglass principal-group member”Commands for the member resource
omniglass principal-group member create
Section titled “omniglass principal-group member create”Add a member to a group
omniglass principal-group member create <group> [flags]Adds a principal to a group; its members inherit the group’s grants. Gated by principal_group:update (all-scope). Idempotent.
| Flag | Type | Default | Description |
|---|---|---|---|
--principal-id | string | (none) | The principal to add: a human’s username, a service account’s name, or its uuid |
Example:
omniglass principal-group member create night-shift --principal-id principal_idomniglass principal-group member delete
Section titled “omniglass principal-group member delete”Remove a member from a group
omniglass principal-group member delete <group> <principal>Removes a principal from a group; it stops inheriting the group’s grants. Gated by principal_group:update (all-scope).
Example:
omniglass principal-group member delete night-shift aliceomniglass principal-group member list
Section titled “omniglass principal-group member list”List a group’s members
omniglass principal-group member list <group>The principals in a group. Gated by principal_group:read:admin.
Example:
omniglass principal-group member list night-shiftomniglass principal-group rename
Section titled “omniglass principal-group rename”Rename a principal group
omniglass principal-group rename <group> [flags]Moves the group’s name. A separate act from an update, and a separately grantable one, because it breaks the references stored outside this system; inside it nothing breaks, since membership and grants both key on the group’s uuid. A taken name is a 409, an illegal or uuid-shaped one a 422. Gated by principal_group:rename (all-scope).
| Flag | Type | Default | Description |
|---|---|---|---|
--name | string | (none) | The new unique group name (lowercase letters, digits, hyphens) |
Example:
omniglass principal-group rename night-shift --name nameomniglass principal-group update
Section titled “omniglass principal-group update”Update a principal group
omniglass principal-group update <group> [flags]Updates a group’s presentational fields. The name is not patchable: renaming is the :rename custom method. Gated by principal_group:update (all-scope).
| Flag | Type | Default | Description |
|---|---|---|---|
--description | string | (none) | Description; empty clears it |
--label | string | (none) | Label; empty clears it |
Example:
omniglass principal-group update night-shiftomniglass product
Section titled “omniglass product”Commands for the product resource
omniglass product create
Section titled “omniglass product create”Create a product
omniglass product create [flags]Creates a custom (non-official) product, classified under a component_type. kind and component_type are both required; kind refuses vm (retired, folded into app). Gated by product:create.
| Flag | Type | Default | Description |
|---|---|---|---|
--component-type | string | (none) | The component_type this product is classified under (mic, camera, …), by name or uuid; every product must belong to one of the tree’s nodes. The generics (generic-device, generic-app, generic-service) fit anything not yet modeled more specifically. |
--driver-id | string | (none) | The driver that talks to it, by handle or uuid |
--icon | string | (none) | A product-level icon override; unset inherits the component_type’s icon |
--kind | string | (none) | What class of thing the product is. vm is retired (folded into app); required, no default, so every product states its class explicitly. |
--label | string | (none) | What an operator reads in pickers and lists |
--label-rule | string | (none) | A Go text/template rendering the label of every component of this product, over a closed map of that component’s facts (Name, Ordinal, TypeName, TypeAbbrev, Stem, ProductName, VendorName, LocationLabel, SystemTypeLabel) and the functions title, upper, lower, slug and words (words turns a kebab or snake name into the words in it, so {{title (words .Name)}} reads north-wing as North Wing). Omit to inherit the component_type chain’s rule, then the global component rule. A template that does not parse is refused here, 422. |
--name | string | (none) | The globally unique name; renameable |
--parent-product-id | string | (none) | The parent product, by handle or uuid |
--vendor-id | string | (none) | The vendor, by handle or uuid |
Example:
omniglass product create --component-type component_type --kind kind --label label --name nameomniglass product delete
Section titled “omniglass product delete”Delete a product
omniglass product delete <id>Deletes a custom product, refused if official (422) or still referenced by a component (409). Gated by product:delete.
Example:
omniglass product delete boreal-edge-55omniglass product get
Section titled “omniglass product get”Get a product
omniglass product get <id>Fetches a product by its name or its uuid. Either form resolves, so omniglass product get acme-soundbar and the uuid are interchangeable. Gated by product:read.
Example:
omniglass product get boreal-edge-55omniglass product list
Section titled “omniglass product list”List products
omniglass product listLists the product registry, ordered alphabetically by label. Each product carries its vendor, driver, kind, and component_type. Gated by product:read.
Example:
omniglass product listomniglass product metric
Section titled “omniglass product metric”Commands for the metric resource
omniglass product metric delete
Section titled “omniglass product metric delete”Withdraw a metric from a product
omniglass product metric delete <id> <metric>Removes one line from a custom product’s contract; instances keep any samples the series already holds, now off-contract. A metric the product does not declare is a 404, and an official product is read-only (422). Gated by product:delete.
Example:
omniglass product metric delete boreal-edge-55 <metric>omniglass product metric list
Section titled “omniglass product metric list”List a product’s declared metrics
omniglass product metric list <id>Lists the product’s declared-metric contract (which metrics every instance of the product carries), ordered by metric name, each with its optional default and required flag. Gated by product:read.
Example:
omniglass product metric list boreal-edge-55omniglass product metric update
Section titled “omniglass product metric update”Declare a metric on a product
omniglass product metric update <id> <metric> [flags]Declares a catalog metric on a custom product, or revises the declaration in place (the line is addressed by name, so the write is idempotent). Official products are read-only (422); an unknown product is a 404 and a metric the catalog does not know is a 422. Gated by product:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--default-value | string | (none) | The contract default, validated against the metric’s data_type; omit for no default |
--required | bool | false | Whether every instance of this product must carry the metric; defaults to false |
Example:
omniglass product metric update boreal-edge-55 <metric>omniglass product property
Section titled “omniglass product property”Commands for the property resource
omniglass product property delete
Section titled “omniglass product property delete”Withdraw a property from a product
omniglass product property delete <id> <property>Removes one line from a custom product’s contract; instances keep any value they set for it, now off-contract. A property the product does not declare is a 404, and an official product is read-only (422). Gated by product:delete.
Example:
omniglass product property delete boreal-edge-55 <property>omniglass product property list
Section titled “omniglass product property list”List a product’s declared properties
omniglass product property list <id>Lists the product’s declared-property contract (what every instance of the product exposes), ordered by property name, each with its optional default and required flag. Gated by product:read.
Example:
omniglass product property list boreal-edge-55omniglass product property update
Section titled “omniglass product property update”Declare a property on a product
omniglass product property update <id> <property> [flags]Declares a catalog property on a custom product, or revises the declaration in place (the line is addressed by name, so the write is idempotent). Official products are read-only (422); an unknown product is a 404 and a property the catalog does not know is a 422. Gated by product:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--default-value | string | (none) | The contract default, validated against the property’s data_type; omit for no default |
--required | bool | false | Whether every instance of this product must set the property; defaults to false |
Example:
omniglass product property update boreal-edge-55 <property>omniglass product update
Section titled “omniglass product update”Update a product
omniglass product update <id> [flags]Patches a custom product’s label, vendor, driver, kind, component_type, icon, or parent. component_type is required, so an empty string on it is a 422 (a reclassify names a real type; it never clears). Official products are read-only (422). Gated by product:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--component-type | string | (none) | Reclassifies the product to this component_type, by name or uuid; component_type is required, so this only reclassifies, it never clears |
--driver-id | string | (none) | A new driver, by handle or uuid |
--icon | string | (none) | A new icon override |
--kind | string | (none) | A new product class |
--label | string | (none) | A new operator-facing label |
--label-rule | string | (none) | A new label template; an empty string clears it, so components fall back to the component_type chain and then the global component rule. Refused with 422 if it does not parse. |
--parent-product-id | string | (none) | A new parent product, by handle or uuid |
--vendor-id | string | (none) | A new vendor, by handle or uuid |
Example:
omniglass product update boreal-edge-55omniglass property-type
Section titled “omniglass property-type”Commands for the property-type resource
omniglass property-type create
Section titled “omniglass property-type create”Create a property
omniglass property-type create [flags]Registers a custom property (official=false). The name must be a valid property key. Gated by property_type:create.
| Flag | Type | Default | Description |
|---|---|---|---|
--data-type | string | (none) | The value type; a numeric signal is a metric type |
--description | string | (none) | What the property means |
--label | string | (none) | A human label |
--name | string | (none) | The property name (lowercase kebab) |
--validation | string | (none) | A JSON Schema fragment constraining the value |
Example:
omniglass property-type create --data-type data_type --name nameomniglass property-type delete
Section titled “omniglass property-type delete”Delete a property
omniglass property-type delete <name>Removes a custom property by name. Official properties are read-only. A property a calc rule writes is a 409 naming the rule. Gated by property_type:delete.
Example:
omniglass property-type delete <name>omniglass property-type get
Section titled “omniglass property-type get”Get a property
omniglass property-type get <name>Returns one property by name. Gated by property_type:read.
Example:
omniglass property-type get <name>omniglass property-type list
Section titled “omniglass property-type list”List properties
omniglass property-type listLists every registered property (official and custom). The catalog is fleet-wide reference data. Gated by property_type:read.
Example:
omniglass property-type listomniglass property-type update
Section titled “omniglass property-type update”Update a property
omniglass property-type update <name> [flags]Patches a custom property’s label, description, or validation (a nil field is unchanged). Data type is fixed at creation. Official properties are read-only. Gated by property_type:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--description | string | (none) | What the property means |
--label | string | (none) | A human label |
--validation | string | (none) | A JSON Schema fragment (replaces wholesale) |
Example:
omniglass property-type update <name>omniglass role
Section titled “omniglass role”Commands for the role resource
omniglass role list
Section titled “omniglass role list”List roles
omniglass role listLists the roles with their metadata and effective (flattened) permissions. Gated by the role:read:admin capability.
Example:
omniglass role listomniglass secret
Section titled “omniglass secret”Commands for the secret resource
omniglass secret copy
Section titled “omniglass secret copy”Decrypt a secret for clipboard copy
omniglass secret copy <secret>Decrypts and returns a secret’s field values for a clipboard copy, audited under the copy verb (distinct from an on-screen reveal). Same exposure and the same secret:reveal gate as reveal.
Example:
omniglass secret copy demo-panel-loginomniglass secret create
Section titled “omniglass secret create”Create a secret
omniglass secret create [flags]Seals a secret at an owner scope. Fields are validated and encrypted against the type shape. Gated by secret:create, plus platform:create when owner_kind is platform (the install-wide tier).
| Flag | Type | Default | Description |
|---|---|---|---|
--admin-sensitive | bool | false | Admin-only visibility; omit to use the type default. Setting true requires the admin tier |
--fields | string | (none) | The operator field map, validated against the type shape |
--label | string | (none) | What an operator reads in lists and pickers (Polling community); omit to fall back to the name |
--name | string | (none) | The cascade name (lowercase letters, digits, and hyphens); unique per owner |
--owner | string | (none) | The owning entity’s name; omit for a platform secret |
--owner-kind | string | (none) | Which tier owns this secret (the system band is retired, ADR-0052) |
--secret-type | string | (none) | A secret_type id |
Example:
omniglass secret create --fields <json> --name name --owner-kind owner_kind --secret-type secret_typeomniglass secret delete
Section titled “omniglass secret delete”Delete a secret
omniglass secret delete <secret>Removes a secret, by name or uuid. Gated by secret:delete, plus platform:delete when the secret sits at the platform tier; read and delete scopes on the owner drive the 404 versus 403 split.
Example:
omniglass secret delete demo-panel-loginomniglass secret list
Section titled “omniglass secret list”List secrets
omniglass secret listLists the secrets the caller may see, with masked fields, filtered to the read scope; admin-sensitive secrets appear only to the admin tier. Gated by secret:read, which the viewer floor does not carry (secret is a sensitive resource).
Example:
omniglass secret listomniglass secret reveal
Section titled “omniglass secret reveal”Reveal a secret’s plaintext
omniglass secret reveal <secret>Decrypts and returns a secret’s field values, auditing the decrypt. Gated by secret:reveal at the caller’s scope; an admin-sensitive secret additionally needs the admin tier (secret:reveal:admin), so a scoped operator reveals device secrets but never a platform credential.
Example:
omniglass secret reveal demo-panel-loginomniglass secret update
Section titled “omniglass secret update”Update a secret
omniglass secret update <secret> [flags]Replaces the given field values on a secret, re-sealing secret fields, and patches its label. Only those change; name, type, and owner are fixed at creation. An omitted field keeps its value, an omitted label leaves it alone, and an empty label clears it. Gated by secret:update, plus platform:update when the secret sits at the platform tier.
| Flag | Type | Default | Description |
|---|---|---|---|
--fields | string | (none) | The field values to replace; an omitted field keeps its value |
--label | string | (none) | A new label; an empty string clears it, and the surface falls back to the name. Omit to leave it alone |
Example:
omniglass secret update demo-panel-loginomniglass secret-type
Section titled “omniglass secret-type”Commands for the secret-type resource
omniglass secret-type list
Section titled “omniglass secret-type list”List secret types
omniglass secret-type listLists the secret_type shapes a secret can take, for the create form. Gated by secret:read.
Example:
omniglass secret-type listomniglass seed-dev
Section titled “omniglass seed-dev”Seed a dev database with example locations, users, and grants (idempotent; never for production)
omniglass seed-dev [flags]Populate a fresh dev database with a small example fleet so make dev comes up with locations, sign-in-able users, and their grants instead of empty. The same trusted direct-DB lane as bootstrap, and idempotent, so it runs on every make dev. Not for production: these are operator rows, not ship-with reference data.
—scenario picks the fleet:
dev the example fleet make dev comes up with
empty nothing beyond the boot seed: a fresh install’s first run
degraded the example fleet with an open alarm on one in every 3 components
large the example fleet plus its self-contained rooms copied 6 times under each of 5 replica sites (only the example fleet is simulated)
| Flag | Type | Default | Description |
|---|---|---|---|
--scenario | string | dev | the fleet to seed (see the list above) |
--sim-fleet | bool | true | wire the simulated fleet: addresses and endpoints on the dev node for every example-fleet component the simulator serves, never a scenario’s copies or a hand-added device (make dev-sim collects from them) |
--sim-port-offset | int | 10000 | the lift the simulator applies to ports below 1024, which the simulated fleet’s endpoints target: the default for make dev-sim’s unprivileged simulator, 0 for one that binds the real ports (in a container) |
omniglass server
Section titled “omniglass server”Run the control-plane server (HTTP API)
omniglass serverRuns the control plane: applies pending migrations and the boot seed, then serves the HTTP API on OMNIGLASS_ADDR and hosts the embedded NATS bus nodes connect to on OMNIGLASS_NATS_ADDR. Either address may name port 0, which binds whatever free port the kernel hands out; set OMNIGLASS_READY_FILE to a path and, once both listeners are bound, the server writes the addresses it got there as JSON (addr, nats_addr, and the nats_url it advertises to nodes). A file already at that path is cleared first thing at boot, and the server removes its own at a graceful shutdown (SIGINT or SIGTERM). A supervisor or a test reads the ports from that file rather than picking one and hoping it stays free. Configured by environment; see the deployment guides.
omniglass session
Section titled “omniglass session”Commands for the session resource
omniglass session list
Section titled “omniglass session list”List your own sessions and tokens
omniglass session listLists the caller’s own active bearer credentials (time-bounded web-login sessions and CLI/API tokens) with their non-secret metadata; the current one is flagged. Requires authentication; self-scoped (never another principal’s). The token secret is never returned.
Example:
omniglass session listomniglass session revoke
Section titled “omniglass session revoke”Revoke one of your own sessions
omniglass session revoke <id>Revokes one of the caller’s own sessions or tokens by id (from the session list); revoking the current one signs it out. Requires authentication; self-scoped, so a credential id that is not yours is a 404.
Example:
omniglass session revoke <id>omniglass session revoke-all
Section titled “omniglass session revoke-all”Revoke all of your own sessions or tokens
omniglass session revoke-all [flags]Revokes every one of the caller’s own web-login sessions, or every one of its CLI/API tokens (chosen by purpose), returning how many were ended. Requires authentication; self-scoped. Always keeps the credential that made this request, so you are never signed out of the one you are on; sessions and tokens never cross.
| Flag | Type | Default | Description |
|---|---|---|---|
--purpose | string | (none) | Which of your own credentials to revoke: all your web-login sessions, or all your CLI/API tokens |
Example:
omniglass session revoke-all --purpose purposeomniglass set-password
Section titled “omniglass set-password”Set or rotate a user’s console password, revoking their sessions (direct DB)
omniglass set-password <username> <password> [flags]Installs or replaces a human’s password credential (argon2id), addressed by username, and revokes the user’s live SESSIONS so a break-glass reset locks out any stolen login at once. API tokens are a separate bearer secret, not tied to the password, and are kept unless —revoke-tokens is given (a full lockout of a compromised account). The same trusted direct-DB lane as bootstrap and token: dev setup, break-glass, or a password reset before the admin UI lands.
| Flag | Type | Default | Description |
|---|---|---|---|
--revoke-tokens | bool | false | also revoke the user’s API tokens (a full lockout of a compromised account) |
omniglass setting
Section titled “omniglass setting”Commands for the setting resource
omniglass setting delete
Section titled “omniglass setting delete”Restore a settings namespace to defaults
omniglass setting delete <namespace>Drops the namespace’s platform override, restoring the file layer and the declared defaults. Gated by settings:update and platform:update.
Example:
omniglass setting delete <namespace>omniglass setting list
Section titled “omniglass setting list”Get effective settings with provenance
omniglass setting listThe effective settings document plus per-key provenance (which level won) and lock state. Gated by settings:read (admin).
Example:
omniglass setting listomniglass setting me
Section titled “omniglass setting me”Commands for the me resource
omniglass setting me list
Section titled “omniglass setting me list”Get the caller’s effective settings
omniglass setting me listThe current principal’s resolved settings, client-visible namespaces only, no provenance. Feeds the SPA at boot. Requires authentication.
Example:
omniglass setting me listomniglass setting restoreDefaults
Section titled “omniglass setting restoreDefaults”Restore all settings to defaults
omniglass setting restoreDefaultsRemoves every platform override (a factory reset). Gated by settings:update and platform:update.
Example:
omniglass setting restoreDefaultsomniglass setting update
Section titled “omniglass setting update”Update a settings namespace
omniglass setting update <namespace>Applies an RFC 7386 JSON Merge Patch to the namespace’s platform override; null on a key restores it. Gated by settings:update and platform:update.
Example:
omniglass setting update <namespace>omniglass severity-level
Section titled “omniglass severity-level”Commands for the severity-level resource
omniglass severity-level create
Section titled “omniglass severity-level create”Create a severity level
omniglass severity-level create [flags]Adds an operator severity level at a rank of its own, between two others without renumbering. A name or rank already taken is a 409; a color outside the palette is a 422. Audited. Gated by severity_level:create, with an all-scope grant: a level’s rank moves health fleet-wide.
| Flag | Type | Default | Description |
|---|---|---|---|
--color | string | (none) | One of gray, blue, green, yellow, orange, red, darkred |
--label | string | (none) | A human label |
--name | string | (none) | The level’s name (lowercase kebab) |
--rank | int | 0 | Its place among the levels: higher is more severe; unique |
Example:
omniglass severity-level create --color color --name name --rank <int>omniglass severity-level delete
Section titled “omniglass severity-level delete”Delete a severity level
omniglass severity-level delete <name>Removes an operator level no alarm or event rule names; an official level or one in use is a 409. Audited. Gated by severity_level:delete, with an all-scope grant.
Example:
omniglass severity-level delete <name>omniglass severity-level get
Section titled “omniglass severity-level get”Get a severity level
omniglass severity-level get <name>Returns one severity level by name. Gated by severity_level:read.
Example:
omniglass severity-level get <name>omniglass severity-level list
Section titled “omniglass severity-level list”List severity levels
omniglass severity-level listLists the severity levels, least to most severe, each with whether an active alarm at it puts a component in outage. Gated by severity_level:read.
Example:
omniglass severity-level listomniglass severity-level update
Section titled “omniglass severity-level update”Update a severity level
omniglass severity-level update <name> [flags]Patches an operator level’s name, label, color or rank (an absent field is unchanged); a rename carries every alarm at the level with it. Official levels are read-only (409). Audited. Gated by severity_level:update, with an all-scope grant.
| Flag | Type | Default | Description |
|---|---|---|---|
--color | string | (none) | One of gray, blue, green, yellow, orange, red, darkred |
--label | string | (none) | A human label |
--name | string | (none) | A new name; every alarm at this level follows |
--rank | int | 0 | Its place among the levels; unique |
Example:
omniglass severity-level update <name>omniglass sim
Section titled “omniglass sim”Simulate the devices placed on a node
omniglass sim run
Section titled “omniglass sim run”Serve the node’s simulated devices and follow changes until interrupted
omniglass sim run [flags]Serves each component placed on the node whose product has a simulator profile and whose endpoints target a loopback address, on that address, and reports every request it answers to the server. Re-pulls the device list on an interval, so devices added or removed on the server start or stop without a restart.
| Flag | Type | Default | Description |
|---|---|---|---|
--impairments | bool | false | apply impairments (unplug, latency, loss) and truthful ping by rewriting the firewall and traffic shaping of this network namespace; needs NET_ADMIN, and is meant for a namespace of the simulator’s own (a pod or container) |
--name | string | (none) | the node this simulator runs beside (env OMNIGLASS_NODE_NAME) |
--poll | duration | 10s | how often to re-pull the device list |
--port-offset | int | 0 | lift the simulated ports below 1024 by this much, to serve without the privilege to bind them |
--server | string | (none) | Omniglass server base URL (env OMNIGLASS_SERVER) |
--token | string | (none) | that node’s enrollment token (env OMNIGLASS_NODE_TOKEN) |
omniglass simulation
Section titled “omniglass simulation”Commands for the simulation resource
omniglass simulation add-component
Section titled “omniglass simulation add-component”Add a simulated component
omniglass simulation add-component <name> [flags]Creates a component of a simulated product, at the lowest free address in the simulated block (127.60.0.0/16), with the endpoint the collector reaches it through placed on the node: a driver attach where the driver’s inputs are known (an SNMP attach needs the sim-community secret, else it falls back), otherwise a reachability probe on a port the profile serves, lifted as the node’s simulator lifts its ports. The simulator serves it from its next pull, with no restart. Gated by simulation:update, and also needs component:create and endpoint:create, each in the caller’s own scope. A node with no simulator connected is a 409, and a product no profile simulates a 422.
| Flag | Type | Default | Description |
|---|---|---|---|
--location | string | (none) | Where the component sits, by name or dotted path |
--name | string | (none) | The new component’s name |
--product | string | (none) | A product a simulator profile simulates |
Example:
omniglass simulation add-component <name> --name name --product productomniglass simulation add-system
Section titled “omniglass simulation add-system”Add a simulated system
omniglass simulation add-system <name> [flags]Creates a system built to a standard, with a simulated component for each staffed role in the standard’s plan (see plan-simulation-system), each at its own free address in the simulated block with its endpoint placed on the node, and assigned its role, all in one transaction: it lands whole or not at all. Component names are minted as an unnamed create mints them; roles nothing simulated fits are left short and listed. The simulator serves the components from its next pull. Gated by simulation:update, and also needs system:create, system:update, system:read, component:create, endpoint:create and node:read (and location:read when it names a place), each in the caller’s own scope; the components are created without a parent, so component:create must be all-scope. A refused piece is mapped as its own route maps it (a component refused is a 403). A node with no simulator connected is a 409, and a standard nothing simulated can staff a 422.
| Flag | Type | Default | Description |
|---|---|---|---|
--location | string | (none) | Where the system and its components sit, by name or dotted path |
--name | string | (none) | The system’s name; minted from its type when empty |
--standard | string | (none) | The standard the system is built to; its roles decide the components |
--system-type | string | (none) | The system’s type, which also mints its name when none is given |
Example:
omniglass simulation add-system <name> --standard standard --system-type system_typeomniglass simulation get
Section titled “omniglass simulation get”Get the simulated fleet
omniglass simulation getEvery node a simulator has pulled for since the server started, each with its capabilities, its account of impairments, and the components it simulates within the caller’s component read scope, joined to their live hits. A caller sees a node’s simulator when its component read scope holds at least one component the node simulates (an all-scope reader sees all of them); no node read is needed. Connected is true when any listed simulator pulled recently. Hits are per server process, not stored. Gated by simulation:read.
Example:
omniglass simulation getomniglass simulation plan-system
Section titled “omniglass simulation plan-system”Plan a simulated system to a standard
omniglass simulation plan-system <standard>Previews a simulated system built to a standard: each of the standard’s roles (one alternate taken per choice) staffed with the first simulated product that fits its accepted types and pins, as many as its quorum and at least one, or left short with the reason when nothing simulated fits. Creates nothing. Gated by simulation:read.
Example:
omniglass simulation plan-system <standard>omniglass simulation profiles
Section titled “omniglass simulation profiles”List the simulator’s profiles
omniglass simulation profilesThe simulator’s profile catalog, embedded in the binary: each profile with the products it simulates and the protocols it speaks. Adding a simulated component names one of these products. Gated by simulation:read.
Example:
omniglass simulation profilesomniglass standard
Section titled “omniglass standard”Commands for the standard resource
omniglass standard create
Section titled “omniglass standard create”Create a standard
omniglass standard create [flags]Creates a custom (non-official) standard, optionally as a variant of another. Gated by standard:create.
| Flag | Type | Default | Description |
|---|---|---|---|
--label | string | (none) | What an operator reads in pickers and lists |
--name | string | (none) | The globally unique name; renameable |
--parent-standard-id | string | (none) | A standard this one is a variant of, by handle or uuid |
Example:
omniglass standard create --label label --name nameomniglass standard delete
Section titled “omniglass standard delete”Delete a standard
omniglass standard delete <id>Deletes a custom standard, refused if official (422) or still referenced by a system (409). Gated by standard:delete.
Example:
omniglass standard delete meeting-roomomniglass standard get
Section titled “omniglass standard get”Get a standard
omniglass standard get <id>Fetches a standard by id. Gated by standard:read.
Example:
omniglass standard get meeting-roomomniglass standard list
Section titled “omniglass standard list”List standards
omniglass standard listLists the standard catalog, ordered alphabetically by label. A standard is the blueprint a system conforms to. Gated by standard:read.
Example:
omniglass standard listomniglass standard metric
Section titled “omniglass standard metric”Commands for the metric resource
omniglass standard metric delete
Section titled “omniglass standard metric delete”Withdraw a metric from a standard
omniglass standard metric delete <id> <metric>Removes one line from a custom standard’s contract; conforming systems keep any samples the series already holds, now off-contract. A metric the standard does not declare is a 404, and an official standard is read-only (422). Gated by standard:delete.
Example:
omniglass standard metric delete meeting-room <metric>omniglass standard metric list
Section titled “omniglass standard metric list”List a standard’s declared metrics
omniglass standard metric list <id>Lists the standard’s declared-metric contract (which metrics every system conforming to it carries), ordered by metric name, each with its optional default and required flag. Gated by standard:read.
Example:
omniglass standard metric list meeting-roomomniglass standard metric update
Section titled “omniglass standard metric update”Declare a metric on a standard
omniglass standard metric update <id> <metric> [flags]Declares a catalog metric on a custom standard, or revises the declaration in place (the line is addressed by name, so the write is idempotent). Official standards are read-only (422); an unknown standard is a 404 and a metric the catalog does not know is a 422. Gated by standard:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--default-value | string | (none) | The contract default, validated against the metric’s data_type; omit for no default |
--required | bool | false | Whether every system conforming to this standard must carry the metric; defaults to false |
Example:
omniglass standard metric update meeting-room <metric>omniglass standard property
Section titled “omniglass standard property”Commands for the property resource
omniglass standard property delete
Section titled “omniglass standard property delete”Withdraw a property from a standard
omniglass standard property delete <id> <property>Removes one line from a custom standard’s contract; conforming systems keep any value they set for it, now off-contract. A property the standard does not declare is a 404, and an official standard is read-only (422). Gated by standard:delete.
Example:
omniglass standard property delete meeting-room <property>omniglass standard property list
Section titled “omniglass standard property list”List a standard’s declared properties
omniglass standard property list <id>Lists the standard’s declared-property contract (what every system conforming to it exposes), ordered by property name, each with its optional default and required flag. Gated by standard:read.
Example:
omniglass standard property list meeting-roomomniglass standard property update
Section titled “omniglass standard property update”Declare a property on a standard
omniglass standard property update <id> <property> [flags]Declares a catalog property on a custom standard, or revises the declaration in place (the line is addressed by name, so the write is idempotent). Official standards are read-only (422); an unknown standard is a 404 and a property the catalog does not know is a 422. Gated by standard:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--default-value | string | (none) | The contract default, validated against the property’s data_type; omit for no default |
--required | bool | false | Whether every system conforming to this standard must set the property; defaults to false |
Example:
omniglass standard property update meeting-room <property>omniglass standard role
Section titled “omniglass standard role”Commands for the role resource
omniglass standard role delete
Section titled “omniglass standard role delete”Withdraw a role from a standard
omniglass standard role delete <id> <role>Removes the role from the standard, and with it every assignment conforming systems made to it. A role the standard does not declare is a 404. Gated by standard:delete.
Example:
omniglass standard role delete meeting-room <role>omniglass standard role list
Section titled “omniglass standard role list”List a standard’s declared roles
omniglass standard role list <id>Lists the roles this standard declares (every conforming system inherits them live), ordered by name, each with its quorum and the component_types (accepted_types) and, if pinned, the products a filling component must match. Gated by standard:read.
Example:
omniglass standard role list meeting-roomomniglass standard role update
Section titled “omniglass standard role update”Declare a role on a standard
omniglass standard role update <id> <role> [flags]Declares a role every conforming system needs filled, or revises it in place (the role is addressed by name, so the write is idempotent and declaring is this same route). Partial by default: the fields present in the body change and the rest of the declaration is left alone. update_mask overrides that, writing exactly the fields it names, which is how a field is cleared, and [”*”] replaces the whole declaration. An unknown standard, type, or product is a 422, as is a mask naming a field this resource does not patch. Gated by standard:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--accepted-types | string | (none) | The component_types a filling component’s product must be classified within (self or a descendant); replaces the accepted set wholesale when written, and an empty set accepts any type. Clearing it means naming accepted_types in update_mask |
--alternate | string | (none) | The choice/alternate this role joins, addressed as “choice-name/alternate-name” (#626). An empty string detaches the role, making it unconditional; an unknown choice or alternate is a 422 |
--capacity | int | 0 | The most components the role will accept; must be at least quorum, and unbounded on first declare. Name capacity in update_mask with no value here to clear it back to unbounded |
--impact | string | (none) | What an impaired role means for its system; degraded on first declare. The same broken component matters differently depending on the slot it was filling: a dead confidence monitor is not a dead main display |
--label | string | (none) | The role’s human label; defaults to the role name on first declare |
--pinned-products | string | (none) | If set, a filling component’s product must be one of these; replaces the pinned set wholesale when written, and an empty set accepts any product of an accepted type. Clearing it means naming pinned_products in update_mask |
--position-labels | string | (none) | Human labels for each position within the role, by index; replaces the label set wholesale when written. An empty list is not a populated field, so clearing the labels means naming position_labels in update_mask |
--quorum | int | 0 | How many components must fill the role; one on first declare |
--update-mask | string | (none) | Which fields this write changes (AIP-134). Omit it and the fields present in the body change and nothing else; name a field here and it is written even when the body leaves it empty, which is how a field is CLEARED; send [”*”] for full replacement, where every field the body omits goes back to its default. A field this resource does not patch is a 422 naming it |
Example:
omniglass standard role update meeting-room <role>omniglass standard update
Section titled “omniglass standard update”Update a standard
omniglass standard update <id> [flags]Patches a custom standard’s label or parent. Official standards are read-only (422). Gated by standard:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--label | string | (none) | A new operator-facing label |
--map | string | (none) | The room-layout declaration to store; JSON null clears it; absent leaves it. Validated: positive aspect, coordinates in [0, 1], 1-based positions, no duplicate (role, position) pair |
--parent-standard-id | string | (none) | A new variant parent, by handle or uuid |
Example:
omniglass standard update meeting-roomomniglass system
Section titled “omniglass system”Commands for the system resource
omniglass system alarm
Section titled “omniglass system alarm”Commands for the alarm resource
omniglass system alarm list
Section titled “omniglass system alarm list”List a system’s members’ alarms
omniglass system alarm list <name>Every member’s alarms in one read, newest first, each naming its component: the active ones whatever their age, and those cleared in the last 30 days, capped at 500. It is what a system’s Activity reads to explain its incidents, one request however many members the system has. Gated by system:read; an out-of-scope system is a non-disclosing 404.
Example:
omniglass system alarm list <name>omniglass system checkName
Section titled “omniglass system checkName”Check a system name
omniglass system checkName [flags]Reports whether a proposed name is a valid slug and currently free within the given placement (parent wins over location; neither means the root/unplaced bucket). Advisory (Save is still gated by the unique constraint). Gated by system:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--location | string | (none) | The location (by name or uuid) the entity would be placed at, if any and if unparented; ignored by the locations check |
--name | string | (none) | The proposed name to check |
--parent | string | (none) | The parent (by name or uuid) the entity would be created under, if any; omit for a root/unplaced check |
Example:
omniglass system checkName --name nameomniglass system create
Section titled “omniglass system create”Create a system
omniglass system create [flags]Creates a system, optionally under a parent (a root needs an all-scoped grant), at a location, conforming to a standard, and classified as a system_type. Gated by system:create; the location reference resolves within the caller’s location:read scope, because the label this stores is rendered from it, and a location outside that scope is refused (422) exactly as :renderLabel refuses to preview it.
| Flag | Type | Default | Description |
|---|---|---|---|
--expected-name | string | (none) | The name a create form previewed (POST /systems:renderLabel returns it). The create is refused with a 409 naming what it would produce instead, rather than silently landing a different name, if the number was taken or the system_type’s stem moved while the form was open. It does not name the row (the platform still does, and the row is still name_generated): it only asserts what that name will be. Applies only when the platform names the row: sending it beside a name is a 422. |
--label | string | (none) | What an operator reads; the name is the address |
--location | string | (none) | Location name this system is placed at |
--name | string | (none) | Name, unique within its placement (the address; lowercase letters, digits, hyphens). Omit to have the platform generate one from the system_type’s stem. |
--parent | string | (none) | Parent system name; omit for a root system |
--standard-id | string | (none) | The standard it conforms to, by handle or uuid; omit for a one-off system |
--system-type-id | string | (none) | The system_type it is classified as (what kind of space it is), by name or uuid; omit to leave it unclassified |
Example:
omniglass system createomniglass system delete
Section titled “omniglass system delete”Delete a system
omniglass system delete <name>Deletes a system, refused (409) while it still has child systems or is still referenced elsewhere. Gated by system:delete; read and delete scopes drive the 404 versus 403 split.
Example:
omniglass system delete <name>omniglass system event
Section titled “omniglass system event”Commands for the event resource
omniglass system event list
Section titled “omniglass system event list”List a system’s recent events, members included
omniglass system event list <name>Returns the system’s own events and its members’, newest first, bounded to the last 24 hours, each row labeled by the owner that raised it. A component shared with another system appears in both systems’ lists. Gated by system:read; an out-of-scope system is a non-disclosing 404.
Example:
omniglass system event list <name>omniglass system get
Section titled “omniglass system get”Get a system
omniglass system get <name>Fetches a system by name within the caller’s read scope. Out of scope is a non-disclosing 404. Gated by system:read.
Example:
omniglass system get <name>omniglass system health
Section titled “omniglass system health”Read every system’s health verdict
omniglass system health list
Section titled “omniglass system health list”Read a system’s health
omniglass system health list <name>The system’s current verdict and why: every role it needs filled, whether it is impaired, what an impaired role means for the system (impact), and for an impaired role which assigned components are down plus the alarms that took them down. A role that belongs to a choice (#626, an exclusive-or group such as an all-in-one alternate versus a component-built one) carries choice and alternate, and active is false when a different alternate answered the choice, meaning this role’s own impaired figure did not move the verdict. Transitions are the recorded edges over the last 30 days, one entry per change. Gated by system:read; an out-of-scope system is a non-disclosing 404.
Example:
omniglass system health list <name>omniglass system list
Section titled “omniglass system list”List systems in scope
omniglass system listLists the systems the caller may read, each filtered to its scope subtree. Gated by system:read.
Example:
omniglass system listomniglass system listTags
Section titled “omniglass system listTags”List tags on a system
omniglass system listTags <name>Lists the tags bound directly on a system (not the resolved cascade). Gated by system:read.
Example:
omniglass system listTags <name>omniglass system log
Section titled “omniglass system log”Commands for the log resource
omniglass system log list
Section titled “omniglass system log list”List a system’s members’ recent log lines
omniglass system log list <name>Returns the members’ raw log lines merged newest first, bounded to the last 24 hours and capped, each naming the component that wrote it. Gated by system:read; an out-of-scope system is a non-disclosing 404.
Example:
omniglass system log list <name>omniglass system member
Section titled “omniglass system member”Commands for the member resource
omniglass system member delete
Section titled “omniglass system member delete”Take a component out of a system
omniglass system member delete <name> <component>Unbinds this component from the system. Refused with a 409 while it still fills a role here, since removing it would leave the system staffed by a non-member: unassign the role first. A component that was not a member is a 404. Gated by system:update; read and update scopes drive the 404 versus 403 split.
Example:
omniglass system member delete <name> <component>omniglass system member list
Section titled “omniglass system member list”List the components in a system
omniglass system member list <name>The components bound into this system, ordered by name. Membership is what a role attaches to: every component staffing a role here is a member, and a member may also carry no role at all (a power conditioner is in the room without filling a declared slot). Each member carries its own verdict, so a system’s view can poll its members’ health here rather than reading the whole fleet. Gated by system:read; an out-of-scope system is a non-disclosing 404.
Example:
omniglass system member list <name>omniglass system member setPrimary
Section titled “omniglass system member setPrimary”Make this the component’s default system
omniglass system member setPrimary <name> <component>Moves the component’s default to this membership. The default answers questions asked without a system in hand; it does not decide anything that names a system explicitly. A component that was not a member here is a 404. Gated by system:update; read and update scopes drive the 404 versus 403 split.
Example:
omniglass system member setPrimary <name> <component>omniglass system member update
Section titled “omniglass system member update”Put a component in a system
omniglass system member update <name> <component>Binds this component into the system. Idempotent. A component’s first membership becomes its primary with nobody asking, so a component in exactly one system never has to think about the concept; a later membership does not take that default away. Gated by system:update; read and update scopes drive the 404 versus 403 split.
Example:
omniglass system member update <name> <component>omniglass system metric
Section titled “omniglass system metric”Commands for the metric resource
omniglass system metric list
Section titled “omniglass system metric list”List a system’s effective metrics
omniglass system metric list <name>Every metric the system’s standard declares, resolved to the series’ latest observed or calculated sample or the contract default until one arrives (is_sampled marks a live series), plus any metric sampled directly on the system (from_contract false). Gated by system:read; an out-of-scope system is a non-disclosing 404.
Example:
omniglass system metric list <name>omniglass system metric sample
Section titled “omniglass system metric sample”Commands for the sample resource
omniglass system metric sample list
Section titled “omniglass system metric sample list”Read one metric series’ raw samples
omniglass system metric sample list <name> <metric> [flags]The samples behind the effective read’s latest value for one series, newest first, windowed (hours) and capped (limit, newest kept). Gated by system:read; an out-of-scope owner is a non-disclosing 404.
| Flag | Type | Default | Description |
|---|---|---|---|
--hours | int | 0 | The window in hours, counted back from now; 24 when unset |
--limit | int | 0 | The row cap, newest kept; 500 when unset |
Example:
omniglass system metric sample list <name> <metric>omniglass system move
Section titled “omniglass system move”Move a system
omniglass system move <name> [flags]Relocates and/or re-parents a system: at least one of location or parent is required (422 otherwise). Both follow the three-state convention (an omitted field is unchanged, an explicit empty string clears, a name sets). A reparent is cycle-guarded and scope-injected; clearing parent to root requires an all-scoped move grant, the same authorization a root create already requires. A separate act from update, and a separately grantable one (system:move), because a placement change is an authorization act, not a label edit: it moves a row out from under one grant’s subtree and under another’s. Recorded under its own audit verb, move, distinct from update. A relocate still recomputes health at both ends (the location it left and the one it arrived at); a reparent does not, since the health rollup runs system -> location, never through the system tree. A taken name at the destination is a 409. A move can RENAME the system: a platform-generated name is scoped to its placement bucket, so a move that changes the bucket re-mints the name and the ordinal in the destination. A move that changes no bucket, including a re-stated placement and a relocate of a parented system (a parent wins over a location), leaves the name alone, and an operator-typed name is never touched. Gated by system:move; read and move scopes drive the 404 versus 403 split, and the destination location resolves within the caller’s location:read scope, because the move restamps the label from it: a destination outside that scope is refused (422).
| Flag | Type | Default | Description |
|---|---|---|---|
--location | string | (none) | Relocates the system to this location name. An empty string clears its placement. |
--parent | string | (none) | Re-parents the system within the system tree to this system name; cycle-guarded and scope-injected. An empty string makes it a root system (requires an all-scoped move grant). |
Example:
omniglass system move <name>omniglass system previewLabels
Section titled “omniglass system previewLabels”Preview a system label recompute
omniglass system previewLabelsLists exactly the rows a recompute would change, and leaves the fleet as it found it. Use it before :recomputeLabels to see the blast radius of a rule edit. Every generated label in the caller’s read and update scope is re-rendered from its current rules and compared with what is stored; a label an operator typed by hand is never a candidate. Bounded by the same two scopes the apply is, so it never lists a row the apply would then refuse to touch. A location preview also lists the components and systems placed at every location whose label would move, because those go stale the moment it does. Gated by system:update, the same permission the apply needs: a preview is half of an edit rather than a report, and an operator who cannot apply has no use for it.
Example:
omniglass system previewLabelsomniglass system property
Section titled “omniglass system property”Commands for the property resource
omniglass system property delete
Section titled “omniglass system property delete”Clear a property on a system
omniglass system property delete <name> <property>Removes the system’s declared value, so the property falls back to the standard contract’s default (or leaves the effective read entirely when it was off-contract). Clearing a property the system never set is a 404. Gated by system:update; read and update scopes drive the 404 versus 403 split.
Example:
omniglass system property delete <name> <property>omniglass system property list
Section titled “omniglass system property list”List a system’s effective properties
omniglass system property list <name>Every property the system’s standard declares, resolved to the system’s own value or the contract default (is_set marks the override), plus any property set directly on the system (from_contract false). Gated by system:read; an out-of-scope system is a non-disclosing 404.
Example:
omniglass system property list <name>omniglass system property sample
Section titled “omniglass system property sample”Commands for the sample resource
omniglass system property sample list
Section titled “omniglass system property sample list”Read one property series’ change history
omniglass system property sample list <name> <property> [flags]The change history behind the effective value for one property series, newest first, windowed (hours) and capped (limit, newest kept). Gated by system:read; an out-of-scope owner is a non-disclosing 404.
| Flag | Type | Default | Description |
|---|---|---|---|
--hours | int | 0 | The window in hours, counted back from now; 24 when unset |
--limit | int | 0 | The row cap, newest kept; 500 when unset |
Example:
omniglass system property sample list <name> <property>omniglass system property update
Section titled “omniglass system property update”Set a property on a system
omniglass system property update <name> <property> [flags]Declares a value for the property on this system, overriding the standard contract’s default. Idempotent: the first set stores the value, a later set replaces it. The property need not be on the contract, but it must exist in the catalog (422 otherwise). Gated by system:update; read and update scopes drive the 404 versus 403 split.
| Flag | Type | Default | Description |
|---|---|---|---|
--value | string | (none) | The value to declare, shape given by the property’s data_type |
Example:
omniglass system property update <name> <property> --value <json>omniglass system recomputeLabels
Section titled “omniglass system recomputeLabels”Recompute system labels
omniglass system recomputeLabelsApplies what :previewLabels describes, over the rows in the caller’s read and update scope, and returns exactly what it changed. Idempotent: a second call changes nothing. A label an operator typed by hand is left alone, and clearing that label by hand is how it is handed back to the platform. Recorded as ONE audit row for the operation, naming the rule tier and the affected count, rather than one row per changed entity. Gated by system:update.
Example:
omniglass system recomputeLabelsomniglass system removeTag
Section titled “omniglass system removeTag”Remove a tag value from a system
omniglass system removeTag <name> [flags]Removes a key’s value from a system. Gated by system:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--key | string | (none) | The tag key to remove |
Example:
omniglass system removeTag <name> --key keyomniglass system rename
Section titled “omniglass system rename”Rename a system
omniglass system rename <name> [flags]Moves the system’s name, the address an operator types and every external reference stores. A separate act from an update, and a separately grantable one, because it breaks bookmarks, runbooks, and integration config outside this system; inside it nothing breaks, since every reference holds the uuid. A taken name is a 409, an illegal or uuid-shaped one a 422. Gated by system:rename; read and rename scopes drive the 404 versus 403 split.
| Flag | Type | Default | Description |
|---|---|---|---|
--name | string | (none) | The new name, unique within its placement (lowercase letters, digits, hyphens) |
Example:
omniglass system rename <name> --name nameomniglass system renderLabel
Section titled “omniglass system renderLabel”Draft the name and label a system create would store
omniglass system renderLabel [flags]The system tier of :renderLabel on components. Drafts the name and the label a system create would stamp, allocating nothing: the ordinal is read from the placement bucket and the drafted name is posted back as expected_name on the create. A system suppresses the first ordinal in a bucket, so the first boardroom in a room drafts as boardroom and the second as boardroom-2. Omitting name drafts the name the platform would mint and refuses (422) an unclassified system, the same refusal a nameless create gives, since the stem lives on the system_type. Gated by system:create; the parent resolves within the caller’s system:create scope and the location ref within location:read, because a system’s label can carry its location’s. Omitting parent is the parentless bucket, refused (403) without an all-scoped create grant, exactly as the create refuses it.
| Flag | Type | Default | Description |
|---|---|---|---|
--location | string | (none) | The location this system will sit at, by name or uuid. Resolved within the caller’s location:read scope. |
--name | string | (none) | The name the row will carry. Omit it to draft the name and label the platform would produce; supply it to draft the label an operator-named row would carry, which has no ordinal at all. |
--parent | string | (none) | The parent system, by name or uuid. Part of the placement bucket a generated name’s ordinal is read from. Resolved within the caller’s system:create scope. |
--standard-id | string | (none) | The standard this system conforms to, by name or uuid; omit for a one-off system |
--system-type-id | string | (none) | The system_type this system is classified by, by name or uuid. Required to render a generated name’s label: the stem lives on that registry row. |
Example:
omniglass system renderLabelomniglass system resetName
Section titled “omniglass system resetName”Regenerate a system’s name
omniglass system resetName <name>Hands the pen back to the platform: regenerates the name from the system’s current system_type and placement (the same rule a nameless create applies, the type’s stem plus the lowest free ordinal, bare for the first of that stem in the placement) and marks it name_generated, whether or not it already was. An unclassified system is a 422: the stem lives on the system_type. Gated by system:rename, the same token :rename uses: it changes the name, exactly that permission’s blast radius.
Example:
omniglass system resetName <name>omniglass system role
Section titled “omniglass system role”Commands for the role resource
omniglass system role assignment
Section titled “omniglass system role assignment”Commands for the assignment resource
omniglass system role assignment delete
Section titled “omniglass system role assignment delete”Unassign a component from a role
omniglass system role assignment delete <name> <role> <component>Takes this component out of the role, leaving the role understaffed until another fills it. A component that was not filling the role is a 404. Gated by system:update; read and update scopes drive the 404 versus 403 split.
Example:
omniglass system role assignment delete <name> <role> <component>omniglass system role assignment update
Section titled “omniglass system role assignment update”Assign a component to a role
omniglass system role assignment update <name> <role> <component>Puts this component in the role for this system. Refused with a 422 naming both parties when the component is not a typed match: its product’s component_type outside every type the role accepts, or (if the role pins products) its product not one of them. A role with no accepted types takes any type. Idempotent. Gated by system:update; read and update scopes drive the 404 versus 403 split.
Example:
omniglass system role assignment update <name> <role> <component>omniglass system role delete
Section titled “omniglass system role delete”Withdraw a role from a system
omniglass system role delete <name> <role>Removes a role declared on this system, and with it every assignment to it. A role the system does not declare itself is a 404 (a role inherited from its standard is withdrawn on the standard, not here). Gated by system:update; read and update scopes drive the 404 versus 403 split.
Example:
omniglass system role delete <name> <role>omniglass system role list
Section titled “omniglass system role list”List a system’s effective roles
omniglass system role list <name>Every role this system needs filled: those its standard declares (from_standard true) plus those declared directly on it, each with the types it accepts (and products it pins, if any), the components filling it, and how many more it wants before quorum (understaffed). A one-off system shows only its own. Gated by system:read; an out-of-scope system is a non-disclosing 404.
Example:
omniglass system role list <name>omniglass system role swapPositions
Section titled “omniglass system role swapPositions”Exchange two occupants’ positions within a role
omniglass system role swapPositions <name> <role> [flags]Exchanges the positions of whichever components currently hold position and with within this role: an ordering change only, it does not affect who is assigned or the system’s health. Either position missing an occupant is a 404. Gated by system:update; read and update scopes drive the 404 versus 403 split.
| Flag | Type | Default | Description |
|---|---|---|---|
--position | int | 0 | One of the two positions to exchange |
--with | int | 0 | The other position to exchange with |
Example:
omniglass system role swapPositions <name> <role> --position <int> --with <int>omniglass system role update
Section titled “omniglass system role update”Declare a role on a system
omniglass system role update <name> <role> [flags]Declares a role directly on this system (how a one-off system gets roles at all, and how a conforming one adds what its standard does not cover), or revises it in place. Partial by default: the fields present in the body change and the rest of the declaration is left alone. update_mask overrides that, writing exactly the fields it names, which is how a field is cleared, and [”*”] replaces the whole declaration. Gated by system:update; read and update scopes drive the 404 versus 403 split.
| Flag | Type | Default | Description |
|---|---|---|---|
--accepted-types | string | (none) | The component_types a filling component’s product must be classified within (self or a descendant); replaces the accepted set wholesale when written, and an empty set accepts any type. Clearing it means naming accepted_types in update_mask |
--alternate | string | (none) | The choice/alternate this role joins, addressed as “choice-name/alternate-name” (#626). An empty string detaches the role, making it unconditional; an unknown choice or alternate is a 422 |
--capacity | int | 0 | The most components the role will accept; must be at least quorum, and unbounded on first declare. Name capacity in update_mask with no value here to clear it back to unbounded |
--impact | string | (none) | What an impaired role means for its system; degraded on first declare. The same broken component matters differently depending on the slot it was filling: a dead confidence monitor is not a dead main display |
--label | string | (none) | The role’s human label; defaults to the role name on first declare |
--pinned-products | string | (none) | If set, a filling component’s product must be one of these; replaces the pinned set wholesale when written, and an empty set accepts any product of an accepted type. Clearing it means naming pinned_products in update_mask |
--position-labels | string | (none) | Human labels for each position within the role, by index; replaces the label set wholesale when written. An empty list is not a populated field, so clearing the labels means naming position_labels in update_mask |
--quorum | int | 0 | How many components must fill the role; one on first declare |
--update-mask | string | (none) | Which fields this write changes (AIP-134). Omit it and the fields present in the body change and nothing else; name a field here and it is written even when the body leaves it empty, which is how a field is CLEARED; send [”*”] for full replacement, where every field the body omits goes back to its default. A field this resource does not patch is a 422 naming it |
Example:
omniglass system role update <name> <role>omniglass system setTag
Section titled “omniglass system setTag”Set a tag value on a system
omniglass system setTag <name> [flags]Binds a value for a key on a system. The key must exist and apply to this entity kind. Setting a value is the ordinary entity write, gated by system:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--key | string | (none) | The tag key (must exist and apply to this kind) |
--value | string | (none) | The bound value |
Example:
omniglass system setTag <name> --key key --value valueomniglass system update
Section titled “omniglass system update”Update a system
omniglass system update <name> [flags]Patches a system’s label, standard, or system_type. The name is not patchable: renaming is the :rename custom method. Placement is not patchable either: relocating or re-parenting is the :move custom method, gated separately, because a placement change is an authorization act. The standard and system_type fields both follow the three-state convention: an omitted field is unchanged, an explicit empty string clears (a one-off system, an unclassified system), a name sets. Gated by system:update; read and update scopes drive the 404 versus 403 split.
| Flag | Type | Default | Description |
|---|---|---|---|
--label | string | (none) | A new operator-facing label |
--standard-id | string | (none) | A new standard, by handle or uuid; "" clears it (a one-off system) |
--system-type-id | string | (none) | A new system_type, by name or uuid; "" clears it (an unclassified system) |
Example:
omniglass system update <name>omniglass system-type
Section titled “omniglass system-type”Commands for the system-type resource
omniglass system-type create
Section titled “omniglass system-type create”Create a system type
omniglass system-type create [flags]Creates a custom (non-official) system_type, optionally under a parent and optionally with the label_rule systems of that type get. A root type must carry a stem, since it has no ancestor to inherit one from. An unparseable label_rule is a 422. Gated by system_type:create.
| Flag | Type | Default | Description |
|---|---|---|---|
--abbrev | string | (none) | A compact form of label; omit to inherit the parent’s |
--icon | string | (none) | A glyph key; omit to inherit the parent’s |
--label | string | (none) | What an operator reads in pickers and lists |
--label-rule | string | (none) | The label template systems of this type get, a Go text/template over the system data map; omit to inherit the nearest ancestor’s. Refused (422) if it does not compile |
--name | string | (none) | The globally unique name |
--parent-id | string | (none) | The parent system_type, by name or uuid; omit for a root type |
--stem | string | (none) | The prefix a generated system name is built from; omit to inherit the parent’s. Lowercase letters, digits, and hyphens. Required for a root type, which has no ancestor to inherit one from. |
Example:
omniglass system-type create --label label --name nameomniglass system-type delete
Section titled “omniglass system-type delete”Delete a system type
omniglass system-type delete <id>Deletes a custom system_type, refused if official (422), still a parent of another system_type (409), or still classifying a system (409). Gated by system_type:delete.
Example:
omniglass system-type delete avomniglass system-type list
Section titled “omniglass system-type list”List system types
omniglass system-type listLists the system_type registry (the coarse taxonomy of what kind of space a system is: a boardroom, a classroom, a video wall), ordered alphabetically by label. Each row carries its parent link, so the console reconstructs the tree client-side. Distinct from standard, which is the blueprint a system conforms to. Gated by system_type:read.
Example:
omniglass system-type listomniglass system-type update
Section titled “omniglass system-type update”Update a system type
omniglass system-type update <id> [flags]Patches a custom system_type’s label, stem, icon, abbrev, or label_rule. An unparseable label_rule is a 422 at rule-edit time, never a broken row at create time, and setting one restamps nothing on its own: apply it with /systems:recomputeLabels after seeing the blast radius with :previewLabels. Official types are read-only (422). Gated by system_type:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--abbrev | string | (none) | A new compact form; an empty string clears it, so this type inherits the nearest ancestor’s again |
--icon | string | (none) | A new glyph key; an empty string clears it, so this type inherits the nearest ancestor’s again |
--label | string | (none) | A new operator-facing label |
--label-rule | string | (none) | A new label template for systems of this type; omit to leave unchanged, "" to clear back to the inherited one. Refused (422) if it does not compile. Editing it restamps nothing on its own: apply it with /systems:recomputeLabels, having seen the blast radius with :previewLabels |
--stem | string | (none) | A new name prefix (lowercase letters, digits, and hyphens); an empty string CLEARS it, so this type inherits the nearest ancestor’s again. A root type has no ancestor to inherit from and is refused (422). |
Example:
omniglass system-type update avomniglass tag
Section titled “omniglass tag”Commands for the tag resource
omniglass tag clearPlatform
Section titled “omniglass tag clearPlatform”Clear a platform tag value
omniglass tag clearPlatform <name>Removes the platform-tier binding for a key. Gated by tag:update (all-scope) and platform:update.
Example:
omniglass tag clearPlatform <name>omniglass tag create
Section titled “omniglass tag create”Mint a tag key
omniglass tag create [flags]Adds a key to the governed vocabulary. The name is normalized (a lowercase identifier); the optional label is what an operator reads instead. Gated by tag:create (all-scope, an admin action).
| Flag | Type | Default | Description |
|---|---|---|---|
--allowed-values | string | (none) | The value enum a bound value must belong to; omit for free text |
--applies-to | string | (none) | Entity kinds this key may bind to (component, system, location); omit for universal |
--label | string | (none) | What an operator reads in lists and pickers (Cost Center); omit to fall back to the name |
--name | string | (none) | The normalized name (lowercase letters, digits, and hyphens), unique tenant-wide |
--propagates | bool | false | Whether bindings cascade to descendants; defaults true |
Example:
omniglass tag create --name nameomniglass tag delete
Section titled “omniglass tag delete”Delete a tag key
omniglass tag delete <name>Removes a key from the vocabulary, cascading its bindings. Gated by tag:delete (all-scope).
Example:
omniglass tag delete <name>omniglass tag list
Section titled “omniglass tag list”List tag keys
omniglass tag listLists the governed key vocabulary. Rides the tag:read floor.
Example:
omniglass tag listomniglass tag setPlatform
Section titled “omniglass tag setPlatform”Set a platform tag value
omniglass tag setPlatform <name> [flags]Binds an install-wide default value for a key at the platform tier. Gated by tag:update (all-scope) and platform:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--value | string | (none) | The bound value |
Example:
omniglass tag setPlatform <name> --value valueomniglass tag update
Section titled “omniglass tag update”Update a tag key
omniglass tag update <name> [flags]Replaces a key’s governance fields (applies_to, propagates) and patches its label; the name is fixed. Gated by tag:update (all-scope).
| Flag | Type | Default | Description |
|---|---|---|---|
--allowed-values | string | (none) | The value enum a bound value must belong to; omit for free text |
--applies-to | string | (none) | Entity kinds this key may bind to; omit for universal |
--label | string | (none) | A new label; an empty string clears it, and the surface falls back to the name. Omit to leave it alone |
--propagates | bool | false | Whether bindings cascade to descendants; defaults true |
Example:
omniglass tag update <name>omniglass tag values
Section titled “omniglass tag values”List the distinct values bound for a key
omniglass tag values <name>Returns the distinct values already bound for a key across the fleet, for value autocomplete on a free-text key (an enum key carries its allowed set on the key itself). Rides the tag:read floor.
Example:
omniglass tag values <name>omniglass task
Section titled “omniglass task”Commands for the task resource
omniglass task get
Section titled “omniglass task get”Get a task
omniglass task get <id>Fetches a task by id. A task whose component is out of the caller’s read scope is a non-disclosing 404. Gated by task:read.
Example:
omniglass task get <id>omniglass task list
Section titled “omniglass task list”List tasks in scope
omniglass task listLists the tasks whose endpoint’s owning component the caller may read (the component cascade). Tasks are derived from endpoints, not authored. Gated by task:read.
Example:
omniglass task listomniglass telemetry
Section titled “omniglass telemetry”Commands for the telemetry resource
omniglass telemetry push
Section titled “omniglass telemetry push”Push telemetry for an owner
omniglass telemetry push [flags]Accepts per-lane observations (metrics, properties, events) and raw log lines for one owner and publishes them onto the ingest lane. Each lane validates against its own catalog: an unregistered name is rejected and reported in the response rather than silently dropped, and a property or event payload violating its type’s schema refuses the batch with a 422. Every key has one writer class, and a push writes only a collected key: a key a native probe writes (a reachability verdict or rung, a probe metric or timing, a held session’s state, collection-failed) is a node’s own observation and a platform key (health) is the platform’s, each rejected by name on every lane; a key a calc rule outputs is rejected naming the rule. Gated by telemetry:push, and the caller’s scope must cover the declared owner; an out-of-scope owner is a non-disclosing 404.
| Flag | Type | Default | Description |
|---|---|---|---|
--events | string | (none) | Natively caught occurrences, validated against event_type |
--logs | string | (none) | Raw untyped log lines. No registry gate |
--metrics | string | (none) | Numeric observations, validated against metric_type |
--owner | string | (none) | The entity every row in the batch lands under |
--properties | string | (none) | Categorical observations, validated against property_type and each type’s validation schema |
--source | string | (none) | Who observed this batch (recorded as the provenance source on every row) |
--ts | string | (none) | Batch timestamp; a per-item timestamp overrides it |
Example:
omniglass telemetry push --owner <json>omniglass token
Section titled “omniglass token”Mint an additional bearer token for an existing principal (direct DB)
omniglass token <username> [flags]Issues a new bearer credential for an existing principal, addressed by username, and prints the token once. The same trusted direct-DB lane as bootstrap: token reissue, break-glass, or a fresh login token for make dev when the owner already exists. A —description (required) names what the token is for. The token expires after —ttl (default 90 days, hard maximum 365 days); every credential is time-bounded.
| Flag | Type | Default | Description |
|---|---|---|---|
--description | string | (none) | what the token is for (required) |
--ttl | duration | 2160h0m0s | how long the token is valid before it expires (max 365 days) |
omniglass transport
Section titled “omniglass transport”Commands for the transport resource
omniglass transport list
Section titled “omniglass transport list”List the transports the platform speaks
omniglass transport listLists the transport registry: the wires an endpoint can speak over, a build-time fact of the binary (ADR-0073). Gated by endpoint:read, the surface that consumes it.
Example:
omniglass transport listomniglass variable
Section titled “omniglass variable”Commands for the variable resource
omniglass variable create
Section titled “omniglass variable create”Create a variable
omniglass variable create [flags]Sets a variable at an owner scope. The value is validated against value_type; the optional label is what an operator reads instead of the name. Gated by variable:create, plus platform:create when owner_kind is platform (the install-wide tier).
| Flag | Type | Default | Description |
|---|---|---|---|
--label | string | (none) | What an operator reads in lists and pickers (Poll Interval); omit to fall back to the name |
--name | string | (none) | The cascade name (lowercase letters, digits, and hyphens); unique per owner |
--owner | string | (none) | The owning entity’s name; omit for a platform variable |
--owner-kind | string | (none) | Which tier owns this variable |
--value | string | (none) | The value, validated against value_type |
--value-type | string | (none) | The declared value type |
Example:
omniglass variable create --name name --owner-kind owner_kind --value <json> --value-type value_typeomniglass variable delete
Section titled “omniglass variable delete”Delete a variable
omniglass variable delete <variable>Removes a variable, by name or uuid. Gated by variable:delete, plus platform:delete when the variable sits at the platform tier; read and delete scopes on the owner drive the 404 versus 403 split.
Example:
omniglass variable delete poll-intervalomniglass variable list
Section titled “omniglass variable list”List variables (admin directory)
omniglass variable listLists every variable. Requires an all-scope read. Gated by variable:read.
Example:
omniglass variable listomniglass variable update
Section titled “omniglass variable update”Update a variable
omniglass variable update <variable> [flags]Replaces a variable’s value (validated against its fixed value_type) and patches its label; either may be omitted, and an empty label clears it. Name, type, and owner are fixed at creation. Gated by variable:update, plus platform:update when the variable sits at the platform tier.
| Flag | Type | Default | Description |
|---|---|---|---|
--label | string | (none) | A new label; an empty string clears it, and the surface falls back to the name. Omit to leave it alone |
--value | string | (none) | The new value, validated against the fixed value_type; omit to leave it |
Example:
omniglass variable update poll-intervalomniglass vendor
Section titled “omniglass vendor”Commands for the vendor resource
omniglass vendor create
Section titled “omniglass vendor create”Create a vendor
omniglass vendor create [flags]Creates a custom (non-official) vendor. Gated by vendor:create.
| Flag | Type | Default | Description |
|---|---|---|---|
--icon | string | (none) | A glyph key, e.g. crestron-logo |
--kind | string | (none) | The role the organization plays |
--label | string | (none) | What an operator reads in pickers and lists |
--name | string | (none) | The globally unique name; renameable |
--support-phone | string | (none) | The vendor’s support line |
--website | string | (none) | The vendor’s website (http or https) |
Example:
omniglass vendor create --label label --name nameomniglass vendor delete
Section titled “omniglass vendor delete”Delete a vendor
omniglass vendor delete <id>Deletes a custom vendor, refused if official (422). Gated by vendor:delete.
Example:
omniglass vendor delete borealomniglass vendor get
Section titled “omniglass vendor get”Get a vendor
omniglass vendor get <id>Fetches a vendor by id. Gated by vendor:read.
Example:
omniglass vendor get borealomniglass vendor list
Section titled “omniglass vendor list”List vendors
omniglass vendor listLists the vendor registry, ordered alphabetically by label. Populates the vendor picker on the product form. Gated by vendor:read.
Example:
omniglass vendor listomniglass vendor update
Section titled “omniglass vendor update”Update a vendor
omniglass vendor update <id> [flags]Patches a custom vendor’s label, kind, icon, support_phone, or website. Official vendors are read-only (422). Gated by vendor:update.
| Flag | Type | Default | Description |
|---|---|---|---|
--icon | string | (none) | A new glyph key |
--kind | string | (none) | A new organization role |
--label | string | (none) | A new operator-facing label |
--support-phone | string | (none) | A new support line |
--website | string | (none) | A new website (http or https) |
Example:
omniglass vendor update borealomniglass view
Section titled “omniglass view”Commands for the view resource
omniglass view fleet
Section titled “omniglass view fleet”Commands for the fleet resource
omniglass view fleet list
Section titled “omniglass view fleet list”Read the whole in-scope fleet in one call
omniglass view fleet listReturns every in-scope location (flat, with parent and verdict), every in-scope system (with location and verdict), and one dot per component in each system. A dot carries the component id, its verdict, and the primary/shared flags, not a full component row. Each tier is scoped on its own read permission: a caller who can read locations but not components gets locations with empty systems, and a caller with no scope gets an empty result, not an error. Gated by location:read.
Example:
omniglass view fleet list