@staqon/cli 0.1.1 → 0.1.2

package/README.md

@@ -1,279 +1,311 @@
-# @staqon/cli
-
-Command-line client for the StaqOn partner API. Send messages, post comments, run push-approval
-verifications and broadcast ads as your workspace, from a terminal or a script.
-
-- Requires **Node.js 20 or newer**.
-- Talks to `https://staqon.one` by default (override with `--base-url` or `STAQON_BASE_URL`).
-
-## Install
-
-```sh
-npm install -g @staqon/cli
-staqon --version
-```
-
-## Getting started
-
-1. **The workspace owner creates an API key first.** Open your workspace at
-   `<your-workspace-url>/workspace/settings.php?w=<your-workspace-slug>&tab=api` and, under the
-   relevant card (Messaging API, Ad API, etc.), generate a key for the team you want the CLI to
-   act as. Messaging and Ad keys both require a **Link** key to already exist on that same tab �
-   set that up first if you see a "set up Link API first" notice.
-2. On that same `api` tab, turn on **"Allow CLI access"** for the workspace. This is a separate
-   switch from the API key above � it must be ON before `staqon login` can be approved. Turning it
-   OFF immediately signs out every CLI session for that workspace.
-3. Run `staqon login` from the machine or server you want to use. It prints a URL and a short code.
-4. The **workspace owner** opens that URL (it's also reachable directly at `/cli`) and approves the
-   code � they may be asked for their MPIN if their web session is old.
-5. Run `staqon whoami`. It lists every key the CLI can use and which teams hold it. If a command you
-   need isn't listed, go back to step 1 for that key type � the CLI itself can never create or see
-   API keys, only the owner can.
-6. Send your first message:
-   ```sh
-   staqon message send --email member@example.com -m "Hello from the CLI"
-   ```
-7. **Member approval (exit code 6).** Most calls that reach a specific member � direct messages,
-   comments, internal messages, verification requests � require that member to have approved
-   linking with your workspace in their own StaqOn app first. If they haven't, the CLI exits with
-   code 6 and a message like "This member hasn't approved linking with this workspace." This isn't
-   something the CLI or the owner can bypass � the member has to approve it on their end.
-
-## Sign in
-
-There is no separate `init` step: `staqon login` is the whole setup.
-
-```sh
-staqon login            # prints a URL and a one-time code
-staqon login --open     # also opens the URL in your browser
-```
-
-1. The CLI shows a verification URL and a code.
-2. **The workspace owner** opens the URL and approves the code (they may be asked for their MPIN).
-3. The CLI polls, receives a session token, and stores it.
-
-Where the token lives: the OS keychain when available, otherwise a user-only file
-(`credentials.json` in the `staqon` config directory: `%APPDATA%\staqon` on Windows,
-`$XDG_CONFIG_HOME/staqon` or `~/.config/staqon` elsewhere). The CLI says so when it has to use the file.
-
-| Command | What it does |
-|---|---|
-| `staqon whoami` | Workspace, session expiry, rate limits, and which teams can do what |
-| `staqon refresh` | Rotate the session token (the old one works for 5 more minutes) |
-| `staqon logout` | Forget the local token. Revoking it is done by the owner in the web UI |
-
-### Running unattended (a server sending automatic alerts)
-
-Session tokens are sliding-expiry: **90 days of inactivity invalidates them, and every call extends
-that window**, up to a hard cap of **1 year from the original login**. For a server that calls the
-CLI regularly (e.g. daily alerts), the token effectively never goes stale on its own � but you should
-still rotate it well before the 90-day mark, in case the server is ever idle for a stretch:
-
-- Run `staqon refresh` on a schedule (cron / Task Scheduler) every 30-60 days. It rotates the token;
-  the old one keeps working for 5 more minutes, so overlap is safe. Save the new token exactly as
-  `staqon` does (OS keychain, or the user-only `credentials.json` file) � don't hardcode it elsewhere.
-- Once a year, at the hard cap, `refresh` will stop working and the command exits with an auth error.
-  At that point a human (the workspace owner, or whoever can reach the approval URL) has to run
-  `staqon login` again � there is no way around this step by design, since it's what lets the owner
-  revoke access.
-- Do **not** try to use the partner's raw API key directly as a substitute for a long-lived token:
-  the CLI protocol deliberately never hands the API key to the CLI session at all (see the server
-  contract) � the CLI only ever gets a revocable, rate-limited session token, scoped to the CLI's own
-  separate limits, so the partner's production API key headroom is never affected by CLI traffic.
-  `STAQON_TOKEN` (below) is the only supported "skip login" path, and it still expires the same way.
-
-For CI, set `STAQON_TOKEN` instead of logging in (and `STAQON_BASE_URL` if not production). Tokens are
-only ever sent to the host that issued them, and the CLI refuses to send one to a different `--base-url`.
-`refresh` is not available for `STAQON_TOKEN` sessions -- if you use this path, you are responsible for
-replacing the value yourself before it expires (same 90-day sliding / 1-year hard cap rules apply).
-
-## Teams
-
-Most calls are made on behalf of a **team** that holds the right API key. Selection order:
-
-1. `--team <id|slug>` on the command line
-2. the saved default (`staqon use <team>`; `staqon use` shows it; `staqon use --clear` removes it)
-3. if the server answers `team_required`:
-   - in a terminal, you are asked to pick one (and can save it as the default);
-   - otherwise the CLI exits with code 5 and lists the eligible teams. It never picks one for you.
-
-`team_not_eligible` (exit 5) means the chosen team has no key for that call; the error lists the teams that do.
-`staqon whoami` shows which teams can send messages and ads.
-
-## Commands
-
-Every command accepts the global options below. `--to` takes an email **or** a username and converts it if the
-endpoint wants the other kind (see [Identity](#identity-email-vs-username)).
-
-| Global option | |
-|---|---|
-| `--json` | Machine-readable: raw response body on stdout, errors as JSON on stderr |
-| `--team <team>` | Team to act as |
-| `--base-url <url>` | API host |
-| `--verbose` | Print request lines and trace ids to stderr |
-| `--no-color` | Disable colors |
-
-### Messaging
-
-```sh
-staqon message send --email ada@example.com -m "Hello"
-staqon message send --to ada_username -m "Hello"          # username resolved to an email
-staqon message send --email ada@example.com --message-file note.txt   # or -m - to read stdin
-
-staqon messages --username ada_username --limit 20        # read a thread (needs the member's approved link)
-staqon messages --username ada_username --before 152698   # page backwards (--after pages forwards)
-
-staqon comment --username ada_username -c "Looks good" --external-ref order-1042
-staqon comment --username ada_username -c "Status" --card @card.json
-
-staqon internal message --email ada@example.com -m "FYI" --title "Heads up" --link-url https://example.com
-```
-
-- Message and comment text: up to 60,000 characters. `--external-ref` (max 190) is an idempotency key: a repeat is
-  rejected and nothing is posted.
-- `messages --limit` is 1-200 (default 50). Attachment URLs in results are signed and **expire after 1 day**;
-  re-fetch the thread for fresh ones.
-- `internal message` sends to a member's one-way API Messages feed and needs their approval.
-
-### Members
-
-```sh
-staqon members list --search "Ada" --limit 50 --page 2
-staqon member ada@example.com            # or: staqon member --member-id 311
-staqon internal members --search ada     # internal directory (search also matches username)
-```
-
-`members list` shows email and username side by side. `--limit` is **1-100**: the directory is slow server-side
-(about 0.35 s per row) and larger pages hit the gateway timeout. Member searches match **name or email**, not username.
-
-### Verification (push approval)
-
-```sh
-staqon verify start --username ada_username --action "Approve payout #1042" \
-  --context "Payout of 5,000 to account ending 1234" --ttl 60
-staqon verify check <verification_id>             # prints Verified. / Not verified: <reason>
-staqon verify check <verification_id> --strict    # exit 1 unless verified
-staqon verify cancel <verification_id>
-```
-
-- `--ttl` is clamped to 30-180 seconds (default 30). `--action` max 100 chars, `--context` max 500.
-- `check` reasons include `pending`, `declined`, `timeout` and `cancelled`. Without `--strict`, `check` exits 0 for any
-  answer; with it, only a verified result exits 0.
-- `cancel` after the member answered returns exit 1 with "Too late to cancel"; after expiry, "already expired".
-- Needs the member's approved link.
-
-### Ads
-
-Ads are delivered asynchronously by a background worker.
-
-```sh
-staqon ad image banner.png                          # upload only; nothing is delivered
-staqon ad create --body-file ad.txt --button-label "Open" --button-url https://example.com --image banner.png --wait
-staqon ad status <ad_request_id>                    # or --external-ref <ref>
-```
-
-- Images: JPEG, PNG or WebP (checked on file contents), **max 300 KB**; the server crops to 16:9 and downsizes to
-  at most 1280x720, so the stored size differs from your file.
-- `ad create`: body 50-900 characters; success is HTTP 202 plus an `ad_request_id`. `--wait` polls every 5 s for up
-  to 10 minutes. `--external-ref` (max 150) is an idempotency key.
-
-### Raw access
-
-```sh
-staqon api external/members -q search=ada -q limit=10
-staqon api external/message -d '{"email":"ada@example.com","message":"Hi"}'
-```
-
-Calls any CLI-proxy endpoint directly: `external/{message,messages,comment,members,member,ad,ad-image,ad-status,
-staqon-verify-start,staqon-verify-check,staqon-verify-cancel}` and `internal/{message,members}`.
-`-d` takes inline JSON, `@file.json` or `-` for stdin; `-F k=v` / `-F k=@path` sends multipart.
-
-### Cards
-
-`--card` (comment, internal message, verify start) takes a JSON object, inline, `@file.json` or `-`. The CLI
-validates it before sending: required `header_color` (one of the palette colors), `title` (200) and `body` (2000);
-optional `meta_title`, `sub_body`, `icon`, `button` (`label`, `url`; not allowed on verification cards) and `table`
-(2-6 columns, 1-500 rows). Unknown keys are rejected.
-
-## Identity: email vs. username
-
-The endpoints disagree: `message send` wants an email, while `messages`, `comment`, `verify` want a username. Give
-`--email`, `--username` or `--to <either>`; the CLI converts when needed.
-
-- email -> username is one fast lookup.
-- username -> email tries the directory search, then looks up the member's name via their thread and searches by
-  name (fast, but only for members linked to your workspace), then **pages through the whole directory**. That last
-  step can take minutes on a large workspace. **If you know the email, pass `--email`.**
-
-## The consent model (why some calls return 403)
-
-Members control what a workspace may do. For `messages`, `comment`, `verify *` and `internal message`, the member must
-have approved the link with your workspace in their app. If they have not, the server answers 403 and the CLI prints
-a friendly message and exits with **code 6**:
-
-```
-Error: This member hasn't approved linking with this workspace.
-trace id: ...
-Server said: No approved link for this member
-The member has to approve the link in their app; the CLI can't do it for them.
-```
-
-The CLI can't work around it. Ask the member to approve, then retry. A 403 that is *not* about consent (CLI access
-switched off, workspace inactive) exits with code 3 instead.
-
-## Exit codes
-
-| Code | Meaning |
-|---|---|
-| 0 | Success |
-| 1 | General failure: server rejected the request (4xx/5xx), network error or timeout, `verify check --strict` not verified, cancel too late or expired |
-| 2 | Usage error: bad flags or input, caught before anything is sent; also a token used against a different host |
-| 3 | Authentication: not logged in, session expired/revoked (401), or access denied (non-consent 403) |
-| 4 | Rate limited (429): session 30/min, 3,000/day, or the API key's own ceiling. `Retry after` is shown when sent |
-| 5 | Team or key problem: `team_required` (non-interactive), `team_not_eligible`, `no_key` |
-| 6 | Member has not approved the link (consent 403) |
-| 130 | Interrupted (Ctrl-C) |
-
-The CLI never retries on its own, except re-asking once after you pick a team interactively.
-Requests time out after 30 s (120 s for member directory listings); override with `STAQON_TIMEOUT_MS`.
-
-## `--json`
-
-With `--json`, success prints the server's response body, unchanged, on stdout. Errors print **one JSON object on
-stderr** and nothing on stdout:
-
-```json
-{
-  "error": "This member hasn't approved linking with this workspace.",
-  "exit_code": 6,
-  "status": 403,
-  "trace_id": "30becdb4-daac-46b0-9fb6-395249329632",
-  "body": { "ok": false, "error": "No approved link for this member" },
-  "hint": "Server said: No approved link for this member\n..."
-}
-```
-
-`status`, `trace_id` and `body` appear for errors that came from the server; client-side errors have only
-`error`, `exit_code` and optionally `hint`. In `--json` mode the CLI never prompts, so team selection must be
-explicit (`--team` or a saved default). Tokens are redacted (`stq_cli_***`) from all output. Quote the `trace_id`
-when contacting support.
-
-## Environment variables
-
-| Variable | Purpose |
-|---|---|
-| `STAQON_TOKEN` | Use this session token instead of the stored login |
-| `STAQON_BASE_URL` | API host (default `https://staqon.one`) |
-| `STAQON_TIMEOUT_MS` | Request timeout in milliseconds |
-
-## Development
-
-```sh
-npm install
-npm run build      # bundle to dist/
-npm test           # 52 mocked tests; no network, no login needed
-npm run test:live  # optional; needs a login: STAQON_LIVE_USERNAME=... STAQON_LIVE_EMAIL=... (slow case: SLOW=1)
-```
-
-The mocked tests run the real CLI against a local fake server with an isolated config directory, so they never touch
-your real login or keychain.
+# @staqon/cli
+
+Command-line client for the StaqOn partner API. Send messages, post comments, run push-approval
+verifications and broadcast ads as your workspace, from a terminal or a script.
+
+- Requires **Node.js 20 or newer**.
+- Talks to `https://staqon.one` by default (override with `--base-url` or `STAQON_BASE_URL`).
+
+## Install
+
+```sh
+npm install -g @staqon/cli
+staqon --version
+```
+
+## Getting started
+
+1. **The workspace owner creates an API key first.** Open your workspace at
+   `<your-workspace-url>/workspace/settings.php?w=<your-workspace-slug>&tab=api` and, under the
+   relevant card (Messaging API, Ad API, etc.), generate a key for the team you want the CLI to
+   act as. Messaging and Ad keys both require a **Link** key to already exist on that same tab —
+   set that up first if you see a "set up Link API first" notice.
+2. On that same `api` tab, turn on **"Allow CLI access"** for the workspace. This is a separate
+   switch from the API key above — it must be ON before `staqon login` can be approved. Turning it
+   OFF immediately signs out every CLI session for that workspace.
+3. Run `staqon login` from the machine or server you want to use. It prints a URL and a short code.
+4. The **workspace owner** opens that URL (it's also reachable directly at `/cli`) and approves the
+   code — they may be asked for their MPIN if their web session is old.
+5. Run `staqon whoami`. It lists every key the CLI can use and which teams hold it. If a command you
+   need isn't listed, go back to step 1 for that key type — the CLI itself can never create or see
+   API keys, only the owner can.
+6. Send your first message:
+   ```sh
+   staqon message send --email member@example.com -m "Hello from the CLI"
+   ```
+7. **Member approval (exit code 6).** Most calls that reach a specific member — direct messages,
+   comments, internal messages, verification requests — require that member to have approved
+   linking with your workspace in their own StaqOn app first. If they haven't, the CLI exits with
+   code 6 and a message like "This member hasn't approved linking with this workspace." This isn't
+   something the CLI or the owner can bypass — the member has to approve it on their end.
+
+## Sign in
+
+There is no separate `init` step: `staqon login` is the whole setup.
+
+```sh
+staqon login            # prints a URL and a one-time code
+staqon login --open     # also opens the URL in your browser
+```
+
+1. The CLI shows a verification URL and a code.
+2. **The workspace owner** opens the URL and approves the code (they may be asked for their MPIN).
+3. The CLI polls, receives a session token, and stores it.
+
+Where the token lives: the OS keychain when available, otherwise a user-only file
+(`credentials.json` in the `staqon` config directory: `%APPDATA%\staqon` on Windows,
+`$XDG_CONFIG_HOME/staqon` or `~/.config/staqon` elsewhere). The CLI says so when it has to use the file.
+
+| Command | What it does |
+|---|---|
+| `staqon whoami` | Workspace, session expiry, rate limits, and which teams can do what |
+| `staqon refresh` | Rotate the session token (the old one works for 5 more minutes) |
+| `staqon logout` | Forget the local token. Revoking it is done by the owner in the web UI |
+
+### Running unattended (a server sending automatic alerts)
+
+Session tokens are sliding-expiry: **90 days of inactivity invalidates them, and every call extends
+that window**, up to a hard cap of **1 year from the original login**. For a server that calls the
+CLI regularly (e.g. daily alerts), the token effectively never goes stale on its own — but you should
+still rotate it well before the 90-day mark, in case the server is ever idle for a stretch:
+
+- Run `staqon refresh` on a schedule (cron / Task Scheduler) every 30-60 days. It rotates the token;
+  the old one keeps working for 5 more minutes, so overlap is safe. Save the new token exactly as
+  `staqon` does (OS keychain, or the user-only `credentials.json` file) — don't hardcode it elsewhere.
+- Once a year, at the hard cap, `refresh` will stop working and the command exits with an auth error.
+  At that point a human (the workspace owner, or whoever can reach the approval URL) has to run
+  `staqon login` again — there is no way around this step by design, since it's what lets the owner
+  revoke access.
+- Do **not** try to use the partner's raw API key directly as a substitute for a long-lived token:
+  the CLI protocol deliberately never hands the API key to the CLI session at all (see the server
+  contract) — the CLI only ever gets a revocable, rate-limited session token, scoped to the CLI's own
+  separate limits, so the partner's production API key headroom is never affected by CLI traffic.
+  `STAQON_TOKEN` (below) is the only supported "skip login" path, and it still expires the same way.
+
+For CI, set `STAQON_TOKEN` instead of logging in (and `STAQON_BASE_URL` if not production). Tokens are
+only ever sent to the host that issued them, and the CLI refuses to send one to a different `--base-url`.
+`refresh` is not available for `STAQON_TOKEN` sessions -- if you use this path, you are responsible for
+replacing the value yourself before it expires (same 90-day sliding / 1-year hard cap rules apply).
+
+## Teams
+
+Most calls are made on behalf of a **team** that holds the right API key. Selection order:
+
+1. `--team <id|slug>` on the command line
+2. the saved default (`staqon use <team>`; `staqon use` shows it; `staqon use --clear` removes it)
+3. if the server answers `team_required`:
+   - in a terminal, you are asked to pick one (and can save it as the default);
+   - otherwise the CLI exits with code 5 and lists the eligible teams. It never picks one for you.
+
+`team_not_eligible` (exit 5) means the chosen team has no key for that call; the error lists the teams that do.
+`staqon whoami` shows which teams can send messages and ads.
+
+## Commands
+
+Every command accepts the global options below. `--to` takes an email **or** a username and converts it if the
+endpoint wants the other kind (see [Identity](#identity-email-vs-username)).
+
+| Global option | |
+|---|---|
+| `--json` | Machine-readable: raw response body on stdout, errors as JSON on stderr |
+| `--team <team>` | Team to act as |
+| `--base-url <url>` | API host |
+| `--verbose` | Print request lines and trace ids to stderr |
+| `--no-color` | Disable colors |
+
+### Messaging
+
+```sh
+staqon message send --email ada@example.com -m "Hello"
+staqon message send --to ada_username -m "Hello"          # username resolved to an email
+staqon message send --email ada@example.com --message-file note.txt   # or -m - to read stdin
+
+staqon messages --username ada_username --limit 20        # read a thread (needs the member's approved link)
+staqon messages --username ada_username --before 152698   # page backwards (--after pages forwards)
+
+staqon comment --username ada_username -c "Looks good" --external-ref order-1042
+staqon comment --username ada_username -c "Status" --card @card.json
+
+staqon internal message --email ada@example.com -m "FYI" --title "Heads up" --link-url https://example.com
+```
+
+- Message and comment text: up to 60,000 characters. `--external-ref` (max 190) is an idempotency key: a repeat is
+  rejected and nothing is posted.
+- `messages --limit` is 1-200 (default 50). Attachment URLs in results are signed and **expire after 1 day**;
+  re-fetch the thread for fresh ones.
+- `internal message` sends to a member's one-way API Messages feed and needs their approval.
+
+### Members
+
+```sh
+staqon members list --search "Ada" --limit 50 --page 2
+staqon member ada@example.com            # or: staqon member --member-id 311
+staqon internal members --search ada     # internal directory (search also matches username)
+
+staqon members add --name "Ada Lovelace" --email ada@example.com --phone +919812345678
+staqon members remove --email ada@example.com
+staqon members teams ext-ref-1042        # external teams a linked member has joined
+```
+
+`members list` shows email and username side by side. `--limit` is **1-100**: the directory is slow server-side
+(about 0.35 s per row) and larger pages hit the gateway timeout. Member searches match **name or email**, not username.
+
+`members add` creates the member if the email is new, otherwise links them; the response says which (`status`:
+`invited` or `existing`). `members remove` archives their thread rather than deleting history. `members teams`
+looks up by the `external_ref` you sent to `staqon-verify-start`/link-invite, not by email.
+
+### Escalations
+
+```sh
+staqon escalation create --title "Payout stuck" --description "Payout #1042 failed twice" \
+  --due-date 2026-12-01 --priority high
+staqon escalation list --page 1 --limit 20 --status open
+staqon escalation get --uuid 3f9b2c10-...          # or: staqon escalation get --matter-id 882
+```
+
+- `create`: `--title` and `--due-date` (`YYYY-MM-DD`) are required; `--description` or `--description-file` (not
+  both); `--priority` is optional. Success returns a `matter_id` and `uuid`.
+- `list` results expose `uuid`, not `matter_id` — use `--uuid` with `get` to look up a single matter from a list.
+- `get` takes exactly one of `--uuid` / `--matter-id`.
+
+### Status & webhooks
+
+```sh
+staqon status                 # key context for this external team: workspace, members, rate limit
+staqon internal status        # same, for the internal team
+staqon webhook status         # webhook health for this external team
+staqon internal webhook-status
+```
+
+### Verification (push approval)
+
+```sh
+staqon verify start --username ada_username --action "Approve payout #1042" \
+  --context "Payout of 5,000 to account ending 1234" --ttl 60
+staqon verify check <verification_id>             # prints Verified. / Not verified: <reason>
+staqon verify check <verification_id> --strict    # exit 1 unless verified
+staqon verify cancel <verification_id>
+```
+
+- `--ttl` is clamped to 30-180 seconds (default 30). `--action` max 100 chars, `--context` max 500.
+- `check` reasons include `pending`, `declined`, `timeout` and `cancelled`. Without `--strict`, `check` exits 0 for any
+  answer; with it, only a verified result exits 0.
+- `cancel` after the member answered returns exit 1 with "Too late to cancel"; after expiry, "already expired".
+- Needs the member's approved link.
+
+### Ads
+
+Ads are delivered asynchronously by a background worker.
+
+```sh
+staqon ad image banner.png                          # upload only; nothing is delivered
+staqon ad create --body-file ad.txt --button-label "Open" --button-url https://example.com --image banner.png --wait
+staqon ad status <ad_request_id>                    # or --external-ref <ref>
+```
+
+- Images: JPEG, PNG or WebP (checked on file contents), **max 300 KB**; the server crops to 16:9 and downsizes to
+  at most 1280x720, so the stored size differs from your file.
+- `ad create`: body 50-900 characters; success is HTTP 202 plus an `ad_request_id`. `--wait` polls every 5 s for up
+  to 10 minutes. `--external-ref` (max 150) is an idempotency key.
+
+### Raw access
+
+```sh
+staqon api external/members -q search=ada -q limit=10
+staqon api external/message -d '{"email":"ada@example.com","message":"Hi"}'
+```
+
+Calls any CLI-proxy endpoint directly: `external/{message,messages,comment,members,member,ad,ad-image,ad-status,
+staqon-verify-start,staqon-verify-check,staqon-verify-cancel,add-member,remove-member,member-teams,escalation,escalations,
+webhook-status,status}` and `internal/{message,members,webhook-status,status}`.
+`-d` takes inline JSON, `@file.json` or `-` for stdin; `-F k=v` / `-F k=@path` sends multipart.
+
+### Cards
+
+`--card` (comment, internal message, verify start) takes a JSON object, inline, `@file.json` or `-`. The CLI
+validates it before sending: required `header_color` (one of the palette colors), `title` (200) and `body` (2000);
+optional `meta_title`, `sub_body`, `icon`, `button` (`label`, `url`; not allowed on verification cards) and `table`
+(2-6 columns, 1-500 rows). Unknown keys are rejected.
+
+## Identity: email vs. username
+
+The endpoints disagree: `message send` wants an email, while `messages`, `comment`, `verify` want a username. Give
+`--email`, `--username` or `--to <either>`; the CLI converts when needed.
+
+- email -> username is one fast lookup.
+- username -> email tries the directory search, then looks up the member's name via their thread and searches by
+  name (fast, but only for members linked to your workspace), then **pages through the whole directory**. That last
+  step can take minutes on a large workspace. **If you know the email, pass `--email`.**
+
+## The consent model (why some calls return 403)
+
+Members control what a workspace may do. For `messages`, `comment`, `verify *` and `internal message`, the member must
+have approved the link with your workspace in their app. If they have not, the server answers 403 and the CLI prints
+a friendly message and exits with **code 6**:
+
+```
+Error: This member hasn't approved linking with this workspace.
+trace id: ...
+Server said: No approved link for this member
+The member has to approve the link in their app; the CLI can't do it for them.
+```
+
+The CLI can't work around it. Ask the member to approve, then retry. A 403 that is *not* about consent (CLI access
+switched off, workspace inactive) exits with code 3 instead.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | General failure: server rejected the request (4xx/5xx), network error or timeout, `verify check --strict` not verified, cancel too late or expired |
+| 2 | Usage error: bad flags or input, caught before anything is sent; also a token used against a different host |
+| 3 | Authentication: not logged in, session expired/revoked (401), or access denied (non-consent 403) |
+| 4 | Rate limited (429): session 30/min, 3,000/day, or the API key's own ceiling. `Retry after` is shown when sent |
+| 5 | Team or key problem: `team_required` (non-interactive), `team_not_eligible`, `no_key` |
+| 6 | Member has not approved the link (consent 403) |
+| 130 | Interrupted (Ctrl-C) |
+
+The CLI never retries on its own, except re-asking once after you pick a team interactively.
+Requests time out after 30 s (120 s for member directory listings); override with `STAQON_TIMEOUT_MS`.
+
+## `--json`
+
+With `--json`, success prints the server's response body, unchanged, on stdout. Errors print **one JSON object on
+stderr** and nothing on stdout:
+
+```json
+{
+  "error": "This member hasn't approved linking with this workspace.",
+  "exit_code": 6,
+  "status": 403,
+  "trace_id": "30becdb4-daac-46b0-9fb6-395249329632",
+  "body": { "ok": false, "error": "No approved link for this member" },
+  "hint": "Server said: No approved link for this member\n..."
+}
+```
+
+`status`, `trace_id` and `body` appear for errors that came from the server; client-side errors have only
+`error`, `exit_code` and optionally `hint`. In `--json` mode the CLI never prompts, so team selection must be
+explicit (`--team` or a saved default). Tokens are redacted (`stq_cli_***`) from all output. Quote the `trace_id`
+when contacting support.
+
+## Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `STAQON_TOKEN` | Use this session token instead of the stored login |
+| `STAQON_BASE_URL` | API host (default `https://staqon.one`) |
+| `STAQON_TIMEOUT_MS` | Request timeout in milliseconds |
+
+## Development
+
+```sh
+npm install
+npm run build      # bundle to dist/
+npm test           # 52 mocked tests; no network, no login needed
+npm run test:live  # optional; needs a login: STAQON_LIVE_USERNAME=... STAQON_LIVE_EMAIL=... (slow case: SLOW=1)
+```
+
+The mocked tests run the real CLI against a local fake server with an isolated config directory, so they never touch
+your real login or keychain.

package/dist/cli.js

@@ -642,8 +642,17 @@ var ENDPOINTS = [
   "external/staqon-verify-start",
   "external/staqon-verify-check",
   "external/staqon-verify-cancel",
+  "external/add-member",
+  "external/remove-member",
+  "external/member-teams",
+  "external/status",
+  "external/escalation",
+  "external/escalations",
+  "external/webhook-status",
   "internal/message",
-  "internal/members"
+  "internal/members",
+  "internal/webhook-status",
+  "internal/status"
 ];
 function kv(items, flag) {
   return (items ?? []).map((s) => {
@@ -977,6 +986,31 @@ function registerTyped(program2) {
     const r = await proxy({ ep: "external/members", method: "GET", query: memberQuery(o), timeoutMs: LIST_TIMEOUT_MS });
     show(r, (b) => memberTable(b, "last_message_at"));
   });
+  members.command("add").description("Add a member to this team (creates the user if the email is new)").option("--name <name>", "full name (required)").option("--email <email>", "email address (required)").option("--phone <phone>", "phone number, optional").action(async (o) => {
+    const name = required("--name", o["name"]);
+    const email = required("--email", o["email"]);
+    const json = { name, email };
+    if (o["phone"]) json["phone"] = o["phone"];
+    const r = await proxy({ ep: "external/add-member", json });
+    show(
+      r,
+      (b) => ok(`${b["status"] === "existing" ? "Already a member" : "Added"}. member_id=${b["member_id"]} username=${b["username"]}${b["conversation_id"] ? ` conversation_id=${b["conversation_id"]}` : ""} status=${b["status"]}`)
+    );
+  });
+  members.command("remove").description("Remove a member from this team (archives their thread, keeps history)").option("--email <email>", "email address (required)").action(async (o) => {
+    const email = required("--email", o["email"]);
+    const r = await proxy({ ep: "external/remove-member", json: { email } });
+    show(r, (b) => ok(`Removed. member_id=${b["member_id"]}`));
+  });
+  members.command("teams <external_ref>").description("Which external teams (in this workspace) has a linked member joined? Looks up by the external_ref sent to link-invite").action(async (externalRef) => {
+    maxLen("external_ref", externalRef, 255);
+    const r = await proxy({ ep: "external/member-teams", method: "GET", query: { external_ref: externalRef } });
+    show(r, (b) => {
+      const rows = (b["teams"] ?? []).map((t) => [String(t["id"]), t["name"] ?? "", t["role"] ?? "", t["joined_at"] ?? ""]);
+      if (!rows.length) return void out(pc4.dim("No external teams."));
+      table(rows, ["ID", "NAME", "ROLE", "JOINED_AT"]);
+    });
+  });
   program2.command("member [email-or-id]").description("Look up one member by email or member id").option("--email <email>", "look up by email").option("--member-id <id>", "look up by member id").action(async (arg, o) => {
     const given = [arg, o["email"], o["memberId"]].filter((x) => x);
     if (given.length !== 1) throw usage("Give exactly one of: <email-or-id>, --email, --member-id.");
@@ -994,6 +1028,73 @@ function registerTyped(program2) {
         out(`${pc4.bold(k.padEnd(14))} ${m[k] ?? ""}`);
     });
   });
+  program2.command("status").description("Key context and usage for this (external) team").action(async () => {
+    const r = await proxy({ ep: "external/status", method: "GET" });
+    show(r, (b) => {
+      for (const k of ["workspace", "team", "team_type", "total_members", "active_members", "api_key_usage", "rate_limit", "rate_remaining"])
+        out(`${pc4.bold(k.padEnd(16))} ${b[k] ?? ""}`);
+    });
+  });
+  const escalation = program2.command("escalation").description("Raise and read escalation matters against your team's members");
+  withWho(escalation.command("create").description("Raise an escalation against a member in this team")).option("--title <title>", "at least 2 chars (required)").option("--description <text>", 'required; "-" reads stdin').option("--description-file <path>", "read the description from a file").option("--priority <level>", "low|medium|high|critical (default medium)").option("--due-date <YYYY-MM-DD>", "must be a future date (required)").action(async (o) => {
+    const title = required("--title", o["title"]);
+    if (title.length < 2) throw usage("--title must be at least 2 characters.");
+    const description = await textFrom("description", o["description"], o["descriptionFile"]);
+    if (!description) throw usage("--description (or --description-file) is required.");
+    const dueDate = required("--due-date", o["dueDate"]);
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(dueDate)) throw usage("--due-date must be YYYY-MM-DD.");
+    if (o["priority"] && !["low", "medium", "high", "critical"].includes(o["priority"])) throw usage("--priority must be one of: low, medium, high, critical.");
+    const w = who(o);
+    if (!!w.email === !!w.username && !w.to) throw usage("Give exactly one of --email or --username (or --to).");
+    const json = { title, description, due_date: dueDate };
+    if (o["priority"]) json["priority"] = o["priority"];
+    if (w.email) json["email"] = w.email;
+    if (w.username) json["username"] = w.username;
+    if (w.to) {
+      const email = await resolveIdentity(w, "email").catch(() => void 0);
+      if (email) json["email"] = email;
+      else json["username"] = w.to;
+    }
+    const r = await proxy({ ep: "external/escalation", json });
+    show(r, (b) => {
+      ok(`Raised. matter_id=${b["matter_id"]} uuid=${b["uuid"]}`);
+      out(`Check it with: staqon escalation get --uuid ${b["uuid"]}`);
+    });
+  });
+  escalation.command("list").description("List escalation matters raised against this team's members").option("--page <n>", "page number", intOpt("--page", 1, 1e6)).option("--limit <n>", "1-200 (default 50)", intOpt("--limit", 1, 200)).option("--status <status>", "open|in_progress|resolved").action(async (o) => {
+    const query = {};
+    if (o["page"]) query["page"] = String(o["page"]);
+    if (o["limit"]) query["limit"] = String(o["limit"]);
+    if (o["status"]) query["status"] = o["status"];
+    const r = await proxy({ ep: "external/escalations", method: "GET", query });
+    show(r, (b) => {
+      const rows = (b["matters"] ?? []).map((m) => [m["uuid"], m["title"], m["status"], m["priority"], m["due_date"], m["target_username"] ?? ""]);
+      table(rows, ["UUID", "TITLE", "STATUS", "PRIORITY", "DUE_DATE", "MEMBER"]);
+      out(pc4.dim(`page ${b["page"]}/${b["pages"]}, ${b["total"]} total`));
+    });
+  });
+  escalation.command("get").description("Get one escalation matter by uuid or matter id").option("--uuid <uuid>", 'look up by uuid (as shown in "escalation list")').option("--matter-id <id>", "look up by numeric matter id").action(async (o) => {
+    if (!!o["uuid"] === !!o["matterId"]) throw usage("Give exactly one of --uuid, --matter-id.");
+    const query = o["uuid"] ? { uuid: o["uuid"] } : { matter_id: o["matterId"] };
+    const r = await proxy({ ep: "external/escalations", method: "GET", query });
+    show(r, (b) => {
+      const m = obj3(b["matter"]);
+      for (const k of ["uuid", "title", "description", "status", "priority", "due_date", "resolved_at", "comment_count", "last_activity_at", "created_at", "target_username"])
+        out(`${pc4.bold(k.padEnd(16))} ${m[k] ?? ""}`);
+    });
+  });
+  const webhookRow = (h) => [h["url"], (h["events"] ?? []).join(","), h["is_active"] ? "yes" : "NO", String(h["failure_count"]), h["last_triggered_at"] ?? "-", h["created_at"] ?? ""];
+  const webhookHuman = (b) => {
+    const rows = (b["webhooks"] ?? []).map(webhookRow);
+    if (!rows.length) return void out(pc4.dim("No webhooks configured for this team."));
+    table(rows, ["URL", "EVENTS", "ACTIVE", "FAILURES", "LAST_TRIGGERED", "CREATED"]);
+    const dead = (b["webhooks"] ?? []).filter((h) => !h["is_active"]);
+    if (dead.length) out(pc4.yellow(`${dead.length} webhook(s) auto-disabled after 10 consecutive failures.`));
+  };
+  const webhook = program2.command("webhook").description("Webhook health for this team");
+  webhook.command("status").description("Webhook health for this (external) team").action(async () => {
+    show(await proxy({ ep: "external/webhook-status", method: "GET" }), webhookHuman);
+  });
   const internal = program2.command("internal").description("Internal (one-way API Messages feed)");
   withWho(internal.command("message").description("Send a one-way message to a member's API Messages feed (needs their approval)")).option("-m, --message <text>", 'message text, max 60000 chars; "-" reads stdin').option("--message-file <path>", "read the message from a file").option("--title <title>", "max 200 chars").option("--external-ref <ref>", "idempotency key, max 190 chars").option("--link-url <url>", "http(s) URL").option("--card <json>", "card object: inline JSON, @file.json, or - for stdin").action(async (o) => {
     const text = maxLen("message", await textFrom("message", o["message"], o["messageFile"]), 6e4);
@@ -1024,6 +1125,16 @@ function registerTyped(program2) {
     const r = await proxy({ ep: "internal/members", method: "GET", query: memberQuery(o), timeoutMs: LIST_TIMEOUT_MS });
     show(r, (b) => memberTable(b, "role"));
   });
+  internal.command("webhook-status").description("Webhook health for this (internal) team").action(async () => {
+    show(await proxy({ ep: "internal/webhook-status", method: "GET" }), webhookHuman);
+  });
+  internal.command("status").description("Key context and usage for this (internal) team").action(async () => {
+    const r = await proxy({ ep: "internal/status", method: "GET" });
+    show(r, (b) => {
+      for (const k of ["workspace", "team", "team_type", "total_members", "active_members", "api_key_usage", "rate_limit", "rate_remaining"])
+        out(`${pc4.bold(k.padEnd(16))} ${b[k] ?? ""}`);
+    });
+  });
   const ad = program2.command("ad").description("Ads (asynchronous: delivered by a background worker)");
   const uploadImage = async (file2) => {
     const { bytes, type } = checkImageFile(file2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staqon/cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "StaqOn command-line client for partner developers",
   "keywords": [
     "staqon",