@inquir/compute-cli 0.3.0 → 0.4.1

package/README.md

@@ -1,69 +1,73 @@
-# @inquir/compute-cli
-
-CLI for workspace-first Inquir Compute development.
-
-## Install
-
-Global (recommended). `@latest` also upgrades an existing install to the newest
-published version:
-
-```bash
-npm install -g @inquir/compute-cli@latest
-```
-
-Verify it's on your `PATH`:
-
-```bash
-inquir --version
-inquir --help
-```
-
-Or run without installing:
-
-```bash
-npx @inquir/compute-cli@latest --help
-```
-
-> Requires **Node.js 22+**. To upgrade later, re-run the install command above. On
-> macOS/Linux you may need `sudo` for a global install, or use a Node version
-> manager (nvm/fnm) to avoid it. To remove: `npm uninstall -g @inquir/compute-cli`.
-
-## Concepts
-
-- **Function**: a single compute unit with typed input/output (Zod schemas). Defined with `defineFunction()`. Run locally with `inquir run`, deployed and invoked remotely with `inquir deploy` / `inquir invoke`.
-- **Pipeline**: a declarative DAG of functions defined with `definePipeline()`. Registered in the codegen registry for client use; remote run/deploy for pipelines is handled by the backend.
-- **Client**: the generated TypeScript module at `.inquir/generated/client.ts`. Wraps remote invocation with schemas inferred from your source. Import it in your application code.
-- **Source of truth**: your local files under `functionsDir` and `pipelinesDir`. `registry.json` is a derived artifact rebuilt by `inquir codegen` — never hand-edit it.
-- **Local ↔ remote link**: each deployed remote function stores a `linkedLocalName` (your local asset name) and a `sourceHash`. `inquir sync status` compares hashes to detect drift.
-
-## Quick Start
-
-```bash
-inquir init
-inquir codegen
-inquir list
-inquir run hello --payload '{"name":"World"}'
-```
-
-## Authentication
-
-The recommended way to authenticate on your own machine is a browser login,
-which mints a user-scoped **Personal Access Token** (PAT) bound to your account
-and stores it in `~/.inquir/config.json`:
-
-```bash
-inquir login                 # opens your browser to approve this device
-inquir whoami                # show the signed-in user + active workspace
-```
-
-`inquir login` prints a short code and opens a dashboard page; confirm the code
-matches and click **Authorize**. The CLI then receives its token automatically.
-
-Other login modes:
-
-```bash
-inquir login --browserless   # print the URL + code instead of opening a browser
-inquir login --token <pat>   # non-interactive (CI): use a PAT created in the dashboard
+# @inquir/compute-cli
+
+CLI for workspace-first Inquir Compute development.
+
+## Install
+
+Global (recommended). `@latest` also upgrades an existing install to the newest
+published version:
+
+```bash
+npm install -g @inquir/compute-cli@latest
+```
+
+Verify it's on your `PATH`:
+
+```bash
+inquir --version
+inquir --help
+```
+
+Or run without installing:
+
+```bash
+npx @inquir/compute-cli@latest --help
+```
+
+> Requires **Node.js 22+**. To upgrade later, re-run the install command above. On
+> macOS/Linux you may need `sudo` for a global install, or use a Node version
+> manager (nvm/fnm) to avoid it. To remove: `npm uninstall -g @inquir/compute-cli`.
+
+## Concepts
+
+- **Function**: a single compute unit with typed input/output (Zod schemas). Defined with `defineFunction()`. Run locally with `inquir run`, deployed and invoked remotely with `inquir deploy` / `inquir invoke`.
+- **Pipeline**: a declarative DAG of functions defined with `definePipeline()`. Registered in the codegen registry for client use; remote run/deploy for pipelines is handled by the backend.
+- **Client**: the generated TypeScript module at `.inquir/generated/client.ts`. Wraps remote invocation with schemas inferred from your source. Import it in your application code.
+- **Source of truth**: your local files under `functionsDir` and `pipelinesDir`. `registry.json` is a derived artifact rebuilt by `inquir codegen` — never hand-edit it.
+- **Local ↔ remote link**: each deployed remote function stores a `linkedLocalName` (your local asset name) and a `sourceHash`. `inquir sync status` compares hashes to detect drift.
+
+## Quick Start
+
+```bash
+inquir init
+inquir codegen
+inquir list
+inquir run hello --payload '{"name":"World"}'
+```
+
+## Authentication
+
+The recommended way to authenticate on your own machine is a browser login,
+which mints a user-scoped **Personal Access Token** (PAT) bound to your account
+and stores it in `~/.inquir/config.json`:
+
+```bash
+inquir login                 # opens your browser to approve this device
+inquir whoami                # show the signed-in user + active workspace
+```
+
+`inquir login` prints a short code and opens a dashboard page; confirm the code
+matches and click **Authorize**. The CLI then receives its token automatically.
+Browser-issued CLI sessions expire (90 days by default; the server can configure
+a shorter lifetime). The CLI records the issuing API and expiry with the token.
+Logging in again saves the new session before revoking the previous session owned
+by that profile, unless another stored profile or environment variable still uses it.
+
+Other login modes:
+
+```bash
+inquir login --browserless   # print the URL + code instead of opening a browser
+inquir login --token <pat>   # non-interactive (CI): use a PAT created in the dashboard
 inquir login --name "my CI"  # label the device/token shown in the dashboard
 ```
 
@@ -82,30 +86,37 @@ the token remains saved and subsequent commands do not reuse the previous
 account's stored workspace.
 
 Create and revoke PATs from the dashboard under **API Keys → Personal Access
-Tokens**. To sign out and remove the stored token: `inquir logout`.
-
-> A PAT can deploy to **any workspace you belong to**. A workspace-scoped **API
-> key** is pinned to a single workspace and ignores workspace switching.
-
-## Workspaces
-
-A single login works across every workspace you're a member of. List them and
-choose a default:
-
-```bash
-inquir workspaces            # list workspaces (active one marked with *)
-inquir use <slug|id>         # set the active workspace for subsequent commands
-```
-
-Target a different workspace for a single command with `--workspace`:
-
-```bash
-inquir deploy hello --workspace acme-prod
-inquir deploys hello --workspace acme-prod
-inquir whoami --workspace acme-prod
-```
-
-Under the hood, user-scoped credentials send an `X-Inquir-Workspace` header; the
+Tokens**. `inquir logout` revokes its browser-issued CLI session at the API that
+issued it, then clears the local credentials and workspace. If the API is offline,
+the local logout still completes and warns that server revocation was not confirmed.
+Imported PATs (`--token`), tokens saved by older CLI versions, and credentials shared
+with another profile are only cleared locally; revoke them in the dashboard when
+they are no longer needed. Shell environment variables are never removed by logout.
+`inquir logout --env staging` leaves the default profile intact and prevents the
+logged-out profile from inheriting its credentials again.
+
+> A PAT can deploy to **any workspace you belong to**. A workspace-scoped **API
+> key** is pinned to a single workspace and ignores workspace switching.
+
+## Workspaces
+
+A single login works across every workspace you're a member of. List them and
+choose a default:
+
+```bash
+inquir workspaces            # list workspaces (active one marked with *)
+inquir use <slug|id>         # set the active workspace for subsequent commands
+```
+
+Target a different workspace for a single command with `--workspace`:
+
+```bash
+inquir deploy hello --workspace acme-prod
+inquir deploys hello --workspace acme-prod
+inquir whoami --workspace acme-prod
+```
+
+Under the hood, user-scoped credentials send an `X-Inquir-Workspace` header; the
 server verifies your membership before honoring it.
 
 ## Application projects
@@ -122,6 +133,8 @@ inquir projects use shop
 inquir apps create api --port 3000
 inquir apps create db --template postgres --project shop
 inquir projects add shop existing-app
+inquir projects move shop db        # file it in shop, take it out of its other projects
+inquir projects remove shop old-api # unfile it; it keeps running
 inquir projects current
 inquir projects use --clear
 ```
