@moda-ai/cli 1.13.0 → 1.13.2

package/skills/moda-cli/SKILL.md

@@ -44,10 +44,12 @@ the user specifically asked for `moda prompts sync` or `moda prompts promote`.
 
 ## Required inputs
 
-Before running any command except `moda init`:
+Before running any command except `moda init`, `moda provision`, and the
+`moda auth ...` session commands (which use the browser/CLI session instead):
 
 - `MODA_API_KEY` env var must be set (`moda_sk_...`). If missing, run
-  `moda init` to provision one, or have the user export it.
+  `moda init` (interactive) or `moda provision` (headless, needs an existing
+  session) to provision one, or have the user export it.
 
 Optional:
 
@@ -78,6 +80,103 @@ npx -p @moda-ai/cli moda <command>
 export MODA_API_KEY="moda_sk_..."   # from moda.dev/settings
 ```
 
+### Headless provisioning (CI / agents): `moda provision`
+
+`moda provision` mints (or reuses) a tenant API key with zero prompts and
+prints a single JSON credentials document to stdout — in every output mode,
+even on an interactive terminal, so it composes directly:
+
+```bash
+KEY=$(moda provision --tenant-id t1 | jq -r .apiKey)
+```
+
+Output shape:
+
+```json
+{
+  "apiKey": "moda_sk_...",
+  "tenantId": "t1",
+  "tenantName": "Acme",
+  "tenantSlug": "acme",
+  "ingestUrl": "https://moda-ingest.modas.workers.dev",
+  "baseUrl": "https://moda.dev",
+  "reused": false
+}
+```
+
+Rules and limitations:
+
+- **Requires an existing CLI session.** There is no browserless signup or
+  login: with no stored session it exits `4` (`auth_required`) telling you to
+  run `moda auth login` on a machine with a browser first, or to skip
+  provisioning and export `MODA_API_KEY` directly.
+- **Never prompts, even on a TTY.** A single-tenant account auto-selects;
+  with multiple tenants you must pass `--tenant-id=<id>` (or set
+  `MODA_TENANT_ID`), otherwise it exits `5` (`needs_input`) with per-tenant
+  `resume_flags`.
+- `reused: true` means a previously stored key for that tenant passed a
+  liveness probe and was reused instead of minting a new one (same dedup +
+  idempotent bootstrap machinery as `moda init`).
+- **Does not write `~/.moda/config.json` by default** — headless callers own
+  their credential storage. Pass `--save` to opt into the init-style
+  persistence.
+- `--label=<text>` names the created key (default: machine hostname);
+  `--profile=NAME` scopes the session lookup.
+- stdout carries a live credential — a warning is printed to stderr; never
+  pipe provision stdout into logs.
+
+**When to use which:** `moda init` is the interactive first-time onboarding
+wizard for a repo (harness discovery, skills, prompts, validation);
+`moda provision` is for CI jobs and agents that already have a session and
+just need credentials.
+
+### Auth session inspection and token composition
+
+```bash
+moda auth login                  # browser PKCE sign-in; stores a moda_ct_ session token
+moda auth logout                 # revoke the session server-side, then delete it locally
+moda auth status                 # local session state; exit 0 logged in, exit 4 logged out
+moda auth status --online        # additionally probe GET /api/cli/context
+moda auth token                  # print the raw bearer token + newline, nothing else
+curl -H "Authorization: Bearer $(moda auth token)" https://moda.dev/api/cli/context
+```
+
+- `moda auth login` opens the browser consent flow at `{MODA_BASE_URL}/auth/cli`
+  with a localhost callback (ports 8432-8435, first free). Approving in the
+  browser hands the CLI a one-time code that it exchanges for a `moda_ct_...`
+  session token (sliding 30-day expiry, renewed automatically in the
+  background while you keep using the CLI). If the browser cannot reach the
+  machine, paste the callback URL or the code shown on the consent page into
+  the terminal.
+- `moda auth logout` revokes the stored `moda_ct_` session server-side
+  (best-effort) and deletes the local credential; legacy sessions are just
+  deleted locally.
+- `moda auth status` reports
+  `{ "loggedIn": <bool>, "profile": <string|null>, "expiresAt": <ISO|null> }`
+  plus `"user": { "email": <string> }` when the stored session carries an
+  email (PKCE `moda_ct_` sessions do; legacy sessions omit it), and exits `4`
+  when logged out. That exit is an **expected state signal, not
+  an error**: the payload is clean data (no error block, no stderr noise), and
+  no browser is ever opened. With `--online` the payload adds
+  `{ "online": { "reachable": <bool>, "ok": <bool>, "tenantCount": <n> } }`:
+  `reachable: true` means any HTTP response arrived (even a 401/500), `ok`
+  reflects HTTP success, and `tenantCount` is present only when the response
+  was ok and carried a tenants array. A network failure or probe timeout
+  (5 s) yields `reachable: false`; the exit code always follows local session
+  validity only, never the probe.
+- `moda auth token` writes exactly the bare token plus a trailing newline to
+  stdout in **every** output mode — including piped/json/agent, because
+  command substitution is a pipe — so `$(moda auth token)` composes safely
+  with no envelope to strip. When logged out it prints a stderr message and
+  exits `4`; with an explicit `--json` flag it instead prints
+  `{"error":"not_authenticated"}` to stdout (still exit `4`).
+- `moda auth token` prints whichever credential kind is stored. Newer logins
+  store a `moda_ct_...` CLI session token, which authenticates **`/api/cli/*`
+  endpoints only** — it is not accepted by the Data API (`/api/v1/data/*`
+  wants a `moda_sk_...` API key) or other dashboard endpoints. Legacy
+  sessions print the Auth0 bearer token as before.
+- Both respect `--profile=NAME` and `MODA_PROFILE`.
+
 ## Agent protocol
 
 Run `moda manifest --json` first when integrating with the CLI. It returns the
@@ -117,10 +216,73 @@ Branch on the exit code; it is stable and cheaper than parsing the payload:
 | `0` | ok — answer is grounded in Moda Cloud intelligence | Trust it. |
 | `1` | error — bad input, API/network failure, or unexpected failure | Read `errors[]`; retry only when the code is retryable. |
 | `3` | degraded — Moda Cloud was unavailable; answer synthesized from local Data API evidence | Answer is present but lower-trust; verify before acting. |
-| `4` | auth required | Run `auth.login_command`, then re-run `auth.resume_command` if present. |
-| `5` | input required | Pick a choice, append its `resume_flags`, and re-run. |
+| `4` | auth required — credentials are missing or expired | Run the `login_command` from the `auth` payload (`moda auth login`), then re-run `resume_command`. |
+| `5` | input required — a choice is needed that the non-interactive run could not answer | Pick a choice from the `input_request` payload and re-invoke the same command with that choice's `resume_flags` appended. |
 | `130` | cancelled | Treat as interrupted or closed pipe; do not retry blindly. |
 
+Exit codes `4` and `5` are recoverable-by-caller failures: the envelope's
+`errors[]` entry carries the exact commands/flags to recover with, as argv
+arrays (execute element-wise; join with spaces only for display).
+
+#### `auth_required` payload (exit `4`)
+
+The envelope's `errors[]` entry carries the recovery data on its `auth` field
+(in `--agent --stream` mode the same error arrives as an NDJSON event with
+`"event": "auth_required"`):
+
+```json
+{
+  "code": "auth_required",
+  "message": "Browser authentication is required before non-interactive init can continue.",
+  "suggested_commands": ["moda auth login", "moda init --yes"],
+  "blocking": true,
+  "auth": {
+    "reason": "no_stored_credentials",
+    "login_command": ["moda", "auth", "login"],
+    "resume_command": ["moda", "init", "--yes"]
+  }
+}
+```
+
+`reason` is one of:
+
+- `no_stored_credentials` — no session stored. Run `login_command`, then
+  `resume_command` (when present).
+- `token_expired` — the stored session expired. Run `login_command`, then
+  `resume_command`.
+- `token_revoked` — the stored `moda_ct_` CLI session token was revoked
+  server-side (e.g. from the dashboard). Run `login_command`, then
+  `resume_command`.
+- `renew_failed` — the API rejected an **unexpired** `moda_ct_` token but the
+  renewal check could not reach the server, so this is likely transient:
+  **retry the command; do not re-login.**
+
+#### `needs_input` payload (exit `5`)
+
+The envelope's `errors[]` entry carries the recovery data on its
+`input_request` field (in `--agent --stream` mode the event type is
+`"needs_input"`):
+
+```json
+{
+  "code": "needs_input",
+  "message": "An organization must be selected to continue.",
+  "blocking": true,
+  "input_request": {
+    "id": "init_tenant_selection",
+    "question": "Select organization",
+    "kind": "select",
+    "choices": [
+      { "value": "tnt_a", "label": "Acme (owner)", "resume_flags": ["--tenant-id", "tnt_a"] },
+      { "value": "tnt_b", "label": "Beta (viewer)", "resume_flags": ["--tenant-id", "tnt_b"] }
+    ]
+  }
+}
+```
+
+Re-invoke the original command with the chosen `resume_flags` appended (here:
+`moda init --tenant-id tnt_a`).
+
 ### The `moda.agent.v1` envelope
 
 Fields an agent should read:
@@ -584,6 +746,11 @@ npx: `npx -p @moda-ai/cli moda <command>`.
 | Command | Purpose |
 |---|---|
 | `moda init` | Browser auth + provision API key + install agent rules |
+| `moda provision` | Headless tenant + API key provisioning; single JSON credentials doc on stdout (exit `4` without a session, `5` when `--tenant-id` is needed) |
+| `moda auth login` | Browser PKCE sign-in; stores a revocable `moda_ct_` session token |
+| `moda auth logout` | Revoke the CLI session server-side, then delete it locally |
+| `moda auth status` | Local auth session state (exit `4` = logged out — expected, not an error) |
+| `moda auth token` | Print the raw bearer token for `$(moda auth token)` composition |
 | `moda search "<query>"` | **Message-grain semantic/keyword/hybrid search (incl. tool calls); primary content-discovery path** |
 | `moda overview` | Dashboard KPIs, top clusters, recent activity |
 | `moda ask "<question>"` | Natural-language production/harness answer with evidence (exit `3` = degraded local fallback) |