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

# Routes, Persons & Auth

> Agent routing, person directory, authentication, and API key management.

# Routes, Persons & Auth

Three command groups for access and routing: `omni routes` controls which agent handles which chat, `omni persons` manages the contact directory, and `omni auth`/`omni keys` handle authentication and API key lifecycle.

## Route Commands

Routes determine which AI agent handles messages for a specific chat or person.

### `omni routes list`

List agent routes for an instance.

```bash theme={"dark"}
omni routes list [options]
```

| Option            | Description                       |
| ----------------- | --------------------------------- |
| `--instance <id>` | Instance ID                       |
| `--scope <scope>` | Filter by scope: `chat` or `user` |
| `--active`        | Show only active routes           |

### `omni routes get`

Get route details.

```bash theme={"dark"}
omni routes get <route-id>
```

### `omni routes create`

Create a new agent route.

```bash theme={"dark"}
omni routes create [options]
```

| Option                                       | Description                                     |
| -------------------------------------------- | ----------------------------------------------- |
| `--instance <id>`                            | Instance ID                                     |
| `--scope <scope>`                            | Route scope: `chat` or `user`                   |
| `--chat <chat-id>`                           | Chat UUID (required when scope=`chat`)          |
| `--person <person-id>`                       | Person UUID (required when scope=`user`)        |
| `--agent <agent-id>`                         | Agent UUID                                      |
| `--timeout <seconds>`                        | Agent timeout in seconds                        |
| `--stream` / `--no-stream`                   | Enable or disable streaming responses           |
| `--prefix-sender` / `--no-prefix-sender`     | Prefix messages with sender name                |
| `--wait-media` / `--no-wait-media`           | Wait for media processing before routing        |
| `--send-media-path` / `--no-send-media-path` | Include file path in media text                 |
| `--gate` / `--no-gate`                       | Enable or disable LLM response gate             |
| `--gate-model <model>`                       | Response gate model                             |
| `--gate-prompt <prompt>`                     | Response gate prompt                            |
| `--reply-filter-mode <mode>`                 | Reply filter: `all` or `filtered`               |
| `--label <label>`                            | Human-readable label                            |
| `--priority <number>`                        | Priority (higher = higher priority, default: 0) |
| `--inactive`                                 | Create as inactive                              |

```bash theme={"dark"}
# Route a chat to an agent
omni routes create \
  --instance <id> \
  --scope chat \
  --chat <chat-uuid> \
  --agent <agent-uuid> \
  --label "Support Bot"

# Route all messages from a person to an agent
omni routes create \
  --instance <id> \
  --scope user \
  --person <person-uuid> \
  --agent <agent-uuid> \
  --gate \
  --gate-model "claude-sonnet-4-20250514"

# High-priority route with streaming
omni routes create \
  --instance <id> \
  --scope chat \
  --chat <chat-uuid> \
  --agent <agent-uuid> \
  --stream \
  --priority 10
```

### `omni routes update`

Update an existing route. Accepts the same options as `create`.

```bash theme={"dark"}
omni routes update <route-id> [options]
```

### `omni routes delete`

Delete a route.

```bash theme={"dark"}
omni routes delete <route-id>
```

### `omni routes test`

Test which route would resolve for a given instance, chat, and/or person.

```bash theme={"dark"}
omni routes test [options]
```

| Option                 | Description         |
| ---------------------- | ------------------- |
| `--instance <id>`      | Instance ID         |
| `--chat <chat-id>`     | Chat UUID to test   |
| `--person <person-id>` | Person UUID to test |

```bash theme={"dark"}
omni routes test --instance <id> --chat <chat-uuid>
```

### `omni routes metrics`

View route cache metrics.

```bash theme={"dark"}
omni routes metrics
```

***

## Person Commands

### `omni persons search`

Search the person directory.

```bash theme={"dark"}
omni persons search <query> [options]
```

| Option        | Description                 |
| ------------- | --------------------------- |
| `--limit <n>` | Limit results (default: 20) |

```bash theme={"dark"}
omni persons search "João" --limit 10
```

### `omni persons get`

Get full person details.

```bash theme={"dark"}
omni persons get <id>
```

### `omni persons presence`

Get person presence and activity info.

```bash theme={"dark"}
omni persons presence <id>
```

### `omni persons update`

Update person fields.

```bash theme={"dark"}
omni persons update <id> [options]
```

| Option              | Description                  |
| ------------------- | ---------------------------- |
| `--name <name>`     | Display name                 |
| `--phone <phone>`   | Primary phone (E.164 format) |
| `--email <email>`   | Primary email                |
| `--avatar <url>`    | Avatar URL                   |
| `--metadata <json>` | Metadata as JSON string      |

```bash theme={"dark"}
omni persons update abc123 --name "João Silva" --email "joao@example.com"
```

### `omni persons merge`

Merge two person records into one. The source person is deleted and all identities transfer to the target. Use this to deduplicate contacts that represent the same person across different instances.

```bash theme={"dark"}
omni persons merge [options] <source> <target>
```

| Option              | Description      |
| ------------------- | ---------------- |
| `--reason <reason>` | Reason for merge |

```bash theme={"dark"}
omni persons merge person-abc person-def --reason "Same WhatsApp user across two instances"
```

