insta 0.0.36 → 0.0.38

package/README.md

@@ -26,14 +26,33 @@ npm install -g insta
 ```
 
 For coding agents. Installs the CLI, the `insta` skill for every agent on the machine, and
-registers the MCP server:
+registers the MCP server — one command for macOS, Linux, WSL, and native Windows shells
+(PowerShell/cmd). Needs Node 18+ with a writable npm global prefix (a Node version manager
+qualifies; if the global install can't write, setup continues and prints the exact
+version-pinned `npm install -g` fallback to run yourself). E2e-validated on macOS, Linux,
+and Windows (PowerShell + cmd):
 
 ```bash
-curl -fsSL agents.instacloud.com | sh
+npx -y insta setup agent
+```
+
+This command means **production** (CLI ≥ 0.0.38): if the machine was previously switched to
+staging it switches back — announced, session dropped, like `insta env use prod`. Staging is
+its own explicit command, which also persists the choice:
+
+```bash
+npx -y insta setup agent --env staging
 ```
 
-On Windows, download `insta-windows-x64.exe` from the
-[releases page](https://github.com/InsForge/insta-cli/releases).
+On macOS/Linux without Node, the native-binary installer puts the `insta` CLI on PATH (the
+skill + MCP steps it then runs still need Node — the skills tool runs via npx). Never run it
+on native Windows — PowerShell's `curl` alias and the WSL `bash` shim break it; use npx
+above, or download `insta-windows-x64.exe` from the
+[releases page](https://github.com/InsForge/insta-cli/releases):
+
+```bash
+curl -fsSL agents.instacloud.com | sh
+```
 
 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
@@ -101,7 +120,8 @@ prints an approval id for an admin to grant with `insta approvals approve <id>`.
 
 `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.
+agents on the machine — and, when running from the npx cache with no durable `insta` on
+PATH, first installs the CLI itself globally.
 
 ## Environments
 
@@ -167,7 +187,7 @@ build never reaches a production installer.
 |---|---|
 | `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 setup` | `agent` — install the CLI (if missing), the skill, and MCP for every coding agent; targets prod, `--env staging` for staging |
 | `insta mcp` | `install` — register the remote MCP server only |
 | `insta org` | `list` · `create` (one free org per user) |
 | `insta project` | `create` · `list` · `link` · `delete` |

package/dist/api.js

@@ -2,7 +2,7 @@
 // 2xx (including 202 approval_required) returns the parsed body; >=400 throws ApiError.
 import { readGlobal, writeGlobal, readProject, writeProject } from './config.js';
 import { autoResolveProject, promptChoice } from './resolve-project.js';
