@datarails-ai/dr-cli 0.0.1-locked → 1.6.71

package/dist/skills/dr-cli/reference/admin.md

@@ -0,0 +1,796 @@
+# IT / admin / misc
+
+## Auth / impersonation
+
+- `login --server <key>` — browser device flow; the operator's own login.
+- `login-as <email> --server <key>` — impersonate a user with **JWT only**
+  (no browser). Requires an operator `login` first. Resolves the email to a
+  user id via `can_login_as` (or pass `--user-id <n>`), mints an impersonation
+  JWT from the monolith (`POST /jwt/api/loginas/`) authorized by the operator,
+  and stores it as a switchable identity keyed by `(server, email)`. Target it
+  afterward with `--account <email>`. `--as <operator-email>` selects the
+  operator when several are stored. The token refreshes silently and
+  auto-remints from the operator if its refresh dies — no re-prompt until the
+  operator's own login expires. Denials surface as clear messages
+  (not permitted / inactive / unavailable). `whoami --account <email>` shows
+  `Impersonated by:`.
+  - **Skipping the email lookup.** The email→id resolution is an extra
+    round-trip against the user directory before the mint. If it errors or times
+    out, get the id once and bypass it:
+    `dr users can-login-as --search <email> --json` → `--user-id <n>`. Same for
+    scripted runs over many users: resolve the ids up front, then pass
+    `--user-id` so a directory hiccup can't fail the batch mid-way.
+  - **Requires dr ≥ 1.3.24.** `login-as` shipped in 1.3.24; older installs
+    answer `unknown command 'login-as'`. If the browser Login-As works but the
+    CLI "can't", check `dr --version` first and `dr update` — that, not a
+    permission block, is the most common cause of "the CLI won't let me".
+  - **The product `SUPER_ADMIN` role is NOT Django `is_superuser`.** The gate
+    (`IT.helpers.it_loginas`, wired as Django's `CAN_LOGIN_AS`; the JWT view
+    resolves it via `_loginas_permitted` — same gate as the browser Login-As)
+    blocks only genuine Django **`is_superuser`**, sync-service, or application
+    targets. A customer/demo user whose *product* role is `SUPER_ADMIN` is
+    still impersonable. **Verified on DEMO:** `login-as superadmin@demo.<org>`
+    (product role SUPER_ADMIN, `is_admin: true`) minted successfully, same as a
+    CONTRIBUTOR. So a `can_login_as` hit is generally reliable; there is **no**
+    "equal-or-higher privilege" rule.
+  - **When `not_permitted` really does fire:** the target is a true Django
+    superuser / sync-service / application user, **or** you (the operator)
+    lack scope — a Django superuser operator can impersonate any non-superuser;
+    a supporting-manager operator only users in their supported orgs
+    (`profile.get_supporting_login_as_organization_users()`). Note the CLI
+    `users get` payload exposes `profile.role` (product role) but **not**
+    `is_superuser`, so you can't confirm the Django flag from the CLI.
+
+## Users
+
+- `users list`, `users get`, `users me`.
+- `users can-login-as` — users the operator can impersonate; `--search`,
+  `--limit`, `--all`, `--json`. Feeds the email→id lookup for `login-as`.
+  It can list a genuine Django superuser / sync-service / application account
+  that the mint will still refuse (the gate is applied at mint time), but for
+  ordinary customer accounts — including product `SUPER_ADMIN`-role users — a
+  hit is reliable. See the gotcha above.
+- `users set-password <user_id>` — set a new password on a **sync-service
+  account only** (`profile.is_sync_service === true`). Refuses every other user
+  up-front; regular humans authenticate via Descope/SSO and must use the
+  product's "Send a reset password link by email" flow instead. The new value
+  is read from an interactive hidden TTY prompt — there is no `--password` flag
+  and stdin is required (refuses non-TTY to avoid silent hangs); paste works.
+  Text mode prints the target's email + org for sanity-check before the prompt;
+  `--json` skips that preamble and emits `{"id":…,"email":"…","ok":true}` on
+  success. Server-side complexity rejections (HTTP 400 with
+  `{password:[…]}`) are surfaced verbatim as bullet lines so the operator sees
+  the exact policy that failed. PUTs `/api/it/users/<id>/set_password`,
+  mirroring the FE `dialog-user-set-password.component.ts` path.
+
+### `users bulk-create` — invite many users from a CSV
+
+`users bulk-create --file <csv> [--organization <id>] [--no-register-identity] [--confirm] [--json] [--timeout <seconds>]`
+automates the UI's **Invite Users → Set Permissions** flow for a whole list:
+one backend call to create each user (`POST /api/it/users`), then one to scope
+their data access (`POST /api/it/users/<id>/permission_groups`). Turns an
+hours-long manual job into seconds.
+
+**No passwords, SSO as normal.** This never sets or sends a password. The
+server creates each user with a random throwaway password it never surfaces and
+sends the standard invite (`send_invite_mail_or_ciam` — the Descope/CIAM path),
+exactly like a UI invite. Invited users onboard through the org's **default
+SSO/Descope login** — identical to inviting them one-by-one. There is no
+`--password` here (that's `users set-password`, sync-service accounts only).
+
+**CSV format** (header is exact; comma-delimited, so multi-group cells use `;`):
+
+```csv
+email,first_name,last_name,role,permission_groups,department,job_role,register_identity
+jane.doe@acme.com,Jane,Doe,VIEWER,US Sales;Marketing Reports,FINANCE_FPA,ANALYST_OR_SPECIALIST,true
+john.roe@acme.com,John,Roe,VIEWER,EMEA Sales,SALES,MANAGER,
+sam.lee@acme.com,Sam,Lee,VIEWER,US Sales;EMEA Sales;Exec Dashboards,,,false
+```
+
+| Column | Required | Notes |
+|--------|----------|-------|
+| `email` | ✅ | Unique per file. The only truly required field. |
+| `first_name` / `last_name` | – | Optional. |
+| `role` | – | Blank ⇒ `VIEWER`. Accepts `VIEWER`, `COLLABORATOR`, `CONTRIBUTOR`, `ADMIN` (the privileged `SUPER_ADMIN`/`DR_CONNECT_ADMIN` are rejected on purpose). |
+| `permission_groups` | – | `;`-separated group **names** (not ids), resolved case-insensitively against `dr organizations permission-groups`. This is the data-access column; blank = invited but sees nothing until scoped. |
+| `department` / `job_role` | – | Optional enum names (e.g. `FINANCE_FPA`, `MANAGER`); validated server-side. |
+| `register_identity` | – | **Optional 8th column.** Per-row control over identity-provider registration + invite email. `true`/blank ⇒ register + invite on create (the default). `false` ⇒ defer — create the user without IdP registration / invite (register later with `register-identity`). **Omit the column entirely and every row defaults to `true`** (back-compat). `--no-register-identity` forces `false` for the whole batch regardless of this column. |
+
+> **`bulk-create` does not create groups — the name must already exist.** Any name
+> in the `permission_groups` column is resolved against existing groups; an unknown
+> name aborts the run (fail-fast) before any user is created. Pre-create groups
+> with **`dr organizations create-group`** (see Organizations below) or in the web
+> UI's Permission Groups settings. On a brand-new org with no groups yet, leave the
+> column blank (users are invited unscoped) and pass `--organization <id>` since the
+> target org can't be inferred without groups.
+
+Ready-to-edit templates ship at `docs/examples/users-bulk-create.csv` (with
+permission groups) and `docs/examples/users-bulk-create-no-groups.csv` (blank
+`permission_groups` — invite unscoped, e.g. into a fresh org).
+
+**Big CSVs finish in one run — do not chunk them.** The whole-command budget is
+sized to the work: 30s of base, plus 5s per **round-trip** (not per row — one row
+that fans out to N calls is sized as N), capped at 30 minutes. A 140-row CSV gets
+~12 minutes, which is far more than the ~5 minutes it actually needs.
+
+`--timeout <seconds>` raises that budget for something unusually large or a very
+slow tenant. It is a **floor, not a cap**: auto-sizing may still widen it, so a
+value smaller than what the plan needs costs you nothing. Max 86400 (24h). Past
+~354 round-trips the 30-minute ceiling starts biting and the per-call allowance
+decays — the command warns on stderr when that happens, and `--timeout` is the
+answer if the run then aborts part-way.
+
+> **If a run ever stops partway and the CLI says `session expired; re-login
+> required`, do not conclude the JWT expired.** dr-cli auto-refreshes the JWT
+> (proactively at a 60s buffer, and again on any 401), so a mid-batch expiry is
+> not a thing you need to work around. That message was historically what a
+> whole-command *timeout* looked like when the abort happened to land inside the
+> auth pre-flight. Re-logging-in and re-running in smaller chunks "worked" only
+> because each run restarted the clock. The fix is the sized budget above, or
+> `--timeout`, not chunking and not a re-login.
+
+**Deferring registration — create quietly, invite later.** By default each
+create registers the user in the identity provider (Descope) and sends the
+invite email — on prod, registration *is* the invite email (one atomic Descope
+call). Two ways to defer that:
+- **Per row:** set the `register_identity` column to `false` on the rows you
+  want deferred (blank/absent ⇒ `true`). Lets one CSV mix invited and deferred
+  users.
+- **Whole batch:** pass **`--no-register-identity`**, which forces every row to
+  `false` regardless of the column.
+Deferred users still get the row, async data-model provisioning, and seat-limit
+alert — they just can't authenticate until registered. Stand up an environment
+silently, then fire the invites with **`users register-identity --file <same
+csv>`** (below). The command sends `register_identity: false` only for deferred
+rows; a fully-invited run's create body is unchanged. See DR-52009.
+
+**Safety model:**
+- **Dry-run by default.** Without `--confirm` the command parses the CSV,
+  resolves every group name + the target org, prints the plan, and makes **zero
+  mutating calls**. Nothing is created (and no invite emails go out) until you
+  re-run with `--confirm`.
+- **Fail-fast before any write.** A typo'd/unknown group name, an ambiguous
+  name, or a duplicate email aborts the whole run *before* the first user is
+  created — you never get a half-built batch.
+- **Target org.** Auto-resolved from the tenant's permission groups (the create
+  endpoint requires an org id and the profile endpoint doesn't expose one).
+  Pass `--organization <id>` to be explicit, or when the tenant has no groups /
+  groups spanning multiple orgs (the command asks for it in those cases). The
+  resolved org **name** is printed so you can eyeball the target before
+  confirming — the guard against creating users on the wrong tenant.
+- **Per-row isolation on execute.** An already-existing email is **not created
+  again**, but if the row lists permission groups those groups are **assigned to
+  the existing user** (reported as `re-scoped`). This makes re-runs idempotent
+  *and* self-healing: a row that created a user but then failed to scope them
+  (see below) is repaired on the next `--confirm` run. Assignment is **additive**
+  — it only adds groups, never removes existing access. A row with no groups on
+  an existing email is simply `skipped`. A hard failure is recorded and the batch
+  keeps going; any failure makes the command exit non-zero, with a
+  created/re-scoped/skipped/failed summary.
+- **Partial-failure remediation (`failed` rows).** A row that reports
+  `created (id N) but group assignment failed` means the user exists but is
+  **unscoped** — fix the group name if it was rejected, then re-run the same CSV
+  with `--confirm`: the create step finds the user already exists and re-scopes
+  it. A row reporting `already exists but could not resolve its user id` means
+  the operator can't see that user via `/api/it/users` (usually a different org)
+  — assign the groups in the UI or check `--organization`.
+- Requires an **org-admin or supporting-manager** login (same gate as the UI
+  invite); a support/CSM account with those rights on the tenant works. Note the
+  re-scoping behavior means this command can **grant data access to users that
+  already existed**, not just ones it creates — the printed org name + `--confirm`
+  gate are your guard against doing that on the wrong tenant.
+
+### `users set-email` — change one user's login email
+
+`users set-email <user_id> <new_email> [--confirm] [--json]` changes a user's
+**login email** through `PUT /api/it/users/<id>` — the same endpoint the IT
+admin edit dialog uses. The PUT (not a PATCH) is deliberate: it lets the
+server's SSO/CIAM email-sync run, and it preserves the user's
+`excel_online_email` rather than blanking it.
+
+- **Dry-run by default.** Without `--confirm` the command GETs the user and
+  prints `current_email -> new_email` (or the same as JSON) and makes **zero
+  mutating calls**. Re-run with `--confirm` to apply.
+- **Validation.** The `<user_id>` must be positive and `<new_email>` must
+  contain `@`, both checked before any network call. A target already taken by
+  another user fails with `email already in use: <email>. Pick a different
+  address.` (server `EmailInUseError`).
+- On success `--json` emits `{id, previous_email, email}`.
+
+### `users bulk-set-email` — rename many users' emails from a CSV
+
+`users bulk-set-email --file <csv> [--confirm] [--json] [--timeout <seconds>]` applies many login-email
+renames in one run, each row reusing the same `PUT /api/it/users/<id>` path as
+single-user `set-email`. Same shape as `bulk-create` / `bulk-permissions`:
+resolve + validate the whole file first, then execute with per-row isolation.
+
+**CSV format** (header is exact, in order):
+
+```csv
+source,target
+old.jane@acme.com,jane.doe@acme.com
+old.john@acme.com,john.roe@acme.com
+```
+
+| Column | Required | Notes |
+|--------|----------|-------|
+| `source` | ✅ | The user's **current** email; must contain `@`; matched case-insensitively against tenant users; unique per file. |
+| `target` | ✅ | The **new** email; must contain `@`; unique per file; a row whose `source` == `target` is rejected. |
+
+A ready-to-edit template ships at `docs/examples/users-bulk-set-email.csv`.
+
+**Safety model:**
+- **Fail-fast before any write.** `planEmailRenames` aborts the whole run
+  *before* the first PUT when: a `source` matches no tenant user; the batch
+  spans **more than one organization** (all sources must belong to a single org
+  — the org name + id are printed so you can eyeball the target); a source user
+  has **no organization** (can't verify the same-org rule); or a `target` is
+  already in use by an existing user. If that existing user is itself a source
+  in the batch, it's a **swap/chain**, which is unsupported (renames apply
+  sequentially, not atomically) and also aborts.
+- **Dry-run by default.** Without `--confirm` it prints the resolved plan
+  (`source -> target (id N)` per row) and changes nothing.
+- **Per-row isolation on execute.** With `--confirm` each rename runs in order;
+  a row failure (e.g. a race where the target got taken) is recorded as `failed`
+  and the batch continues. A non-empty failure set makes the command exit
+  non-zero after reporting every row's `changed`/`failed` status. `--json`
+  emits `{organization, results, attempted, planned}` even if the run aborts
+  mid-way.
+- Requires the same **org-admin / supporting-manager** login as the other IT
+  user commands.
+
+### `users set-email-notifications` — turn one user's notification email on/off
+
+`users set-email-notifications <user_id> --enable|--disable [--confirm] [--json]`
+is the CLI equivalent of the **"Enable notifications"** Yes/No field in the
+admin user-edit form. It writes `disable_emails` through the same
+`PUT /api/it/users/<id>` the dialog uses. Exactly one of `--enable` /
+`--disable` is required.
+
+- `--enable` → the user **receives** notification mail (`disable_emails=false`).
+- `--disable` → the user receives none (`disable_emails=true`).
+- **Dry-run by default.** Without `--confirm` it prints
+  `notifications off  ->  on` and makes zero mutating calls; it also says so
+  when the user is already in the requested state.
+- **Only `disable_emails` changes.** The write body is deliberately minimal —
+  `{disable_emails, email, excel_online_email}` — with `email` echoed back
+  **unchanged** from the GET. Sending no `email` would make the server compare
+  the stored address against `None` and run its SSO email-sync for a change
+  that isn't happening; `excel_online_email` is echoed because the server
+  clears it when the key is absent. Role, department, job role, organization
+  and block status are all left untouched.
+
+**Sync-service and support accounts are refused**, with a message naming why —
+they are provisioned with notifications off and the platform does not send them
+notification mail. The bulk command skips them for the same reason, so the two
+verbs never disagree about the same user. (The server would actually accept the
+write: its sync-service override only fires when `is_sync_service` is in the
+payload, which this minimal body never sends.)
+
+**Accounts with a malformed stored email can't be toggled.** Because the write
+echoes the current address back, the server re-runs its email validation over
+it. A user whose stored address isn't a valid one (no TLD, legacy seed data)
+fails with a message naming the address and pointing at
+`users set-email <id> <valid@address>` as the prerequisite. The admin UI has
+the same limitation — its edit payload echoes `email` too — so this is a
+property of the endpoint, not of the CLI.
+
+**Blocked users are the one surprise.** The server reports notification state
+as `disable_emails OR is_blocked`, so enabling a blocked user succeeds but
+`users get <id>` keeps showing notifications off until the user is unblocked.
+The command prints an explicit note saying the write landed and no retry is
+needed — don't re-run it.
+
+**An unreported current state stays `unknown`.** The server omits `profile`
+entirely for some accounts, and `disable_emails` is optional even when
+`profile` is present. Where the field is missing the preview prints
+`notifications unknown  ->  on`, never claims "already in the requested
+state", and `--json` reports `current_email_notifications: null` with
+`no_change: null` (and `previous_email_notifications: null` after the write).
+The requested write still goes ahead — you asked for a specific user — but
+nothing in the output asserts a starting state we have no evidence for. The
+bulk command, which was not asked about any one user, skips those users
+instead.
+
+To find who is affected on a tenant, `users list` now renders an
+`EMAIL_NOTIF` column, and `users list --email-notifications off
+[--organization <id>]` filters directly to the users who receive nothing.
+
+### `users bulk-set-email-notifications` — same toggle, whole organization
+
+`users bulk-set-email-notifications --organization <id> --enable|--disable
+[--only-changed] [--confirm] [--json] [--timeout <seconds>]` applies the toggle to every user in one
+organization. There is **no org-level notification setting** in the data model —
+the flag lives on each user — so this is a per-user write loop, shaped like
+`bulk-set-email`: plan first, dry-run by default, per-user isolation on execute.
+
+**Always skipped, without being asked:**
+
+| Skipped | Why |
+|---------|-----|
+| sync-service users | Provisioned with notifications off; the platform sends them no notification mail, so the setting has no effect. The single-user command refuses them for the same reason. |
+| support users | Provisioned with notifications off by design. |
+| users whose state the server didn't report | State unknown; writing blind could flip someone you didn't mean to touch. |
+| users already in the requested state | Only with `--only-changed`, and **never** for a blocked user — see below. |
+
+**Safety model:**
+- **Fail-fast.** An `--organization` matching no users aborts before any write
+  rather than reporting an empty plan — the usual cause is a wrong org id.
+- **Dry-run by default.** Without `--confirm` it prints the full plan
+  (`~ email (id N)  off -> on`, `[blocked]` where relevant) plus every skipped
+  user and its reason, and changes nothing.
+- **Per-user isolation on execute.** A failed user is recorded and the batch
+  continues; a non-empty failure set exits non-zero, names the failed ids, and
+  points at `--only-changed` to retry just the remainder. `--json` emits
+  `{organization, email_notifications, results, skipped, attempted, planned}`
+  even if the run aborts mid-way.
+- **`--only-changed` never skips a blocked user.** Their read state is
+  `_disable_emails OR is_blocked`, so it always says "off" and reveals nothing
+  about the stored column. Skipping on it would pass over a blocked user still
+  stored as enabled during `--disable --only-changed`, and they would start
+  receiving mail the moment they were unblocked. Blocked users are always
+  written.
+- Blocked users in the batch get one summary note, for the same read-back
+  reason as the single-user command.
+
+### `users register-identity` — send the deferred invites for a `--no-register-identity` batch
+
+`users register-identity --file <csv> [--confirm] [--json] [--timeout <seconds>]` is the second half
+of the `bulk-create --no-register-identity` flow (DR-52009): it registers the deferred
+users in the identity provider and sends the invite email that create skipped.
+**Feed it the SAME CSV** you bulk-created from — it only reads the `email`
+column (all other columns are ignored), resolves each email to its tenant user
+id via `GET /api/it/users`, and calls `PUT /api/it/users/<id>/register_identity`
+per row. That endpoint uses the *same* invite path as create, so the resulting
+email is identical to an immediate invite (**not** a password-reset).
+
+**Safety model:**
+- **Dry-run by default.** Without `--confirm` it resolves every email and prints
+  the plan — `~ email (id N)` for resolved rows, `! email (NOT FOUND …)` for
+  emails not in the tenant — and makes **zero** mutating calls. Re-run with
+  `--confirm` to register + invite.
+- **Honest per-row status** (from the server's contract): `registered` (200
+  `{"sent":true}` — newly provisioned + emailed), `already_exists` (200
+  `{"sent":false}` — the identity was already in the IdP, a safe no-op), or
+  `failed` (a 502 `provider_error` from the IdP, an email not found in the
+  tenant, or any other error). The run prints a `registered / already_exists /
+  failed` summary.
+- **Per-row isolation + idempotent re-runs.** A failed row is recorded and the
+  batch keeps going; **only a non-empty `failed` set makes the command exit
+  non-zero**. Because an already-registered user reports `already_exists` (not
+  `failed`), re-running the same CSV after a partial batch only retries the ones
+  that didn't land. `--json` emits `{results}` with per-row `{line, email,
+  status, user_id, detail?}`.
+- Requires the same **org-admin / supporting-manager** login as the other IT
+  user commands (server enforces `IsAuthenticatedOriginalITAdmin`).
+
+> **Note (adjacent monolith bug DR-52121):** the deferred invite emails because
+> a monolith comparison bug forces `send_mail=True`. That's the desired behavior
+> here, but a future DR-52121 fix must keep passing `send_mail=True` or deferred
+> (and inline) invites will silently stop emailing.
+
+### `users permissions` — the Permission Manager (data tables + elements)
+
+The CLI surface of the web **Permission Manager** (`/#/it/users/:id/permissions`).
+**Requires the `use_new_table_perms` product flag on the tenant** — verify with
+`dr features orgs list <org_id>`; the new grant/revoke endpoints this uses are
+only active when it's on. All *write* subcommands are **dry-run unless
+`--confirm`** (like `bulk-create`), and support `--json`.
+
+```console
+users permissions get <user_id>
+users permissions set-role <user_id> --role <ROLE>                         [--confirm]
+users permissions grant-table   --email <e> --table <id[,id]> --role <ROLE> [--confirm]
+users permissions revoke-table  --email <e> --table <id[,id]>               [--confirm]
+users permissions grant-element  --type <T> --email <e> --id <id[,id]> --role <ROLE> [--confirm]
+users permissions revoke-element --type <T> --email <e> --id <id[,id]>               [--confirm]
+users permissions set-filters   <user_id> --file <json>                    [--confirm]
+users permissions remove-group  <user_id> --group <id>                     [--confirm]
+```
+
+- `get` prints identity, org role, permission-group membership, and the user's
+  **per-table roles** (`GET /api/templates?user_to_check_role_id=<id>` — only
+  tables with a direct personal role are listed; group-derived access is
+  annotated), and the user's **row-level data-access filters**
+  (`GET /api/it/users/<id>/permission_filters?include_inherited=true` — direct +
+  group-inherited, shown as `Table.Field in/not in [values]`). A **Super Admin**
+  shows a full-access note instead of grants. Per-**element** role read-back and
+  filter *authoring* (`POST …/permission_filters`) are **not** assembled yet
+  (DR-51917 follow-ups).
+- **Common trap — "the user has no table permissions".** Do **not** answer
+  "what tables can this user see?" from the raw `GET /api/it/users/<id>` object's
+  `permissions` field. That field is Django **global model-level** perm codenames
+  (`user.user_permissions`) and is **empty for essentially every VIEWER** — it
+  never reflects table access. Real table access lives as **guardian object-level
+  roles per table**, visible only via the `user_to_check_role_id` sweep that this
+  `get` runs. Always use `users permissions get <id>` (or the sweep directly); an
+  empty top-level `permissions: []` is **not** evidence of no access.
+- **`CUSTOM` role in a read/export.** The sweep can report a role of
+  `{id: -1, name: "CUSTOM", label: "Custom"}`. This is a **server sentinel**, not
+  a catalog role — `BackOffice/serializers.py` returns it whenever the user's
+  perms on that object don't map to a named preset role. On a plain VIEWER it
+  corresponds to the web UI's **"No access"**; treat/label it as no access (or a
+  bespoke perm set), never as a grantable role.
+- `set-role` changes the **org role** via `PUT /api/it/users/<id>/permissions`
+  `{role: <NAME>}` — `VIEWER | CONTRIBUTOR | COLLABORATOR | ADMIN | SUPER_ADMIN`
+  (the `UserProfileRole` PK is the name). Server-side guards (SUPER_ADMIN
+  promotion needs a super-admin operator, `COLLABORATOR` needs `use_new_table_perms`,
+  seat limits) surface verbatim.
+- `grant-table` / `revoke-table` drive `POST /api/templates/users/grant_permissions_bulk`
+  (`role: null` revokes). Note the path is `/api/templates/…`, not `/api/tables/…`
+  — the monolith mounts the Tables app under `/api/templates/` (a `/api/tables/…`
+  POST 404s). The `--role` name is resolved case-insensitively against
+  `GET /api/permissions/roles/table` — role names are the full enum keys, e.g.
+  `OWNER_TABLE_ROLE`, `VIEWER_TABLE_DATA_ROLE`.
+- `grant-element` / `revoke-element` cover **every category in the web Permission
+  Manager's Elements pane**. `--type` is one of
+  `dashboard | storyboard | filebox | lookup | model | report | datasource`, each
+  mapped to its app + role catalog:
+
+  | `--type` | web category | grant endpoint | role catalog |
+  |---|---|---|---|
+  | `dashboard` | Dashboards | `POST /api/dashboards/users/grant_permissions_bulk` | `roles/dashboard` |
+  | `storyboard` | Storyboards | `POST /api/storytelling/users/grant_permissions_bulk` | `roles/story` |
+  | `filebox` | Input fileboxes | `POST /api/documents/users/grant_permissions_bulk` | `roles/files_box` |
+  | `lookup` | Lookup fileboxes | `POST /api/documents/users/grant_permissions_bulk` | `roles/files_box` |
+  | `model` | Model fileboxes | `POST /api/documents/users/grant_permissions_bulk` | `roles/files_box` |
+  | `report` | Reports | `POST /api/filebox_reports/users/grant_permissions_bulk` | `roles/filebox_reports` |
+  | `datasource` | Data sources | `POST /api/v3/data_integrations/data-sources/users/grant_permissions_bulk` | `roles/data_source` |
+
+  `--id` is the entity id (dashboard/story/document/report-space/data-source id),
+  repeatable or comma-separated. `filebox`, `lookup`, and `model` share the
+  Documents surface — they differ only by which documents the web UI lists; grant
+  by id is identical. **`datasource` caveat:** `roles/data_source` is **empty
+  unless the tenant has the `new_data_sources_perms_and_roles` flag on**, so
+  `--role` resolution fails with an empty valid-role list when it's off.
+- **`report` caveat:** grants at the report-*space* level only; the web UI also
+  cascades to the report's nested documents via a second `/api/documents/...` call
+  — not yet mirrored here (DR-51917).
+- `set-filters` replaces the user's **row-level data-access filters** via
+  `POST /api/it/users/<id>/permission_filters`. **This is a FULL REPLACE** — the
+  server deletes every existing own filter and recreates from the file, so pass
+  the complete desired set (an empty array clears them all). `--file` is a JSON
+  array (or `{"new_filters":[…]}`) of `{field:<FlatTableField id>, values:[…],
+  is_excluded?:bool}`. `is_excluded:true` makes it a deny-list. Dry-run prints
+  the intended set and the replace warning; `--confirm` applies. (Filter *reads*
+  are shown by `get`.)
+- `remove-group` deletes one membership (`DELETE /api/it/users/<id>/permission_groups/<gid>`);
+  the additive *add* is done by `bulk-create`'s `permission_groups` column.
+- Every write subcommand echoes a `Target: account <server>, operator <email>`
+  line first (text mode only) so a mis-set `--account`/`--server` is visible
+  before — and after — a mutation lands. Under `--json` the line is suppressed so
+  output stays a single parseable object.
+- With `--json`, every write subcommand emits structured JSON on **both** paths:
+  the dry-run object carries `"dry_run": true`; the confirmed object omits it. So
+  a script can diff the two without parsing prose.
+
+### `users bulk-permissions` — many Permission-Manager grants from a CSV
+
+`users bulk-permissions --file <csv> [--confirm] [--json] [--timeout <seconds>]`
+
+The bulk counterpart to `users permissions` — applies the four grant kinds above
+from one CS-authorable CSV instead of one flag-driven call at a time. Same
+`use_new_table_perms` requirement, same **dry-run unless `--confirm`** / `--json`
+model. Header (exact, seven columns): `email,resource,type,ids,role,filter_values,filter_excluded`.
+One row = one grant, discriminated by `resource`:
+
+| `resource` | maps to | row shape |
+|---|---|---|
+| `table` | `grant-table` | `ids` = `;`-sep table ids, `role` required |
+| `element` | `grant-element` | `type` = filebox/lookup/model/report/dashboard/storyboard/datasource, `ids` = `;`-sep, `role` required |
+| `role` | `set-role` | `role` = org role; `ids`/`type`/`filter_*` blank |
+| `filter` | `set-filters` | `ids` = one FlatTableField id, `filter_values` = `;`-sep, `filter_excluded` blank/`true`/`false` |
+
+- **Resolves everything first and fails loud before any write:** every `email`
+  must exist on the tenant, and each `table`/`element` `role` must resolve against
+  that surface's role catalog (org roles and filter field ids are validated
+  server-side, per row). A typo aborts the whole run before a single grant lands.
+- **`filter` rows are full-replace, aggregated per user:** all `filter` rows for
+  one email are collected into a single `POST …/permission_filters`, so the CSV
+  must list that user's *complete* desired filter set (re-run idempotency depends
+  on it). Grants (`table`/`element`/`role`) are additive.
+- **Per-row isolation on apply:** a failed row is reported, the batch continues,
+  and any failure exits non-zero. A corrected re-run is safe for `table`,
+  `element`, and `role` rows (additive); a `filter` re-run must still carry each
+  user's *complete* set, since the full replace deletes any omitted filter.
+- Requires an org-admin / supporting-manager / contributor operator (same as the
+  per-item grants). Ready template: `docs/examples/users-bulk-permissions.csv`.
+
+## Organizations
+
+Alias `orgs`.
+
+- `organizations list [--mini]`, `organizations get`.
+- `organizations contacts` — per-tenant user directory (the source for
+  share-with-user pickers); `role` is `ADMIN|CONTRIBUTOR|VIEWER`.
+- `organizations permission-groups` — **lists** named user bundles (same role
+  enum + `members[]`). Read-only (`GET /api/organizations/permission_groups`).
+- `organizations create-group --org <id> --name <n> [--role <VIEWER|CONTRIBUTOR|ADMIN>]
+  [--member <email> ...]` — **creates** a permission group via
+  `POST /api/it/permission_groups` (the IT app — a different endpoint from the
+  list above). `--org` is sent in the body and must be one of your accessible
+  tenants (else 403); `--name` is unique per org. `--role` is upper-cased;
+  `--member` is repeatable and each must be accessible to you, in the target org,
+  and not outrank `--role`. **Dry-run unless `--confirm`**; `--json` on both
+  paths. Requires an org-admin / supporting-manager / contributor operator. This
+  is the group-creation the web UI's Permission Groups settings does — and the
+  way to pre-create groups that `users bulk-create` then references.
+- `organizations update-group <id> --name <n>` — **renames** a group
+  (`PUT /api/it/permission_groups/<id>`). The IT update endpoint is **name-only**:
+  role is immutable and members are managed separately, so this changes the name
+  and nothing else. **Dry-run unless `--confirm`**; `--json` too. The server 403s
+  a rename of a default/system group (`is_editable:false`).
+- `organizations delete-group <id>` — **deletes** a group
+  (`DELETE /api/it/permission_groups/<id>`), behind the **two-step confirm-token**
+  flow like every other `delete`: the first run prints the group's
+  name/role/member count and a token; re-run with `--confirm-token <tok>`. Hard
+  delete that also removes the group's access to shared assets (members
+  themselves remain in Datarails). Prod-gate **Tier A**.
+- `organizations bulk-groups --file <csv> [--organization <id>] [--timeout <seconds>]` — **provisions
+  many groups + membership from one CSV** (header `group_name,role,members`,
+  exactly those three columns; `members` is `;`-separated emails — a stray comma
+  is rejected, not silently truncated, and duplicate emails are deduped
+  case-insensitively). Each row is classified against the tenant's existing
+  groups: an unknown name is **created** (`create-group`), a known name is
+  **augmented** — its listed members are added additively
+  (`POST /api/it/users/<id>/permission_groups`, a no-op for existing members).
+  `role` applies **only on create** (it's immutable on an existing group); a
+  blank `role` lets the server assign its default on create, and on augment
+  leaves the existing role untouched. Resolves everything first and **fails loud
+  before any write**: a member email not on the tenant, an ambiguous existing
+  group name (matches more than one group id), or a `role` cell that disagrees
+  with an existing group's role, aborts the whole run. **Dry-run unless
+  `--confirm`** — the sole write gate: this is additive + reversible, so unlike
+  `delete-group` it is *not* behind the two-step confirm-token flow. `--json` on
+  both paths; per-row isolation on apply (a failed row is reported, the batch
+  continues, non-zero exit if any failed). `--organization` is only needed to
+  place *created* groups, and only when it can't be derived from the tenant's
+  existing groups (none exist, or they span multiple orgs); an augment-only run
+  never requires it. Requires an org-admin / supporting-manager / contributor
+  operator (same as `create-group`). Ready template:
+  `docs/examples/organizations-bulk-groups.csv`.
+- `organizations push-targets` — the organizations this account may push a
+  dashboard or filebox into. **Run this before `dashboards push` / `filebox
+  push`**; those commands reject any destination not on this list.
+  - Requires admin or supporting-manager rights; a 403 surfaces verbatim.
+  - What you get back depends on the signed-in org: a **template** org
+    (`use_as_template=true`) sees its sibling orgs and their descendants; any
+    other org sees its own descendants. Both are full subtrees, not just direct
+    children. An empty list means there is nowhere to push.
+  - The list does **not** carry customer status, so it can include an inactive
+    org. `filebox push` to an `Opt-Out`/`Churn`/`On Hold` org is rejected by the
+    server with that reason.
+- `organizations add --domain <d> [--name <n>] [--license-type <l>]
+  [--category <c>] [--from-template <org_id>] [--use-as-template]
+  [--include-input-versions] [--payload-file <p>]` — a 403 (insufficient
+  permission) is surfaced verbatim; re-impersonate as needed.
+  - `--from-template <org_id>` clones the new tenant from an existing org; the
+    source must already have `use_as_template=true` on its row (else 400). There
+    is no CLI surface to flip that flag.
+  - `--include-input-versions` clones input file versions too (requires
+    `--from-template`; the lone flag is rejected client-side).
+  - The clone runs **asynchronously** — the POST returns 201 with a sparse org
+    row immediately; the new tenant's data lands a few minutes later.
+  - `--use-as-template` flags the **new** org as a template (off by default).
+
+`support-manager list` (alias `sm`).
+
+## Organization export / import (full-org migration)
+
+Move or duplicate a whole organization — same server under a new domain, or
+across servers (e.g. US → EU). Wraps `POST|DELETE /api/organizations/export`
+and `POST|DELETE /api/organizations/import` (the org clone-over-blob
+pipeline). **Requires a datarails.com admin or supporting-manager identity on
+every server involved** — a 403 means the active account isn't one (check
+`dr whoami`).
+
+**The completion contract (read this first).** Both POSTs return 200
+immediately and run server-side as background chains. **Completion is
+signaled ONLY by email** to the triggering operator
+(`EXPORT/IMPORT_ORGANIZATION_SUCCESS/WARNING/FAILED`) — there is **no status
+API to poll**, so there is no `--wait`. Do not chain export → import in one
+breath: trigger the export, stop, and only import after the export email
+confirms success. The imported org's row appears immediately, but the tenant
+is **not usable** until its email arrives — a "finished" import may still be
+partial (per-phase failures don't abort the run; the WARNING email lists
+what was skipped).
+
+The flow:
+
+1. **Export (on the source server):**
+   `organizations export create --domain <src> --new-domain <dest>
+   [--keep-user-passwords] [--allow-foreign-server] [--exported-before]`
+   - `--new-domain` is the full identity of the copy — it becomes both the
+     new org's domain AND its display name, and names the blob folder the
+     import reads. Omit only when re-importing under the same domain.
+   - **Passwords are hands-off.** A renamed export automatically randomizes
+     EVERY user password in the imported org — a fresh cryptographic secret
+     per org, sent to the server and recorded nowhere. The copy is simply not
+     reachable with knowable credentials; Datarails staff access it via
+     impersonation. For a REAL migration (users must keep logging in), pass
+     `--keep-user-passwords` to preserve source-org credentials.
+   - `--allow-foreign-server` is **required when the source server is not US**
+     and whenever the export will be imported on another server.
+   - A repeat export is rejected until you either pass `--exported-before`
+     (resume) or `export delete` the stale one — the error says which.
+2. **Wait for the export email.** No email = still running (or the chain
+   broke — a hard failure can die without any email; check with the RnD team
+   or Groundcover if it's been hours).
+3. **Import (on the target server):**
+   `organizations import run --domain <dest> [--temporary] [--no-skip-models]
+   [--imported-before]`
+   - `--domain` is always the **domain chosen at export** (the `--new-domain`
+     from step 1), NOT the source domain — it names the blob folder.
+   - Imports are **permanent by default**. `--temporary` opts into a
+     throwaway copy marked for auto-deletion by the server GC.
+   - Unknown model types in the blob are **skipped by default** (typical
+     version skew between servers; the completion email lists anything
+     skipped). `--no-skip-models` makes the import fail instead when the
+     blob carries model types this server cannot import.
+4. **Wait for the import email**, verify the tenant, then — **back on the
+   source server** — clean up:
+   `organizations export delete --domain <src> [--new-domain <dest>] --server <source>`
+   — removes the export record + blob only (org data untouched; two-step
+   confirm, Tier B). The source org must still exist on the server you call,
+   so clean up the export **before** ever deleting the source org (otherwise
+   the record is unreachable via this API and only the ~60-day server GC
+   removes it). `--allow-foreign-server` is only needed when deleting a blob
+   from a different env than the one that created it — not for the normal
+   same-server cleanup.
+
+**Desk is NOT part of this clone today.** The full org export/import copies
+Desk config only when the server lists `DESK_AI` in `LIST_OF_MICROSERVICES`
+(pending monolith work); tickets, teams and their members are not. To provision
+Desk in a demo org, run the org clone (or use an existing org) and then
+[`dr desk clone`](desk.md#clone-a-reference-orgs-desk-into-another-org-desk-clone-dr-52763),
+which matches-or-creates the users, teams and Desk data from a reference org
+without touching anything else.
+
+**Undo an import:** `organizations import delete-orgs --domain <dest>` —
+**PERMANENTLY DELETES the imported organization** (the full org-delete flow,
+all tenant data destroyed). Two-step confirm, prod word-gate (**Tier A**).
+The server only accepts domains created via the import API; anything else
+must go through the standard permanent-delete flow. The "successfully
+deleted" response acks the **dispatch** — deletion itself runs
+asynchronously, so the org can linger in `organizations list` for a few
+minutes before disappearing. The export blob is not touched — that cleanup
+is `export delete`.
+
+- `devices list`, `devices get`, `devices logs`,
+  `devices received-logs <machine_id>`, `devices commands <machine_id>`.
+- `devices request-logs <id>…`, `devices download-logs`,
+  `devices command-delete <cmd_id>` (two-step confirm-token flow).
+
+## Feature flags (IT)
+
+- `features list`, `features groups list`, `features groups get`,
+  `features orgs list <org_id>`.
+- `features orgs add <org_id> --flag …`, `features orgs remove <org_id> --flag …`
+  (both two-step confirm-token flow — flipping flags changes customer-visible
+  behavior).
+
+**Know the flag name? Skip the listing entirely.** `--flag` accepts a flag **id
+or name** (repeatable), and the server resolves it — so to enable/disable a flag
+you already know, go straight to `features orgs add <org_id> --flag <name>`. Only
+reach for `features list` when you need to *discover* or confirm a flag's exact
+name.
+
+**The two list shapes differ — don't confuse them:**
+
+- `features list` (the global catalog) is **paginated** — the `--json` is a DRF
+  envelope `{count, next, previous, results}` and returns only **one page**
+  (default 50; there are 270+ flags). A name grep on the default page silently
+  finds nothing for anything past #50. Pull the whole catalog in one shot with
+  `--page-size 500` (max 500), or walk `--page <n>`. This paginates in **both**
+  table and `--json` mode; the table footer says "Showing 1-50 of N (more
+  available — bump --page)".
+- `features orgs list <org_id>` is a **plain JSON array** of exactly the flags
+  **enabled/overridden for that org** — a flag's *presence* in this list is what
+  tells you it's on for the org. The `default_on` field on each row is the
+  flag's **global default**, NOT the org state (a flag can be enabled for the
+  org while `default_on:false`). To confirm an `orgs add` worked, check the flag
+  now *appears* here — don't read `default_on`.
+
+## Semantic tables / FX (finance-os)
+
+- `semantictables list|get|data|distinct` (alias `semtables`).
+- `fx rates`.
+
+### FX configuration (bulk enablement)
+
+- `fx set-posting <template_id> [--field <id|name>]` — mark the table's Monetary
+  **posting** amount (`fx_role: posting_amount`). Defaults to the field named
+  "Posting Amount" (case/underscore-insensitive). Refuses a second posting field.
+  Two-step confirm (`--confirm-token`); Tier B on prod.
+- `fx set-reporting <template_id>` — mark Monetary **reporting** amount(s) with
+  currency code + symbol. Three forms:
+  - no flags: heuristic, in this precedence — (1) a field already carrying a
+    reporting currency keeps it (so a re-run is a no-op, and such a field is listed
+    whatever it is named); (2) a currency in the field NAME, read wherever it sits —
+    `USD Amount`, `Amount USD`, `Reporting Amount (EUR)`, `Amount in GBP`,
+    `Reporting_Amount_USD` all work; (3) a single bare `Amount` / `Reporting Amount`
+    takes its code from the table's "Reporting Currency" column when that column
+    holds exactly one distinct value (otherwise the error tells you to map
+    explicitly). A name that contradicts the stored currency is refused, not guessed.
+  - `--field <id|name> --code <CODE> [--symbol <S>]` for one field;
+  - repeatable `--map "<field>=<CODE>[:<SYMBOL>]"` for several.
+  Symbols default from the FE's ISO catalog; codes validate against the catalog +
+  org custom currencies (`--allow-custom` bypasses, and then **registers** the
+  unknown code — see below). One reporting field per currency per table is
+  enforced. Two-step confirm.
+- **`--all-tables`** on both field commands sweeps every table in the org instead of
+  taking a template id — the onboarding shape. A table it cannot judge is reported and
+  **skipped, never guessed**: the plan separates tables that need a human decision
+  (ambiguous currency, two posting candidates, a currency collision) from tables that
+  simply are not FX tables, which are counted rather than listed. One confirm token
+  covers the whole sweep. `--field`/`--map`/`--code` name one table's fields, so they
+  cannot be combined with it; single-table mode still raises the detailed error with the
+  field roster.
+- `fx default-currency [<CODE>] [--none] [--confirm]` — show or set the **org-wide
+  default** reporting currency (`GET/PUT /api/v1/currencies/default-currency`), i.e. the
+  star in the dashboard dropdown. With no argument it prints the current default plus
+  every currency the org can offer (`organization-currencies`) — the answer to "what will
+  the selector show". `--none` records the "None" choice, meaning the posting currency.
+  A code the org cannot offer is refused (`--allow-unlisted` overrides), because a
+  default the selector cannot serve leaves every dashboard on a currency with no data.
+  Dry-run by default. **Setting it needs Super Admin server-side**, and the server has
+  the last word — the command reports what was stored, not what was sent. This matters
+  beyond the UI: an AI agent with no currency of its own uses this default.
+- `fx add-currency <CODE> [--symbol <S>]` — register an org-level custom currency
+  (`POST /api/v1/currencies/custom-currencies`), i.e. a code the ISO list doesn't
+  carry, such as `BUSD` for "budgeted USD" (compare actuals to budget without FX
+  noise). 2-5 letters/digits, upper-cased; re-running with a different `--symbol`
+  updates it, mirroring the web app. An ISO code is refused — there is nothing to
+  register. Not gated (additive org config, same as `cash currencies set-prefs`).
+
+> **Why registration matters.** The web app registers a custom code the moment
+> someone uses it, so the org's custom-currency list and the field's
+> `currency_code` never drift. `set-reporting --allow-custom` therefore registers
+> an unknown code itself, **before** writing the field, and aborts without touching
+> any field if that fails — a field pointing at a code the org doesn't know is the
+> exact state this avoids (the Tables dialog stops offering it). Use
+> `fx add-currency` to pre-register a code before a bulk run, or to fix a symbol.
+- `fx convert-functions [--template <id>] [--force-sum] [--off] [--confirm]` — set
+  `is_fx_aware: true` on every Excel/DR.GET function whose value field is Monetary
+  **and carries an fx_role**. Non-SUM functions are skipped unless `--force-sum`
+  switches them. **Dry-run by default** — always run once without `--confirm` and
+  read the plan.
+- `fx convert-widgets (--dashboard <id> | --all) [--force-sum] [--off] [--confirm]` —
+  same sweep for dashboard widgets (eligible = exactly one value field, Monetary,
+  with an fx_role). The server has the final say per widget; an echo that doesn't
+  confirm the flag is reported as a failure, not silently accepted. Dry-run by
+  default.
+
+**Eligibility is stricter server-side than in the web app.** `FxEligibilityService`
+requires the value field to be Monetary AND to have an `fx_role`; the serializer
+answers a flip on a role-less field with a **400**, not a silent skip. Both
+converters therefore report those as `needs-fx-role` and skip them — run
+`fx set-posting` / `fx set-reporting` first. Chain the four commands in that order:
+tag the posting field, tag the reporting fields, then sweep widgets and functions.
+
+**Rollback — `--off`.** Both converters take `--off` to sweep the other way and turn
+conversion off. It acts on the stored flag alone: eligibility and the aggregator are
+irrelevant to a rollback, and the aggregator is never touched (so `--off --force-sum`
+is refused). This deliberately reaches targets the enable direction would call
+ineligible — a widget whose value section has since gained a second field, or a
+function whose field lost its Monetary type, can strand a flag that nothing else can
+clear. Dry-run by default, same as the enable direction.
+
+## Knowledge base
+
+`kb search|get|categories|sections|articles-in-section|recent|attachments|article-images`.
+
+## MCP & skills (the binary's own surface)
+
+- `mcp register|unregister|list|serve`.
+- `skill list` (file count + total bytes per skill),
+  `skill print [name] [--file <relPath>] [--hash]` (defaults to `dr-cli`'s router
+  `SKILL.md`; `--file reference/<x>.md` prints a reference file),
+  `skill install <target_dir>`, `skill init-project [dir]`.
+- `update` (top-level) — self-upgrade the CLI in place.
+
+## Customer-facing docs (KB)
+
+Help Center → the **"User & Permissions"**, **"Billing"**, and **"Security & Legal"** categories. Find current articles with `dr kb search "users permissions billing security"` (or
+browse `dr kb categories` / `dr kb sections`). Cite the article; don't
+paraphrase from memory.