@alter-ai/cli 0.3.0 → 0.3.2

package/README.md

@@ -1,208 +1,46 @@
-# `@alter-ai/cli` — the Alter Vault command-line interface
+# `@alter-ai/cli`
 
-`alter` is a command-line client for the Alter Vault dev portal. It authenticates with a Personal Access Token (PAT) minted from the dashboard and exposes the same dashboard operations as scriptable commands.
+Command-line client for the Alter Vault dev portal. Authenticates with a Personal Access Token (PAT) and exposes the dashboard's resource model as scriptable commands.
+
+📖 **Full docs:** [docs.alterauth.com/reference/cli](https://docs.alterauth.com/reference/cli)
 
 ## Install
 
 ```bash
 npm install -g @alter-ai/cli
-# verify
 alter --version
 ```
 
-## Quick start
-
-The fastest interactive sign-in is the browser-dance flow — `alter auth login` opens the dashboard, you click **Authorize**, and the CLI receives the freshly-minted token on a localhost listener:
-
-```bash
-alter auth login
-# alter: opening browser at https://portal.alterauth.com/cli-auth
-#        (waiting up to 2 minutes for you to approve)…
-# alter: signed in via browser-dance flow.
-
-alter auth status
-```
-
-For headless / CI environments, mint a PAT manually from the dashboard (**Settings → Personal Access Tokens → New token**) and feed it to the CLI through one of the channels below:
-
-**Token file (recommended for local headless use):** keeps the value out of `process.argv` (visible to other users via `ps`) and out of shell history.
-
-```bash
-umask 077 && echo "alter_pat_xxxxxxxxxxxxxxxxxxxxxxxx_yyyyyy" > ~/alter-pat.txt
-alter auth login --token-file ~/alter-pat.txt
-```
-
-**Stdin:**
-
-```bash
-pbpaste | alter auth login --token-stdin                       # macOS
-xclip -o -selection clipboard | alter auth login --token-stdin  # Linux
-```
-
-**Env var (CI):** skip persistence entirely. The SDK reads `ALTER_PAT` directly; it never lands in argv.
+## Sign in
 
 ```bash
-export ALTER_PAT="alter_pat_xxxxxxxxxxxxxxxxxxxxxxxx_yyyyyy"
-alter apps list
+alter auth login                          # interactive browser flow
+ALTER_PAT=alter_pat_... alter apps list   # headless / CI
 ```
 
-**Inline `--token <pat>` is supported but discouraged** — the value lands in `process.argv` (visible to other local users via `ps aux`) and shell history. Use only on single-user machines and rotate afterwards.
-
 ## Commands
 
-The CLI mirrors the dashboard's resource model. Every namespace lives at `alter <namespace> <verb>`:
-
-```
-auth        login | status | logout                       Sign in / out + token introspection
-apps        list | create | show | update | delete         Manage applications
-keys        list | mint | show | rotate | revoke | rename  Manage runtime API keys
-agents      list | create | show | update | revoke         Managed-agent identities (+ mint-key, list-keys, revoke-key)
-providers   list | list-catalog | create | show | update | delete   OAuth provider integrations per app
-managed-secrets
-            templates | list | show | create | delete | rotate | access | users |
-            grants {list, list-for-agent, create, update, revoke} |
-            groups {list, show}                            Managed-secret credentials, grants, and access (CRUD + autocomplete helpers)
-policy      show-app                                       View app-level policy (org-wide policy is dashboard-only)
-audit       list | show | portal-actions | grant-events | traces   Dev-portal audit log
-pats        whoami                                         Same as `auth status`, under the `pats` namespace
-link        <app-id> | --status                            Pin an app to the current directory tree
-unlink                                                    Clear the workspace pin
-completion  install | print                               Generate shell completions (bash/zsh/fish)
-self-update --to <v> | --dry-run                          Upgrade the CLI via npm
-sdk-passthrough request <method> <path> [...]             Raw authenticated request (escape hatch for routes the CLI doesn't model)
-```
-
-PAT lifecycle (mint, revoke) remains **dashboard-only** in v1 — a PAT cannot mint or revoke another PAT, including its own. Operators use the dashboard for those actions. Org-wide policy and identity-provider configuration are also dashboard-only per the destructive-action policy in CLAUDE.md.
-
-Every list / show command accepts `--output=json|table|jsonl` (default: `json` for pipelines, `table` for interactive). Object commands default to `json`. Use `--fields a,b,c` at the top level to project to specific keys (see [Field selection](#field-selection---fields)).
-
-## Authentication
-
-The CLI resolves credentials in this order (highest precedence first):
-
-1. **`ALTER_PAT` environment variable** — canonical CI / headless source.
-2. **OS keychain** (macOS Keychain, Linux Secret Service / `gnome-keyring`, Windows Credential Manager) via the optional `keytar` native module. This is the default location after a successful `alter auth login`.
-3. **Plaintext file** `~/.config/alter/auth.toml` (XDG-compliant, mode `0600`). Used as the fallback when `keytar` failed to build on the host (e.g. missing `libsecret-1-dev` on Linux). The CLI prints a warning at login time when it falls back to this path.
-
-The `--base-url` flag and the `ALTER_BASE_URL` environment variable both require an `https://` URL — non-HTTPS schemes (`http`, `file`, `gopher`, etc.) are rejected at login time so a misconfigured backend URL cannot exfiltrate the PAT in clear text or to an unintended target.
-
-If keytar isn't loading on your host, install the native build tools and re-install:
-
-```bash
-# macOS
-xcode-select --install
-# Linux (Debian/Ubuntu — adjust for your distro)
-sudo apt install libsecret-1-dev gnome-keyring
-# Windows — install windows-build-tools or VS Build Tools
-
-npm install -g @alter-ai/cli
-```
-
-## Workspace config (`alter link`)
-
-If you work primarily on one app, run `alter link <app-id>` once in the project root. The CLI writes a tiny `.alter/config.yaml` that pins the default app for every subsequent `alter keys`, `alter agents`, `alter providers`, and `alter policy show-app` invocation in that directory tree. No more retyping the UUID.
-
-```bash
-cd ~/code/my-product
-alter link app_abc123
-# alter: pinned app_id=app_abc123 in /Users/me/code/my-product/.alter/config.yaml
-# alter: appended `.alter/` to .gitignore so the pin isn't committed.
-
-# from anywhere in this tree, --app becomes optional:
-alter keys list
-alter agents create --name worker --type service
-alter policy show-app
-
-# show the current pin
-alter link --status
-
-# clear the pin
-alter unlink
 ```
-
-`app_id` precedence (highest first):
-
-1. `--app <id>` on the command line
-2. `ALTER_APP_ID` env var
-3. The nearest `.alter/config.yaml` found by walking up from `process.cwd()`
-4. Error: `no app selected` (exit code 2)
-
-Discovery walks up the directory tree until it finds an `.alter/` directory OR crosses your home directory (whichever comes first). The home-dir bound prevents a misplaced config in `$HOME` from silently pinning every shell.
-
-If your project lives in a git repo, `alter link` appends `.alter/` to `.gitignore` so the workspace pin doesn't get committed — same posture as `vercel link`. The pin is personal-to-the-checkout.
-
-## Field selection (`--fields`)
-
-Narrow the JSON / JSONL output to specific top-level keys with `--fields a,b,c` at the top level — useful for scripts that only need one or two columns. Inert when paired with `--output=table` (the table columns are already a pre-defined slice). Missing fields render as `null` to keep the column visible.
-
-```bash
-# List apps, keep only id + name
-alter apps list --fields id,name
-# [
-#   { "id": "app_abc", "name": "demo" },
-#   ...
-# ]
-
-# Single object — same projection rule
-alter apps show app_abc --fields id,name,environment
-
-# JSONL — one projected object per line
-alter audit list --fields timestamp,action --output=jsonl
+auth              login | status | logout
+apps              list | create | show | update | archive | unarchive | delete
+keys              list | mint | show | rotate | revoke | rename
+agents            list | create | show | update | revoke (+ mint-key, list-keys, revoke-key)
+providers         list | list-catalog | create | show | update | delete
+managed-secrets   list | show | create | rotate | delete | templates | access |
+                  set-delegation-policy | users |
+                  grants {list, list-for-agent, create, update, revoke} |
+                  groups {list, show}
+policy            show-app
+audit             list | show | portal-actions | grant-events | traces
+pats              whoami
+link / unlink     pin an app to the current directory
+completion        install | print
+self-update       --to <v>
+sdk-passthrough   request <grant-id> --url <url>
 ```
 
-The `--fields` value is `,`-separated. Spaces around commas are ignored; spaces INSIDE a field name are rejected up front (catches the common `--fields 'id name'` typo with a clear error rather than silently dropping the second name).
-
-## Exit codes
-
-`alter` returns a structured exit code so scripts can branch on the failure mode without parsing stderr text. Codes are stable contract — operators can rely on them across releases.
-
-| Code | Name             | Meaning                                                                                       |
-|------|------------------|-----------------------------------------------------------------------------------------------|
-| 0    | OK               | Command succeeded.                                                                            |
-| 1    | ERROR            | Generic runtime failure (uncategorized — including unknown SDK / network errors).             |
-| 2    | USAGE            | Bad flag, arg, or input format. Always paired with a stderr line naming the offending input.  |
-| 3    | AUTH             | Not signed in, or PAT revoked / expired. **Remediation:** re-run `alter auth login`.          |
-| 4    | NOT_FOUND        | Resource not found — 404 from the backend, or a referenced local file is missing.             |
-| 5    | CONFLICT         | 409 from the backend — most commonly a type-to-confirm mismatch or dependent-resource block.  |
-| 6    | RATE_LIMIT       | 429 from the backend — retry with backoff.                                                    |
-| 7    | FORBIDDEN        | 403 from the backend — PAT is valid but lacks the required scope. **Remediation:** re-mint the PAT with broader scopes (or switch PATs); `alter auth login` alone does NOT help. |
-| 8    | CANCELLED        | Operator declined an interactive prompt (type-to-confirm mismatch on a destructive action, "no" at a y/N gate). Distinct from `ERROR` (1) — the CLI did nothing wrong, the operator chose not to proceed. Pass `--yes` or `--confirm <name>` in CI to skip the prompt. |
-
-Example:
-
-```bash
-# Probe whether an app exists without erroring on the not-found case.
-# Capture $? into a local variable BEFORE running anything else; ``$?``
-# is clobbered by every command, so a stray ``log_attempt`` between the
-# ``if`` and ``elif`` would silently break the not-found branch.
-alter apps show "$APP_ID" --output=json > /dev/null 2>&1
-status=$?
-if [ "$status" -eq 0 ]; then
-  echo "app exists"
-elif [ "$status" -eq 4 ]; then
-  echo "app not found"
-elif [ "$status" -eq 7 ]; then
-  echo "PAT lacks dashboard_apps:read — re-mint with broader scopes"
-else
-  echo "unexpected error" && exit 1
-fi
-```
-
-Backend-thrown errors flow through `withClient` and get mapped from HTTP status to exit code automatically (401 → 3, 403 → 7, 404 → 4, 409 → 5, 429 → 6, everything else → 1). Validation errors raised by the CLI itself (e.g. malformed `--limit`) exit 2.
-
-## Scope
-
-This CLI ships the full dev-portal command surface — `auth`, `apps`, `keys`, `agents`, `providers`, `managed-secrets`, `policy` (read-only at the app level), `audit`, `pats`, `link` / `unlink`, `completion`, `self-update`, and `sdk-passthrough` as a typed-route escape hatch. Backend routes are PAT-callable via `dashboard_*` scopes (see the [scope catalog](https://docs.alterauth.com/api-reference/scopes) for the full list).
-
-**Managed secrets — destructive verb tier:** `alter managed-secrets delete <secret-id>` cascade-revokes every grant and delegation tied to the secret, removes the stored credential from secret storage, and writes cascade audit log entries — irrecoverable. The route is gated by `dashboard_secrets:delete` (NOT bundled into `:write` or `:admin`) AND requires `?confirm=<slug>` matching the target secret's slug. The CLI prompts interactively when stdin is a TTY; CI must pass `--confirm <slug>` explicitly. Mirrors `alter apps delete`. Soft-delete operations on grants (`grants revoke`) use the recoverable `:write` tier.
-
-**Managed secrets — credential intake:** `create` and `rotate` accept the credential value through three channels, in decreasing safety order: `--credential-value -` reads one line from stdin (preferred for CI piping), `--credential-value @/path/to/file` reads from a file, and `--credential-value <value>` accepts the value inline with a stderr warning about shell-history leakage. Multi-field templates (those whose backend Pydantic model requires more than a single primary credential string) take `--credentials @file.json` (a JSON object of string fields, takes precedence) or repeated `--credential-field key=value` flags.
-
-**Dashboard-only operations** (intentional, not scope gaps):
+All commands accept `--output=json|table|jsonl` and `--fields a,b,c`. See [scripting](https://docs.alterauth.com/reference/cli/scripting) for exit codes and CI patterns, and [authentication](https://docs.alterauth.com/reference/cli/authentication) for token storage details.
 
-- PAT mint / revoke — a PAT cannot manage another PAT, including its own.
-- Org-wide key policy (`/organizations/current/key-policy`) — reading the response body is a security-posture fingerprint, so the route refuses PAT auth on both reads and writes.
-- Identity-provider configuration — affects every grant in the org; never settable by a single scripted call.
-- App-level policy *writes* / *deletes* — only `policy show-app` is exposed by the CLI; mutations remain dashboard-only until a CLI use case emerges.
+## License
 
-When the CLI doesn't model a route you need, drop down to `alter sdk-passthrough request <METHOD> <path>` — it forwards the request with the current PAT and prints the raw JSON.
+MIT

package/dist/cli.js

@@ -1,8 +1,5 @@
 #!/usr/bin/env node
 
-// src/cli.ts
-import { Command as Command14 } from "commander";
-
 // src/exit-codes.ts
 var EXIT_ERROR = 1;
 var EXIT_USAGE = 2;
@@ -176,7 +173,7 @@ async function maybePrintUpdateBanner(currentVersion, argv2 = process.argv.slice
 // package.json
 var package_default = {
   name: "@alter-ai/cli",
-  version: "0.3.0",
+  version: "0.3.2",
   description: "Command-line interface for the Alter Vault dev portal \u2014 scripted dashboard automation.",
   type: "module",
   bin: {
@@ -192,7 +189,9 @@ var package_default = {
     dev: "tsx src/cli.ts",
     test: "vitest run",
     "test:watch": "vitest",
-    typecheck: "tsc --noEmit",
+    "docs:check": "tsx scripts/check-docs-drift.ts",
+    "docs:print": "tsx scripts/check-docs-drift.ts --print",
+    typecheck: "tsc --noEmit && tsc -p tsconfig.scripts.json",
     lint: "eslint src/ tests/ --ext .ts",
     format: "prettier --write 'src/**/*.ts' 'tests/**/*.ts'"
   },
@@ -224,6 +223,9 @@ var package_default = {
   }
 };
 
+// src/program.ts
+import { Command as Command14 } from "commander";
+
 // src/commands/agents.ts
 import { Command } from "commander";
 
@@ -6227,6 +6229,21 @@ var Agent = class _Agent {
   async connect(options) {
     return this.#client.connect(options);
   }
+  /**
+   * Poll a Connect session to completion. See
+   * {@link _VaultClient.pollConnectSession} for the full signature.
+   */
+  async pollConnectSession(...args) {
+    return this.#client.pollConnectSession(...args);
+  }
+  /**
+   * Mint a recovery Connect session from a typed error. See
+   * {@link _VaultClient.createConnectSessionForError} for the full
+   * signature.
+   */
+  async createConnectSessionForError(...args) {
+    return this.#client.createConnectSessionForError(...args);
+  }
   // ── Delegation self-revoke ─────────────────────────────────────────────
   /**
    * Opt out of this agent's delegation on an OAuth grant.
@@ -6406,6 +6423,21 @@ var App = class _App {
   async connect(options) {
     return this.#client.connect(options);
   }
+  /**
+   * Poll a Connect session to completion. See
+   * {@link _VaultClient.pollConnectSession} for the full signature.
+   */
+  async pollConnectSession(...args) {
+    return this.#client.pollConnectSession(...args);
+  }
+  /**
+   * Mint a recovery Connect session from a typed error. See
+   * {@link _VaultClient.createConnectSessionForError} for the full
+   * signature.
+   */
+  async createConnectSessionForError(...args) {
+    return this.#client.createConnectSessionForError(...args);
+  }
   // ── Auth (operator-only) ───────────────────────────────────────────────
   async authenticate(options) {
     return this.#client.authenticate(options);
@@ -6839,7 +6871,7 @@ var DEFAULT_BASE_URL = "https://backend.alterauth.com";
 var PAT_API_PREFIX = "/api/v1/dev-portal";
 var HTTP_ERROR_THRESHOLD = 400;
 var DEFAULT_TIMEOUT_MS = 3e4;
-var CLI_VERSION = "0.3.0";
+var CLI_VERSION = "0.3.2";
 var USER_AGENT = buildUserAgent();
 function buildUserAgent() {
   let osTag = "";
@@ -7770,6 +7802,31 @@ var ManagedSecretsNamespace = class {
     );
     return expectDict(body, "managed_secrets.rotate", 200);
   }
+  /**
+   * Set the per-secret user → agent delegation policy. Requires
+   * ``dashboard_secrets:write``. Controls whether a group-typed grant on
+   * this secret may be delegated to an agent (``allow_group_source``) and
+   * the per-delegation TTL ceiling (``max_delegation_ttl_days``).
+   *
+   * REPLACE semantics — the backend overwrites the whole policy object,
+   * so the command always sends the full intended state (omitting
+   * ``max_delegation_ttl_days`` lets the backend apply its 90-day default).
+   */
+  async setDelegationPolicy(appId, secretId, options) {
+    const app = encodePathParam(appId, "appId");
+    const secret = encodePathParam(secretId, "secretId");
+    const payload = filterUndefined({
+      allow_group_source: options.allow_group_source,
+      max_delegation_ttl_days: options.max_delegation_ttl_days
+    });
+    const body = await this.#client._call(
+      "PUT",
+      `/apps/${app}/managed-secrets/${secret}/delegation-policy`,
+      "managed_secrets.set_delegation_policy",
+      { jsonBody: payload }
+    );
+    return expectDict(body, "managed_secrets.set_delegation_policy", 200);
+  }
   /**
    * List grants on a managed secret. Requires ``dashboard_secrets:read``.
    *
@@ -10686,7 +10743,7 @@ function buildKeysCommand() {
     }
   );
   keys.command("rotate").description(
-    "Rotate a key (new plaintext returned ONCE; old key enters grace until revoke). Requires dashboard_keys:admin scope."
+    "Rotate a key (new plaintext returned ONCE; old key enters grace until revoke). Requires dashboard_keys:write scope."
   ).option("--app <app-id>", "App ID. Falls back to ALTER_APP_ID env or .alter/config.yaml").requiredOption("--key <key-id>", "Key ID", parseUuidArgument("--key")).option(
     "--scopes <list>",
     "Optional new scope set (defaults to the key's current scopes)"
@@ -11695,7 +11752,14 @@ function buildManagedSecretsCommand() {
   ).option(
     "--injection-rule <@file.json>",
     "Path-prefixed JSON file containing the additional_injections array"
-  ).option("--label <label>", "Base-grant display label").option("--account-identifier <id>", "Optional account identifier metadata").option("--account-display-name <name>", "Optional account display name metadata").option("--output <format>", "Output format: json|table (default: json)", "json").action(
+  ).option("--label <label>", "Base-grant display label").option("--account-identifier <id>", "Optional account identifier metadata").option("--account-display-name <name>", "Optional account display name metadata").option(
+    "--allow-group-delegation",
+    "Allow members of a group-typed grant on this secret to delegate it to an agent (default: off)"
+  ).option(
+    "--max-delegation-ttl-days <days>",
+    "Cap on a single delegation's lifetime, in days (1..1825, default 90)",
+    parseBoundedInt("--max-delegation-ttl-days", 1, 5 * 365)
+  ).option("--output <format>", "Output format: json|table (default: json)", "json").action(
     async (options) => {
       const format = coerceOutputFormat(options.output);
       const appId = resolveAppIdOrExit(options.app);
@@ -11718,7 +11782,9 @@ function buildManagedSecretsCommand() {
           "injectionRule",
           "label",
           "accountIdentifier",
-          "accountDisplayName"
+          "accountDisplayName",
+          "allowGroupDelegation",
+          "maxDelegationTtlDays"
         ].filter((k) => {
           if (k === "credentialType") return options.credentialType !== "bearer_token";
           return options[k] !== void 0;
@@ -11804,6 +11870,16 @@ function buildManagedSecretsCommand() {
       if (options.accountDisplayName !== void 0) {
         body.account_display_name = options.accountDisplayName;
       }
+      if (options.allowGroupDelegation !== void 0 || options.maxDelegationTtlDays !== void 0) {
+        const delegationPolicy = {};
+        if (options.allowGroupDelegation !== void 0) {
+          delegationPolicy.allow_group_source = options.allowGroupDelegation;
+        }
+        if (options.maxDelegationTtlDays !== void 0) {
+          delegationPolicy.max_delegation_ttl_days = options.maxDelegationTtlDays;
+        }
+        body.delegation_policy = delegationPolicy;
+      }
       await withClient(async (client) => {
         const row = await client.managedSecrets.create(
           resolveAppIdOrExit(options.app),
@@ -11813,6 +11889,29 @@ function buildManagedSecretsCommand() {
       });
     }
   );
+  root.command("set-delegation-policy <secret-id>").description(
+    "Set the user \u2192 agent delegation policy on a managed secret. REPLACES the current policy (omitting --allow-group-delegation turns group delegation OFF). Requires dashboard_secrets:write."
+  ).option("--app <app-id>", "App ID. Falls back to ALTER_APP_ID env or .alter/config.yaml").option(
+    "--allow-group-delegation",
+    "Allow members of a group-typed grant on this secret to delegate it to an agent (default: off)"
+  ).option(
+    "--max-delegation-ttl-days <days>",
+    "Cap on a single delegation's lifetime, in days (1..1825; omit for the 90-day default)",
+    parseBoundedInt("--max-delegation-ttl-days", 1, 5 * 365)
+  ).option("--output <format>", "Output format: json|table (default: json)", "json").action(
+    async (rawSecretId, options) => {
+      const format = coerceOutputFormat(options.output);
+      const appId = resolveAppIdOrExit(options.app);
+      const secretId = parseUuidArgument("<secret-id>")(rawSecretId);
+      await withClient(async (client) => {
+        const row = await client.managedSecrets.setDelegationPolicy(appId, secretId, {
+          allow_group_source: options.allowGroupDelegation === true,
+          max_delegation_ttl_days: options.maxDelegationTtlDays
+        });
+        emit(format, row);
+      });
+    }
+  );
   root.command("delete <secret-id>").description(
     "Cascade-delete a managed secret. Requires dashboard_secrets:delete scope (NOT bundled into :write). Cascade-revokes grants + delegations + audit anchors and vault-deletes the credential."
   ).option("--app <app-id>", "App ID").option(
@@ -12092,6 +12191,46 @@ function collectRedirectUris(value, previous = []) {
   const next = value.split(",").map((s) => s.trim()).filter(Boolean);
   return [...previous, ...next];
 }
+function sanitizeStderrText(value) {
+  return value.replace(/[\u0000-\u001f\u007f-\u009f]+/g, " ").trim();
+}
+function surfaceProviderResponse(row) {
+  if (typeof row !== "object" || row === null) return;
+  const r = row;
+  const preflight = r.preflight;
+  if (preflight && typeof preflight === "object") {
+    const status = preflight.status;
+    const msg = typeof preflight.message === "string" ? sanitizeStderrText(preflight.message) : "";
+    if (status === "passed") {
+      process.stderr.write("alter: preflight: passed\n");
+    } else if (status === "failed") {
+      process.stderr.write(
+        `alter: preflight: failed${msg ? ` \u2014 ${msg}` : ""}
+`
+      );
+    } else if (status === "inconclusive") {
+      process.stderr.write(
+        `alter: preflight: inconclusive${msg ? ` \u2014 ${msg}` : ""} (save was allowed)
+`
+      );
+    }
+  }
+  const bc = r.breaking_changes;
+  if (Array.isArray(bc) && bc.length > 0) {
+    process.stderr.write(
+      `alter: warning: ${bc.length} breaking change(s) \u2014 ${sanitizeStderrText(JSON.stringify(bc))}
+`
+    );
+  }
+  const warning = r.warning;
+  if (typeof warning === "string") {
+    const sanitized = sanitizeStderrText(warning);
+    if (sanitized.length > 0) {
+      process.stderr.write(`alter: warning: ${sanitized}
+`);
+    }
+  }
+}
 function buildProvidersCommand() {
   const providers = new Command11("providers").description(
     "Manage OAuth provider configs"
@@ -12182,6 +12321,7 @@ function buildProvidersCommand() {
             appId,
             body
           );
+          surfaceProviderResponse(row);
           emit(format, row);
         });
         return;
@@ -12221,6 +12361,7 @@ function buildProvidersCommand() {
           scopes,
           redirect_uris: redirects
         });
+        surfaceProviderResponse(row);
         emit(format, row);
       });
     }
@@ -12267,6 +12408,7 @@ function buildProvidersCommand() {
             options.provider,
             body
           );
+          surfaceProviderResponse(row);
           emit(format, row);
         });
         return;
@@ -12293,6 +12435,7 @@ function buildProvidersCommand() {
           redirect_uris: redirects,
           status: providerStatus
         });
+        surfaceProviderResponse(row);
         emit(format, row);
       });
     }
@@ -12565,6 +12708,46 @@ function buildSelfUpdateCommand() {
   });
 }
 
+// src/program.ts
+function buildProgram() {
+  const program2 = new Command14();
+  program2.name("alter").description("Alter Vault command-line interface").version(package_default.version);
+  program2.option(
+    "--fields <list>",
+    "Comma-separated top-level keys to keep in JSON output (e.g. ``--fields id,name``). Inert with --output=table."
+  );
+  program2.hook("preAction", (thisCommand) => {
+    setGlobalFields(void 0);
+    const raw = thisCommand.opts().fields;
+    if (raw !== void 0) {
+      try {
+        setGlobalFields(parseFieldsList(raw));
+      } catch (e) {
+        process.stderr.write(
+          `alter: ${e instanceof Error ? e.message : String(e)}
+`
+        );
+        process.exit(EXIT_USAGE);
+      }
+    }
+  });
+  program2.addCommand(buildAuthCommand());
+  program2.addCommand(buildAppsCommand());
+  program2.addCommand(buildKeysCommand());
+  program2.addCommand(buildAgentsCommand());
+  program2.addCommand(buildProvidersCommand());
+  program2.addCommand(buildManagedSecretsCommand());
+  program2.addCommand(buildPolicyCommand());
+  program2.addCommand(buildAuditCommand());
+  program2.addCommand(buildPatsCommand());
+  program2.addCommand(buildLinkCommand());
+  program2.addCommand(buildUnlinkCommand());
+  program2.addCommand(buildCompletionCommand());
+  program2.addCommand(buildSdkPassthroughCommand());
+  program2.addCommand(buildSelfUpdateCommand());
+  return program2;
+}
+
 // src/cli.ts
 var COMMANDER_USAGE_CODES = /* @__PURE__ */ new Set([
   "commander.missingArgument",
@@ -12628,41 +12811,7 @@ function rewriteLegacySelfUpdateVersionFlag(argv2) {
   }
   return rewritten;
 }
-var program = new Command14();
-program.name("alter").description("Alter Vault command-line interface").version(package_default.version);
-program.option(
-  "--fields <list>",
-  "Comma-separated top-level keys to keep in JSON output (e.g. ``--fields id,name``). Inert with --output=table."
-);
-program.hook("preAction", (thisCommand) => {
-  setGlobalFields(void 0);
-  const raw = thisCommand.opts().fields;
-  if (raw !== void 0) {
-    try {
-      setGlobalFields(parseFieldsList(raw));
-    } catch (e) {
-      process.stderr.write(
-        `alter: ${e instanceof Error ? e.message : String(e)}
-`
-      );
-      process.exit(EXIT_USAGE);
-    }
-  }
-});
-program.addCommand(buildAuthCommand());
-program.addCommand(buildAppsCommand());
-program.addCommand(buildKeysCommand());
-program.addCommand(buildAgentsCommand());
-program.addCommand(buildProvidersCommand());
-program.addCommand(buildManagedSecretsCommand());
-program.addCommand(buildPolicyCommand());
-program.addCommand(buildAuditCommand());
-program.addCommand(buildPatsCommand());
-program.addCommand(buildLinkCommand());
-program.addCommand(buildUnlinkCommand());
-program.addCommand(buildCompletionCommand());
-program.addCommand(buildSdkPassthroughCommand());
-program.addCommand(buildSelfUpdateCommand());
+var program = buildProgram();
 applyExitOverride(program);
 var argv = rewriteLegacySelfUpdateVersionFlag(process.argv);
 async function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alter-ai/cli",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Command-line interface for the Alter Vault dev portal — scripted dashboard automation.",
   "type": "module",
   "bin": {
@@ -16,7 +16,9 @@
     "dev": "tsx src/cli.ts",
     "test": "vitest run",
     "test:watch": "vitest",
-    "typecheck": "tsc --noEmit",
+    "docs:check": "tsx scripts/check-docs-drift.ts",
+    "docs:print": "tsx scripts/check-docs-drift.ts --print",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.scripts.json",
     "lint": "eslint src/ tests/ --ext .ts",
     "format": "prettier --write 'src/**/*.ts' 'tests/**/*.ts'"
   },