insta 0.0.22 → 0.0.24

package/README.md

@@ -1,118 +1,220 @@
 # insta-cli
 
-InstaCloud CLI (`insta`) — a thin client of the [platform](../platform) control-plane API.
-Manages project / branch / secrets / deploy / governance — built for developers and agents.
+[![npm](https://img.shields.io/npm/v/insta?color=blue)](https://www.npmjs.com/package/insta)
+[![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg)](LICENSE)
 
-Tech stack: Node 20 + TypeScript (ESM) + commander. Every command is a wrapper around the platform API.
+The InstaCloud CLI. Provision Postgres, object storage and compute, fork the whole
+environment per branch, and give your coding agent scoped credentials without pasting
+secrets into a chat window.
 
-## Installation
+`insta` is a thin client over the InstaCloud control-plane API. Every command is one API
+call, so anything you can do, an agent can do.
 
-**One-line install (native binary, no node required)** — macOS / Linux / WSL:
+## Install
+
+Native binary, no Node required (macOS / Linux / WSL). Installs to `~/.insta/bin` and
+verifies the download against `SHA256SUMS`:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/InsForge/insta-cli/main/install.sh | sh
-#   Installs to ~/.insta/bin/insta (override with INSTA_INSTALL_DIR); verifies SHA256SUMS.
-#   Pin a version: curl -fsSL .../install.sh | INSTA_VERSION=v0.1.0 sh
-# Windows: download insta-windows-x64.exe from the releases page.
 ```
 
-**Build from source (requires node):**
+From npm:
 
 ```bash
-npm install
-npm run build         # -> dist/index.js (bin: insta; pure JS, requires node to run)
-node dist/index.js --help
+npm install -g insta
 ```
 
-### Build your own binaries (Bun cross-compilation)
-
-The binaries that `install.sh` installs are cross-compiled with Bun by CI (tag `v*` → `.github/workflows/release.yml`)
-and published to GitHub releases. You can also build them locally: requires [Bun](https://bun.sh). The npm package still
-ships JS (`dist/index.js`) — binaries are a separate distribution channel.
+For coding agents. Installs the CLI, the `insta` skill for every agent on the machine, and
+registers the MCP server:
 
 ```bash
-npm run compile            # compile for the current platform only -> dist/bin/insta
-npm run build:binaries     # cross-compile all platforms -> dist/bin/insta-<os>-<arch>(.exe) + SHA256SUMS
-#   The version (baked into `insta --version`) defaults to package.json, or pass it: bash scripts/build-binaries.sh 1.2.3
+curl -fsSL agents.instacloud.com | sh
 ```
 
-Artifacts look like `insta-darwin-arm64` / `insta-linux-x64` / `insta-windows-x64.exe` (`file` reports native Mach-O/ELF/PE executables).
-`dist/` is gitignored; binaries are not committed — CI publishes them to releases.
+On Windows, download `insta-windows-x64.exe` from the
+[releases page](https://github.com/InsForge/insta-cli/releases).
+
+Pin a version with `INSTA_VERSION=v0.0.22`; change the install directory with
+`INSTA_INSTALL_DIR`. While the CLI is pre-1.0 it updates itself on new releases. Turn that
+off with `insta autoupdate off`.
 
 ## Quickstart
 
 ```bash
-# Point at the control plane (defaults to http://localhost:8080; override with $INSTA_API_URL or --api-url)
-insta login --email you@example.com --password ****** --api-url http://localhost:8080
-insta project create my-app          # create an empty project and link the current directory (no services by default)
-insta services add postgres db       # add services on demand (postgres/storage/compute)
-insta services add compute api       # compute is used to deploy images
-insta secrets                        # write the current branch's credentials to ./.env (secret seam)
-insta deploy --image <registry/img>  # deploy a container image to the current branch's compute service
-insta status                         # login state + linked project/branch
+insta login --oauth github
+insta project create my-app
+insta services add postgres db
+insta services add compute api
+insta secrets
+insta deploy .
 ```
 
-## Commands
+`project create` makes an empty project and links the current directory. Services are
+opt-in, so you add only what you need. `secrets` writes the current branch's credentials to
+`./.env`. `deploy .` builds the directory remotely and ships it to the branch's compute
+service; it needs a `Dockerfile`, but no local Docker.
 
-| Command | Description |
-|------|------|
-| `insta login [--email --password --api-url]` | Log in (email/password; tokens auto-refresh) |
-| `insta login --oauth <github\|google>` | Browser OAuth login (starts a local loopback port; the token is carried back automatically after browser authorization) |
-| `insta logout` / `insta status [--json]` | Log out / show status |
-| `insta org list [--json]` / `org create <name>` | Organizations (each user may own only one free org) |
-| `insta project create <name> [--org]` | Create an empty project and link it (no services by default) |
-| `insta project list [--org] [--json]` / `link <id>` / `delete` | Project management |
-| `insta services add <postgres\|storage\|compute> <name>` | Provision a service on demand (postgres/compute get a default access domain) |
-| `insta services list [--json]` / `services remove <type> <name>` | List / remove services |
-| `insta services scale compute <name> <number> [region]` | Set the compute machine count (paid tiers; rejected on free) |
-| `insta services upgrade <compute\|postgres> <name> <spec>` | Upgrade the spec (paid tiers; upgrade only, no downgrade) |
-| `insta branch create <name> [--from]` | Create a branch environment (materializes the project's current services; up to 10 branches per project) |
-| `insta branch list [--json]` / `switch <name>` / `delete <name>` | Branch management |
-| `insta secrets [--branch -o --print --json]` | Secret seam: write credentials to `.env` |
-| `insta secrets list [--branch]` | List secret names only |
-| `insta deploy --image <url> [--branch --group --port]` | Deploy an image |
-| `insta manifest [--json]` | Agent-readable environment manifest |
-| `insta metrics <db\|compute> [group] [--branch --from --to --step --json]` | Resource metrics (compute=Fly; db limited) |
-| `insta logs <db\|compute> [group] [--branch --limit --region --instance --json]` | Runtime logs (compute=Fly; db limited) |
-| `insta events [--branch --limit --json]` | Audit + agent event timeline |
-| `insta usage [--from --to --json]` | Resource usage aggregated by meter (includes costUsd) |
-| `insta billing [--org --json]` | Current billing-cycle summary (tier / quota / used / overage / status) |
-| `insta billing upgrade <pro\|enterprise> [--org --no-open --json]` | Subscribe to a paid tier via Stripe Checkout; returns and opens the payment link |
-| `insta billing portal [--org --no-open --json]` | Open the Stripe Customer Portal (change plan / card / cancel) |
-| `insta approvals list [--status] [--json]` | Governance approval list |
-| `insta approvals approve <id> [--always]` / `deny <id>` | Approve / deny (admin) |
-| `insta policy get [--json]` / `policy set <action> <decision>` | Governance policy (actions include `service.add/remove/scale/upgrade`) |
-
-When a governance-gated operation (`secrets.read`/`deploy`/`project.delete`/`branch.delete`/`service.add`/`service.remove`/`service.scale`/`service.upgrade`) hits an approval,
-the CLI prompts `approval required — run: insta approvals approve <id>`.
-
-## Configuration locations
-
-- Global: `~/.insta/config.json` (apiUrl + access/refresh token + user)
-- Project: `./.insta/project.json` (projectId / orgId / current branch)
-
-## Local end-to-end run
-
-The platform provides a `dev:fake` mode (fake provider adapters, no Neon/Fly/Tigris credentials required):
+## Authentication
 
 ```bash
-# 1) Start Postgres + the platform dev server (see ../platform)
-docker run -d --name pg -e POSTGRES_PASSWORD=insta -e POSTGRES_DB=insta_dev -p 55432:5432 postgres:16-alpine
-cd ../platform && DATABASE_URL='postgres://postgres:insta@localhost:55432/insta_dev' PORT=8899 npm run dev:fake
+insta login --email you@example.com          # password from $INSTA_PASSWORD or a prompt
+insta login --oauth github                   # or google, through the browser
+insta login --env staging --oauth github     # log in to a specific deployment
+```
+
+Tokens are stored in `~/.insta/config.json` and refresh automatically.
+
+`--oauth` starts a loopback listener on `127.0.0.1`, opens the browser at the control
+plane's `/auth/cli/authorize`, and receives the token back on that listener once the
+provider has authorized you. Nothing is pasted by hand.
+
+If you operate your own control plane, the provider's OAuth app needs
+`GITHUB_OAUTH_CLIENT_ID` / `GITHUB_OAUTH_CLIENT_SECRET` (or the `GOOGLE_*` equivalents), and
+its callback URL must be `{INSTA_API_BASE_URL}/api/auth/callback/<provider>` — the control
+plane's address, not the CLI's loopback address.
+
+## How it works
+
+### Services are branch-scoped
+
+A project holds services (`postgres`, `storage`, `compute`) and each branch owns its own
+set. `insta branch create feature-x` forks the parent's services: a Neon branch per
+Postgres, a copy-on-write bucket per storage, a clone of every compute service. From there
+the two branches diverge independently. A project is capped at 10 branches.
+
+### Credentials come from the secret seam, not a file you maintain
+
+`insta secrets` fetches the current branch's bundle and writes `./.env`. `insta run <cmd>`
+does the same without touching disk, injecting the bundle into the child process only.
+Credential names are per service — `DATABASE_URL`, `BUCKET_NAME`, `AWS_ACCESS_KEY_ID` —
+suffixed with the service name when a project has more than one service of a type.
+
+### Destructive actions can require approval
+
+Reading secrets, deploying, deleting a project or branch, and changing services are
+governed by a per-project policy. Where the policy says `approve`, the command stops and
+prints an approval id for an admin to grant with `insta approvals approve <id>`. Run
+`insta policy get` for the live policy.
+
+### Agents get the same surface
 
-# 2) Run the full flow with the CLI (signup goes through /auth/signup + /auth/verify-email; in dev mode the verification code is printed in the server logs)
-INSTA_API_URL=http://localhost:8899 insta login --email you@x.com --password ...
+`insta manifest` prints an agent-legible view of every branch and its URLs. `insta setup
+agent` installs the InstaCloud skill and registers the remote MCP server for the coding
+agents on the machine.
+
+## Environments
+
+`prod` and `staging` are separate deployments, in different regions, with different
+databases and different auth. A session minted by one cannot authenticate against the
+other, so switching environments drops the stored session and you log in again.
+
+| | `prod` (default) | `staging` |
+|---|---|---|
+| control plane | `api.instacloud.com` | `api.staging.instacloud.com` |
+| MCP server | `mcp.instacloud.com/mcp` | `mcp.staging.instacloud.com/mcp` |
+| MCP registers as | `insta-cloud` | `insta-cloud-staging` |
+| agent skills | `InsForge/insta-skills` | `InsForge/insta-skills#devel` |
+| CLI channel | latest stable release | newest prerelease, else stable |
+
+```bash
+insta env                 # current environment and everything derived from it
+insta env use staging     # switch; persisted to ~/.insta/config.json
 ```
 
-## OAuth browser login
+The control plane, the MCP host and the skill source all resolve from that one switch, so a
+machine cannot end up running staging while its agents read production's skill text. The
+two MCP registrations use different names, so both environments can be installed side by
+side.
+
+To install against staging directly:
 
 ```bash
-insta login --oauth github          # or google
-# CLI starts a local loopback port → opens the browser to /auth/cli/authorize → Better Auth runs provider authorization →
-# the platform reads the session cookie to exchange for a bearer token → carries it back to the loopback port → CLI stores it as login state
+curl -fsSL agents.staging.instacloud.com | sh
 ```
 
-> The platform must have an OAuth app configured for that provider (`GITHUB_OAUTH_CLIENT_ID/SECRET` or `GOOGLE_*`),
-> and the app's callback URL must be **`{INSTA_API_BASE_URL}/api/auth/callback/<provider>`** (not the loopback address).
+That host is a CloudFront cache, so after a change to the installer it can serve the
+previous copy for up to about a day. This form is equivalent and always current:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/InsForge/insta-cli/main/install.sh | sh -s -- --agents --staging -y
+```
+
+If the environment cannot be applied — an installed CLI older than 0.0.23 has no `insta
+env` — the installer exits non-zero and says so, rather than leaving you silently pointed
+at production. The canonical usage is `curl … | sh && insta project create`, often run
+unattended by an agent, and a silent fallback there would provision real production
+infrastructure.
+
+Resolution order, most specific first:
+
+1. `INSTA_API_URL` — a literal URL, and the only way to reach a host no environment name
+   covers, such as a local daemon or a preview deployment. `INSTA_MCP_URL` and
+   `INSTA_SKILLS_REPO` do the same for the MCP host and the skill source.
+2. `INSTA_ENV` — `prod` or `staging`. An unrecognised value is an error, never a fallback.
+3. The `apiUrl` persisted in `~/.insta/config.json`.
+4. `prod`.
+
+Prereleases publish with `--prerelease` on GitHub and under npm's `next` tag, so a staging
+build never reaches a production installer.
+
+## Commands
 
-> `metrics` / `logs` / `usage` are supported (usage is aggregated at the collection layer). Multiple compute services (`services add compute`) and `services scale/upgrade` are implemented; image building will come later. Multiple postgres/storage services (>1 per project) are currently constrained by the credential seam and remain future work.
+`insta --help` is the authoritative list. For flags, approval gates and plan limits, see the
+[full command reference](https://github.com/InsForge/insta-skills/blob/main/insta/cli-reference.md).
+
+| Command | What it covers |
+|---|---|
+| `insta login` · `logout` · `status` | Email/password or `--oauth github\|google`; `status` shows the environment, login and linked project/branch |
+| `insta env` | `show` · `use <prod\|staging>` |
+| `insta setup` | `agent` — install the skill and register MCP for every coding agent |
+| `insta mcp` | `install` — register the remote MCP server only |
+| `insta org` | `list` · `create` (one free org per user) |
+| `insta project` | `create` · `list` · `link` · `delete` |
+| `insta branch` | `create` · `list` · `switch` · `delete` · `merge` |
+| `insta services` | `add` · `list` · `remove` · `rename` · `set-access` · `scale` · `upgrade` · `secrets` |
+| `insta secrets` | Write `.env`, plus `list` · `set` · `unset` · `tree` |
+| `insta run <cmd>` | Run a command with the branch bundle injected, nothing written to disk |
+| `insta deploy [dir]` | Deploy a source directory (built remotely) or `--image <url>` |
+| `insta compute` | `start` · `stop` · `suspend` · `status` · `set-domain` · `check-domain` · `remove-domain` |
+| `insta regions` | Regions available for postgres and compute |
+| `insta manifest` | Agent-legible view of every branch and its URLs |
+| `insta metrics` · `logs` · `events` | Service metrics; runtime logs (`--deploy` for deploy events); audit timeline |
+| `insta usage` · `billing` | Usage by billing dimension; `billing upgrade` · `billing portal` |
+| `insta approvals` | `list` · `approve` · `deny` |
+| `insta policy` | `get` · `set <action> <decision>` |
+| `insta observe` | `install` · `uninstall` · `report` · `sync` — local credential audit |
+| `insta upgrade` · `autoupdate` | Update the CLI; show or set auto-update |
+
+## Configuration
+
+| Location | Contents |
+|---|---|
+| `~/.insta/config.json` | API URL, access and refresh tokens, user, auto-update preference |
+| `./.insta/project.json` | Project id, org id, current branch |
+
+| Variable | Effect |
+|---|---|
+| `INSTA_API_URL` | Control-plane URL; outranks every other source |
+| `INSTA_ENV` | `prod` or `staging` |
+| `INSTA_MCP_URL` · `INSTA_SKILLS_REPO` | Override the MCP host and the agent-skill source |
+| `INSTA_PROJECT_ID` · `INSTA_ORG_ID` · `INSTA_BRANCH` | Target a project, org or branch without linking |
+| `INSTA_PASSWORD` | Password for non-interactive login |
+| `INSTA_NO_AUTOUPDATE` | Disable self-update |
+
+## Agent skills
+
+The `insta` skill and its task guides live in
+[InsForge/insta-skills](https://github.com/InsForge/insta-skills). `insta setup agent`
+installs it user-globally for every coding agent on the machine. `insta project create` and
+`insta project link` additionally install the stack skills (Neon Postgres, Tigris, Better
+Auth) into the project, along with the `insta observe` credential-audit hook.
+
+## Contributing
+
+Dev loop, architecture, cross-compilation and the release process are in
+[CONTRIBUTING.md](CONTRIBUTING.md). Issues and pull requests are welcome.
+
+## License
+
+Apache 2.0. See [LICENSE](LICENSE).

package/dist/commands/auth.js

@@ -1,13 +1,28 @@
 import { createServer } from 'node:http';
 import { randomBytes } from 'node:crypto';
 import { ApiClient, linkedProject } from '../api.js';
+import { ENVS, ENV_NAMES, envForApiUrl, isEnvName } from '../env.js';
 import { info, die, printJson, promptPassword, openUrl } from '../util.js';
+/** --api-url and --env both set the target host; --api-url wins (more specific), matching the
+ *  INSTA_API_URL > INSTA_ENV precedence in config.ts. Returns the URL to point at, or undefined
+ *  to leave whatever is already resolved alone. */
+function targetApiUrl(opts) {
+    if (opts.apiUrl)
+        return opts.apiUrl;
+    if (!opts.env)
+        return undefined;
+    const want = opts.env.trim().toLowerCase();
+    if (!isEnvName(want))
+        die(`unknown --env "${opts.env}" — expected one of: ${ENV_NAMES.join(', ')}`);
+    return ENVS[want].api;
+}
 export async function login(opts) {
     if (opts.oauth)
         return loginOauth(opts.oauth, opts);
     const api = await ApiClient.load();
-    if (opts.apiUrl)
-        api.setApiUrl(opts.apiUrl);
+    const target = targetApiUrl(opts);
+    if (target)
+        api.setApiUrl(target);
     if (!opts.email)
         die('--email is required (or use --oauth <github|google>)');
     const password = opts.password ?? process.env.INSTA_PASSWORD ?? (await promptPassword());
@@ -22,8 +37,9 @@ export async function loginOauth(provider, opts) {
     if (provider !== 'github' && provider !== 'google')
         die('provider must be github or google');
     const api = await ApiClient.load();
-    if (opts.apiUrl)
-        api.setApiUrl(opts.apiUrl);
+    const target = targetApiUrl(opts);
+    if (target)
+        api.setApiUrl(target);
     const token = await browserOauth(api.apiUrl, provider);
     api.setSession({ accessToken: token, refreshToken: token });
     const me = await api.request('GET', '/me');
@@ -91,8 +107,12 @@ export async function status(opts) {
     }
     catch { /* not logged in */ }
     const project = await linkedProject();
+    // Surface the environment name alongside the URL: "api: https://api.staging.instacloud.com" is
+    // easy to skim past, and mistaking staging for prod is the mistake worth making loud.
+    const env = envForApiUrl(api.apiUrl);
     if (opts.json)
-        return printJson({ apiUrl: api.apiUrl, user, project });
+        return printJson({ env, apiUrl: api.apiUrl, user, project });
+    info(`env:     ${env ?? '(custom)'}`);
     info(`api:     ${api.apiUrl}`);
     info(`user:    ${user ? (user.email ?? user.id) : '(not logged in)'}`);
     info(`project: ${project ? `${project.projectId} (branch ${project.branch})` : '(none linked)'}`);

package/dist/commands/compute.js

@@ -70,4 +70,21 @@ export async function computeStatus(serviceName, opts) {
         return printJson(r);
     info(`compute ${serviceName ?? id}: desired=${r.desiredState}  live=${r.state}`);
 }
+// ---- always-on (opt out of scale-to-zero; all plans; billing is actual usage either way) ----
+export async function computeAlwaysOn(mode, serviceName, opts) {
+    if (mode !== 'on' && mode !== 'off')
+        throw new Error('mode must be on|off');
+    const api = await ApiClient.load();
+    const p = await requireProject();
+    const branch = opts.branch ?? p.branch;
+    const { services } = await api.request('GET', `/projects/${p.projectId}/services${q(branch)}`);
+    const id = resolveComputeServiceId(services, serviceName);
+    const res = await api.rawRequest('PUT', `/projects/${p.projectId}/services/${id}/always-on`, { enabled: mode === 'on' });
+    if (handleApproval(res))
+        return;
+    if (opts.json)
+        return printJson(res.body);
+    const on = res.body.service?.always_on;
+    info(`compute ${res.body.service?.name ?? id}: always-on ${on ? 'ENABLED — machines stay warm (no cold starts; idle RAM bills at actual usage)' : 'disabled — scales to zero when idle (default)'}`);
+}
 //# sourceMappingURL=compute.js.map

package/dist/commands/db.js

@@ -0,0 +1,27 @@
+import { ApiClient, requireProject } from '../api.js';
+import { info, printJson, handleApproval } from '../util.js';
+// Toggle a postgres service between scale-to-zero (the default: instance suspends when idle,
+// cold-starts on the next connection) and always-on (instance stays warm; idle RAM bills at
+// actual usage). Thin wrapper over PATCH /database/settings {scaleToZero} — insta-db-backed
+// postgres only; Neon-backed services manage their own autosuspend and the platform returns an
+// error for them.
+export async function dbAlwaysOn(mode, opts) {
+    if (mode !== 'on' && mode !== 'off')
+        throw new Error('mode must be on|off');
+    const api = await ApiClient.load();
+    const p = await requireProject();
+    const qs = new URLSearchParams();
+    const branch = opts.branch ?? p.branch;
+    if (branch)
+        qs.set('branch', branch);
+    if (opts.group)
+        qs.set('group', opts.group);
+    const res = await api.rawRequest('PATCH', `/projects/${p.projectId}/database/settings${qs.toString() ? `?${qs}` : ''}`, { scaleToZero: mode !== 'on' });
+    if (handleApproval(res))
+        return;
+    if (opts.json)
+        return printJson(res.body);
+    const s2z = res.body?.scaleToZero;
+    info(`postgres ${opts.group ?? 'default'}: always-on ${s2z === false ? 'ENABLED — instance stays warm (no cold starts; idle RAM bills at actual usage)' : 'disabled — scales to zero when idle (default; first connection after idle cold-starts)'}`);
+}
+//# sourceMappingURL=db.js.map

package/dist/commands/env.js

@@ -0,0 +1,63 @@
+// `insta env` — show or switch the deployment environment (prod | staging).
+//
+// This exists because the canonical install is a pipe: `curl -fsSL agents.staging.instacloud.com | sh`.
+// A piped script cannot export anything into the parent shell, so the staging one-liner has no way
+// to make `INSTA_ENV=staging` stick for the `insta project create` the user runs next. Persisting
+// the choice into ~/.insta/config.json is the only mechanism that survives the pipe — and it is the
+// same file `login --api-url` already writes, so this adds a surface, not a concept.
+import { readPersistedGlobal, resolveEnv, writeGlobal } from '../config.js';
+import { DEFAULT_ENV, ENVS, ENV_NAMES, envForApiUrl, isEnvName, mcpServerName, normalizeUrl } from '../env.js';
+import { die, info, printJson } from '../util.js';
+export async function envShow(opts) {
+    const { apiUrl, env, mcpUrl, skills } = await resolveEnv();
+    const mcpServer = mcpServerName(env ?? DEFAULT_ENV);
+    if (opts.json)
+        return printJson({ env, apiUrl, mcpUrl, mcpServer, skills });
+    info(`env:     ${env ?? '(custom)'}`);
+    info(`api:     ${apiUrl}`);
+    info(`mcp:     ${mcpUrl} (${mcpServer})`);
+    info(`skills:  ${skills}`);
+    if (!env)
+        info('  (custom apiUrl — `insta env use <name>` to switch to a named environment)');
+}
+export async function envUse(name) {
+    const want = name.trim().toLowerCase();
+    if (!isEnvName(want))
+        die(`unknown environment "${name}" — expected one of: ${ENV_NAMES.join(', ')}`);
+    const target = want;
+    const nextApi = ENVS[target].api;
+    // The PERSISTED config, deliberately not the override-resolved view — see readPersistedGlobal.
+    const stored = await readPersistedGlobal();
+    const from = envForApiUrl(stored.apiUrl);
+    // Compare normalised, so a stored trailing slash is recognised as the same environment (which is
+    // how envForApiUrl already treats it) instead of being rewritten as a "switch" that needlessly
+    // drops a perfectly good session.
+    if (normalizeUrl(stored.apiUrl) === normalizeUrl(nextApi)) {
+        info(`already on ${target} (${nextApi})`);
+        return;
+    }
+    // A real switch, so drop the stored session unconditionally. prod and staging are separate
+    // deployments: the old token cannot authenticate here, and keeping it is actively unsafe because
+    // api.ts's 401 path POSTs the refresh token to whatever apiUrl now resolves to, handing one
+    // deployment's credential to another. Same reasoning as the retired-host path in config.ts.
+    //
+    // "Any field" rather than accessToken alone: a config holding only a refreshToken (an interrupted
+    // login, a hand-edited file) would otherwise keep that token and post it to the new host.
+    const hadSession = !!(stored.accessToken || stored.refreshToken || stored.user);
+    const next = { ...stored, apiUrl: nextApi };
+    delete next.accessToken;
+    delete next.refreshToken;
+    delete next.user;
+    await writeGlobal(next);
+    info(`switched ${from ?? '(custom)'} → ${target}`);
+    info(`  api: ${nextApi}`);
+    info(`  mcp: ${ENVS[target].mcp} (registers as \`${mcpServerName(target)}\`)`);
+    if (hadSession)
+        info('  previous session dropped (separate deployment) — run `insta login --oauth github`');
+    // Switching the CLI does NOT re-point already-installed agents: their MCP registration and skill
+    // files were written for the previous environment and are keyed by a different server name, so
+    // they keep talking to it until setup is re-run. (The installer path is fine — install.sh runs
+    // `env use` before `setup agent`.)
+    info('  re-point this machine\'s agents at it with: insta setup agent');
+}
+//# sourceMappingURL=env.js.map

package/dist/commands/mcp.js

@@ -8,7 +8,7 @@ import { existsSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { info } from '../util.js';
-import { DEFAULT_MCP_URL, MCP_SERVER_NAME, registerMcp } from './setup.js';
+import { MCP_SERVER_NAME, registerMcp, resolveMcpTarget } from './setup.js';
 export const MCP_AGENT_TARGETS = ['cursor', 'codex', 'opencode', 'copilot', 'factory-droid'];
 export function configPath(slug, home) {
     switch (slug) {
@@ -26,7 +26,7 @@ export function detectAgents(home) {
 }
 // Merge our entry into existing JSON config. Returns null (skip, leave file alone) when the
 // existing content isn't valid JSON — never clobber a config we can't parse.
-export function renderJsonConfig(slug, existing, url) {
+export function renderJsonConfig(slug, existing, url, name = MCP_SERVER_NAME) {
     let root = {};
     if (existing && existing.trim()) {
         try {
@@ -40,28 +40,28 @@ export function renderJsonConfig(slug, existing, url) {
     }
     if (slug === 'opencode') {
         // OpenCode: `mcp` key, `type: "remote"` schema (docs.opencode.ai).
-        root.mcp = { ...(root.mcp ?? {}), [MCP_SERVER_NAME]: { type: 'remote', url, enabled: true } };
+        root.mcp = { ...(root.mcp ?? {}), [name]: { type: 'remote', url, enabled: true } };
         root.$schema ??= 'https://opencode.ai/config.json';
     }
     else {
         const entry = slug === 'cursor' ? { url } // Cursor auto-detects HTTP from `url`
             : slug === 'copilot' ? { type: 'http', url, tools: ['*'] }
                 : { type: 'http', url, disabled: false }; // factory-droid
-        root.mcpServers = { ...(root.mcpServers ?? {}), [MCP_SERVER_NAME]: entry };
+        root.mcpServers = { ...(root.mcpServers ?? {}), [name]: entry };
     }
     return JSON.stringify(root, null, 2) + '\n';
 }
 // Codex config is TOML. Appending a complete `[mcp_servers.<name>]` table is always valid at
 // EOF, so we avoid a TOML parser: string-detect for idempotency, append for install.
-export function renderCodexConfig(existing, url) {
+export function renderCodexConfig(existing, url, name = MCP_SERVER_NAME) {
     const base = existing ?? '';
-    if (base.includes(`[mcp_servers.${MCP_SERVER_NAME}]`))
+    if (base.includes(`[mcp_servers.${name}]`))
         return null; // already configured
     const sep = base.length && !base.endsWith('\n') ? '\n' : '';
-    return `${base}${sep}\n[mcp_servers.${MCP_SERVER_NAME}]\nurl = "${url}"\n`;
+    return `${base}${sep}\n[mcp_servers.${name}]\nurl = "${url}"\n`;
 }
 // Install for one agent. Returns 'installed' | 'already' | 'skipped' (unparseable config).
-export async function installFor(slug, home, url) {
+export async function installFor(slug, home, url, name = MCP_SERVER_NAME) {
     const file = configPath(slug, home);
     let existing = null;
     try {
@@ -71,7 +71,7 @@ export async function installFor(slug, home, url) {
         existing = null;
     }
     if (slug === 'codex') {
-        const next = renderCodexConfig(existing, url);
+        const next = renderCodexConfig(existing, url, name);
         if (next === null)
             return 'already';
         await fs.mkdir(path.dirname(file), { recursive: true });
@@ -81,13 +81,13 @@ export async function installFor(slug, home, url) {
     if (existing) {
         try {
             const root = JSON.parse(existing);
-            const entry = slug === 'opencode' ? root?.mcp?.[MCP_SERVER_NAME] : root?.mcpServers?.[MCP_SERVER_NAME];
+            const entry = slug === 'opencode' ? root?.mcp?.[name] : root?.mcpServers?.[name];
             if (entry)
                 return 'already';
         }
         catch { /* fall through to renderJsonConfig, which refuses to clobber */ }
     }
-    const next = renderJsonConfig(slug, existing, url);
+    const next = renderJsonConfig(slug, existing, url, name);
     if (next === null)
         return 'skipped';
     await fs.mkdir(path.dirname(file), { recursive: true });
@@ -100,7 +100,7 @@ const AGENT_LABELS = {
 // Configure every detected config-file agent (or one forced via `agent`). Returns the labels of
 // agents now configured (installed or already present) for the caller's summary line.
 export async function installAgentConfigs(agent, home = os.homedir()) {
-    const url = process.env.INSTA_MCP_URL || DEFAULT_MCP_URL;
+    const { name, url } = await resolveMcpTarget();
     const targets = agent
         ? MCP_AGENT_TARGETS.includes(agent) ? [agent] : []
         : detectAgents(home);
@@ -110,9 +110,9 @@ export async function installAgentConfigs(agent, home = os.homedir()) {
     }
     const done = [];
     for (const slug of targets) {
-        const result = await installFor(slug, home, url);
+        const result = await installFor(slug, home, url, name);
         if (result === 'skipped')
-            info(`  ${AGENT_LABELS[slug]}: existing config at ${configPath(slug, home)} isn't valid JSON — add ${MCP_SERVER_NAME} manually`);
+            info(`  ${AGENT_LABELS[slug]}: existing config at ${configPath(slug, home)} isn't valid JSON — add ${name} manually`);
         else
             done.push(AGENT_LABELS[slug]);
     }

package/dist/commands/metrics.js

@@ -77,10 +77,33 @@ export async function usage(opts) {
             info(`  ${pr.name}: $${Number(pr.totalCostUsd ?? 0).toFixed(4)}`);
     }
 }
+// pure: platform path for a compute deploy-events request (used by `insta logs --deploy`).
+export function deployEventsPath(projectId, opts) {
+    return `/projects/${projectId}/deploy-events${qs({ group: opts.group, branch: opts.branch, limit: opts.limit, instance: opts.instance })}`;
+}
+// pure: render one deploy event as a log-style line.
+export function deployEventLine(ev) {
+    const inst = ev.instance ? `  (${ev.instance})` : '';
+    return `${ev.ts ?? ''}  [${ev.origin ?? ''}] ${ev.type ?? ''}: ${ev.status ?? ''}${inst}`;
+}
 // insta logs <db|compute> [group]
 export async function logs(component, group, opts) {
     const api = await ApiClient.load();
     const p = await requireProject();
+    if (opts.deploy) {
+        if (component !== 'compute')
+            return info('deploy events are only available for compute');
+        const res = await api.request('GET', deployEventsPath(p.projectId, { group, branch: opts.branch ?? p.branch, limit: opts.limit, instance: opts.instance }));
+        if (opts.json)
+            return printJson(res);
+        if (res.note)
+            info(`note: ${res.note}`);
+        if (!res.events?.length)
+            return info('(no deploy events)');
+        for (const ev of res.events)
+            info(deployEventLine(ev));
+        return;
+    }
     const res = await api.request('GET', `/projects/${p.projectId}/logs${qs({ component, group, branch: opts.branch ?? p.branch, limit: opts.limit, region: opts.region, instance: opts.instance })}`);
     if (opts.json)
         return printJson(res);

package/dist/commands/services.js

@@ -53,6 +53,7 @@ export function servicesAddRequestBody(type, name, branch, opts) {
         type, name, ...(branch ? { branch } : {}), public: !!opts.public,
         ...(opts.image ? { image: opts.image } : {}), ...(opts.port ? { port: Number(opts.port) } : {}),
         ...(opts.region ? { region: opts.region } : {}),
+        ...(opts.alwaysOn ? { alwaysOn: true } : {}),
     };
 }
 export async function servicesAdd(type, name, opts = {}) {
@@ -65,6 +66,8 @@ export async function servicesAdd(type, name, opts = {}) {
         throw new Error('--image is only valid for compute services');
     if (opts.port && type !== 'compute')
         throw new Error('--port is only valid for compute services');
+    if (opts.alwaysOn && type !== 'compute')
+        throw new Error('--always-on is only valid for compute services (for postgres, use `insta db always-on on` after creation)');
     const api = await ApiClient.load();
     const p = await requireProject();
     const branch = opts.branch ?? p.branch;

package/dist/commands/setup.js

@@ -8,6 +8,8 @@
 import { spawn } from 'node:child_process';
 import os from 'node:os';
 import { ApiClient } from '../api.js';
+import { resolveEnv } from '../config.js';
+import { DEFAULT_ENV, ENVS, mcpServerName } from '../env.js';
 import { info } from '../util.js';
 import { installAgentConfigs } from './mcp.js';
 // The `skills` tool we shell out to prints a clack UI: a frame-by-frame clone spinner, an
@@ -91,10 +93,25 @@ const defaultRunner = (cmd, args) => new Promise((resolve) => {
 });
 // -g = user-level (machine-global); -a '*' = every agent dir the skills tool supports
 // (Claude Code, Codex, Cursor, OpenCode, Copilot, …); --copy = real files, not cache symlinks.
-export const SETUP_ARGS = ['skills', 'add', 'InsForge/insta-skills', '-s', 'insta', '-a', '*', '-g', '-y', '--copy'];
+// `spec` is the skill source for the resolved environment (`owner/repo` or `owner/repo@ref`), so a
+// staging install reads the staging skill text rather than what's published on main.
+export const setupArgs = (spec) => ['skills', 'add', spec, '-s', 'insta', '-a', '*', '-g', '-y', '--copy'];
+/** Production's args. Kept as a named export because it is the installed-base default and is
+ *  asserted directly by tests; runtime goes through `setupArgs(resolveEnv().skills)`. */
+export const SETUP_ARGS = setupArgs(ENVS[DEFAULT_ENV].skills);
 // ---- remote MCP registration ----
-export const MCP_SERVER_NAME = 'insta-cloud';
-export const DEFAULT_MCP_URL = 'https://mcp.instacloud.com/mcp';
+// Prod's name/URL, kept as named exports because they are the installed-base defaults and are
+// asserted directly by tests. Everything at runtime goes through `resolveMcpTarget()` instead, so
+// a staging install registers staging's MCP server under its own name rather than reusing prod's.
+export const MCP_SERVER_NAME = mcpServerName(DEFAULT_ENV);
+export const DEFAULT_MCP_URL = ENVS[DEFAULT_ENV].mcp;
+/** The MCP server this machine should register, derived from the SAME resolved environment as the
+ *  control-plane API. Returning name and url together is deliberate: they must never be chosen
+ *  independently, or a staging machine ends up registering prod's URL under prod's name. */
+export async function resolveMcpTarget() {
+    const { env, mcpUrl } = await resolveEnv();
+    return { name: mcpServerName(env ?? DEFAULT_ENV), url: mcpUrl };
+}
 const defaultMinter = async () => {
     try {
         const api = await ApiClient.load();
@@ -115,14 +132,14 @@ const defaultMinter = async () => {
 // Idempotent — an existing registration is left alone. Best-effort: the skill install is the
 // primary outcome; agents without an MCP registry are covered by the skill alone.
 export async function registerMcp(run = defaultRunner, mint = defaultMinter, useToken = false) {
-    const url = process.env.INSTA_MCP_URL || DEFAULT_MCP_URL;
+    const { name, url } = await resolveMcpTarget();
     if (!(await run('claude', ['--version'])).ok)
         return; // no Claude Code on this machine
-    if ((await run('claude', ['mcp', 'get', MCP_SERVER_NAME])).ok) {
-        info(`✓ MCP — ${MCP_SERVER_NAME} already registered with Claude Code`);
+    if ((await run('claude', ['mcp', 'get', name])).ok) {
+        info(`✓ MCP — ${name} already registered with Claude Code`);
         return;
     }
-    const args = ['mcp', 'add', '--transport', 'http', '--scope', 'user', MCP_SERVER_NAME, url];
+    const args = ['mcp', 'add', '--transport', 'http', '--scope', 'user', name, url];
     if (useToken) {
         const token = await mint();
         if (!token) {
@@ -133,23 +150,29 @@ export async function registerMcp(run = defaultRunner, mint = defaultMinter, use
     }
     const res = await run('claude', args);
     if (res.ok) {
-        info(`✓ MCP — ${MCP_SERVER_NAME} registered with Claude Code (\`claude mcp list\` to verify)`);
+        info(`✓ MCP — ${name} registered with Claude Code (\`claude mcp list\` to verify)`);
         if (!useToken)
             info('  first use: run `/mcp` in Claude Code and authorize in the browser (headless machines: `insta setup agent --mcp-token`)');
     }
     else {
-        info(`  MCP registration failed — add manually:\n    claude mcp add --transport http ${MCP_SERVER_NAME} ${url}`);
+        info(`  MCP registration failed — add manually:\n    claude mcp add --transport http ${name} ${url}`);
     }
 }
 export async function setupAgent(opts, run = defaultRunner, mint, installConfigs = installAgentConfigs) {
     if (!opts.yes && !process.stdout.isTTY) {
         info('non-interactive shell — assuming -y');
     }
-    info('setting up coding-agent skills …');
-    const res = await run('npx', SETUP_ARGS);
+    // One resolve for the whole step, so the skills and the MCP registration below cannot disagree
+    // about which environment this machine belongs to.
+    const { env, skills } = await resolveEnv();
+    const args = setupArgs(skills);
+    info(env && env !== DEFAULT_ENV
+        ? `setting up coding-agent skills (${env}) …`
+        : 'setting up coding-agent skills …');
+    const res = await run('npx', args);
     if (!res.ok) {
         info('  skill install failed — install manually with:');
-        info('    npx skills add InsForge/insta-skills -s insta -a "*" -g -y --copy');
+        info(`    npx ${args.map((a) => (a === '*' ? '"*"' : a)).join(' ')}`);
         // Surface the REAL error: the captured tail, minus the expected no-global-support noise.
         const tail = (res.output ?? '')
             .split('\n')

package/dist/config.js

@@ -2,6 +2,7 @@
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { DEFAULT_ENV, ENVS, envForApiUrl, envFromEnvVar, normalizeUrl } from './env.js';
 const GLOBAL_DIR = join(homedir(), '.insta');
 const GLOBAL_FILE = join(GLOBAL_DIR, 'config.json');
 const PROJECT_DIR = '.insta';
@@ -9,17 +10,74 @@ const PROJECT_FILE = 'project.json';
 // The cloud API default. Uses the instacloud.com brand domain (matches the agents.instacloud.com
 // onboarding), NOT the legacy beta-api.insta.insforge.dev host — same backend, branded domain.
 // Only affects fresh installs: a persisted apiUrl (from a prior login) or INSTA_API_URL wins below.
-const DEFAULT_API = 'https://api.instacloud.com';
+const DEFAULT_API = ENVS[DEFAULT_ENV].api;
 export async function readGlobal() {
-    // INSTA_API_URL overrides the persisted apiUrl, not just the default — otherwise the
-    // env var is silently ignored as soon as any login has written a config file.
+    // Precedence, most explicit first:
+    //   1. INSTA_API_URL  — a literal URL. Overrides the persisted apiUrl, not just the default,
+    //      otherwise the env var is silently ignored as soon as any login has written a config file.
+    //      It also outranks INSTA_ENV: a hand-written URL is the more specific instruction, and it
+    //      is the only way to reach a host no environment name covers (insta-oss, a preview).
+    //   2. INSTA_ENV      — a named environment (see env.ts), resolved to its api host.
+    //   3. the persisted apiUrl, written by `insta login --env|--api-url` or `insta env use`.
+    //   4. DEFAULT_API.
     const envApi = process.env.INSTA_API_URL;
+    const named = envFromEnvVar();
+    const override = envApi ?? (named ? ENVS[named].api : undefined);
     try {
         const parsed = JSON.parse(await readFile(GLOBAL_FILE, 'utf8'));
-        return { ...parsed, apiUrl: envApi ?? parsed.apiUrl ?? DEFAULT_API };
+        const persisted = parsed.apiUrl ?? DEFAULT_API;
+        // An override that points at a DIFFERENT deployment than the stored session was minted for
+        // must not carry that session along. `env use` already drops it on an explicit switch; without
+        // this, `INSTA_ENV=staging insta …` on a prod-logged-in machine sends prod's bearer to staging
+        // and then — on the 401 — POSTs prod's REFRESH token to staging's /auth/refresh (api.ts), which
+        // is the cross-deployment credential leak env.ts's header calls out as never allowed.
+        //
+        // In-memory only: the file keeps the real login, so unsetting the override restores it. A
+        // custom host (insta-oss, a preview) is treated the same way — its session is equally foreign.
+        if (override && normalizeUrl(override) !== normalizeUrl(persisted)) {
+            const scrubbed = { ...parsed, apiUrl: override };
+            delete scrubbed.accessToken;
+            delete scrubbed.refreshToken;
+            delete scrubbed.user;
+            return scrubbed;
+        }
+        return { ...parsed, apiUrl: override ?? persisted };
+    }
+    catch {
+        return { apiUrl: override ?? DEFAULT_API };
+    }
+}
+/** The environment the CLI is currently pointed at, plus everything derived from it. `env` is null
+ *  when apiUrl is a custom host (insta-oss, a preview deployment) — deliberate, and left alone.
+ *
+ *  API host, MCP host, and skill source are resolved from ONE environment on purpose: the failure
+ *  mode of picking them independently is silent (a machine whose CLI talks to staging while its
+ *  agents are wired to prod and reading prod's skill text). */
+export async function resolveEnv() {
+    const { apiUrl } = await readGlobal();
+    const env = envForApiUrl(apiUrl);
+    const hosts = ENVS[env ?? DEFAULT_ENV];
+    // Each single-purpose env var still wins outright, for a self-hosted MCP / a tunnel / a skills
+    // fork. A custom apiUrl with none of them set falls back to the default environment, since
+    // there is nothing better to guess and it preserves today's behaviour.
+    const mcpUrl = process.env.INSTA_MCP_URL || hosts.mcp;
+    const skills = process.env.INSTA_SKILLS_REPO || hosts.skills;
+    return { apiUrl, env, mcpUrl, skills };
+}
+/** The config exactly as stored: no env-var overrides, no session scrubbing.
+ *
+ *  `env use` must read this rather than `readGlobal()`. With INSTA_ENV set, `readGlobal()` already
+ *  reports the override's host, so `env use <that same env>` would look like a no-op, print
+ *  "already on X" and never write the file — leaving the next process (without the override in its
+ *  environment) still pointed at the old one. Deciding "is this a real switch?" has to be done
+ *  against what is persisted. */
+export async function readPersistedGlobal() {
+    try {
+        const parsed = JSON.parse(await readFile(GLOBAL_FILE, 'utf8'));
+        return { ...parsed, apiUrl: parsed.apiUrl ?? DEFAULT_API };
     }
     catch {
-        return { apiUrl: envApi ?? DEFAULT_API };
+        return { apiUrl: DEFAULT_API };
     }
 }
 export async function writeGlobal(c) {

package/dist/ensure-skills.js

@@ -7,6 +7,8 @@
 import { spawn } from 'node:child_process';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { resolveEnv } from './config.js';
+import { DEFAULT_ENV, ENVS } from './env.js';
 // Where `npx skills add` drops skills for the agents we pin below: Claude Code → .claude/skills/,
 // Codex → .agents/skills/ (.github/skills/ is the third well-known dir). These are regenerable
 // agent context, not the developer's source — keep them out of git.
@@ -28,8 +30,11 @@ const defaultRunner = (cmd, args, inherit = false) => new Promise((resolve) => {
 // name the exact skills (-s …) so there's no skill picker; -y to skip the scope/confirm prompt;
 // --copy to write real files (not symlinks into a transient npx cache).
 const AGENT_FLAGS = ['-a', 'claude-code', '-a', 'codex', '-y', '--copy'];
-const SKILLS = [
-    { label: 'insta', args: ['skills', 'add', 'InsForge/insta-skills', '-s', 'insta', ...AGENT_FLAGS] },
+// `instaSpec` is the insta skill source for the resolved environment (`owner/repo[@ref]`), so a
+// project created against staging gets the staging skill text. The third-party stack skills are
+// environment-independent — they document Neon/Tigris/Better Auth, not our control plane.
+const skillTargets = (instaSpec) => [
+    { label: 'insta', args: ['skills', 'add', instaSpec, '-s', 'insta', ...AGENT_FLAGS] },
     { label: 'neon-postgres', args: ['skills', 'add', 'neondatabase/agent-skills', '-s', 'neon-postgres', ...AGENT_FLAGS] },
     { label: 'tigris', args: ['skills', 'add', 'tigrisdata/skills',
             '-s', 'tigris-object-operations', '-s', 'file-storage', '-s', 'tigris-sdk-guide',
@@ -40,6 +45,8 @@ const SKILLS = [
             '-s', 'better-auth-best-practices', '-s', 'email-and-password-best-practices',
             '-s', 'better-auth-security-best-practices', ...AGENT_FLAGS] },
 ];
+/** Production's targets — kept for tests and as the fallback when no env resolves. */
+const SKILLS = skillTargets(ENVS[DEFAULT_ENV].skills);
 // Install all related skills. Production omits `run`/`print` → the real spawn + stdout; tests inject
 // a fake runner and capture output. Continues past a per-skill failure so one bad repo doesn't skip
 // the rest, and never throws.
@@ -47,8 +54,17 @@ export async function installSkills(deps) {
     const run = deps.run ?? defaultRunner;
     const print = deps.print ?? ((s) => process.stdout.write(s + '\n'));
     try {
+        // Resolve once per call so the insta skill follows this machine's environment. Falls back to
+        // production's targets if anything about the resolve fails — a bad read must not skip the
+        // whole best-effort install.
+        let targets = SKILLS;
+        try {
+            const { skills } = await resolveEnv();
+            targets = skillTargets(skills);
+        }
+        catch { /* keep production defaults */ }
         print('  installing related agent skills (insta, neon-postgres, tigris, better-auth) …');
-        for (const s of SKILLS) {
+        for (const s of targets) {
             // Don't stream: the `skills` tool's clack UI (clone spinner, banners) is noise. Run it
             // silent (stdio 'ignore') and let the per-skill ✓/failed line below be the clean output —
             // it appears as each skill finishes, so there's still live progress. (Also avoids the

package/dist/env.js

@@ -0,0 +1,52 @@
+export const ENVS = {
+    prod: {
+        api: 'https://api.instacloud.com',
+        mcp: 'https://mcp.instacloud.com/mcp',
+        skills: 'InsForge/insta-skills',
+    },
+    staging: {
+        api: 'https://api.staging.instacloud.com',
+        mcp: 'https://mcp.staging.instacloud.com/mcp',
+        skills: 'InsForge/insta-skills#devel',
+    },
+};
+export const DEFAULT_ENV = 'prod';
+export const ENV_NAMES = Object.keys(ENVS);
+export function isEnvName(v) {
+    return ENV_NAMES.includes(v);
+}
+/** Strip trailing slashes so 'https://x/' and 'https://x' compare equal. */
+export const normalizeUrl = (url) => url.replace(/\/+$/, '');
+/** The environment a persisted apiUrl belongs to, or null for a custom/self-hosted host
+ *  (insta-oss on localhost, a preview deployment). null is not an error — it means "the user
+ *  chose this URL deliberately", and callers must leave such a choice alone. */
+export function envForApiUrl(apiUrl) {
+    const want = normalizeUrl(apiUrl);
+    return ENV_NAMES.find((n) => normalizeUrl(ENVS[n].api) === want) ?? null;
+}
+/** $INSTA_ENV, validated. An unrecognised value throws rather than falling back to prod: a
+ *  typo'd `INSTA_ENV=stagng` that silently provisions real infrastructure in production is the
+ *  worst possible outcome, and it would be invisible until the bill arrived. */
+export function envFromEnvVar(raw = process.env.INSTA_ENV) {
+    if (raw === undefined)
+        return null;
+    const v = raw.trim().toLowerCase();
+    if (v === '')
+        return null;
+    if (!isEnvName(v)) {
+        throw new Error(`unknown INSTA_ENV "${raw}" — expected one of: ${ENV_NAMES.join(', ')}`);
+    }
+    return v;
+}
+/** MCP registration name for an environment.
+ *
+ *  Prod keeps the bare `insta-cloud` name — it is the installed base, and renaming it would
+ *  orphan every existing registration. Other environments get a suffix so they can coexist on
+ *  one machine. This matters more than it looks: `registerMcp` treats an already-registered
+ *  name as "nothing to do", and the config-file agents key their entry by name, so sharing one
+ *  name across environments leaves a staging install silently wired to the prod MCP server
+ *  while reporting success. */
+export function mcpServerName(env) {
+    return env === DEFAULT_ENV ? 'insta-cloud' : `insta-cloud-${env}`;
+}
+//# sourceMappingURL=env.js.map

package/dist/index.js

@@ -4,6 +4,8 @@ import { Command } from 'commander';
 import { ApiError } from './api.js';
 import { die } from './util.js';
 import * as auth from './commands/auth.js';
+import * as envCmd_ from './commands/env.js';
+import { ENV_NAMES } from './env.js';
 import * as setup from './commands/setup.js';
 import * as mcp from './commands/mcp.js';
 import * as runCmd from './commands/run.js';
@@ -15,6 +17,7 @@ import * as regions from './commands/regions.js';
 import * as secretsCmd from './commands/secrets.js';
 import { deploy } from './commands/deploy.js';
 import * as computeCmd from './commands/compute.js';
+import * as dbCmd from './commands/db.js';
 import { manifest } from './commands/manifest.js';
 import * as govern from './commands/govern.js';
 import * as observe from './commands/observe.js';
@@ -56,9 +59,16 @@ program.command('login').description('Log in with email + password, or --oauth <
     .option('--password <password>', 'account password (else $INSTA_PASSWORD or prompt)')
     .option('--oauth <provider>', 'browser OAuth login: github | google')
     .option('--api-url <url>', 'control-plane API base URL')
+    .option('--env <name>', `deployment environment: ${ENV_NAMES.join(' | ')}`)
     .action(guard((o) => auth.login(o)));
 program.command('logout').description('Log out and clear local tokens').action(guard(() => auth.logout()));
 program.command('status').description('Show login + linked project').option('--json').action(guard((o) => auth.status(o)));
+// ---- environment (prod | staging) ----
+const envCmd = program.command('env').description('Show or switch the deployment environment (prod | staging)');
+envCmd.command('show', { isDefault: true }).description('Show the current environment and its hosts')
+    .option('--json').action(guard((o) => envCmd_.envShow(o)));
+envCmd.command('use <name>').description(`Switch environment (${ENV_NAMES.join(' | ')}) — drops the stored session, which is deployment-specific`)
+    .action(guard((name) => envCmd_.envUse(name)));
 // ---- run (per-request secret injection — nothing written to disk) ----
 program.command('run <cmd> [args...]').description('Run a command with the branch credential bundle injected into its environment (no .env written)')
     .option('--branch <b>', 'branch bundle to inject (default: linked branch)')
@@ -102,6 +112,7 @@ svc.command('add <type> <name>').description('Provision a service on demand (ass
     .option('--public', 'storage only: serve the bucket with anonymous public-read (default private)')
     .option('--image <url>', 'compute only: run this container image at creation')
     .option('--port <n>', 'compute only: port the image listens on (default 8080)')
+    .option('--always-on', 'compute only: create as always-on — never scales to zero (all plans; billing is actual usage either way)')
     .action(guard((type, name, o) => services.servicesAdd(type, name, o)));
 svc.command('list').option('--json').option('--branch <branch>', 'branch (default: current)')
     .action(guard((o) => services.servicesList(o)));
@@ -152,6 +163,13 @@ compute.command('suspend [service]').description('Suspend a compute service (RAM
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((service, o) => computeCmd.computeSuspend(service, o)));
 compute.command('status [service]').description("Show a compute service's desired vs. live state")
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((service, o) => computeCmd.computeStatus(service, o)));
+compute.command('always-on <mode> [service]').description('Set a compute service always-on (mode: on|off). on = machines never scale to zero; off = default scale-to-zero. All plans; billing is actual usage either way')
+    .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((mode, service, o) => computeCmd.computeAlwaysOn(mode, service, o)));
+// ---- db (postgres service controls) ----
+const db = program.command('db').description('Postgres service controls (always-on / scale-to-zero)');
+db.command('always-on <mode>').description('Set a postgres service always-on (mode: on|off). on = instance stays warm, no cold starts; off = default scale-to-zero (idle instance suspends; first connection cold-starts). insta-db-backed services only')
+    .option('--json').option('--branch <branch>', 'branch (default: current)').option('--group <g>', 'postgres service name (default: the sole/default one)')
+    .action(guard((mode, o) => dbCmd.dbAlwaysOn(mode, o)));
 // ---- manifest ----
 program.command('manifest').description('Print an agent-legible view of the project environments').option('--json').action(guard((o) => manifest(o)));
 // ---- regions ----
@@ -160,8 +178,8 @@ program.command('regions').description('List regions available for postgres/comp
 program.command('metrics <target> [group]').description('Service metrics (target: db|compute)')
     .option('--branch <b>').option('--from <unix>').option('--to <unix>').option('--step <s>').option('--json')
     .action(guard((target, group, o) => obs.metrics(target, group, o)));
-program.command('logs <target> [group]').description('Service runtime logs (target: db|compute)')
-    .option('--branch <b>').option('--limit <n>').option('--region <r>').option('--instance <i>').option('--json')
+program.command('logs <target> [group]').description('Service logs (runtime by default; --deploy = compute deploy events; target: db|compute)')
+    .option('--branch <b>').option('--limit <n>').option('--region <r>').option('--instance <i>').option('--deploy', 'show compute deploy events (machine lifecycle) instead of runtime logs').option('--json')
     .action(guard((target, group, o) => obs.logs(target, group, o)));
 program.command('usage').description('Usage for the current billing cycle by billing dimension (org by default; --proj for one project)')
     .option('--from <unix>').option('--to <unix>').option('--proj [id]', 'show one project (the linked one, or a given id) instead of the whole org').option('--json')

package/dist/observe/install.js

@@ -58,8 +58,11 @@ function claudeEntry() {
     // Claude Code executes `command` as ONE shell string with $CLAUDE_PROJECT_DIR in the env —
     // there is no `args` field in its hooks schema, so a ${…} template in args reaches node
     // verbatim and throws MODULE_NOT_FOUND after every tool call.
+    // .claude/settings.json is often committed while ./.insta stays local-only, so a fresh
+    // clone (cloud session, teammate) gets the hook without the script — no-op there.
+    const hook = '"$CLAUDE_PROJECT_DIR/.insta/observe/hook.js"';
     return { matcher: '*', hooks: [{ type: 'command',
-                command: 'node "$CLAUDE_PROJECT_DIR/.insta/observe/hook.js"', timeout: 15, _insta: MARKER }] };
+                command: `[ ! -f ${hook} ] || node ${hook}`, timeout: 15, _insta: MARKER }] };
 }
 function codexEntry(cwd) {
     const abs = join(cwd, '.insta', 'observe', 'hook.js'); // Codex doesn't expand ${CLAUDE_PROJECT_DIR}; use an absolute path

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "insta",
-  "version": "0.0.22",
+  "version": "0.0.24",
   "type": "module",
-  "description": "InstaCloud CLI \u2014 a thin client of the platform control-plane API.",
+  "description": "InstaCloud CLI — a thin client of the platform control-plane API.",
   "keywords": [
     "insta",
     "insforge",