-import { die, info } from './util.js';
+import { die } from './util.js';
 export class ApiError extends Error {
     status;
     constructor(status, msg) {
@@ -117,7 +117,9 @@ export async function requireProject() {
             promptChoice,
             save: async (c) => {
                 await writeProject(c);
-                info(`auto-linked project ${c.projectId} → ./.insta/project.json`);
+                // stderr: this is a diagnostic that can precede ANY command's output — under --json,
+                // stdout must stay one parseable document.
+                process.stderr.write(`auto-linked project ${c.projectId} → ./.insta/project.json\n`);
             },
             tty: !!process.stdin.isTTY && !!process.stderr.isTTY,
         });

package/dist/commands/branch.js

@@ -5,6 +5,8 @@ export async function branchCreate(name, opts) {
     const api = await ApiClient.load();
     const p = await requireProject();
     const out = await api.request('POST', `/projects/${p.projectId}/branches`, { name, from: opts.from ?? p.branch });
+    if (opts.json)
+        return printJson(out);
     info(`created branch ${out.branch.name} (${out.branch.id})`);
     renderNextActions(out.nextActions);
 }
@@ -17,16 +19,18 @@ export async function branchList(opts) {
     for (const b of branches)
         info(`${b.is_default ? '*' : ' '} ${b.name}  [${b.status}]  ${b.id}`);
 }
-export async function branchSwitch(name) {
+export async function branchSwitch(name, opts = {}) {
     const api = await ApiClient.load();
     const p = await requireProject();
     const { branches } = await api.request('GET', `/projects/${p.projectId}/branches`);
     if (!branches.some((b) => b.name === name))
         die(`branch not found: ${name}`);
     await writeProject({ ...p, branch: name });
+    if (opts.json)
+        return printJson({ projectId: p.projectId, branch: name });
     info(`switched to branch ${name} — run \`insta secrets\` to refresh .env`);
 }
-export async function branchDelete(name) {
+export async function branchDelete(name, opts = {}) {
     const api = await ApiClient.load();
     const p = await requireProject();
     const { branches } = await api.request('GET', `/projects/${p.projectId}/branches`);
@@ -34,8 +38,10 @@ export async function branchDelete(name) {
     if (!b)
         die(`branch not found: ${name}`);
     const res = await api.rawRequest('DELETE', `/projects/${p.projectId}/branches/${b.id}`);
-    if (handleApproval(res))
+    if (handleApproval(res, opts.json))
         return;
+    if (opts.json)
+        return printJson({ ok: true, branch: { id: b.id, name: b.name } });
     info(`deleted branch ${name}`);
 }
 // insta branch merge <source> [--into <target>] — structurally merge source's services into target
@@ -47,8 +53,10 @@ export async function branchMerge(source, opts = {}) {
     if (!target)
         throw new Error('no target branch — pass --into <branch> (or link a branch first)');
     const res = await api.rawRequest('POST', `/projects/${p.projectId}/branches/${encodeURIComponent(target)}/merge`, { from: source });
-    if (handleApproval(res))
+    if (handleApproval(res, opts.json))
         return;
+    if (opts.json)
+        return printJson(res.body ?? {});
     const { created = [], skipped = [] } = (res.body ?? {});
     info(`merged ${source} → ${target}: ${created.length} created, ${skipped.length} skipped`);
     for (const c of created)

package/dist/commands/compute.js

@@ -7,7 +7,7 @@ export async function setDomain(host, opts) {
     const api = await ApiClient.load();
     const p = await requireProject();
     const res = await api.rawRequest('POST', `/projects/${p.projectId}/compute/domain`, { hostname: host, branch: opts.branch ?? p.branch, group: opts.group });
-    if (handleApproval(res))
+    if (handleApproval(res, opts.json))
         return;
     printDomain(res.body, opts.json);
 }
@@ -26,9 +26,16 @@ export async function removeDomain(host, opts) {
     const api = await ApiClient.load();
     const p = await requireProject();
     const res = await api.rawRequest('DELETE', `/projects/${p.projectId}/compute/domain`, { hostname: host, branch: opts.branch ?? p.branch, group: opts.group });
-    if (handleApproval(res))
+    if (handleApproval(res, opts.json))
         return;
-    info(`removed custom domain ${res.body.hostname} from ${res.body.flyApp}`);
+    renderRemoveDomain(res.body, opts.json);
+}
+// Split out (same pattern as applyExecResult) so the --json contract — stdout carries the platform
+// response, never prose — is unit-testable without a network mock.
+export function renderRemoveDomain(body, json) {
+    if (json)
+        return printJson(body);
+    info(`removed custom domain ${body.hostname} from ${body.flyApp}`);
 }
 function printDomain(r, json) {
     if (json)
@@ -50,7 +57,7 @@ async function lifecycle(verb, serviceName, opts) {
     const { services } = await api.request('GET', `/projects/${p.projectId}/services${q(branch)}`);
     const id = resolveComputeServiceId(services, serviceName);
     const res = await api.rawRequest('POST', `/projects/${p.projectId}/services/${id}/${verb}`);
-    if (handleApproval(res))
+    if (handleApproval(res, opts.json))
         return;
     if (opts.json)
         return printJson(res.body);
@@ -107,19 +114,13 @@ export function execRequestBody(command, timeoutSec) {
 // of (res, json) so it's unit-testable without a network mock, same as handleApproval's own
 // {status, body} shape.
 //
-// A 202 means the command has NOT run: unlike every other gated command (where "nothing happened"
-// is the safe default), a caller chaining `insta compute exec … && next` must not see exit 0 here,
-// or `next` runs believing the command succeeded. --json prints the raw envelope (so a scripted
-// caller can inspect approvalId/action) instead of the human hint; either way exit 1.
+// A 202 means the command has NOT run: handleApproval owns the whole contract (hint on stderr,
+// raw envelope on stdout with --json, exit 2), so a caller chaining `insta compute exec … && next`
+// can never mistake a pending gate for the command having succeeded — and exit 2 stays
+// distinguishable from the remote command's own exit 1.
 export function applyExecResult(res, json) {
-    if (res.status === 202 && res.body?.status === 'approval_required') {
-        if (json)
-            printJson(res.body);
-        else
-            handleApproval(res);
-        process.exitCode = 1;
+    if (handleApproval(res, json))
         return;
-    }
     const { exitCode, stdout, stderr, truncated } = res.body;
     if (json) {
         printJson(res.body);
@@ -170,7 +171,7 @@ export async function computeAlwaysOn(mode, serviceName, opts) {
     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))
+    if (handleApproval(res, opts.json))
         return;
     if (opts.json)
         return printJson(res.body);
@@ -271,7 +272,7 @@ export async function computeVolume(serviceName, opts) {
         catch (e) {
             throw volumeDeleteError(e);
         }
-        if (handleApproval(res))
+        if (handleApproval(res, opts.json))
             return;
         if (opts.json)
             return printJson(res.body);
@@ -288,7 +289,7 @@ export async function computeVolume(serviceName, opts) {
     }
     const sizeGib = parseVolumeGib(opts.size);
     const res = await api.rawRequest('PUT', `/projects/${p.projectId}/services/${id}/volume`, { sizeGib });
-    if (handleApproval(res))
+    if (handleApproval(res, opts.json))
         return;
     if (opts.json)
         return printJson(res.body);
@@ -317,7 +318,7 @@ export async function computeLimits(serviceName, opts) {
     if (opts.cpu)
         body.cpu = parseCpu(opts.cpu);
     const res = await api.rawRequest('PUT', `/projects/${p.projectId}/services/${id}/limits`, body);
-    if (handleApproval(res))
+    if (handleApproval(res, opts.json))
         return;
     if (opts.json)
         return printJson(res.body);

package/dist/commands/db.js

@@ -19,7 +19,7 @@ export async function dbAlwaysOn(mode, opts) {
     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))
+    if (handleApproval(res, opts.json))
         return;
     if (opts.json)
         return printJson(res.body);
@@ -111,7 +111,7 @@ export async function dbLimits(opts) {
             throw new Error(`setting the ceiling failed (${e.status}): ${e.message}`);
         throw e;
     }
-    if (handleApproval(res))
+    if (handleApproval(res, opts.json))
         return;
     if (opts.json)
         return printJson(res.body);
@@ -230,7 +230,7 @@ export async function dbVolume(opts) {
             throw new Error(`growing the volume failed (${e.status}): ${e.message}`);
         throw e;
     }
-    if (handleApproval(res))
+    if (handleApproval(res, opts.json))
         return;
     if (opts.json)
         return printJson(res.body);

package/dist/commands/deploy.js

@@ -1,8 +1,11 @@
 import { resolve, join } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { ApiClient, ApiError, requireProject } from '../api.js';
-import { info, die, handleApproval, renderNextActions } from '../util.js';
-import { flyctlBuildAndPush, ensureFlyctl, defaultBuildRunner } from '../flyctl-build.js';
+import { info, die, printJson, handleApproval, renderNextActions } from '../util.js';
+import { flyctlBuildAndPush, ensureFlyctl, defaultBuildRunner, stderrBuildRunner } from '../flyctl-build.js';
+// With --json, stdout must carry exactly one JSON document (the deploy result), so every progress
+// line moves to stderr.
+const note = (opts) => (opts.json ? (m) => void process.stderr.write(m + '\n') : info);
 // Map CLI options to the platform deploy request body. Pure, so it's unit-tested. --websocket is only
 // sent when set (plain deploys unchanged).
 export function deployRequestBody(image, branch, opts) {
@@ -36,20 +39,23 @@ export async function deploy(dir, opts) {
     const api = await ApiClient.load();
     const p = await requireProject();
     const branch = opts.branch ?? p.branch;
+    const log = note(opts);
     let port = opts.port ? Number(opts.port) : undefined;
     if (dir && port === undefined) {
         const dockerfile = join(resolve(process.cwd(), dir), 'Dockerfile');
         const exposed = existsSync(dockerfile) ? dockerfileExposedPort(readFileSync(dockerfile, 'utf8')) : undefined;
         if (exposed) {
             port = exposed;
-            info(`using port ${exposed} (Dockerfile EXPOSE) — override with --port`);
+            log(`using port ${exposed} (Dockerfile EXPOSE) — override with --port`);
         }
     }
     const effOpts = { ...opts, port: port?.toString() };
     const image = dir ? await buildFromSource(api, p.projectId, dir, branch, effOpts) : opts.image;
     const res = await api.rawRequest('POST', `/projects/${p.projectId}/deploy`, deployRequestBody(image, branch, effOpts));
-    if (handleApproval(res))
+    if (handleApproval(res, opts.json))
         return;
+    if (opts.json)
+        return printJson({ image, ...res.body });
     info(`deployed ${image} -> ${res.body.url} (branch ${res.body.branch}, group ${res.body.group})`);
     renderNextActions(res.body.nextActions);
 }
@@ -71,10 +77,11 @@ export async function dockerBuildLocal(absDir, tag, run = defaultBuildRunner) {
 // Dockerfile) with flyctl's remote builder, returning the pushed image ref to deploy. Against a
 // local daemon (insta-oss) the token mint answers 501 — build with docker instead, same contract.
 // Exported with injectable pieces for tests (the repo's DI pattern; no global mocks).
-export async function buildFromSource(api, projectId, dir, branch, opts, run = defaultBuildRunner) {
+export async function buildFromSource(api, projectId, dir, branch, opts, run = opts.json ? stderrBuildRunner : defaultBuildRunner) {
     const absDir = resolve(process.cwd(), dir);
     if (!existsSync(join(absDir, 'Dockerfile')))
         die(`no Dockerfile at ${join(absDir, 'Dockerfile')} — add one, or use --image <url>`);
+    const log = note(opts);
     let tok;
     try {
         tok = await api.rawRequest('POST', `/projects/${projectId}/deploy-token`, { branch, group: opts.group });
@@ -85,19 +92,20 @@ export async function buildFromSource(api, projectId, dir, branch, opts, run = d
         if (!(e instanceof ApiError) || e.status !== 501)
             throw e;
         const tag = localImageTag(projectId, opts.group);
-        info(`no remote builder on this daemon — building ${dir} locally with docker…`);
+        log(`no remote builder on this daemon — building ${dir} locally with docker…`);
         const built = await dockerBuildLocal(absDir, tag, run);
-        info(`  built ${built}`);
+        log(`  built ${built}`);
         return built;
     }
-    if (handleApproval(tok))
-        die('deploy requires approval — get it approved, then re-run');
+    // exit() with no argument honors the exit code handleApproval just set (2).
+    if (handleApproval(tok, opts.json))
+        process.exit();
     const { token, flyApp } = tok.body;
     await ensureFlyctl(); // cloud path only — the local path needs docker, which the daemon requires anyway
     const port = opts.port ? Number(opts.port) : 8080;
-    info(`building ${dir} for ${flyApp} (remote builder)…`);
+    log(`building ${dir} for ${flyApp} (remote builder)…`);
     const { imageRef } = await flyctlBuildAndPush({ dir: absDir, flyApp, imageLabel: `insta-${Date.now()}`, token, port }, run);
-    info(`  pushed ${imageRef}`);
+    log(`  pushed ${imageRef}`);
     return imageRef;
 }
 //# sourceMappingURL=deploy.js.map

package/dist/commands/env.js

@@ -20,7 +20,20 @@ export async function envShow(opts) {
     if (!env)
         info('  (custom apiUrl — `insta env use <name>` to switch to a named environment)');
 }
-export async function envUse(name) {
+// One stable schema for BOTH envUse outcomes (no-op and real switch), so a scripted caller can key
+// on any field — mcpServer, previous — without probing which branch ran. Pure, unit-tested.
+export function envUseResult(target, previous, changed, sessionDropped) {
+    return {
+        env: target,
+        previous,
+        apiUrl: ENVS[target].api,
+        mcpUrl: ENVS[target].mcp,
+        mcpServer: mcpServerName(target),
+        changed,
+        sessionDropped,
+    };
+}
+export async function envUse(name, opts = {}) {
     const want = name.trim().toLowerCase();
     if (!isEnvName(want))
         die(`unknown environment "${name}" — expected one of: ${ENV_NAMES.join(', ')}`);
@@ -33,6 +46,8 @@ export async function envUse(name) {
     // 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)) {
+        if (opts.json)
+            return printJson(envUseResult(target, from ?? target, false, false));
         info(`already on ${target} (${nextApi})`);
         return;
     }
@@ -49,6 +64,8 @@ export async function envUse(name) {
     delete next.refreshToken;
     delete next.user;
     await writeGlobal(next);
+    if (opts.json)
+        return printJson(envUseResult(target, from ?? null, true, hadSession));
     info(`switched ${from ?? '(custom)'} → ${target}`);
     info(`  api: ${nextApi}`);
     info(`  mcp: ${ENVS[target].mcp} (registers as \`${mcpServerName(target)}\`)`);
@@ -56,8 +73,8 @@ export async function envUse(name) {
         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');
+    // they keep talking to it until setup is re-run. --env is REQUIRED in the hint: since 0.0.38 a
+    // bare `setup agent` forces prod, which would silently undo the switch the user just made.
+    info(`  re-point this machine's agents at it with: insta setup agent --env ${target}`);
 }
 //# sourceMappingURL=env.js.map

package/dist/commands/feedback.js

@@ -37,7 +37,10 @@ export const LIMITS = {
 const FEEDBACK_ENDPOINT = process.env.INSTA_FEEDBACK_URL ||
     'https://feedback.instacloud.com/v1/feedback';
 const FEEDBACK_INGEST_TOKEN = process.env.INSTA_FEEDBACK_TOKEN || 'insta-feedback-public-v1';
-const FEEDBACK_TIMEOUT_MS = 10_000;
+// 15s gives the backend's scale-to-zero cold start room to answer (the ingest service waits out
+// the DB wake and persists, so a report can land after the old 10s deadline gave up on it).
+// An expired deadline is reported as UNCONFIRMED, not failed — the report may well be stored.
+const FEEDBACK_TIMEOUT_MS = 15_000;
 const MAX_FILE_BYTES = 256 * 1024;
 function resolveCliVersion() {
     // Same resolution as index.ts: the standalone binary bakes INSTA_CLI_VERSION via --define;
@@ -178,8 +181,10 @@ export async function submit(payload, fetchImpl) {
         });
     }
     catch (e) {
-        const timedOut = e instanceof Error && e.name === 'TimeoutError';
-        return { status: 'error', error: timedOut ? `timed out after ${FEEDBACK_TIMEOUT_MS / 1000}s` : `network error: ${e instanceof Error ? e.message : String(e)}` };
+        if (e instanceof Error && e.name === 'TimeoutError') {
+            return { status: 'unconfirmed', error: `no response after ${FEEDBACK_TIMEOUT_MS / 1000}s — the report may have been recorded anyway` };
+        }
+        return { status: 'error', error: `network error: ${e instanceof Error ? e.message : String(e)}` };
     }
     let body = {};
     try {
@@ -211,6 +216,14 @@ export async function feedback(opts, deps = {}) {
         return;
     }
     const result = await submit(payload, deps.fetchImpl ?? fetch);
+    if (result.status === 'unconfirmed') {
+        // NOT a failure claim: the request was still in flight at the deadline and the server
+        // finishes what it started, so saying "not submitted" here would be a false negative.
+        if (opts.json)
+            return printJson({ status: 'unconfirmed', error: result.error });
+        process.stderr.write(`warning: feedback receipt unconfirmed (${result.error}) — continue with your task, do not retry\n`);
+        return;
+    }
     if (result.status === 'error') {
         // Deliberate exit 0: an agent CANNOT fix a down/rate-limited backend, and feedback must never
         // fail or distract from the task the user actually asked for. Do not retry.

package/dist/commands/govern.js

@@ -29,12 +29,16 @@ export async function approvalsApprove(id, opts) {
     const api = await ApiClient.load();
     const p = await requireProject();
     const out = await api.request('POST', `/projects/${p.projectId}/approvals/${id}/approve`, { always: !!opts.always });
+    if (opts.json)
+        return printJson(out);
     info(`approved ${out.approval.action} (${id})${opts.always ? ' — policy set to allow' : ''}`);
 }
-export async function approvalsDeny(id) {
+export async function approvalsDeny(id, opts = {}) {
     const api = await ApiClient.load();
     const p = await requireProject();
     const out = await api.request('POST', `/projects/${p.projectId}/approvals/${id}/deny`);
+    if (opts.json)
+        return printJson(out);
     info(`denied ${out.approval.action} (${id})`);
 }
 export async function policyGet(opts) {
@@ -46,10 +50,12 @@ export async function policyGet(opts) {
     for (const [action, decision] of Object.entries(policy))
         info(`${action}: ${decision}`);
 }
-export async function policySet(action, decision) {
+export async function policySet(action, decision, opts = {}) {
     const api = await ApiClient.load();
     const p = await requireProject();
-    await api.request('PUT', `/projects/${p.projectId}/policy/${action}`, { decision });
+    const out = await api.request('PUT', `/projects/${p.projectId}/policy/${action}`, { decision });
+    if (opts.json)
+        return printJson({ action, decision, ...(out ?? {}) });
     info(`policy ${action} = ${decision}`);
 }
 //# sourceMappingURL=govern.js.map

package/dist/commands/metrics.js

@@ -140,8 +140,42 @@ export function deployEventLine(ev) {
     const inst = ev.instance ? `  (${ev.instance})` : '';
     return `${ev.ts ?? ''}  [${ev.origin ?? ''}] ${ev.type ?? ''}: ${ev.status ?? ''}${inst}`;
 }
+// A log-window instant from the CLI: unix seconds (all digits) or anything Date.parse reads
+// (ISO-8601 etc.). Throws on junk — a mistyped instant must fail here, not become NaN on the wire.
+export function parseLogInstant(raw, flag) {
+    if (/^\d+$/.test(raw))
+        return Number(raw);
+    const ms = Date.parse(raw);
+    if (Number.isNaN(ms))
+        throw new Error(`invalid ${flag}: ${raw} (unix seconds or an ISO-8601 date)`);
+    return Math.floor(ms / 1000);
+}
+// '90s' | '30m' | '2h' | '1d' → seconds. Throws on junk, zero, and unknown units.
+export function parseSinceSeconds(raw) {
+    const m = /^(\d+)([smhd])$/.exec(raw.trim());
+    if (!m)
+        throw new Error(`invalid --since: ${raw} (e.g. 90s, 30m, 2h, 1d)`);
+    const n = Number(m[1]);
+    if (n === 0)
+        throw new Error(`invalid --since: ${raw} (must be > 0)`);
+    return n * { s: 1, m: 60, h: 3600, d: 86400 }[m[2]];
+}
+// The from/to pair for the logs request, from whichever window flags were given. Pure, unit-tested.
+export function resolveLogWindow(opts, now = Math.floor(Date.now() / 1000)) {
+    if (opts.since && opts.from)
+        throw new Error('pass --since or --from, not both');
+    const from = opts.since ? now - parseSinceSeconds(opts.since) : opts.from !== undefined ? parseLogInstant(opts.from, '--from') : undefined;
+    const to = opts.to !== undefined ? parseLogInstant(opts.to, '--to') : undefined;
+    if (from !== undefined && to !== undefined && to < from)
+        throw new Error('--to is before --from');
+    return { from, to };
+}
 // insta logs <db|compute|redis|mysql|mongodb> [group]
 export async function logs(component, group, opts) {
+    const windowFlags = opts.from !== undefined || opts.to !== undefined || opts.since !== undefined;
+    if (opts.deploy && windowFlags)
+        throw new Error('--from/--to/--since apply to runtime logs, not --deploy events');
+    const { from, to } = resolveLogWindow(opts);
     const api = await ApiClient.load();
     const p = await requireProject();
     if (opts.deploy) {
@@ -159,7 +193,7 @@ export async function logs(component, group, opts) {
             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 })}`);
+    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, from: from !== undefined ? String(from) : undefined, to: to !== undefined ? String(to) : undefined })}`);
     if (opts.json)
         return printJson(res);
     if (res.note)

package/dist/commands/org.js

@@ -8,9 +8,11 @@ export async function orgList(opts) {
     for (const o of orgs)
         info(`${o.id}  ${o.name}${o.is_personal ? ' (personal)' : ''}  [${o.role}]`);
 }
-export async function orgCreate(name) {
+export async function orgCreate(name, opts = {}) {
     const api = await ApiClient.load();
     const { org } = await api.request('POST', '/orgs', { name });
+    if (opts.json)
+        return printJson(org);
     info(`created org ${org.id} (${org.name})`);
 }
 //# sourceMappingURL=org.js.map

package/dist/commands/project.js

@@ -13,14 +13,19 @@ const GENERIC_DIRS = new Set([
     'app', 'apps', 'users', 'user', 'bin', 'new', 'test', 'tests',
 ]);
 // Best-effort: wire the credential-audit hook into the project (no-op if assets aren't built).
-function tryInstallObserve() {
+// quiet: with --json the install still runs, but its note moves to stderr (stdout is JSON-only).
+function tryInstallObserve(quiet = false) {
     try {
         const r = installObserve({ cwd: process.cwd() });
-        if (r.claude || r.codex)
-            info('  installed observe hook (credential audit) → ./.insta/observe');
+        if (r.claude || r.codex) {
+            const line = '  installed observe hook (credential audit) → ./.insta/observe';
+            quiet ? process.stderr.write(line + '\n') : info(line);
+        }
     }
     catch { /* assets missing (dev/unbuilt) — skip silently */ }
 }
+// installSkills prints to stdout by default; with --json its notes go to stderr instead.
+const skillsPrint = (json) => (json ? (s) => void process.stderr.write(s + '\n') : undefined);
 async function resolveOrg(api, given) {
     if (given)
         return given;
@@ -51,7 +56,10 @@ export async function projectCreate(name, opts) {
     const resolved = resolveProjectName(name, process.cwd());
     if (!resolved) {
         // No name given and the cwd name is generic — don't provision resources under a junk name.
-        // Guide instead (no hang, no error): name it explicitly, or just ask the skill-equipped agent.
+        // A terminal gets guidance (no hang, no error); --json is a scripted caller with no human to
+        // guide, so it gets a hard error instead of an empty success.
+        if (opts.json)
+            die('no project name — pass one: insta project create <name>');
         info('name your project:  insta project create <name>');
         info('  (or just ask your coding agent — it has the insta skill and will do this for you)');
         return;
@@ -60,12 +68,17 @@ export async function projectCreate(name, opts) {
     const orgId = await resolveOrg(api, opts.org);
     const out = await api.request('POST', `/orgs/${orgId}/projects`, { name: resolved });
     await writeProject({ projectId: out.project.id, orgId, branch: out.defaultBranch.name });
-    info(`created project ${out.project.id} (${resolved})`);
-    info(`  resources: ${out.resources.map((r) => r.kind).join(', ')}`);
-    info(`  linked ./.insta/project.json (branch ${out.defaultBranch.name})`);
-    renderNextActions(out.nextActions);
-    tryInstallObserve();
-    await installSkills({ cwd: process.cwd() });
+    if (opts.json) {
+        printJson({ ...out, linked: { projectId: out.project.id, orgId, branch: out.defaultBranch.name } });
+    }
+    else {
+        info(`created project ${out.project.id} (${resolved})`);
+        info(`  resources: ${out.resources.map((r) => r.kind).join(', ')}`);
+        info(`  linked ./.insta/project.json (branch ${out.defaultBranch.name})`);
+        renderNextActions(out.nextActions);
+    }
+    tryInstallObserve(opts.json);
+    await installSkills({ cwd: process.cwd(), print: skillsPrint(opts.json) });
 }
 export async function projectList(opts) {
     const api = await ApiClient.load();
@@ -78,20 +91,25 @@ export async function projectList(opts) {
     for (const p of projects)
         info(`${p.id}  ${p.name}  [${p.status}]`);
 }
-export async function projectLink(id) {
+export async function projectLink(id, opts = {}) {
     const api = await ApiClient.load();
     const { project } = await api.request('GET', `/projects/${id}`);
     await writeProject({ projectId: project.id, orgId: project.org_id, branch: 'main' });
-    info(`linked project ${project.id} (${project.name})`);
-    tryInstallObserve();
-    await installSkills({ cwd: process.cwd() });
+    if (opts.json)
+        printJson({ project, linked: { projectId: project.id, orgId: project.org_id, branch: 'main' } });
+    else
+        info(`linked project ${project.id} (${project.name})`);
+    tryInstallObserve(opts.json);
+    await installSkills({ cwd: process.cwd(), print: skillsPrint(opts.json) });
 }
 export async function projectDelete(opts) {
     const api = await ApiClient.load();
     const projectId = opts.project ?? (await requireProject()).projectId;
     const res = await api.rawRequest('DELETE', `/projects/${projectId}`);
-    if (handleApproval(res))
+    if (handleApproval(res, opts.json))
         return;
+    if (opts.json)
+        return printJson({ ok: true, projectId });
     info(`deleted project ${projectId}`);
 }
 //# sourceMappingURL=project.js.map

package/dist/commands/run.js

@@ -4,7 +4,7 @@
 // as the process does.
 import { spawn } from 'node:child_process';
 import { ApiClient, requireProject } from '../api.js';
-import { die, info } from '../util.js';
+import { die, handleApproval } from '../util.js';
 /** Core, dependency-injected for tests: spawn cmd with the bundle in env, return its exit code. */
 export async function runWithSecrets(cmd, args, deps) {
     const bundle = await deps.fetchBundle();
@@ -28,10 +28,12 @@ export async function run(cmdAndArgs, opts) {
     const code = await runWithSecrets(cmd, rest, {
         fetchBundle: async () => {
             const res = await api.rawRequest('GET', `/projects/${p.projectId}/secrets?branch=${encodeURIComponent(branch)}`);
-            if (res.status === 202) {
-                die(`secrets.read requires approval — run: insta approvals approve ${res.body.approvalId}, then re-run`);
-            }
-            info(`running with ${Object.keys(res.body.secrets).length} injected secrets (branch ${branch}) — nothing written to disk`);
+            // exit() with no argument honors the exit code handleApproval just set (2).
+            if (handleApproval(res))
+                process.exit();
+            // stderr, not stdout: `insta run`'s stdout belongs entirely to the child command (that's why
+            // run has no --json — wrapping would break the child's own output contract).
+            process.stderr.write(`running with ${Object.keys(res.body.secrets).length} injected secrets (branch ${branch}) — nothing written to disk\n`);
             return res.body.secrets;
         },
     });