@sylphx/cli 0.3.2 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,238 @@
+# @sylphx/cli
+
+## 0.5.0
+
+### Minor Changes
+
+- [`c4471cf`](https://github.com/SylphxAI/platform/commit/c4471cf729a2a60865d0df5bbf04b87f55d57858) Thanks [@shtse8](https://github.com/shtse8)! - OAuth device flow migrated from platform bypass to BaaS plane (RFC 8628). New `sylphx logout` command (BaaS-dogfooded), automatic OAuth refresh, and `sylphx.toml` manifest workflow (`pull` / `push` / `validate` / `diff` / versioning). New top-level commands: `regions`, `branch-db`, `scale`, `secrets`, `realtime`, `saml`, `ai`, `session-replay`, `search`, `engagement`, `consent`, `privacy`, `referrals`, `newsletter`. ESM-only build, bundled `@sylphx/management`, install-to-run install path fixed.
+
+## 0.4.1 (2026-04-24 — ADR-089 Phase 4c)
+
+### Added
+
+- **`sylphx user`** — current-user self-service: `profile show|update`, `security`, `sessions list|revoke|purge`, `export` (GDPR), `delete` (GDPR erasure). Dogfoods `@sylphx/management.user.*`.
+- **`sylphx users`** — platform-admin user directory: `list`, `get <userId>`, `set-role <userId> <role>`. Dogfoods `@sylphx/management.admin.*` user-search endpoints.
+- **`sylphx admin`** — platform-admin ops grouped by surface: `quotas list|alerts|ack`, `audit logs`, `invitations list|create|revoke|resend`, `jwt-keys list|rotate|retire`, `project migrate`. Dogfoods `@sylphx/management.admin.*`.
+
+### Coverage
+
+- `scripts/check-cli-coverage.ts` flipped from advisory to strict. 46/46 non-excluded `@sylphx/management` namespaces covered (100%); 9 namespaces excluded with per-entry rationale (`kv`, `authSettings`, `billingSettings`, `branchDatabases`, `envVars`, `github`, `management`, `refresh`, `serviceTokenRequests` — BaaS-plane / Console-only / internal-lifecycle). Kebab ↔ camelCase namespace normalisation matches the Phase 4b `check-paas-sdk-coverage.ts` pattern; an extended CLI-alias table covers non-trivial renames (e.g. `tokens` ↔ `serviceTokens`, `orgs` ↔ `organizations`, `session-replay` ↔ `sessionReplay`).
+- Completes ADR-089 Phase 4 (S6 + S7 + S8 all strict): `check-baas-sdk-coverage` + `check-paas-sdk-coverage` + `check-cli-coverage` all block CI on regression.
+
+## 0.4.0 (wrongly labelled 1.0.0; reverted 2026-04-23 — still in beta)
+
+### Changes
+
+- **Beta release (0.4.0).** The CLI's public surface is NOT yet frozen. 60 commands across auth, project lifecycle, deployment, managed primitives (db / storage / volumes / services / tasks / domains / functions / sandbox / runners), integrations (webhooks / flags / secrets / realtime / SAML / AI / session-replay / search / engagement / consent / privacy / referrals / newsletter / backup), billing (plan / billing / experiments / analytics), observability (monitoring / certs / email / notifications), and machine identity (tokens / OIDC / CI).
+- **`@effect/cli` migration complete** (ADR-073 Strategy A). Every command is a pure `Effect` value assembled under one root; `BunRuntime.runMain` is the single `runPromise`-like call site (ADR-058 Rule 21 compliant). Tests swap the Layer and assert on the Exit channel without subprocessing — 351+ passing tests.
+- **ESM-only**, Node ≥ 20 / Bun ≥ 1.3. Previous 0.x CJS output caused `Cannot find module './cjs/index.cjs'` crashes when Effect's package exports resolved to the wrong conditional branch; tsup now emits ESM exclusively.
+- **Self-contained global install.** `@sylphx/management` and `@sylphx/contract` are bundled via tsup `noExternal` — `bun add -g @sylphx/cli` has zero workspace peers to resolve, and consumers never see Effect as a transitive runtime dep through `@sylphx/management`.
+- **Correct `bin` wiring.** `bin.sylphx` points at `./dist/main.js`; the `#!/usr/bin/env bun` shebang is preserved by tsup. Global install + immediate run works with no post-install step.
+
+### OAuth + service tokens (ADR-059)
+
+- **OAuth device flow** replaces legacy `slx_*` personal access tokens as the default login mode. Tokens are an atomic `{ accessToken, refreshToken, expiresAt }` triple stored at `~/.sylphx/config.json` with mode `0600`. The refresh interceptor transparently rotates the access token before expiry; a failed refresh prompts re-login.
+- **Service tokens** (`sk_*`) via `SYLPHX_API_TOKEN=...` for CI / CD and server-side automation. Per-project scope with per-token revocation.
+- **OIDC federation** (`sylphx oidc`) for passwordless CI — GitHub Actions / GitLab CI receive short-lived tokens via `id_token` exchange.
+
+### Plane discipline (ADR-083)
+
+The CLI is **Management-plane-only**. There is no `sylphx kv get`, `sylphx email send`, or `sylphx flags evaluate` — runtime BaaS verbs live inside the deployed application via [`@sylphx/sdk`](https://www.npmjs.com/package/@sylphx/sdk). Attempting to use a `pk_*` / `sk_*` BaaS key against `api.sylphx.com/v1` returns `401 plane_mismatch`.
+
+### Contract-first types (ADR-084)
+
+All wire types (request bodies, response envelopes, error shapes) derive from [`@sylphx/contract`](https://www.npmjs.com/package/@sylphx/contract). Hand-written type shims were removed; adding a new capability starts with a contract entry, not this package.
+
+### Version compatibility
+
+| CLI                      | Management API      | Contract                              |
+| ------------------------ | ------------------- | ------------------------------------- |
+| `@sylphx/cli@0.x` (beta) | `api.sylphx.com/v1` | `@sylphx/contract` (workspace / beta) |
+
+---
+
+## 0.3.3
+
+### Patch Changes
+
+- Updated dependencies [[`b98b1c1`](https://github.com/SylphxAI/platform/commit/b98b1c1052b196bfa1440c4d7ed03c53ff549614)]:
+  - @sylphx/management@0.1.0
+
+## 0.3.2
+
+### Patch Changes
+
+- Updated dependencies [[`a493b61`](https://github.com/SylphxAI/platform/commit/a493b61743ae6559a91ed056175304948ab6d43f)]:
+  - @sylphx/management@1.0.1
+
+## 0.3.1
+
+### Patch Changes
+
+- [`1381a94`](https://github.com/SylphxAI/platform/commit/1381a94046043517841e9ed35f5d36afeb9c9cff) Thanks [@shtse8](https://github.com/shtse8)! - feat: extract Management SDK as standalone @sylphx/management package
+
+  - New package @sylphx/management@1.0.0 — full Management API client
+  - Resource-namespaced interface: mgmt.projects._, mgmt.deployments._, etc.
+  - CLI now depends on @sylphx/management (dogfooding)
+  - All types exported from @sylphx/management
+
+- Updated dependencies [[`1381a94`](https://github.com/SylphxAI/platform/commit/1381a94046043517841e9ed35f5d36afeb9c9cff)]:
+  - @sylphx/management@1.0.0
+
+## 0.3.0
+
+### Minor Changes
+
+- [`0e1c4a9`](https://github.com/SylphxAI/platform/commit/0e1c4a9d15ddab0068d4863b2423c6c7e79ec77c) Thanks [@shtse8](https://github.com/shtse8)! - feat: full API parity, bug fixes, new commands (v0.2.0)
+
+  **New commands:**
+
+  - `sylphx tasks` — manage task definitions (list/get/create/update/rm), supports job/cron/service modes
+  - `sylphx promote` — promote staging → production environment
+  - `sylphx config` — manage per-environment app config (list/get/set/delete)
+  - `sylphx storage` — manage object storage buckets
+  - `sylphx volumes` — manage persistent volumes
+  - `sylphx services` — list and deploy service blueprints
+  - `sylphx resources` — bind/unbind shared resources (databases, storage)
+
+  **Bug fixes:**
+
+  - `sylphx rollback` — was sending `{ envType }` but backend requires `{ envId | deploymentRecordId }`; now resolves correctly
+  - `sylphx env rm` — backend was missing DELETE endpoint; added to server
+  - `sylphx domains` — all domain commands were hitting `/domains/projects/...` (404); correct path is `/projects/.../domains/...`
+  - `sylphx db create` — tier options now include all 5 tiers: starter | standard | performance | enterprise1 | enterprise2
+  - Fixed 8 API response-shape mismatches (wrong wrapper fields causing silent empty results)
+
+  **Type generation:**
+
+  - `generate:types` URL fixed: was `sylphx.com/api/openapi.json` (404), now `docs.api.sylphx.com/v1/openapi.json`
+  - `generate:types:local` fixed: was `localhost:3002`, now `localhost:3003` (sylphx-sdk dev server)
+
+## 0.1.9
+
+### Patch Changes
+
+- [`e611372`](https://github.com/SylphxAI/platform/commit/e611372008511be7c500622fd51a3cc5e629f4bf) Thanks [@shtse8](https://github.com/shtse8)! - fix(open): read URL from environments[] array instead of missing top-level field
+
+  fix(status): show URL from environments[] — was always blank
+
+  fix(db list): add missing DeploymentStatusEnv type; annotate environments field
+
+## 0.1.8
+
+### Patch Changes
+
+- [`aecec9b`](https://github.com/SylphxAI/platform/commit/aecec9be811aa94664c5ff1e96f8404dd8b8a236) Thanks [@shtse8](https://github.com/shtse8)! - fix(cli): add envType/isActive/publicKey to Project.environments type
+
+  The server-side environments array includes envType (and more) which
+  is required for the projects list display. Fixes TypeScript error
+  TS2339 in projects.ts and link.ts.
+
+## 0.1.7
+
+### Patch Changes
+
+- [`87134cd`](https://github.com/SylphxAI/platform/commit/87134cd2781e200ba939ce35bd660bc8c77c1b6b) Thanks [@shtse8](https://github.com/shtse8)! - fix(cli): proper fixes — domains direct API, resolveEnvId removed
+
+  - Domains API now uses `GET/POST/DELETE /domains/projects/{projectId}/domains?envType=`
+    — no extra API call to resolve envId first (was 2 roundtrips, now 1)
+  - `resolveEnvId` helper removed (no longer needed)
+  - `listDomains` now correctly reads `customDomains` from response shape
+  - `listDomains` + `addDomain` + `removeDomain` all updated to new route
+  - 5 tests updated + 2 new tests (74 total)
+
+## 0.1.6
+
+### Patch Changes
+
+- [`6b79cd9`](https://github.com/SylphxAI/platform/commit/6b79cd956152bfb3387bab2aeab2edd9b21cff42) Thanks [@shtse8](https://github.com/shtse8)! - fix(logs): stream=true required, content field, formatLogEntry
+
+  - `createLogStream` now includes `stream=true` query param — without it the
+    backend returns JSON instead of SSE, causing EventSource to emit no events
+    and the CLI to silently timeout
+  - `stream` param renamed from legacy `tail` to `limit` (backend uses `limit`)
+  - `formatLogEntry` now reads `content` field from build-log chunk payloads
+    (backend sends `{ content, level, timestamp, sequence }`, not `message`)
+  - Added `logs.test.ts` (8 tests) covering formatLogEntry for all field variants
+  - Added 4 createLogStream URL tests in api.test.ts
+  - Total: 73 tests passing (was 61)
+
+## 0.1.5
+
+### Patch Changes
+
+- [`2ea1157`](https://github.com/SylphxAI/platform/commit/2ea1157f178b4a8f7600fb3f9db1f26e0f2f9606) Thanks [@shtse8](https://github.com/shtse8)! - Fix remaining bugs found in 0.1.4 testing:
+
+  - **env list crash**: `listEnvVars()` now unwraps `{ data: [...] }` API response (same pattern as projects/databases)
+  - **projects list environments empty**: Use `e.name || e.envType` instead of `e.slug` (field doesn't exist in API response)
+
+## 0.1.4
+
+### Patch Changes
+
+- [`28cb620`](https://github.com/SylphxAI/platform/commit/28cb620e701bb0eaaac0680428aacf4efc38369b) Thanks [@shtse8](https://github.com/shtse8)! - Fix B1-B6 bugs from 0.1.3 testing:
+
+  - **B1** (400 on status/deploy/env): Backend now accepts legacy `prefix_hex32` IDs alongside base58
+  - **B2** (logs Unauthorized): `eventsource@2` uses `http/https`, not `fetch` — pass auth via `headers` option
+  - **B3** (projects.map crash): Unwrap `{ object: 'list', data: [...] }` response from API
+  - **B4** (domains 410): Route moved to `/domains/projects/{envId}/domains` — resolve envId first
+  - **B5** (db 404): Databases now use unified Resources API at `/resources?kind=database`
+  - **B6** (version 0.1.0): Read version from package.json instead of hardcoding
+
+## 0.1.3
+
+### Patch Changes
+
+- [`fbb8075`](https://github.com/SylphxAI/platform/commit/fbb80755b05048728c97cc0799dfd2636f8343ac) Thanks [@shtse8](https://github.com/shtse8)! - Fix `sylphx whoami` returning 404
+
+  CLI was calling `GET /v1/users/me` (plural) but backend mounts user routes
+  at `/user` (singular). Updated to call `GET /v1/user/me`.
+
+  Backend adds a new `GET /user/me` endpoint that returns `{ user, orgs }`
+  — the combined response the CLI expects for `sylphx whoami`.
+
+## 0.1.2
+
+### Patch Changes
+
+- [`ac5e3a3`](https://github.com/SylphxAI/platform/commit/ac5e3a36771e11f288d15391c90d610a2366aeb6) Thanks [@shtse8](https://github.com/shtse8)! - Fix `sylphx logs` crash in Node.js
+
+  `eventsource@2` exports the class directly (`module.exports = EventSource`),
+  not as a named export. Destructuring `const { EventSource } = require("eventsource")`
+  returned `undefined`, causing `EventSource is not a constructor` at runtime.
+
+  Fix: `const EventSource = require("eventsource")` — the module IS the constructor.
+
+## 0.1.1
+
+### Patch Changes
+
+- [`3aac758`](https://github.com/SylphxAI/platform/commit/3aac7582bd9b8e4a1a5c507bb4826330de267f40) Thanks [@shtse8](https://github.com/shtse8)! - Fix body-read crash on non-JSON API error responses
+
+  `api.ts` was calling `res.json()` and catching the error to fall back to `res.text()`,
+  but by that point the response body stream was already consumed, causing:
+  `Body is unusable: Body has already been read`
+
+  Fix: read body once with `res.text()`, then attempt `JSON.parse()`.
+
+  Also adds 45 regression tests covering all api methods, URL construction,
+  auth headers, error handling, and 204 No Content responses.
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial release of Sylphx CLI
+- **`sylphx login`** — Authenticate with the Sylphx Platform (browser OAuth or `--token` for CI/CD)
+- **`sylphx logout`** — Clear stored credentials
+- **`sylphx whoami`** — Display current authenticated user and org
+- **`sylphx link`** — Link current directory to a Sylphx app
+- **`sylphx deploy`** — Deploy the linked app with real-time log streaming
+- **`sylphx rollback`** — Roll back to a previous deployment
+- **`sylphx logs`** — Stream live application logs
+- **`sylphx status`** — Show deployment and health status
+- **`sylphx env list`** — List environment variables
+- **`sylphx env set`** — Set an environment variable
+- **`sylphx env remove`** — Remove an environment variable
+- **`sylphx domains list`** — List custom domains
+- **`sylphx open`** — Open the app in the browser

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sylphx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,136 +1,250 @@
 # @sylphx/cli
 
 [![npm version](https://img.shields.io/npm/v/@sylphx/cli.svg?style=flat)](https://www.npmjs.com/package/@sylphx/cli)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue?logo=typescript)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue?logo=typescript)](https://www.typescriptlang.org/)
 
-The official CLI tool for the [Sylphx Platform](https://sylphx.com). Deploy, manage logs, environment variables, domains, and more — directly from your terminal.
+The official CLI for the [Sylphx Platform](https://sylphx.com). Deploy and operate your applications — 60 commands across deployment, logs, env vars, domains, managed databases, object storage, monitoring, webhooks, feature flags, and more — directly from your terminal.
 
-📖 **Full documentation:** [sylphx.com/docs/cli](https://sylphx.com/docs/cli)
+Full documentation: [sylphx.com/docs/cli](https://sylphx.com/docs/cli)
 
 ## Installation
 
 ```bash
+bun add -g @sylphx/cli
+# or
 npm install -g @sylphx/cli
 # or
-bun add -g @sylphx/cli
+pnpm add -g @sylphx/cli
 ```
 
-## Quick Start
+Requires **Node.js ≥ 20** (or Bun ≥ 1.3). The CLI binary is `sylphx`; the published package is a single self-contained ESM bundle (`@sylphx/management` and `@sylphx/contract` are bundled via tsup `noExternal`, so there are no workspace peers to resolve on global install).
+
+## Quick start
 
 ```bash
-# Authenticate
+# Authenticate (opens the browser for OAuth device flow)
 sylphx login
 
-# Link your project to a Sylphx app
+# Link the current project to a Sylphx app
 cd my-project
 sylphx link
 
-# Deploy!
+# Ship it
 sylphx deploy
 ```
 
-## Commands
-
-### Authentication
+## Authentication
 
-```bash
-sylphx login                    # Opens browser for OAuth flow
-sylphx login --token <TOKEN>    # Direct token auth (CI/CD)
-sylphx logout                   # Clear stored credentials
-sylphx whoami                   # Show current user + org + app
-```
+The CLI supports two auth paths (ADR-059 + ADR-074):
 
-### Project Management
+| Mode | Use case | How |
+|---|---|---|
+| **OAuth device flow** (default) | Interactive dev | `sylphx login` — browser-backed device flow, 15-min access + 30-day refresh token stored at `~/.sylphx/config.json` (`0600`), auto-refresh built in |
+| **`SYLPHX_TOKEN` env var** | CI / CD / agents | `export SYLPHX_TOKEN=svc_...` — no login step, no disk write, stateless. Service tokens (`svc_*`, ADR-089 §2.10) or short-lived OAuth access JWTs (`eyJ…`) both work |
 
-```bash
-sylphx link                     # Link current directory to a Sylphx app
-sylphx status                   # Show deployment status
-sylphx open                     # Open app in browser
-```
+Legacy `slx_*` personal access tokens were eliminated 2026-04-21 (ADR-059 §1.4) and are no longer accepted by the API.
 
-### Deployments
+Under ADR-059, OAuth tokens are stored as an atomic `{ accessToken, refreshToken, expiresAt }` triple with mode `0600` on disk. The refresh interceptor (`utils/oauth-refresh.ts`) transparently rotates the access token when it's within the refresh window; a failed refresh prompts re-login.
 
 ```bash
-sylphx deploy                         # Deploy to default environment
-sylphx deploy --env staging           # Deploy to staging
-sylphx rollback                       # Rollback to previous deployment
-sylphx rollback --env production      # Rollback production
-```
-
-### Logs
+# Interactive (developers)
+sylphx login
+sylphx whoami        # → "Auth: stored OAuth session (~/.sylphx/config.json)"
+sylphx logout
 
-```bash
-sylphx logs                           # Show recent logs
-sylphx logs -f                        # Follow logs (stream continuously)
-sylphx logs --env staging             # Logs for staging environment
+# Non-interactive (CI / agents)
+export SYLPHX_TOKEN=svc_…
+sylphx whoami        # → "Auth: SYLPHX_TOKEN env var"
+sylphx deploy --env=production
 ```
 
-### Environment Variables
+### Non-interactive use (CI / agents)
 
-```bash
-sylphx env list                       # List all env vars
-sylphx env list --env staging         # List staging env vars
-sylphx env set DATABASE_URL=postgres://...
-sylphx env set PORT=3000 --env staging
-sylphx env rm DATABASE_URL            # Remove an env var
-```
+Set `SYLPHX_TOKEN` and every CLI command honours it as a Bearer token —
+no `sylphx login`, no browser, no `~/.sylphx/config.json` write:
 
-### Domains
+- The env var **wins** over any stored OAuth session — useful when a
+  developer's machine doubles as a CI runner.
+- The OAuth refresh interceptor is **skipped** when the env var is
+  active. Service tokens have no refresh token (rotate via `sylphx
+  tokens rotate` instead); JWTs supplied here are operator-rotated.
+- Empty string (`SYLPHX_TOKEN=`) is treated as unset and falls back to
+  the stored session — defends against misconfigured CI shell exports.
+- The same `SYLPHX_TOKEN` GitHub Actions output minted by `sylphx ci
+  github-actions` is the variable the CLI itself consumes. One contract,
+  no shell glue.
 
-```bash
-sylphx domains list                   # List custom domains
-sylphx domains add example.com        # Add a domain
-sylphx domains rm example.com         # Remove a domain
+GitHub Actions example:
+
+```yaml
+- run: sylphx deploy --env=production
+  env:
+    SYLPHX_TOKEN: ${{ secrets.SYLPHX_TOKEN }}
 ```
 
 ## Configuration
 
-Config is stored in `~/.sylphx/config.json`:
+Stored at `~/.sylphx/config.json`:
 
 ```json
 {
-  "token": "slx_cli_...",
+  "oauth": {
+    "accessToken": "eyJ...",
+    "refreshToken": "ref_...",
+    "expiresAt": "2026-04-23T15:00:00.000Z"
+  },
   "defaultOrg": "my-org",
   "apps": {
-    "/path/to/project": {
-      "appId": "app-uuid",
-      "orgId": "org-slug",
+    "/Users/me/projects/my-app": {
+      "appId": "proj_abc123",
+      "orgId": "org_xyz789",
       "defaultEnv": "production"
     }
   }
 }
 ```
 
-## CI/CD Usage
+Per-project overrides live in `./sylphx.json` (git-committable); the home config is a per-user fallback.
 
-For automated environments, use a pre-generated token:
+## Environment variables
 
-```bash
-sylphx login --token $SYLPHX_API_TOKEN
-sylphx deploy --env production
-```
+| Variable | Description |
+|---|---|
+| `SYLPHX_TOKEN` | Bearer token for non-interactive auth (CI / agents). Accepts `svc_*` service tokens or `eyJ…` OAuth access JWTs. Wins over any stored OAuth session; refresh interceptor is skipped (stateless). Empty string is treated as unset. |
+| `SYLPHX_API_URL` | Override API base URL (default: `https://sylphx.com`) |
 
-Or set the env var:
+## Commands (60)
 
-```bash
-SYLPHX_API_TOKEN=slx_cli_... sylphx deploy
-```
+### Authentication & identity
 
-## Environment Variables
+| Command | Purpose |
+|---|---|
+| `sylphx login` | OAuth device flow — browser-based, stores access + refresh tokens |
+| `sylphx logout` | Clear stored credentials |
+| `sylphx whoami` | Show current user + org + linked app |
 
-| Variable | Description |
+### Project lifecycle
+
+| Command | Purpose |
 |---|---|
-| `SYLPHX_API_URL` | Override API base URL (default: `https://sylphx.com`) |
+| `sylphx init` | Scaffold a new project |
+| `sylphx link` | Link current directory to a Sylphx app |
+| `sylphx unlink` | Remove the project link |
+| `sylphx open` | Open the app in the browser |
+| `sylphx projects` | List / manage projects |
+| `sylphx orgs` | List / switch organizations |
+
+### Deployment
+
+| Command | Purpose |
+|---|---|
+| `sylphx deploy` | Deploy the linked app |
+| `sylphx deployments` | List / inspect deployments |
+| `sylphx releases` | Manage release tags |
+| `sylphx restart` | Restart running deployment |
+| `sylphx inspect` | Inspect a deployment's build + run metadata |
+| `sylphx bisect` | Git-bisect-style regression hunt across deployments |
+| `sylphx promote` | Promote staging → production |
+| `sylphx rollback` | Roll back to a previous deployment |
+| `sylphx status` | Deployment + health status |
+| `sylphx logs` | Tail application logs |
+| `sylphx tail` | Alias for `logs -f` |
+| `sylphx run` | Run a one-off command in the live environment |
+
+### Managed primitives
+
+| Command | Purpose |
+|---|---|
+| `sylphx db` | Manage PostgreSQL databases (CNPG-backed) |
+| `sylphx storage` | Manage object storage buckets (Ceph S3) |
+| `sylphx volumes` | Manage persistent volumes (Rook-Ceph RWO/RWX) |
+| `sylphx resources` | Bind / unbind shared resources |
+| `sylphx services` | List + deploy service blueprints |
+| `sylphx config` | Per-environment app config |
+| `sylphx env` | Environment variables (`list` / `set` / `rm`) |
+| `sylphx tasks` | Task definitions (job / cron / service) |
+| `sylphx domains` | Custom domains + TLS |
+| `sylphx functions` | Serverless function deploy / invoke / logs |
+| `sylphx sandbox` | Interactive sandbox environments |
+| `sylphx runners` | Self-hosted runner admin |
+
+### Integration primitives
+
+| Command | Purpose |
+|---|---|
+| `sylphx backup` | Managed data backup + restore |
+| `sylphx webhooks` | Outbound webhook endpoint CRUD |
+| `sylphx flags` | Feature flag admin |
+| `sylphx secrets` | Secret management (AES-256-GCM at rest) |
+| `sylphx realtime` | Realtime channel admin |
+| `sylphx saml` | SAML SSO configuration |
+| `sylphx ai` | AI model / completion admin |
+| `sylphx session-replay` | Session replay admin |
+| `sylphx search` | Search index admin |
+| `sylphx engagement` | Engagement campaign admin |
+| `sylphx consent` | GDPR / CCPA consent admin |
+| `sylphx privacy` | Privacy / data-subject-request admin |
+| `sylphx referrals` | Referral program admin |
+| `sylphx newsletter` | Newsletter admin |
+
+### Billing & scale
+
+| Command | Purpose |
+|---|---|
+| `sylphx plan` | View / upgrade plan |
+| `sylphx billing` | Invoices, payment methods |
+| `sylphx experiments` | A/B experiment admin |
+| `sylphx analytics` | Analytics admin queries |
+
+### Observability & integrations
+
+| Command | Purpose |
+|---|---|
+| `sylphx monitoring` | Metric + alert admin |
+| `sylphx certs` | TLS certificate inspection |
+| `sylphx email` | Transactional email admin |
+| `sylphx notifications` | Push / in-app notification admin |
+
+### Machine identity & policy
+
+| Command | Purpose |
+|---|---|
+| `sylphx tokens` | Service token issuance + revocation |
+| `sylphx oidc` | OIDC federation (GitHub Actions, GitLab CI, …) |
+| `sylphx ci` | CI integration helpers (generates workflow snippets) |
+
+## Architecture
+
+- Built on `@effect/cli` (ADR-073 Strategy A) — every command is an Effect value, tests can swap the Layer and assert on the Exit channel without subprocessing.
+- `BunRuntime.runMain` is the single `runPromise`-like call site (ADR-058 Rule 21).
+- Management plane only (ADR-083) — runtime BaaS verbs (`kv.*`, `email.send`, `flags.evaluate`, …) live inside the deployed application via [`@sylphx/sdk`](https://www.npmjs.com/package/@sylphx/sdk).
+- Types derive from [`@sylphx/contract`](https://www.npmjs.com/package/@sylphx/contract) (Effect Schema SSOT, ADR-084). Hand-written wire types are a bug.
+- HTTP client is `@sylphx/management` bundled in via `tsup noExternal` — global install has zero workspace peers to resolve.
+
+## Version compatibility
+
+| CLI | Management API | Contract |
+|---|---|---|
+| `@sylphx/cli@0.x` (beta) | `api.sylphx.com/v1` | `@sylphx/contract` (workspace / beta) |
+
+The Management API `/v1` surface is the stable HTTP target per ADR-077; the CLI and SDK packages themselves are still in pre-1.0 beta. The CLI auto-detects API version and degrades gracefully on newer fields.
 
 ## Development
 
 ```bash
 bun install
-bun run dev -- --help     # Run CLI in dev mode
-bun run build             # Build for production
+bun run dev -- --help     # Run CLI against workspace
+bun run build             # Build production bundle via tsup
+bun test                  # Run test suite (bun test)
 ```
 
+## Related packages
+
+- [`@sylphx/management`](https://www.npmjs.com/package/@sylphx/management) — Promise SDK the CLI is built on (bundled).
+- [`@sylphx/contract`](https://www.npmjs.com/package/@sylphx/contract) — Effect Schema SSOT (bundled).
+- [`@sylphx/sdk`](https://www.npmjs.com/package/@sylphx/sdk) — runtime BaaS SDK for deployed apps.
+
 ## License
 
-MIT © Sylphx
+MIT — see [LICENSE](./LICENSE).

package/dist/main.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env bun