---
audience: developer
summary: The `scaiwave` command-line tool.
title: CLI reference
path: reference/cli
status: published
---

# CLI reference

`scaiwave` — operator and developer tooling. Installed as part of the
ScaiWave Python package; available wherever you can run the venv.

```bash
scaiwave --help
```

## Top-level structure

```text
scaiwave
├── sync                        # ScaiKey identity sync
│   ├── register
│   ├── status
│   └── (default)               # full sync
├── admin                       # tenant + partner admin
│   ├── list-tenants
│   ├── create-tenant
│   ├── federation
│   │   └── key {generate|rotate}
│   └── ...
├── role                        # role management
│   └── ...
├── room                        # room export / import
│   ├── export
│   └── import
└── (top-level convenience commands)
    ├── register
    ├── status
    ├── show-config
    └── export-env
```

## sync

ScaiKey identity reconciliation.

```bash
scaiwave sync register           # interactive: register this server with ScaiKey
scaiwave sync status             # registration / drift status
scaiwave sync                    # run a full reconcile (idempotent)
```

The full sync also runs every 10 minutes off-zero as an ARQ cron;
this command is for manual runs. See
`docs/integrations/scaikey/sync.md`.

## admin

### list-tenants

```bash
scaiwave admin list-tenants
```

Tabular dump: slug, name, member count, room count, storage, AI
tokens MTD.

### create-tenant

```bash
scaiwave admin create-tenant --slug acme --name "Acme Corp" \
  --scaikey-tenant-id <id>
```

For partner-managed tenants, pass `--partner-id`.

### federation key

```bash
scaiwave admin federation key generate   # initial key
scaiwave admin federation key rotate     # new key, 30-day overlap
```

## room

### export

```bash
scaiwave room export <room-id> --tenant <tenant-slug> > out.zip
```

Pipes a ZIP bundle to stdout. Same content as
`GET /v1/rooms/{id}/export`.

### import

```bash
scaiwave room import <workspace-id> --tenant <tenant-slug> \
  --as <participant-id> < bundle.zip
```

## Convenience commands

These are aliases for the most-used sub-commands; useful in shell
scripts.

| Command | Equivalent |
|---|---|
| `scaiwave register` | `scaiwave sync register` |
| `scaiwave status` | `scaiwave sync status` |
| `scaiwave show-config` | `scaiwave sync show-config` |
| `scaiwave export-env` | `scaiwave sync export-env` |

## Backfill scripts

Not part of the `scaiwave` entry-point but useful operator tooling
under `scripts/`:

```bash
# Backfill the search index for historical messages.
.venv/bin/python scripts/backfill_search_index.py --execute --inline

# Smoke-test ScaiGrid service-token path.
.venv/bin/python scripts/scaigrid_service_token_smoke.py

# Push docs to scailabs.ai.
.venv/bin/python scripts/publish_docs.py --execute
```

Run them from the project root with the venv activated.

## Authentication

Every CLI command that talks to ScaiKey or ScaiGrid uses the same
configuration as the API server (env vars in `.env`). For
production use, the operator's environment should have the right
admin scopes — typically a service account with `tenant_admin` or
`partner_admin` role.

For one-off admin sessions:

```bash
export SCAIWAVE_ADMIN_TOKEN="..."
scaiwave admin list-tenants
```

## Exit codes

| Code | Meaning |
|---|---|
| 0 | Success. |
| 1 | Domain error (e.g. tenant not found, bad slug). |
| 2 | Configuration error (missing env, unreachable backend). |
| 3 | Auth error. |