@@ -132,268 +145,293 @@ selection is kept locally under `~/.inquir/project-contexts` and isolated by API
 the actual workspace, and signed-in user (or API key). Switching workspace or
 account therefore cannot silently reuse another context's project.
 
-`apps create --project <id|slug>` overrides the selection for one command.
-`projects use --clear` returns to automatic project creation. Selecting or adding
-to a project accepts its ID or slug; adding an application accepts its ID or name.
-All project commands support `--json`. Deploying an existing container application
-with `apps deploy` keeps its project membership; use `projects add` to file an
-existing application. This selection does not change the serverless `inquir deploy`
+`apps create --project <project>` overrides the selection for one command.
+`projects use --clear` returns to automatic project creation. Every project command
+accepts a project's ID, slug, or unique display name, and an application's ID or
+name. `apps create` prints the project an application landed in. All project
+commands support `--json`. Deploying an existing container application with
+`apps deploy` keeps its project membership. `projects add` files an application in
+one more project; `projects move` files it and takes it out of every other one.
+No project command archives a project: the API does not record which were created
+automatically, so an emptied one is reported and left for you to archive in the
+dashboard. This selection does not change the serverless `inquir deploy`
 workflow or local source/configuration project discovery.
-
-## Deploy a function (remote)
-
-Once installed globally, deploying takes three steps:
-
-```bash
-# 1. Authenticate. Easiest on a workstation:
-inquir login
-#    For CI / scripts, export env vars for a one-off instead:
-#      export INQUIR_API_URL="https://api.inquir.org"
-#      export INQUIR_API_KEY="<api-key>"      # workspace-scoped key, or
-#      export INQUIR_TOKEN="<personal-access-token>"
-
-# 2. From your workspace (created by `inquir init`), deploy an asset by name.
-inquir deploy hello                 # streams build/deploy logs, exits non-zero on failure
-
-# 3. Invoke it remotely.
-inquir invoke hello --payload '{"name":"World"}'
-```
-
-Get an API key from your Inquir Compute workspace settings. For CI, prefer the
-[`inquir-compute/deploy-action`](../deploy-action) GitHub Action (supports keyless
-OIDC auth), or run `inquir deploy --ci`.
-
-## Commands
-
-**Project & local dev**
-
-- `inquir init [--name <name>] [--skip-install]` - scaffold `inquir.config.json`, folders, and a sample function. Interactive on a TTY (prompts for the project name); guides you to `login`/`run`/`deploy` afterward.
-- `inquir codegen` - discover assets and generate `.inquir/generated/client.ts` + `registry.json`.
-- `inquir list [--remote]` - list local assets, or deployed remote functions with `--remote`.
-- `inquir run <asset>` - run a local asset.
-- `inquir debug <asset>` - run locally with inspector enabled.
-- `inquir sync status` - compare local hashes with remote hashes (`in-sync`, `drift`, `missing`).
-
-**Auth & workspaces**
-
-- `inquir login` - authenticate the CLI (browser pairing, `--browserless`, or `--token`).
-- `inquir logout` - remove the stored token + active workspace for the current environment.
-- `inquir whoami` - show the signed-in user, active workspace, and role.
-- `inquir workspaces` - list the workspaces you belong to.
-- `inquir use <slug|id> [--local]` - set the active workspace; `--local` links *this project* by writing `workspace` into `inquir.config.json`.
-
-**Deploy & run remotely**
-
-- `inquir deploy <asset>` - package, upload, and deploy a function (async; streams build logs).
-- `inquir invoke <asset>` - invoke remote function by name / linked local name.
-- `inquir logs <asset>` - show recent remote invocation history.
-- `inquir deploys <function>` - list deploy history for a remote function.
-- `inquir status <deployId>` - show a deploy's status (`--follow` to stream logs).
-- `inquir rollback <function> [deployId]` - roll back to a previous successful deploy.
-- `inquir delete <function>` - delete a remote function (asks for confirmation; `--yes` to skip).
-
-**Container services (apps)**
-
-Long-lived containers from any OCI image — the counterpart to functions. HTTP
-ports are served over a hostname; TCP ports are published and dialled directly,
-so a database, SMTP relay or SSH endpoint is a first-class service with no
-runtime adapter involved.
-
-- `inquir apps list` - list applications.
-- `inquir apps create <name> [--port <n>] [--tcp …] [--set K=V]` - create an application.
-- `inquir apps deploy <app> [--image <ref>]` - start a release and wait until it is healthy. Without `--image` the current directory (or `--dir`) is built from its Dockerfile first; `--build <id>` releases an existing build.
-- `inquir apps build <app> [--dir <path>] [--dockerfile <f>] [--context <dir>] [--build-arg K=V]` - build an image from source without releasing it.
-- `inquir apps builds <app>` - build history (`--cancel <buildId>` drops a queued build).
-- `inquir apps status <app>` - endpoints (public and private), hostnames and recent releases. The `private:` lines are what another app in the workspace dials (`{slug}.apps.internal`, port per TCP service); they appear once the platform has verified the route.
-- `inquir apps logs <app|release|build> [--tail <n>]` - stream container (or build) logs.
-- `inquir apps promote <release>` - send production traffic to a release (needs a login, not an API key).
-- `inquir apps rollback <app>` - return production to the previous release.
-- `inquir apps stop <release>` - stop any release that is not serving production.
-- `inquir apps exec <app> -- <command>` - run a command inside the container (owner/admin login only — it can read every secret).
-- `inquir apps update <app> [--set K=V] [--port …] [--egress none|full] [--ingress private|public] …` - change settings; applies to the next release. `--ingress public` creates the generated public domain, `--ingress private` removes it (the private address is unaffected). New apps are private unless created with `--ingress public`.
-- `inquir apps domain <app> [hostname] [--verify|--remove]` - bind a custom hostname; publish the printed TXT record and point DNS at the platform, then `--verify`.
-- `inquir apps delete <app> --yes` - archive an application (stops every release, unbinds every hostname).
-
-```bash
-# an HTTP service built from the Dockerfile in the current directory
-inquir apps create web --port 3000
-inquir apps deploy web
-inquir apps promote <releaseId>
-
-# ...or from a prebuilt image
-inquir apps deploy web --image nginx:alpine
-
-# a database: no HTTP port at all, published on a pinned port,
-# health-checked by asking the service itself
-inquir apps create db \
-  --tcp postgres:5432:public:25432 \
-  --health-command "pg_isready -h 127.0.0.1" \
-  --set POSTGRES_PASSWORD=secret
-inquir apps deploy db --image postgres:16-alpine
-```
-
-`--tcp name:port[:public][:hostPort]` — `public` publishes beyond loopback,
-and a pinned `hostPort` keeps a connection string valid across restarts (an
-unpinned port is reassigned every time the container is recreated). A public
-TCP port is reachable by anyone who can reach the host: the platform
-terminates no TLS and checks no credentials on raw TCP, so the service must
-authenticate its own clients.
-
-**Databases**
-
-- `inquir apps create <name> --template postgres|redis` - create a database: image, persistent volume, pinned public TCP port, generated password and its first release, in one command.
-- `inquir apps connection-url <db>` - print the live connection URL, credentials included (it lands in your shell history).
-- `inquir apps connect <db> <app>` - write that URL into another application's env as `DATABASE_URL` / `REDIS_URL` without it passing through your terminal; it applies on that application's next release.
-- `inquir apps backups <app> [list|create|restore <id>|delete <id>]` - volume snapshots. `restore` **overwrites the volume** with the snapshot and stops the application while it runs, so it asks for confirmation — pass `--yes` in a script.
-
-```bash
-inquir apps create mydb --template postgres
-inquir apps connect mydb web          # web gets DATABASE_URL on its next release
-inquir apps backups mydb create       # snapshot every volume, wait for it to settle
-inquir apps backups mydb restore 3f9c1a2b --yes
-```
-
-An application that declares a volume deploys by stopping its container before
-starting the new one, so two containers never write the same data — expect a
-short outage on every deploy. Backups are crash-consistent (the container is
-paused while it is copied) and need an artifact store configured on the
-deployment; without one the backup commands report that they are unavailable.
-
-**Staying up to date**
-
-The CLI keeps itself in step with the platform. On start it checks — at most
-every 12 hours, with a 2.5 s network timeout, never failing your command — the
-npm registry for the latest `@inquir/compute-cli` and the API for the minimum
-version it still supports (`GET /v1/cli/version`). When a newer version exists
-and the CLI is a global npm install running in an interactive terminal, it
-updates itself and re-runs your command; in CI, under `--json`, without a TTY,
-via `npx` or from a source checkout it only prints a one-line notice. If the
-API's *minimum* is not met, the command stops with the exact fix instead of
-failing later on a changed wire contract.
-
-- `inquir upgrade` - update now (`--check` only reports).
-- Opt out: `inquir config set autoUpdate false`, `INQUIR_NO_AUTO_UPDATE=1`, or `--no-update` on one command.
-
-**Diagnostics & config**
-
-- `inquir doctor` - diagnose environment, credentials, and API connectivity (`--json` for a report).
-- `inquir config [show|get <key>|set <key> <value>|path]` - view/edit CLI configuration.
-- `inquir help [command]` - show grouped help, or help for one command.
-
-### `deploy` flags
-
-```bash
-inquir deploy hello                 # package + async deploy, stream build logs
-inquir deploy hello --stage staging # target a deploy stage (alias: --environment)
-inquir deploy hello --set KEY=val --set OTHER=val   # set environment variables (repeatable)
-inquir deploy hello --env-file .env.production      # load env vars from a dotenv file
-inquir deploy hello --memory 512 --timeout 60000    # memory (MB) / timeout (ms)
-inquir deploy hello --layer <layerId> --layer <id2> # attach layers (repeatable)
-inquir deploy hello --no-logs       # queue and wait for completion without streaming
-inquir deploy hello --ci            # plain output, non-zero exit on failure (for CI)
-inquir deploy hello --dry-run       # validate + package only; no create/deploy
-inquir deploy hello --json          # machine-readable result
-```
-
-> Note: `--env` selects a named **credential environment** from your config; `--stage`
-> (alias `--environment`) selects the **deploy stage** (production/staging/preview). They
-> are different — don't confuse them.
-
-## Global Flags
-
-Global flags work in **any position** (before or after the command) and accept both
-`--flag value` and `--flag=value`:
-
-- `--json` - machine-readable output (implies no color).
-- `--debug` - verbose diagnostics + stack traces (also `INQUIR_DEBUG=1`).
-- `--quiet` - suppress status chatter (errors + requested results only).
-- `--no-color` - disable ANSI color (also honoured: `NO_COLOR`, `FORCE_COLOR`).
-- `--yes`, `-y` - assume "yes" for confirmations (required for destructive ops in CI).
-- `--cwd <path>` - run as if from this directory (alias: `--config`, which also accepts a config file path).
-- `--env <name>` - select a named credential environment from the config.
-- `--workspace <slug|id>` - target a specific workspace for this command (user-scoped login).
-- `--api-url <url>` - override the API base URL.
-- `--token <pat>` - use a Personal Access Token (non-interactive / CI).
-
-```bash
-inquir run hello --cwd ./services/api
-inquir --workspace acme-prod deploy hello
-```
-
-## Exit codes
-
-| Code | Meaning |
-|------|---------|
-| `0`  | success |
-| `1`  | runtime error (build failed, not found, server error) |
-| `2`  | usage / validation error (bad flags, missing args) |
-| `3`  | network / timeout |
-| `4`  | authentication required / forbidden |
-| `130` | interrupted (Ctrl+C / SIGINT) |
-
-A bare `Ctrl+C` aborts cleanly — the CLI prints `Aborted (SIGINT).` to stderr and
-exits `130`, leaving stdout untouched (safe for piping) and no stack trace.
-
-With `--json`, errors are emitted as a structured envelope on stdout:
-
-```json
-{ "ok": false, "error": { "code": "AUTH_REQUIRED", "title": "You are not logged in", "message": "…", "requestId": "…" } }
-```
-
-## CI usage
-
-In CI / non-TTY, the CLI never prompts; supply credentials via env and use `--ci`/`--yes`:
-
-```bash
-export INQUIR_TOKEN="$INQUIR_PAT"        # or INQUIR_API_KEY for a workspace key
-export INQUIR_WORKSPACE="acme-prod"      # optional: target workspace
-inquir deploy hello --ci --json
-```
-
-For GitHub Actions, prefer the [`@inquir/deploy-action`](../deploy-action) GitHub Action
-(supports keyless OIDC auth).
-
-## Payload Input
-
-`run` and `invoke` support:
-
-- `--payload '{"k":"v"}'`
-- `--payload-file ./payload.json`
-- stdin piping
-
-Shell quoting differs by platform. To pass inline JSON:
-
-```bash
-# macOS / Linux (bash, zsh) — single-quote the JSON:
-inquir invoke hello --payload '{"name":"World"}'
-```
-
-```powershell
-# Windows PowerShell — single-quote the JSON:
-inquir invoke hello --payload '{"name":"World"}'
-```
-
-```bat
-:: Windows cmd.exe — escape the inner double quotes:
-inquir invoke hello --payload "{\"name\":\"World\"}"
-```
-
-When quoting gets awkward (especially on Windows), prefer `--payload-file ./payload.json`
-or pipe via stdin: `type payload.json | inquir invoke hello`.
-
-## Remote Auth / Environment
-
-The CLI resolves each credential field independently, in this order (first match
-wins):
-
-1. CLI flags (`--api-url`, `--token`, `--workspace`) / `--env <name>` selection
-2. Environment variables (`LAMBDA_*` are legacy fallbacks):
-   - `INQUIR_API_URL`, `INQUIR_API_KEY`
-   - `INQUIR_TOKEN` — a Personal Access Token (takes precedence over `apiKey`)
-   - `INQUIR_WORKSPACE` — active workspace (slug or id)
-   - `INQUIR_ENV` — pick a named environment
-3. Selected environment in the config file
-4. Project link — `workspace` in the local `inquir.config.json` (set by `inquir use --local`); applies to the workspace only, below flags/env
+
+## Deploy a function (remote)
+
+Once installed globally, deploying takes three steps:
+
+```bash
+# 1. Authenticate. Easiest on a workstation:
+inquir login
+#    For CI / scripts, export env vars for a one-off instead:
+#      export INQUIR_API_URL="https://api.inquir.org"
+#      export INQUIR_API_KEY="<api-key>"      # workspace-scoped key, or
+#      export INQUIR_TOKEN="<personal-access-token>"
+
+# 2. From your workspace (created by `inquir init`), deploy an asset by name.
+inquir deploy hello                 # streams build/deploy logs, exits non-zero on failure
+
+# 3. Invoke it remotely.
+inquir invoke hello --payload '{"name":"World"}'
+```
+
+Get an API key from your Inquir Compute workspace settings. For CI, prefer the
+[`inquir-compute/deploy-action`](../deploy-action) GitHub Action (supports keyless
+OIDC auth), or run `inquir deploy --ci`.
+
+## Commands
+
+**Project & local dev**
+
+- `inquir init [--name <name>] [--skip-install]` - scaffold `inquir.config.json`, folders, and a sample function. Interactive on a TTY (prompts for the project name); guides you to `login`/`run`/`deploy` afterward.
+- `inquir codegen` - discover assets and generate `.inquir/generated/client.ts` + `registry.json`.
+- `inquir list [--remote]` - list local assets, or deployed remote functions with `--remote`.
+- `inquir run <asset>` - run a local asset.
+- `inquir debug <asset>` - run locally with inspector enabled.
+- `inquir sync status` - compare local hashes with remote hashes (`in-sync`, `drift`, `missing`).
+
+**Auth & workspaces**
+
+- `inquir login` - authenticate the CLI (browser pairing, `--browserless`, or `--token`).
+- `inquir logout` - revoke the current browser-issued CLI session and clear its local credentials and workspace.
+- `inquir whoami` - show the signed-in user, active workspace, and role.
+- `inquir workspaces` - list the workspaces you belong to.
+- `inquir use <slug|id> [--local]` - set the active workspace; `--local` links *this project* by writing `workspace` into `inquir.config.json`.
+
+**Deploy & run remotely**
+
+- `inquir deploy <asset>` - package, upload, and deploy a function (async; streams build logs).
+- `inquir invoke <asset>` - invoke remote function by name / linked local name.
+- `inquir logs <asset>` - show recent remote invocation history.
+- `inquir deploys <function>` - list deploy history for a remote function.
+- `inquir status <deployId>` - show a deploy's status (`--follow` to stream logs).
+- `inquir rollback <function> [deployId]` - roll back to a previous successful deploy.
+- `inquir delete <function>` - delete a remote function (asks for confirmation; `--yes` to skip).
+
+**Container services (apps)**
+
+Long-lived containers from any OCI image — the counterpart to functions. HTTP
+ports are served over a hostname; TCP ports are published and dialled directly,
+so a database, SMTP relay or SSH endpoint is a first-class service with no
+runtime adapter involved.
+
+- `inquir apps list` - list applications.
+- `inquir apps create <name> [--port <n>] [--tcp …] [--set K=V]` - create an application.
+- `inquir apps deploy <app> [--image <ref>]` - start a release and wait until it is healthy. Without `--image` the current directory (or `--dir`) is built from its Dockerfile first; `--build <id>` releases an existing build.
+- `inquir apps build <app> [--dir <path>] [--dockerfile <f>] [--context <dir>] [--build-arg K=V]` - build an image from source without releasing it.
+- `inquir apps builds <app>` - build history (`--cancel <buildId>` drops a queued build).
+- `inquir apps status <app>` - endpoints (public and private), hostnames and recent releases. The `private:` lines are what another app in the workspace dials (`{slug}.apps.internal`, port per TCP service); they appear once the platform has verified the route.
+- `inquir apps instances <app> [--json]` - the application's replicas, like pods: name (`<app>-<index>-<id8>`), state, ready, restarts, runner, region, CPU/RAM now.
+- `inquir apps logs <app|release|build> [--tail <n>] [--replica <name|index>]` - stream container (or build) logs; `--replica` follows one replica.
+- `inquir apps promote <release>` - send production traffic to a release (needs a login, not an API key).
+- `inquir apps rollback <app>` - return production to the previous release.
+- `inquir apps stop <release>` - stop any release that is not serving production.
+- `inquir apps exec <app> [--replica <name|index>] -- <command>` - run a command inside the container (owner/admin login only — it can read every secret). `--replica` picks one serving replica; without it the server picks the production container.
+- `inquir apps update <app> [--set K=V] [--port …] [--egress none|full] [--ingress private|public] …` - change settings; applies to the next release. `--ingress public` creates the generated public domain, `--ingress private` removes it (the private address is unaffected). New apps are private unless created with `--ingress public`.
+- `inquir apps update <app> --node-selector inquir.io/region=eu [--node-selector tier=fast]` - run the next releases only on servers carrying every one of these node labels (`--clear-node-selector` removes it). Well-known labels: `inquir.io/region`, `inquir.io/zone`, `inquir.io/runtime`, `inquir.io/arch`, `inquir.io/gpu`, `inquir.io/gpu-count`; operator labels the platform publishes work too. Needs node placement enabled on the platform (`COMPUTE_NODE_AFFINITY=enforce`); a selector no server matches yet is accepted with a warning, and `inquir apps describe` says why a replica waits. Full Kubernetes-style `runtime.nodeAffinity` goes through the API or `inquir.yaml`.
+- `inquir apps update <app> --location <id|auto>` (experimental) - run the next releases in one of the platform's locations (`nl`, `ru`, ...); `auto` runs wherever there is capacity. Shown by `inquir apps status` and `inquir apps describe`; offered only where the platform enables it (`COMPUTE_SERVICE_LOCATIONS=on`). A service whose volume data lives in another location is refused: the data does not move.
+- `inquir apps domain <app> [hostname] [--verify|--remove]` - bind a custom hostname; publish the printed TXT record and point DNS at the platform, then `--verify`.
+- `inquir apps delete <app> --yes` - archive an application (stops every release, unbinds every hostname).
+
+Project archive in the dashboard also archives every application in the project, including applications shared with another project. It requires production permissions (`projects:write` and `apps:promote`). Clearing the local project selection with `inquir projects use --clear` only changes where future applications are created; it does not archive applications.
+
+
+```bash
+# an HTTP service built from the Dockerfile in the current directory
+inquir apps create web --port 3000
+inquir apps deploy web
+inquir apps promote <releaseId>
+
+# ...or from a prebuilt image
+inquir apps deploy web --image nginx:alpine
+
+# a database: no HTTP port at all, published on a pinned port,
+# health-checked by asking the service itself
+inquir apps create db \
+  --tcp postgres:5432:public:25432 \
+  --health-command "pg_isready -h 127.0.0.1" \
+  --set POSTGRES_PASSWORD=secret
+inquir apps deploy db --image postgres:16-alpine
+```
+
+`--tcp name:port[:public][:hostPort]` — `public` publishes beyond loopback,
+and a pinned `hostPort` keeps a connection string valid across restarts (an
+unpinned port is reassigned every time the container is recreated). A public
+TCP port is reachable by anyone who can reach the host: the platform
+terminates no TLS and checks no credentials on raw TCP, so the service must
+authenticate its own clients.
+
+`--drain-grace <seconds>` (`create`, `deploy`, `update`; 0–3600) — the time the
+old container gets after SIGTERM before it is killed (`runtimeSpec.drainGraceSeconds`).
+Like `--memory` or `--cpu` it is saved on the application by `create`/`update`
+and carried into every release built from the saved runtime.
+
+**Databases**
+
+- `inquir apps create <name> --template postgres|redis` - create a database: image, persistent volume, private TCP port, generated password and its first release, in one command. Add `--volume-runner <runner>` to keep its data and container on a worker; the worker runs the operator's digest-pinned mirror of the template image, and without one the create is refused (`APP_TEMPLATE_IMAGE_NOT_MIRRORED`).
+- `inquir apps connection-url <db>` - print the live connection URL, credentials included (it lands in your shell history).
+- `inquir apps connect <db> <app>` - write that URL into another application's env as `DATABASE_URL` / `REDIS_URL` without it passing through your terminal; it applies on that application's next release.
+- `inquir apps backups <app> [list|create|restore <id>|delete <id>]` - volume snapshots. `restore` **overwrites the volume** with the snapshot and stops the application while it runs, so it asks for confirmation — pass `--yes` in a script.
+
+```bash
+inquir apps create mydb --template postgres
+inquir apps connect mydb web          # web gets DATABASE_URL on its next release
+inquir apps backups mydb create       # snapshot every volume, wait for it to settle
+inquir apps backups mydb restore 3f9c1a2b --yes
+```
+
+An application that declares a volume deploys by stopping its container before
+starting the new one, so two containers never write the same data — expect a
+short outage on every deploy. Backups are crash-consistent (the container is
+paused while it is copied) and need an artifact store configured on the
+deployment; without one the backup commands report that they are unavailable.
+
+**Staying up to date**
+
+The CLI keeps itself in step with the platform. On start it checks — at most
+every 12 hours, with a 2.5 s network timeout, never failing your command — the
+npm registry for the latest `@inquir/compute-cli` and the API for the minimum
+version it still supports (`GET /v1/cli/version`). When a newer version exists
+and the CLI is a global npm install running in an interactive terminal, it
+updates itself and re-runs your command; in CI, under `--json`, without a TTY,
+via `npx` or from a source checkout it only prints a one-line notice. If the
+API's *minimum* is not met, the command stops with the exact fix instead of
+failing later on a changed wire contract.
+
+- `inquir upgrade` - update now (`--check` only reports).
+- Opt out: `inquir config set autoUpdate false`, `INQUIR_NO_AUTO_UPDATE=1`, or `--no-update` on one command.
+
+**Diagnostics & config**
+
+- `inquir doctor` - diagnose environment, credentials, and API connectivity (`--json` for a report).
+- `inquir config [show|get <key>|set <key> <value>|path]` - view/edit CLI configuration.
+- `inquir help [command]` - show grouped help, or help for one command.
+
+**Platform operators**
+
+- `inquir admin cluster [status|hold|release|move <memberId>|host register|grant <host> <capability>|revoke <host> <capability>]` -
+  the multi-master control plane (docs/roadmap/R4_MULTI_MASTER.md §6.2). It authenticates with the platform admin token in
+  `INQUIR_ADMIN_TOKEN`, never with your login; changes need the full token and land in the admin audit log.
+- `inquir admin allocations relocate <allocationId> --reason <text> [--target <runnerId>]` - move one serving replica
+  make-before-break: its replacement starts (on the target, which must pass every placement filter and have room), takes
+  the traffic, and only then is the replica stopped. Pinned, volume, preview and TCP-pinned replicas are refused, as is an
+  application in a deployment handoff. `inquir admin allocations relocation <operationId>` shows where it is. Same token.
+
+### `deploy` flags
+
+```bash
+inquir deploy hello                 # package + async deploy, stream build logs
+inquir deploy hello --stage staging # target a deploy stage (alias: --environment)
+inquir deploy hello --set KEY=val --set OTHER=val   # set environment variables (repeatable)
+inquir deploy hello --env-file .env.production      # load env vars from a dotenv file
+inquir deploy hello --memory 512 --timeout 60000    # memory (MB) / timeout (ms)
+inquir deploy hello --layer <layerId> --layer <id2> # attach layers (repeatable)
+inquir deploy hello --no-logs       # queue and wait for completion without streaming
+inquir deploy hello --ci            # plain output, non-zero exit on failure (for CI)
+inquir deploy hello --dry-run       # validate + package only; no create/deploy
+inquir deploy hello --json          # machine-readable result
+```
+
+> Note: `--env` selects a named **credential environment** from your config; `--stage`
+> (alias `--environment`) selects the **deploy stage** (production/staging/preview). They
+> are different — don't confuse them.
+
+## Global Flags
+
+Global flags work in **any position** (before or after the command) and accept both
+`--flag value` and `--flag=value`:
+
+- `--json` - machine-readable output (implies no color).
+- `--debug` - verbose diagnostics + stack traces (also `INQUIR_DEBUG=1`).
+- `--quiet` - suppress status chatter (errors + requested results only).
+- `--no-color` - disable ANSI color (also honoured: `NO_COLOR`, `FORCE_COLOR`).
+- `--yes`, `-y` - assume "yes" for confirmations (required for destructive ops in CI).
+- `--cwd <path>` - run as if from this directory (alias: `--config`, which also accepts a config file path).
+- `--env <name>` - select a named credential environment from the config.
+- `--workspace <slug|id>` - target a specific workspace for this command (user-scoped login).
+- `--api-url <url>` - override the API base URL.
+- `--token <pat>` - use a Personal Access Token (non-interactive / CI).
+
+```bash
+inquir run hello --cwd ./services/api
+inquir --workspace acme-prod deploy hello
+```
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0`  | success |
+| `1`  | runtime error (build failed, not found, server error) |
+| `2`  | usage / validation error (bad flags, missing args) |
+| `3`  | network / timeout |
+| `4`  | authentication required / forbidden |
+| `130` | interrupted (Ctrl+C / SIGINT) |
+
+A bare `Ctrl+C` aborts cleanly — the CLI prints `Aborted (SIGINT).` to stderr and
+exits `130`, leaving stdout untouched (safe for piping) and no stack trace.
+
+With `--json`, errors are emitted as a structured envelope on stdout:
+
+```json
+{ "ok": false, "error": { "code": "AUTH_REQUIRED", "title": "You are not logged in", "message": "…", "requestId": "…" } }
+```
+
+## CI usage
+
+In CI / non-TTY, the CLI never prompts; supply credentials via env and use `--ci`/`--yes`:
+
+```bash
+export INQUIR_TOKEN="$INQUIR_PAT"        # or INQUIR_API_KEY for a workspace key
+export INQUIR_WORKSPACE="acme-prod"      # optional: target workspace
+inquir deploy hello --ci --json
+```
+
+For GitHub Actions, prefer the [`@inquir/deploy-action`](../deploy-action) GitHub Action
+(supports keyless OIDC auth).
+
+## Payload Input
+
+`run` and `invoke` support:
+
+- `--payload '{"k":"v"}'`
+- `--payload-file ./payload.json`
+- stdin piping
+
+Shell quoting differs by platform. To pass inline JSON:
+
+```bash
+# macOS / Linux (bash, zsh) — single-quote the JSON:
+inquir invoke hello --payload '{"name":"World"}'
+```
+
+```powershell
+# Windows PowerShell — single-quote the JSON:
+inquir invoke hello --payload '{"name":"World"}'
+```
+
+```bat
+:: Windows cmd.exe — escape the inner double quotes:
+inquir invoke hello --payload "{\"name\":\"World\"}"
+```
+
+When quoting gets awkward (especially on Windows), prefer `--payload-file ./payload.json`
+or pipe via stdin: `type payload.json | inquir invoke hello`.
+
+## Remote Auth / Environment
+
+The CLI resolves each credential field independently, in this order (first match
+wins):
+
+1. CLI flags (`--api-url`, `--token`, `--workspace`) / `--env <name>` selection
+2. Environment variables (`LAMBDA_*` are legacy fallbacks):
+   - `INQUIR_API_URL`, `INQUIR_API_KEY`
+   - `INQUIR_TOKEN` — a Personal Access Token (takes precedence over `apiKey`)
+   - `INQUIR_WORKSPACE` — active workspace (slug or id)
+   - `INQUIR_ENV` — pick a named environment
+3. Selected environment in the config file
+4. Project link — `workspace` in the local `inquir.config.json` (set by `inquir use --local`); applies to the workspace only, below flags/env
 5. Top-level config file values (credentials and workspace only when the named environment uses the same API)
 6. Default `apiUrl` of `https://api.inquir.org` (override with env/config for local dev)
 
