> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# identity

# `wednesdayai identity`

Manage people and their linked accounts in the Gateway config (`session.identityLinks`).

Related:

* Concepts and flows: [Identities](https://docs.wednesdayai.dev/next/admin/gateway/identity)
* Paired devices: [devices](https://docs.wednesdayai.dev/next/users/cli/devices.md)
* Channel pairing: [pairing](https://docs.wednesdayai.dev/next/users/cli/pairing.md)
* QR setup codes: [qr](https://docs.wednesdayai.dev/next/users/cli/qr.md)

## Commands

### `wednesdayai identity list`

List configured identities and their linked accounts.

```bash theme={"dark"}
wednesdayai identity list
wednesdayai identity list --json
```

If no identities exist yet, prints:

```text theme={"dark"}
No identities yet. Add one with: wednesdayai identity add <name>
```

When identities exist, the command renders a table with `Identity` and `Links` columns. With `--json`, it returns `{ "persons": [ { "person": "<name>", "links": [ ... ] } ] }`.

### `wednesdayai identity add <name>`

Create a new identity (person) for device and account linking.

```bash theme={"dark"}
wednesdayai identity add Alice
wednesdayai identity add Alice --json
```

Arguments:

* `<name>`: Identity name (letters, digits, `.`, `_` or `-`, max 64 characters).

Prints `Added identity <name>.` on success, or `<name> already exists.` if the name is already configured. With `--json`, returns `{ "person": "<name>", "changed": <boolean> }`.

The names `prototype`, `constructor`, and `__proto__` are reserved and refused, as is the `raw~` prefix.

### `wednesdayai identity link <name> [value]`

Link an account to an identity, or issue a user-client QR and setup code.

Pass either a chat or account link value (e.g. `telegram:123`, `slack:U061CR7GN`) or `--qr`. Device values (`device:<deviceId>`) are refused here; link a paired device with `wednesdayai devices link <deviceId> --identity <name>`, from the [Control UI v2](https://docs.wednesdayai.dev/next/admin/web/control-ui-v2.md) console's **Nodes & devices** page (Fleet group), or pair it already bound with `--qr`:

```bash theme={"dark"}
# Link by value
wednesdayai identity link Alice telegram:123456789
wednesdayai identity link Alice telegram:123456789 --json

# Issue a user-client QR and setup code bound to Alice
wednesdayai identity link Alice --qr
wednesdayai identity link Alice --qr --setup-code-only
wednesdayai identity link Alice --qr --no-ascii
wednesdayai identity link Alice --qr --json
```

Options:

* `--qr`: Issue a user-client QR and setup code for this identity instead of passing a value (invokes the QR generator with `--client openclaw-user-client --identity <name>`). `--qr` is local-only: it reads this host's gateway config, so the shared gateway flags `--url`, `--token` and `--password` are rejected (`--qr issues a setup code from this host's gateway config; drop --url/--token/--password (run it on the gateway host).`).
* `--setup-code-only`: With `--qr`, print only the setup code.
* `--no-ascii`: With `--qr`, skip ASCII QR rendering.
* `--json`: Output JSON.

When linking a value, prints `Linked <value> to <name>.` on success or `Already linked.` if the value was already linked to that identity. With `--json`, returns `{ "person": "<name>", "value": "<value>", "changed": <boolean> }`.

### `wednesdayai identity unlink <value>`

Remove a link value from every identity that contains it.

```bash theme={"dark"}
wednesdayai identity unlink telegram:123456789
wednesdayai identity unlink device:6abfaeda
wednesdayai identity unlink telegram:123456789 --json
```

Arguments:

* `<value>`: Link value to remove (e.g. `telegram:123`, `device:<deviceId>`).

Prints `Unlinked <value> from <name1>, <name2>.` on success, or `<value> is not linked.` if the value was not present on any identity. With `--json`, returns `{ "value": "<value>", "unlinkedFrom": [ ... ] }`.

## Shared Gateway options

All `identity` subcommands call Gateway RPC methods (`identity.list`, `identity.add`, `identity.link`, `identity.unlink`) and accept the standard Gateway connection flags:

* `--url <url>`: Gateway WebSocket URL (defaults to `gateway.remote.url` when configured).
* `--token <token>`: Gateway token (if required).
* `--timeout <ms>`: Timeout in ms (defaults to `30000`).
* `--expect-final`: Wait for final response (agent).
* `--json`: Output JSON (available on all subcommands).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.