### `omni persons link`

Link two platform identities to the same person. Useful when the same person has accounts on different channels (WhatsApp, Telegram, etc.) that Omni has not auto-matched.

```bash theme={"dark"}
omni persons link <identityA> <identityB>
```

```bash theme={"dark"}
omni persons link identity-whatsapp-123 identity-telegram-456
```

### `omni persons unlink`

Remove a platform identity from its person record.

```bash theme={"dark"}
omni persons unlink [options] <identityId>
```

| Option              | Description                                       |
| ------------------- | ------------------------------------------------- |
| `--reason <reason>` | Reason for unlinking (default: `"Manual unlink"`) |

```bash theme={"dark"}
omni persons unlink identity-abc --reason "Incorrectly linked"
```

***

## Auth Commands

### `omni auth login`

Save API credentials.

```bash theme={"dark"}
omni auth login [options]
```

| Option            | Description                                     |
| ----------------- | ----------------------------------------------- |
| `--api-key <key>` | API key for authentication                      |
| `--api-url <url>` | API base URL (default: `http://localhost:8882`) |

### `omni auth status`

Show current authentication status.

```bash theme={"dark"}
omni auth status
```

### `omni auth logout`

Clear stored credentials.

```bash theme={"dark"}
omni auth logout
```

### `omni auth recover`

Recover API key when auth is invalid. Requires local PM2 access.

```bash theme={"dark"}
omni auth recover [options]
```

| Option            | Description                                               |
| ----------------- | --------------------------------------------------------- |
| `--api-url <url>` | API base URL (default: `http://localhost:8882`)           |
| `--rotate`        | Generate a new key instead of recovering the existing one |

***

## API Key Commands

### `omni keys create`

Create a new API key with scoped permissions.

```bash theme={"dark"}
omni keys create [options]
```

| Option                 | Description                                                    |
| ---------------------- | -------------------------------------------------------------- |
| `--name <name>`        | Key name                                                       |
| `--scopes <scopes>`    | Comma-separated scopes (e.g., `messages:read,instances:write`) |
| `--instances <ids>`    | Comma-separated instance IDs to restrict access                |
| `--description <desc>` | Key description                                                |
| `--rate-limit <n>`     | Rate limit (requests/minute)                                   |
| `--expires <date>`     | Expiration date (ISO 8601)                                     |

```bash theme={"dark"}
# Full-access key
omni keys create --name "admin" --scopes "*"

# Scoped read-only key
omni keys create \
  --name "monitoring" \
  --scopes "messages:read,events:read" \
  --rate-limit 100

# Instance-restricted key with expiry
omni keys create \
  --name "temp-access" \
  --instances <id1>,<id2> \
  --expires 2025-12-31T23:59:59Z
```

### `omni keys list`

List API keys.

```bash theme={"dark"}
omni keys list [options]
```

| Option              | Description                                      |
| ------------------- | ------------------------------------------------ |
| `--status <status>` | Filter by status: `active`, `revoked`, `expired` |
| `--limit <n>`       | Max results                                      |

### `omni keys get`

Get API key details.

```bash theme={"dark"}
omni keys get <id>
```

### `omni keys update`

Update an API key.

```bash theme={"dark"}
omni keys update <id> [options]
```

| Option                 | Description                                   |
| ---------------------- | --------------------------------------------- |
| `--name <name>`        | New name                                      |
| `--description <desc>` | New description                               |
| `--scopes <scopes>`    | New scopes (comma-separated)                  |
| `--instances <ids>`    | New instance IDs (empty string to unrestrict) |
| `--rate-limit <n>`     | New rate limit                                |
| `--expires <date>`     | New expiration (empty string to clear)        |

### `omni keys revoke`

Revoke an API key.

```bash theme={"dark"}
omni keys revoke <id> [options]
```

| Option              | Description           |
| ------------------- | --------------------- |
| `--reason <reason>` | Reason for revocation |

### `omni keys delete`

Permanently delete an API key.

```bash theme={"dark"}
omni keys delete <id>
```

<Warning>
  `omni keys delete` is irreversible — there is no soft-delete or undo. Prefer `omni keys revoke <id>` for routine deactivation; revoked keys retain their audit trail and can still appear in `omni keys list`.
</Warning>

<Note>
  `omni persons merge` and `omni persons link` rewrite the canonical person identity. Downstream automations keyed on the merged-away `personId` will start receiving events under the surviving ID — coordinate with anyone who built dashboards or alerts on those IDs before merging.
</Note>

<Tip>
  Bulk-restrict a key to specific instances by passing a comma list: `omni keys update <id> --instances "wa-prod,wa-staging"`. Pass an empty string `--instances ""` to remove the restriction.
</Tip>

## See also

<CardGroup cols={2}>
  <Card title="Routes (concept)" icon="diagram-project" href="/omni/concepts/routes">
    Routing rules, priorities, and resolution order.
  </Card>

  <Card title="Auth & API keys" icon="key" href="/omni/cli/agents">
    `omni keys` quick reference and agent-side key usage.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/omni/cli/webhooks">
    Inbound auth surfaces for custom integrations.
  </Card>

  <Card title="Instances" icon="server" href="/omni/concepts/instances">
    Per-instance access and identity model.
  </Card>
</CardGroup>