@alter-ai/cli 0.1.0

package/README.md

@@ -0,0 +1,208 @@
+# `@alter-ai/cli` — the Alter Vault command-line interface
+
+`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.
+
+## 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://dashboard.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.
+
+```bash
+export ALTER_PAT="alter_pat_xxxxxxxxxxxxxxxxxxxxxxxx_yyyyyy"
+alter apps list
+```
+
+**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
+```
+
+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):
+
+- 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.
+
+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.

package/dist/cli.d.ts

@@ -0,0 +1,76 @@
+/**
+ * `alter` — Alter Vault command-line interface.
+ *
+ * v1 surface:
+ *   alter auth login [--token <pat> | --token-file | --token-stdin]
+ *                       Browser-dance OR explicit-token sign-in
+ *   alter auth status   Show the currently-active PAT
+ *   alter auth logout   Forget the locally-stored PAT
+ *
+ *   alter apps          list / create / show / update / delete
+ *   alter keys          list / mint / show / rotate / revoke / rename
+ *   alter agents        list / create / show / update / revoke +
+ *                       mint-key / list-keys / revoke-key
+ *   alter providers     list / create / show / update / delete
+ *   alter managed-secrets
+ *                       templates / list / show / create / delete /
+ *                       rotate / access / users +
+ *                       grants {list, list-for-agent, create, update, revoke} +
+ *                       groups {list, show}
+ *   alter policy        show / show-app    (read-only; updates dashboard-only)
+ *   alter audit         list / show / portal-actions / grant-events / traces
+ *
+ *   alter pats whoami   Same as `auth status`, under the pats namespace
+ *
+ *   alter completion install [--shell ...]   Generate shell completion
+ *   alter sdk-passthrough request <grant>    Runtime SDK escape hatch
+ *   alter self-update                        Upgrade the CLI via npm
+ *
+ * Commands intentionally NOT in the CLI (per CLAUDE.md
+ * Destructive-Action Policy):
+ *   - alter policy update                   Org-wide config edits are
+ *                                           dashboard-only (one CLI call
+ *                                           cannot weaken security org-wide).
+ *   - alter org delete / alter org transfer Org-level destructive ops
+ *                                           are dashboard-only.
+ *
+ * Auth resolution order: ALTER_PAT env var → OS keychain (keytar) →
+ * ~/.config/alter/auth.toml plaintext fallback (with first-use warning).
+ *
+ * Distribution: shipped as `@alter-ai/cli`, binary name `alter`. Single-
+ * file bundle via `tsup`; the bundled `dist/cli.js` carries an
+ * executable shebang via the build script.
+ */
+/**
+ * Rewrite the legacy ``self-update --version <X>`` invocation to use the
+ * canonical ``--to <X>`` flag, emitting a deprecation warning to stderr.
+ *
+ * Background: the subcommand option used to be called ``--version`` but
+ * collided with Commander's program-wide ``-V/--version`` flag. The
+ * collision meant ``self-update --version 0.2.0`` (space form) was
+ * consumed by the global flag, printed the CLI version, and exited 0 —
+ * the operator's requested install never happened. QA test ID SU006 +
+ * the /review Pass 0 Scenario D follow-up.
+ *
+ * The rename to ``--to`` fixed the canonical surface, but operators
+ * with muscle memory from the old flag still hit the silent-exit-0
+ * footgun. This pre-parser runs BEFORE Commander sees argv: if the
+ * legacy pattern matches, the flag is rewritten in-place to ``--to`` so
+ * Commander dispatches into the subcommand's validator path. A
+ * deprecation note is written to stderr so the operator knows to
+ * update their scripts.
+ *
+ * Scope: this pre-parser ONLY touches argv when the ``self-update``
+ * subcommand is present. Every other subcommand sees argv verbatim.
+ * The rewrite handles both ``--version <value>`` (space form) and
+ * ``--version=<value>`` (equals form). A bare ``--version`` without a
+ * follow-up value is LEFT ALONE — that's the legitimate "print CLI
+ * version" invocation, and rewriting it to ``--to`` (which requires a
+ * value) would surface a confusing error.
+ *
+ * Returns the (possibly rewritten) argv array. Pure function modulo
+ * the stderr write on rewrite; safe to call on every CLI startup.
+ */
+declare function rewriteLegacySelfUpdateVersionFlag(argv: string[]): string[];
+
+export { rewriteLegacySelfUpdateVersionFlag };