insta 0.0.22 → 0.0.23-rc.1

package/README.md

@@ -16,6 +16,26 @@ curl -fsSL https://raw.githubusercontent.com/InsForge/insta-cli/main/install.sh
 # Windows: download insta-windows-x64.exe from the releases page.
 ```
 
+**Agent one-liner** (CLI + agent skills + MCP registration, non-interactive):
+
+```bash
+curl -fsSL agents.instacloud.com | sh            # production
+curl -fsSL agents.staging.instacloud.com | sh    # staging
+```
+
+Each installs a complete stack for its environment — CLI build, control plane, MCP registration and
+skill text all match. See [Environments](#environments).
+
+> The staging host serves this repo's `agents-staging.sh` from `main`, so it returns 404 until that
+> file is on `main`. Equivalent, and works regardless:
+>
+> ```bash
+> curl -fsSL https://raw.githubusercontent.com/InsForge/insta-cli/main/install.sh | sh -s -- --agents --staging -y
+> ```
+>
+> If the environment can't be applied (a CLI predating `insta env`), the installer exits non-zero
+> rather than silently leaving you on production.
+
 **Build from source (requires node):**
 
 ```bash
@@ -52,11 +72,48 @@ insta deploy --image <registry/img>  # deploy a container image to the current b
 insta status                         # login state + linked project/branch
 ```
 
+## Environments
+
+`prod` and `staging` are **separate deployments** — different regions, different databases,
+different auth. A session from one cannot authenticate against the other, so switching drops the
+stored session and you log in again.
+
+| | `prod` (default) | `staging` |
+|---|---|---|
+| control plane | `api.instacloud.com` (us-east-2) | `api.staging.instacloud.com` (us-west-1) |
+| MCP server | `mcp.instacloud.com/mcp` | `mcp.staging.instacloud.com/mcp` |
+| registers as | `insta-cloud` | `insta-cloud-staging` |
+| agent skills | `InsForge/insta-skills` | `InsForge/insta-skills@devel` |
+| CLI channel | latest stable release | newest prerelease (`v*-rc.N`), else stable |
+
+```bash
+insta env                      # show the current environment and everything derived from it
+insta env use staging          # switch (persisted to ~/.insta/config.json)
+insta login --env staging --oauth github
+```
+
+Control plane, MCP host **and** skill source are all resolved from one switch, so a machine can
+never end up with its CLI on staging while its agents talk to prod and read prod's skill text.
+Distinct MCP registration names mean both environments can be installed side by side.
+
+Resolution order, most specific first:
+
+1. `INSTA_API_URL` — a literal URL. The only way to reach a host no environment name covers
+   (`insta-oss` on localhost, 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` | `staging`. An unrecognised value is an error, never a silent fallback.
+3. the persisted `apiUrl` in `~/.insta/config.json`.
+4. `prod`.
+
+Prereleases never take the `latest` GitHub release or the `latest` npm dist-tag — they publish with
+`--prerelease` and under npm's `next` tag — so a staging build can't reach production installers.
+
 ## Commands
 
 | Command | Description |
 |------|------|
-| `insta login [--email --password --api-url]` | Log in (email/password; tokens auto-refresh) |
+| `insta login [--email --password --api-url --env]` | Log in (email/password; tokens auto-refresh) |
+| `insta env [--json]` / `insta env use <prod\|staging>` | Show or switch deployment environment |
 | `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) |

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/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/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';
@@ -56,9 +58,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)')
@@ -160,8 +169,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.23-rc.1",
   "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",