wednesdayai devices
Manage device pairing requests and device-scoped tokens.
Commands
wednesdayai devices list
List pending pairing requests and paired devices.
--json returns pending and paired arrays; each paired entry carries a deviceId and, when
the device is linked to a person, an identity field holding that person’s session.identityLinks
key. A device’s person is stored on its pairing record, not in session.identityLinks. Gateway
clients (web client, Control UI) send their turns as device:<deviceId>, and assistants with
workspace lanes require the device to be
linked. The paired-device table also shows an Identity column with the linked key. See
Identities. A companion credential issued by a WednesdayAI app device shows as
<name> (companion of <app name>), and its --json entry carries companionOf: <app deviceId>;
removing, revoking or pruning the app removes its companions (see
Device companions and device.self).
The paired table also shows Registered (age of the first registration, kept across re-pairing),
Last Active (latest connection activity or token use) and State: connected for a device with
an open connection, stale for one inactive longer than gateway.devices.staleAfterDays (default
90), and replaces <n> when a newer enrolment of the same person, app and hardware supersedes n
older records. --json carries the same data as firstRegisteredAtMs, lastActiveAtMs,
connected, stale and supersedes.
wednesdayai devices link <deviceId> --identity <key>
Link a paired device to a session.identityLinks identity.
The key must already exist; unknown keys are never created:
Linked <deviceId> to <Identity>.; when the device is already linked to that identity it
prints <deviceId> is already linked to <Identity>. and writes nothing. A device belongs to one
person for good. Linking a device that is already linked to someone else is refused:
devices remove or devices unlink) and pair again; the new pairing is a new device record. A
node-only device (paired with the node role and not operator) has no person, and linking it is
refused with <deviceId> is a node; nodes have no person and cannot be linked.
(DEVICE_LINK_NODE_REFUSED). An unpaired device is refused with unknown deviceId.
The identities prototype, constructor and __proto__ are reserved and refused; rename them in
session.identityLinks first. That rename is a one-time fix for a hand-edited config; normal
enrollment never needs a hand edit (see Identities).
The Control UI v2 console can link an unlinked device and unlink a linked
one from its Nodes & devices page (Fleet group), over the device.identity.link and
device.identity.unlink RPCs (operator.admin). It does not change a linked device’s person, and
its Unlink deregisters the device like devices unlink.
Identities are created on the gateway host with wednesdayai identity add <name> (see
Identities).
wednesdayai devices unlink <deviceId>
Deregister a device: remove its pairing record, with its tokens and its person, and close its
connections. Unlinking a device is the same as devices remove; there is no unlink-then-link
rebind, and pairing again creates a new device record:
Unlinked <deviceId> from <person>. (or <deviceId> is not linked.) and, when the device
was still paired, Removed <deviceId>; pair it again to use it. (deregistered: true in
--json). Device ids match case-insensitively.
wednesdayai devices remove <deviceId>
Remove one paired device entry and close its connections. If the device was linked, the removal
also unlinks it and prints Unlinked from <keys>.
wednesdayai devices clear --yes [--pending]
Clear paired devices in bulk.
clear needs a running gateway; it is never applied locally.
wednesdayai devices prune --stale|--superseded|--never-used [--dry-run] [--yes]
Revoke and archive stale, superseded or never-used paired records:
--staleselects devices and legacy node records inactive longer thangateway.devices.staleAfterDays.--supersededselects records flagged by a newer enrolment (replaces <n>indevices list). A record is kept when its replacement is being pruned in the same run, so a chain of re-enrolments retires one link at a time and two records never retire each other.--never-usedselects records approved longer thangateway.devices.neverUsedAfterDays(default 7) ago that have never been active at all: no connection, no token use, no node role (node activity history lives on the node record, not the device), no companions, not a companion of another record, no accessories, not connected now, and not the only device of their person. Every paired record considered appears exactly once — selected, or kept with the first failing check: dry runs printKept <id> (<keptBecause>)lines (used,node-role,recent,connected,token-used,has-companions,companion,has-accessories,only-device-of-owner). Each selected record prints its qualifying reason with its approval age. Companion records die with their primary, so a companion of a selected record counts as removed, never as a person’s survivor; when a run would take every device of a person, the most recently approved selection is kept (only-device-of-owner). Without--yes,--never-usedbehaves as a dry run; nothing is ever archived automatically. In--jsonoutput a record’slastActiveAtMsfalls back to its approval time when no activity is recorded; selection never reads that fallback.--dry-runprintsWould archive …lines and changes nothing. Without--dry-run,--yesis required (a lone--never-usedwithout--yespreviews instead of archiving).
Skipped connected <id>. Prune
runs are serialized per gateway process, so two requests never interleave one run’s selection
with another run’s archive. Prune needs a running gateway (it reads live connection state and
writes config).
wednesdayai devices approve [requestId] [--latest]
Approve a pending device pairing request. If requestId is omitted, WednesdayAI
automatically approves the most recent pending request.
wednesdayai devices reject <requestId>
Reject a pending device pairing request.
wednesdayai devices rotate --device <id> --role <role> [--scope <scope...>]
Rotate a device token for a specific role (optionally updating scopes).
wednesdayai devices revoke --device <id> --role <role>
Revoke a device token for a specific role.
Common options
--url <url>: Gateway WebSocket URL (defaults togateway.remote.urlwhen configured).--token <token>: Gateway token (if required).--password <password>: Gateway password (password auth).--timeout <ms>: RPC timeout.--json: JSON output (recommended for scripting).
--url, the CLI does not fall back to config or environment credentials.
Pass --token or --password explicitly. Missing explicit credentials is an error.
Notes
- Token rotation returns a new token (sensitive). Treat it like a secret.
- The pairing and token commands (
list/approve/reject/remove/clear/prune/rotate/revoke) requireoperator.pairing(oroperator.admin) scope.devices linkanddevices unlinkrequireoperator.admin: linking grants a person’s identity. devices clearis intentionally gated by--yes.- Pairing state lives in the session database. When no gateway owns storage,
devices list,devices approve,devices reject,devices remove,devices rotateanddevices revokeopen the database locally and apply the change directly;devices clear,devices prune,devices linkanddevices unlinkneed a running gateway. On first open the CLI imports any legacydevices/*.json/nodes/*.jsonfiles once (see Gateway pairing storage). - Successful bootstrap redemptions (including the bounded-profile ids
openclaw-even-g2-node,openclaw-mentra-node,openclaw-user-client,wednesdayai-glass-node) are approved silently and appear underpaired; non-bootstrap pairing and role or scope upgrade requests can still appear underpending. To cut a device off,devices revoke --device <id> --role <role>prevents subsequent reconnects but does not close an existing connection: restart the gateway (or otherwise close its socket) for immediate containment.devices remove <id>deletes the row so the device must scan a new setup code (see MentraOS glasses).