devices

`remoteclaw devices`

Manage device pairing requests and device-scoped tokens.

Commands

`remoteclaw devices list`

List pending pairing requests and paired devices.

remoteclaw devices list
remoteclaw devices list --json

Pending request output includes the requested role and scopes so approvals can be reviewed before you approve.

`remoteclaw devices remove <deviceId>`

Remove one paired device entry.

remoteclaw devices remove <deviceId>
remoteclaw devices remove <deviceId> --json

`remoteclaw devices clear --yes [--pending]`

Clear paired devices in bulk.

remoteclaw devices clear --yes
remoteclaw devices clear --yes --pending
remoteclaw devices clear --yes --pending --json

`remoteclaw devices approve [requestId] [--latest]`

Approve a pending device pairing request. If requestId is omitted, RemoteClaw automatically approves the most recent pending request.

Note: if a device retries pairing with changed auth details (role/scopes/public key), RemoteClaw supersedes the previous pending entry and issues a new requestId. Run remoteclaw devices list right before approval to use the current ID.

remoteclaw devices approve
remoteclaw devices approve <requestId>
remoteclaw devices approve --latest

`remoteclaw devices reject <requestId>`

Reject a pending device pairing request.

remoteclaw devices reject <requestId>

`remoteclaw devices rotate --device <id> --role <role> [--scope <scope...>]`

Rotate a device token for a specific role (optionally updating scopes).

remoteclaw devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write

`remoteclaw devices revoke --device <id> --role <role>`

Revoke a device token for a specific role.

remoteclaw devices revoke --device <deviceId> --role node

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.
These commands require operator.pairing (or operator.admin) scope.
devices clear is intentionally gated by --yes.
If pairing scope is unavailable on local loopback (and no explicit --url is passed), list/approve can use a local pairing fallback.

Token drift recovery checklist

Use this when Control UI or other clients keep failing with AUTH_TOKEN_MISMATCH or AUTH_DEVICE_TOKEN_MISMATCH.

Confirm current gateway token source:

remoteclaw config get gateway.auth.token

List paired devices and identify the affected device id:

remoteclaw devices list

Rotate operator token for the affected device:

remoteclaw devices rotate --device <deviceId> --role operator

If rotation is not enough, remove stale pairing and approve again:

remoteclaw devices remove <deviceId>
remoteclaw devices list
remoteclaw devices approve <requestId>

Retry client connection with the current shared token/password.