Skip to main content

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. Link a paired device to a session.identityLinks identity. The key must already exist; unknown keys are never created:
Prints 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:
The only way to give a device to someone else, or back to the same person, is to deregister it (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). 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:
Prints 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:
  • --stale selects devices and legacy node records inactive longer than gateway.devices.staleAfterDays.
  • --superseded selects records flagged by a newer enrolment (replaces <n> in devices 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-used selects records approved longer than gateway.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 print Kept <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-used behaves as a dry run; nothing is ever archived automatically. In --json output a record’s lastActiveAtMs falls back to its approval time when no activity is recorded; selection never reads that fallback.
  • --dry-run prints Would archive … lines and changes nothing. Without --dry-run, --yes is required (a lone --never-used without --yes previews instead of archiving).
Each pruned record has every token revoked, is archived in the session database (pairing archive tables, token secrets dropped), is removed from the paired table, and is unlinked from its identity. A connected device is never pruned; it is reported as 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 to gateway.remote.url when configured).
  • --token <token>: Gateway token (if required).
  • --password <password>: Gateway password (password auth).
  • --timeout <ms>: RPC timeout.
  • --json: JSON output (recommended for scripting).
Note: when you set --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) require operator.pairing (or operator.admin) scope. devices link and devices unlink require operator.admin: linking grants a person’s identity.
  • devices clear is 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 rotate and devices revoke open the database locally and apply the change directly; devices clear, devices prune, devices link and devices unlink need a running gateway. On first open the CLI imports any legacy devices/*.json / nodes/*.json files 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 under paired; non-bootstrap pairing and role or scope upgrade requests can still appear under pending. 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).