@@ -411,63 +449,84 @@ continue to inherit defaults. Changing a profile's API also removes its stored A
 key, so logging out of the new PAT cannot reactivate a key from the previous API.
 
 When both a `token` (PAT) and an `apiKey` are present, the PAT wins. The active
-`workspaceId` is only applied to user-scoped credentials (PAT/session); for a
-workspace-scoped API key it is ignored unless you pass `--workspace` explicitly.
-
-Config file locations:
-
-- `~/.inquir/config.json` (preferred, written by `inquir login` / `use`; saved with `0600` permissions)
-- `~/.lambda-cli/config.json` (legacy fallback — **credentials only**; the legacy `apiUrl` is intentionally ignored so you aren't silently pinned to `localhost`)
-
-Example (written/managed by `inquir login`, `inquir use`, `inquir logout`):
-
-```json
-{
-  "apiUrl": "https://api.inquir.org",
-  "token": "inq_pat_…",
-  "workspaceId": "acme-prod",
-  "user": { "id": "…", "email": "you@example.com", "name": "You" },
-  "environments": {
-    "staging": {
-      "apiUrl": "https://staging.example.com",
-      "apiKey": "staging-key"
-    }
-  }
-}
-```
-
-## Troubleshooting
-
-Start with `inquir doctor` — it checks the CLI/Node version, config file, credential,
-API connectivity + latency, active workspace, and local project, and prints a fix for any
-failing check.
-
-| Symptom | Likely cause / fix |
-|---------|--------------------|
-| `You are not logged in` (exit 4) | No credential resolved. Run `inquir login`, or set `INQUIR_TOKEN`/`INQUIR_API_KEY` in CI. |
-| `Permission denied` (exit 4) | Wrong workspace or insufficient role. Check `inquir whoami`; switch with `inquir use`. |
-| `Not found` for a function | Wrong name or workspace. `inquir list --remote` to see what exists in the active workspace. |
-| Commands hit `localhost` unexpectedly | A stale `apiUrl` in config/env. Check `inquir config show`; override with `--api-url` or `INQUIR_API_URL`. |
-| Network error (exit 3) | Can't reach the API. Verify connectivity and `--api-url`; re-run `inquir doctor`. |
-| Garbled output in logs/CI | Disable color with `--no-color` or `NO_COLOR=1` (color auto-disables when not a TTY and in `--json`). |
-| Need raw detail for a failure | Re-run with `--debug` for stack traces and the response body (secrets are redacted). |
-
-## Publishing to npm (maintainers)
-
-The CLI (`@inquir/compute-cli`) depends on the SDK (`@inquir/compute`), so the
+`workspaceId` is only applied to user-scoped credentials (PAT/session); for a
+workspace-scoped API key it is ignored unless you pass `--workspace` explicitly.
+
+Config file locations:
+
+- `~/.inquir/config.json` (preferred, written by `inquir login` / `use`; saved with `0600` permissions)
+- `~/.lambda-cli/config.json` (legacy fallback — **credentials only**; the legacy `apiUrl` is intentionally ignored so you aren't silently pinned to `localhost`)
+
+Credential updates use an atomic file replacement and an exclusive
+`~/.inquir/config.json.lock` while updating or revoking a session. A timed-out lock
+is never stolen from a running command. If a command crashed and subsequent commands
+report `AUTH_CONFIG_LOCKED`, stop all CLI commands before removing that lock file.
+Older CLI versions do not participate in this locking protocol; avoid running old
+and new versions concurrently against the same configuration.
+
+Example (written/managed by `inquir login`, `inquir use`, `inquir logout`):
+
+```json
+{
+  "apiUrl": "https://api.inquir.org",
+  "token": "inq_pat_…",
+  "workspaceId": "acme-prod",
+  "user": { "id": "…", "email": "you@example.com", "name": "You" },
+  "environments": {
+    "staging": {
+      "apiUrl": "https://staging.example.com",
+      "apiKey": "staging-key"
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+Start with `inquir doctor` — it checks the CLI/Node version, config file, credential,
+API connectivity + latency, active workspace, and local project, and prints a fix for any
+failing check.
+
+| Symptom | Likely cause / fix |
+|---------|--------------------|
+| `You are not logged in` (exit 4) | No credential resolved. Run `inquir login`, or set `INQUIR_TOKEN`/`INQUIR_API_KEY` in CI. |
+| `Permission denied` (exit 4) | Wrong workspace or insufficient role. Check `inquir whoami`; switch with `inquir use`. |
+| `Not found` for a function | Wrong name or workspace. `inquir list --remote` to see what exists in the active workspace. |
+| Commands hit `localhost` unexpectedly | A stale `apiUrl` in config/env. Check `inquir config show`; override with `--api-url` or `INQUIR_API_URL`. |
+| Network error (exit 3) | Can't reach the API. Verify connectivity and `--api-url`; re-run `inquir doctor`. |
+| Garbled output in logs/CI | Disable color with `--no-color` or `NO_COLOR=1` (color auto-disables when not a TTY and in `--json`). |
+| Need raw detail for a failure | Re-run with `--debug` for stack traces and the response body (secrets are redacted). |
+
+## Publishing to npm (maintainers)
+
+The CLI (`@inquir/compute-cli`) depends on the SDK (`@inquir/compute`), so the
 SDK must be published **first** at a version satisfying the CLI's dependency
-range (`dependencies["@inquir/compute"]`, `^0.3.0` for CLI 0.3.0). Set the lower
+range (`dependencies["@inquir/compute"]`, `^0.4.0` for CLI 0.4.0). Set the lower
 bound to the first SDK release containing every API the CLI imports. A workspace
 build uses the local SDK and cannot prove that an older published SDK works.
 
+Release order for 0.4.0: CLI 0.4.0 imports `isPromoteAccepted` and
+`getApplicationRollout` (the background promote, `inquir apps promote`), which
+SDK 0.3.0 does not export. Publish SDK 0.4.0 first and confirm it on the
+registry; a CLI published against SDK 0.3.0 would fail at startup.
+
+Next release (CLI 0.4.1): the CLI imports `listAppInstances` and
+`matchAppInstance` (`inquir apps instances`, `--replica`), which SDK 0.4.0 does
+not export, and `createSourceArchive`, `manifestBuildContext` (source
+uploads that honour the build context's .dockerignore/.inquirignore and keep
+secret-like files out) and `getProductionReplacement` (the replacement phase
+while a redeploy waits), which SDK 0.4.1 does not export; its dependency
+floor is `^0.4.2`. Publish SDK 0.4.2 first and
+confirm it on the registry, then the CLI.
+
 New `inquir init` scaffolds inherit this SDK range and require Node.js 22+.
 Existing `package.json` files are preserved; update their dependencies explicitly
 when adopting a newer SDK.
-
-Prerequisites:
-
-- An npm account with publish access to the `@inquir` scope (create the org/scope on npmjs.com), then `npm login`.
-- Both packages declare `"publishConfig": { "access": "public" }`, so scoped packages publish publicly.
+
+Prerequisites:
+
+- An npm account with publish access to the `@inquir` scope (create the org/scope on npmjs.com), then `npm login`.
+- Both packages declare `"publishConfig": { "access": "public" }`, so scoped packages publish publicly.
 - Both packages build before packing or publishing from source. The SDK includes
   `dist/`; the CLI includes `dist/` and its bundled `skill/`. npm also includes
   package metadata and README files.
@@ -503,8 +562,71 @@ After building, preview package contents without publishing with
 `--ignore-scripts` skips build hooks, so only use it after the explicit build.
 The installed command is `inquir`, from `dist/index.js` with its Node shebang.
 After publishing, users can install it with:
-
-```bash
-npm install -g @inquir/compute-cli@latest
-inquir --help
-```
+
+```bash
+npm install -g @inquir/compute-cli@latest
+inquir --help
+```
+## Application observability
+
+Read actual resource history for every release and replica, or HTTP gateway measurements:
+
+```sh
+inquir apps metrics api --since 6h
+inquir apps metrics api --since 30d --json
+inquir apps metrics api --http --since 1d --json
+```
+
+The resource table shows the latest point per replica in the selected window. JSON contains all returned points, their enforced CPU/RAM limits, network transfer rates, disk I/O rates and deployment markers. `null` means the measurement is unavailable; it is not zero. Disk I/O measures reads/writes, not occupied volume space. HTTP measurements cover gateway requests, including request counts, 5xx errors, response bytes and latency percentiles. Resource and HTTP history is retained for 30 days; resource points older than a day are rolled up to one per five minutes, and older than a week to one per hour, each keeping the bucket's last point plus its CPU and memory peak and mean. Inspect `status`, `latestSampleAt` and `truncated` in resource JSON before interpreting a range as current or complete.
+
+Ask what the CPU and memory figures could be, from what the production replicas actually used:
+
+```sh
+inquir apps resources recommend api
+inquir apps resources recommend api --days 3 --json
+```
+
+The recommendation is read-only. Memory is 1.2 × the peak working set in the window (default 7 days), at least 64 MB, at least 256 MB for a database, and never below the peak of the whole 30-day history plus 10%. The CPU limit follows the peak (1.5 ×, at least 0.1 vCPU); the reserved request shown is what the platform would reserve for that limit, next to the request the 95th percentile of five-minute averages alone would justify. A recommendation needs 24 hours of observed usage; `confidence` reports the days observed and the samples behind it, and `--json` adds each release (replica set) seen in the window. Apply one yourself with `inquir apps update api --memory <mb> --cpu <vcpus>` and `inquir apps redeploy api`.
+
+Persisted container logs remain readable after the container is replaced. Select an app and optionally an exact release or runtime identity:
+
+```sh
+inquir apps log-history api --since 1h --level error --json
+inquir apps logs api --history --release <release-id> --replica <allocation-id> --allocation-fence 4
+inquir apps log-history api --since 1h --replica api-1-b1b1b1b1   # a name or index from apps instances
+inquir apps log-history api --runner <runner-id> --runner-epoch 0 --container <full-container-id>
+inquir apps log-history api --http --since 7d --status 503 --search /api --json
+```
+
+History returns one page, newest first. Runtime retention is 7 days; HTTP retention is 30 days. Use `--limit` (up to 200 runtime rows or 500 HTTP rows) and `--cursor` for older pages. Always reuse the response's `from` and `to` as `--from`/`--to`, plus the same filters, when using a cursor. `apps logs api` without `--history` still follows the current release; `apps logs <build-id>` still reads build output.
+
+Configure alert rules using JSON files or stdin. Destinations are write-only and are omitted from command output:
+
+```sh
+inquir apps alerts api list --json
+inquir apps alerts api create --file cpu-alert.json
+inquir apps alerts api update <rule-id> --file patch.json
+inquir apps alerts api incidents --limit 25 --json
+inquir apps alerts api delete <rule-id>
+```
+
+Example `cpu-alert.json` (incident-only until a notification destination is configured):
+
+```json
+{
+  "name": "High CPU",
+  "enabled": true,
+  "metric": "cpu_percent",
+  "threshold": 85,
+  "forSeconds": 120,
+  "recoveryThreshold": 65,
+  "recoveryForSeconds": 60,
+  "noDataSeconds": 180,
+  "noData": "alert",
+  "channels": []
+}
+```
+
+Use `memory_percent` for RAM or `deployment_failed` for failed production deployments. CPU/RAM rules evaluate the continuous maximum across current production replicas; the hot replica can change during the hold period. Percentage thresholds refer to each container's enforced limit. For deployment events, timing and threshold fields do not control the failure trigger. Notification channels have the shape `{"type":"webhook","url":"https://your-endpoint.example/alerts"}` or `{"type":"slack","url":"https://hooks.slack.com/..."}`. Keep secret URLs in a file outside version control, or pipe JSON to `--file -`. The server must have secret encryption configured to accept notification channels.
+
+A patch such as `{"threshold":90}` keeps existing destinations. `{"channels":[]}` removes them. Deleting a rule disables it and resolves active incidents while preserving retained history. Incident results include notification delivery state and retry counts. All commands honor the existing `--workspace`, `--env`, `--api-url` and credential selection rules.