insta 0.1.4 → 0.1.6

package/README.md

@@ -214,6 +214,7 @@ build never reaches a production installer.
 |---|---|
 | `insta login` · `logout` · `status` | Browser sign-in (default), `--email` + password, or `--oauth github\|google`; `status` shows the environment, login and linked project/branch |
 | `insta org` | `list` · `create` (one free org per user) |
+| `insta tokens` | API tokens for CI and agents: `list` · `create <name>` · `revoke <id>`. A new token binds to the current org by default (`--org <id>`, `--project <id>`, or an explicit `--account` for everything the account can do); `--read-only` (GET only); `--expires 30d\|90d\|1y\|never` (default 90d). The plaintext is printed once |
 | `insta project` | `create` · `list` · `link` · `delete` |
 | `insta branch` | `create` · `list` · `switch` · `delete` · `merge` |
 | `insta service` (`services`, `svc`) | `add` · `list` · `remove` · `rename` |
@@ -230,7 +231,7 @@ build never reaches a production installer.
 | `insta billing` | Current cycle overview; `subscribe <tier>` · `portal` · `usage` |
 | `insta agent` | `setup` (this machine's coding agents) · `manifest` · `policy …` · `approvals …` · `observe …` · `events` |
 | `insta config` | `install-mcp` · `regions` · `autoupdate` |
-| `insta feedback` | Report an InstaCloud-side hurdle (bug / feature-request / friction) to the team — never for the app you are building; works logged-out |
+| `insta feedback` | Report an InstaCloud-side hurdle (bug / feature-request / friction) to the team — never for the app you are building; on InstaCloud it needs `insta login`, so the team can reply |
 | `insta upgrade` | Update the CLI |
 
 Every command accepts `--api-url <url>` for this invocation only (internal debugging); for `compute exec`, place it before `compute`. `insta --help` documents it.
@@ -239,7 +240,7 @@ Every command accepts `--api-url <url>` for this invocation only (internal debug
 
 | Location | Contents |
 |---|---|
-| `~/.insta/config.json` | API URL, access and refresh tokens, user, auto-update preference |
+| `~/.insta/config.json` | API URL, access and refresh tokens, user, the API token's scope (org/project-bound logins), auto-update preference |
 | `./.insta/project.json` | Project id, org id, current branch |
 | `./.insta/link-plane.json` | The control-plane URL this machine linked against. Gitignored and per machine; a link made against a different control plane is refused rather than reused. The home directory is never a project |
 

package/dist/api.js

@@ -26,7 +26,9 @@ export class AgentApprovalRequired extends Error {
     }
 }
 // Store a durable insta_ key as the credential: set it as the bearer and drop any refresh token (an insta_ key never rotates; a stale one would leak to /auth/refresh on a 401).
-export function storeApiKeyCredential(cfg, token, user, agentCredential = false) {
+// `tokenScope` is the key's binding from /me (spec §6). It belongs to THIS key: a plain key replacing a
+// scoped one must not inherit a binding that would steer project resolution for the wrong credential.
+export function storeApiKeyCredential(cfg, token, user, agentCredential = false, tokenScope) {
     cfg.accessToken = token;
     delete cfg.refreshToken;
     if (user)
@@ -35,6 +37,10 @@ export function storeApiKeyCredential(cfg, token, user, agentCredential = false)
         cfg.agentCredential = true;
     else
         delete cfg.agentCredential;
+    if (tokenScope)
+        cfg.tokenScope = tokenScope;
+    else
+        delete cfg.tokenScope;
 }
 export class ApiClient {
     cfg;
@@ -69,10 +75,11 @@ export class ApiClient {
         if (user)
             this.cfg.user = user;
         delete this.cfg.agentCredential;
+        delete this.cfg.tokenScope;
     }
     // Adopt a durable insta_ key as the credential (non-interactive `login --api-key`).
-    setApiKey(token, user, agentCredential) {
-        storeApiKeyCredential(this.cfg, token, user, agentCredential);
+    setApiKey(token, user, agentCredential, tokenScope) {
+        storeApiKeyCredential(this.cfg, token, user, agentCredential, tokenScope);
     }
     get agentCredential() { return this.cfg.agentCredential === true; }
     clearSession() {
@@ -80,6 +87,7 @@ export class ApiClient {
         delete this.cfg.refreshToken;
         delete this.cfg.user;
         delete this.cfg.agentCredential;
+        delete this.cfg.tokenScope;
     }
     // Returns parsed body for status < 400 (incl. 202); throws ApiError otherwise.
     async request(method, path, body, opts = {}) {
@@ -169,10 +177,7 @@ export async function requireProject(deps = {}) {
     // one-keystroke picker when several) and persist the choice so this happens once per dir.
     const api = await ApiClient.load();
     try {
-        const orgs = (await api.request('GET', '/orgs')).orgs;
-        const orgId = orgs[0]?.id ?? 'local';
-        return await autoResolveProject(orgId, {
-            listProjects: async () => (await api.request('GET', `/orgs/${orgId}/projects`)).projects,
+        return await resolveProjectFromApi(api, {
             promptChoice,
             save: async (c) => {
                 // stderr: this is a diagnostic that can precede ANY command's output — under --json,
@@ -196,4 +201,26 @@ export async function requireProject(deps = {}) {
         die(e instanceof Error ? e.message : String(e));
     }
 }
+// The unlinked resolution given a client — exported, with the client injectable, so the scoped
+// paths are testable over a fake fetch. The stored tokenScope is read FIRST (spec §9.2): a
+// project-scoped key gets 403 token_scope from GET /orgs and has exactly one project anyway, so
+// its link is built from the project itself; an org-scoped key sees exactly one org, so /orgs is
+// skipped for the bound one. No scope (a session, or a key adopted before scopes were recorded)
+// keeps the original path.
+export async function resolveProjectFromApi(api, deps) {
+    const scope = api.config.tokenScope;
+    if (scope?.projectId) {
+        const { project, branches } = await api.request('GET', `/projects/${scope.projectId}`);
+        // The default branch comes from the project detail (Branch.is_default); `main` is only the
+        // fallback an older platform without the list would get, like `project link` assumes.
+        const link = { projectId: project.id, orgId: project.org_id, branch: branches?.find((b) => b.is_default)?.name ?? 'main' };
+        await deps.save(link);
+        return link;
+    }
+    const orgId = scope?.orgId ?? (await api.request('GET', '/orgs')).orgs[0]?.id ?? 'local';
+    return autoResolveProject(orgId, {
+        listProjects: async () => (await api.request('GET', `/orgs/${orgId}/projects`)).projects,
+        ...deps,
+    });
+}
 //# sourceMappingURL=api.js.map

package/dist/commands/auth.js

@@ -2,6 +2,7 @@ import { createServer } from 'node:http';
 import { randomBytes } from 'node:crypto';
 import { ApiClient, ApiError, linkedProject } from '../api.js';
 import { readGlobal, readPersistedGlobal } from '../config.js';
+import { describeTokenScope } from './tokens.js';
 import { agentMode } from '../agent.js';
 import { ENVS, ENV_NAMES, envForApiUrl, isEnvName, normalizeUrl } from '../env.js';
 import { info, die, printJson, promptPassword, openUrl } from '../util.js';
@@ -111,12 +112,38 @@ export async function loginApiKey(key, opts) {
     const user = await applyApiKeyLogin(api, key);
     await api.persist();
     info(`logged in as ${user.email ?? user.id} @ ${api.apiUrl}`);
+    // Say what this credential can reach: a scoped token's 403s later are easier to place.
+    const scope = api.config.tokenScope;
+    if (scope && (scope.scope !== 'account' || scope.access !== 'full'))
+        info(`  token scope: ${describeTokenScope(scope)}`);
 }
-// Verify an insta_ key with a bare /me probe (an agent-minted key cannot enroll a session, and /me says which kind this is), then store it with the user and that kind.
+// The binding /me reports for an insta_ key (`token`, spec §6), validated rather than cast. A shape
+// this CLI does not know is stored as NO scope — account-wide behaviour, which the platform still
+// enforces against, and the guard's token_scope hint covers the surprise — never as a half-parsed one.
+export function parseTokenScope(v) {
+    if (!v || typeof v !== 'object')
+        return undefined;
+    const t = v;
+    if (t.scope !== 'account' && t.scope !== 'org' && t.scope !== 'project')
+        return undefined;
+    if (t.access !== 'full' && t.access !== 'read_only')
+        return undefined;
+    const out = { scope: t.scope, access: t.access };
+    if (typeof t.orgId === 'string' && t.orgId)
+        out.orgId = t.orgId;
+    if (typeof t.projectId === 'string' && t.projectId)
+        out.projectId = t.projectId;
+    if (out.scope !== 'account' && !out.orgId)
+        return undefined;
+    if (out.scope === 'project' && !out.projectId)
+        return undefined;
+    return out;
+}
+// Verify an insta_ key with a bare /me probe (an agent-minted key cannot enroll a session, and /me says which kind this is), then store it with the user, that kind, and the key's scope.
 export async function applyApiKeyLogin(client, key) {
     key = key.trim(); // tolerate a trailing newline / stray whitespace from `--api-key "$(cat token)"`
     if (!key.startsWith('insta_'))
-        throw new Error('--api-key expects an insta_ token (mint one with POST /tokens)');
+        throw new Error('--api-key expects an insta_ token (mint one with `insta tokens create <name>`)');
     client.setApiKey(key);
     let me;
     try {
@@ -129,7 +156,7 @@ export async function applyApiKeyLogin(client, key) {
     }
     if (!me?.user)
         throw new Error('unexpected response while verifying the API key');
-    client.setApiKey(key, me.user, me.agentCredential === true);
+    client.setApiKey(key, me.user, me.agentCredential === true, parseTokenScope(me.token));
     return me.user;
 }
 const sleepSeconds = (s) => new Promise((r) => setTimeout(r, s * 1000));
@@ -381,11 +408,15 @@ export async function status(opts) {
     // 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);
+    const tokenScope = api.config.tokenScope ?? null;
     if (opts.json)
-        return printJson({ env, apiUrl: api.apiUrl, user, project });
+        return printJson({ env, apiUrl: api.apiUrl, user, project, tokenScope });
     info(`env:     ${env ?? '(custom)'}`);
     info(`api:     ${api.apiUrl}`);
     info(`user:    ${user ? (user.email ?? user.id) : '(not logged in)'}`);
+    // Only a scoped insta_ key has one; a session login is the account itself.
+    if (tokenScope)
+        info(`token:   ${describeTokenScope(tokenScope)}`);
     info(`project: ${project ? `${project.projectId} (branch ${project.branch})` : '(none linked)'}`);
 }
 //# sourceMappingURL=auth.js.map

package/dist/commands/env.js

@@ -64,6 +64,7 @@ export async function envUse(name, opts = {}) {
     delete next.refreshToken;
     delete next.user;
     delete next.agentCredential;
+    delete next.tokenScope; // belongs to the dropped key; status must not report a scope while logged out
     await writeGlobal(next);
     if (opts.json)
         return printJson(envUseResult(target, from ?? null, true, hadSession));

package/dist/commands/feedback.js

@@ -5,14 +5,15 @@
 //
 // The backend is InstaCloud dogfooding itself: the "InstaCloud Agent Feedback" project runs the
 // ingest service (InsForge/instacloud-feedback repo) on a postgres + compute pair. It is NOT the
-// control-plane API on purpose — feedback must work logged-out, unlinked, and from insta-oss,
-// and a control-plane outage is exactly when we most want reports to still arrive.
+// control-plane API on purpose — feedback must work unlinked, from insta-oss, and through a
+// control-plane outage, which is exactly when we most want reports to still arrive.
 import { readFileSync, statSync } from 'node:fs';
 import os from 'node:os';
 import * as clack from '@clack/prompts';
+import { ApiClient, ApiError } from '../api.js';
 import { readGlobal, readProject } from '../config.js';
 import { envForApiUrl } from '../env.js';
-import { info, printJson, CliCancel } from '../util.js';
+import { info, printJson, refuse, CliCancel } from '../util.js';
 import { clean } from '../redact.js';
 import { cliVersion } from '../version.js';
 export const TYPES = ['bug', 'feature-request', 'friction', 'other'];
@@ -42,6 +43,8 @@ const FEEDBACK_INGEST_TOKEN = process.env.INSTA_FEEDBACK_TOKEN || 'insta-feedbac
 // the DB wake and persists, so a report can land after a shorter 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;
+// A slow control plane may cost a report its ticket, never the report itself.
+const ASSERTION_TIMEOUT_MS = 5_000;
 const MAX_FILE_BYTES = 256 * 1024;
 function requireEnum(value, allowed, flag) {
     if (!allowed.includes(value)) {
@@ -156,7 +159,7 @@ export async function buildPayload(opts, ctx) {
 /** One POST, one bounded attempt (FEEDBACK_TIMEOUT_MS), zero retries — feedback is a side quest and must never hang the CLI.
  *  Transport and server failures come back as a result, not an exception: the caller downgrades
  *  them to a warning so a broken feedback backend can't fail the user's actual task. */
-export async function submit(payload, fetchImpl) {
+export async function submit(payload, fetchImpl, assertion) {
     let res;
     try {
         res = await fetchImpl(FEEDBACK_ENDPOINT, {
@@ -164,6 +167,7 @@ export async function submit(payload, fetchImpl) {
             headers: {
                 'Content-Type': 'application/json',
                 Authorization: `Bearer ${FEEDBACK_INGEST_TOKEN}`,
+                ...(assertion ? { 'Insta-User-Assertion': assertion } : {}),
             },
             body: JSON.stringify(payload),
             signal: AbortSignal.timeout(FEEDBACK_TIMEOUT_MS),
@@ -184,7 +188,34 @@ export async function submit(payload, fetchImpl) {
         return { status: 'error', error: body?.error ?? `HTTP ${res.status}` };
     return { status: body?.status === 'duplicate' ? 'duplicate' : 'received', id: body?.id ?? null };
 }
+const SIGNED_OUT = 'not signed in to InstaCloud — run `insta login`, then send this again so the team can reply to you';
+const STAGING = 'not accepted from staging — send InstaCloud feedback from production';
+// Exit 2, not the submit path's 0: the caller can act on this one.
+function refuseFeedback(message, json) {
+    if (json)
+        printJson({ status: 'refused', submitted: false, error: message });
+    refuse([`insta feedback: ${message}`]);
+}
+function inputError(e, json) {
+    if (!json)
+        throw e;
+    printJson({ status: 'error', submitted: false, error: e instanceof Error ? e.message : String(e) });
+    process.exitCode = 1;
+}
 export async function feedback(opts, deps = {}) {
+    let api;
+    try {
+        api = deps.api ?? await ApiClient.load();
+    }
+    catch (e) {
+        return inputError(e, opts.json);
+    }
+    const env = envForApiUrl(api.apiUrl);
+    if (env === 'staging')
+        refuseFeedback(STAGING, opts.json);
+    // Before the prompts, so nobody types out a report only to be told to sign in.
+    if (env === 'prod' && !api.config.accessToken)
+        refuseFeedback(SIGNED_OUT, opts.json);
     const interactive = deps.interactive ?? (!opts.json && !!process.stdin.isTTY && !!process.stdout.isTTY);
     const missingRequired = !opts.type || !opts.component || !opts.title || (!opts.detail && !opts.file);
     if (missingRequired && interactive)
@@ -198,13 +229,22 @@ export async function feedback(opts, deps = {}) {
         payload = await buildPayload(opts, { cliVersion: deps.cliVersion ?? cliVersion() });
     }
     catch (e) {
-        if (!opts.json)
-            throw e;
-        printJson({ status: 'error', submitted: false, error: e instanceof Error ? e.message : String(e) });
-        process.exitCode = 1;
-        return;
+        return inputError(e, opts.json);
+    }
+    // Fetched after the prompts: it lives five minutes, and a person can take longer than that to type.
+    let assertion;
+    if (env === 'prod') {
+        try {
+            // Bearer only: agent evidence adds a session round trip the timeout cannot bound, and 401s signing in cannot fix.
+            assertion = (await api.request('GET', '/me/feedback-assertion', undefined, { evidence: false, signal: AbortSignal.timeout(ASSERTION_TIMEOUT_MS) })).token;
+        }
+        catch (e) {
+            if (e instanceof ApiError && e.status === 401)
+                refuseFeedback(SIGNED_OUT, opts.json);
+            process.stderr.write(`warning: could not confirm who you are (${e instanceof Error ? e.message : String(e)}) — sending anyway, but nobody can reply to this report\n`);
+        }
     }
-    const result = await submit(payload, deps.fetchImpl ?? fetch);
+    const result = await submit(payload, deps.fetchImpl ?? fetch, assertion);
     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.

package/dist/commands/tokens.js

@@ -0,0 +1,132 @@
+// `insta tokens` — mint, list and revoke insta_ API tokens (spec 2026-09-23-scoped-api-tokens §9).
+// A new token binds to an org (or a project) by default; account-wide is an EXPLICIT --account,
+// mirroring the platform rule that "no org" has to be said out loud. The plaintext is printed once.
+import { ApiClient, linkedProject } from '../api.js';
+import { die, info, printJson } from '../util.js';
+const loadApi = async (deps) => deps.api ?? ApiClient.load();
+/** `--expires` → `expiresInDays`: `<n>d` → n, `<n>y` → n×365, 'never' (or absent) → undefined, i.e.
+ *  the field is not sent. 30d / 90d / 1y are the documented presets; any positive `<n>d` / `<n>y` is
+ *  accepted because the platform takes any day count (it caps at its own maximum). Anything else is
+ *  a usage error, raised before any request is made. */
+export function parseExpires(v) {
+    if (v === undefined)
+        return undefined;
+    const s = v.trim().toLowerCase();
+    if (s === 'never')
+        return undefined;
+    const m = /^(\d+)([dy])$/.exec(s);
+    const n = m ? Number(m[1]) : 0;
+    if (!m || !Number.isSafeInteger(n) || n <= 0)
+        throw new Error(`--expires expects a duration like 30d, 90d, 1y (any <n>d or <n>y) or never, got "${v}"`);
+    return m[2] === 'y' ? n * 365 : n;
+}
+/** One phrase for a credential's reach — the login line, `insta status`, and the token_scope hint. */
+export function describeTokenScope(s) {
+    const ro = s?.access === 'read_only' ? ', read-only' : '';
+    if (!s || s.scope === 'account')
+        return `account-wide${ro}`;
+    if (s.scope === 'project')
+        return `project ${s.projectId} (org ${s.orgId})${ro}`;
+    return `org ${s.orgId}${ro}`;
+}
+/** What the command guard prints for a 403 token_scope: the platform's message verbatim, then ONE
+ *  hint naming the credential this login holds. Deliberately not a permissions message — the user
+ *  IS a member; only the credential is narrow (spec §5.2), and "no permission" sends people off to
+ *  check roles. */
+export function tokenScopeErrorLines(body, scope) {
+    const message = typeof body.message === 'string' && body.message ? body.message : 'refused by the scope of this token';
+    const held = scope ? `this login's token: ${describeTokenScope(scope)}` : 'this login uses a scoped token';
+    return `${message}\n  ${held} — mint a wider one with \`insta tokens create <name> --account\` (from an account login) or run \`insta login\``;
+}
+const id8 = (s) => (s ?? '').slice(0, 8);
+const day = (iso) => (iso ? iso.slice(0, 10) : 'never');
+/** The scope column of `tokens list`: `account`, `org:<id8>`, or `<org id8>/<project id8>`. */
+export function scopeColumn(t) {
+    if (t.scope === 'project')
+        return `${id8(t.orgId)}/${id8(t.projectId)}`;
+    if (t.scope === 'org')
+        return `org:${id8(t.orgId)}`;
+    return 'account';
+}
+const scopeOf = (r) => ({
+    scope: r.scope, access: r.access,
+    ...(r.orgId ? { orgId: r.orgId } : {}),
+    ...(r.projectId ? { projectId: r.projectId } : {}),
+});
+// Column-aligned rows; trailing spaces trimmed so an empty last cell leaves no ragged edge.
+function table(rows) {
+    const widths = rows[0].map((_, i) => Math.max(...rows.map((r) => (r[i] ?? '').length)));
+    return rows.map((r) => r.map((c, i) => (c ?? '').padEnd(widths[i])).join('  ').trimEnd());
+}
+export async function tokensList(opts, deps = {}) {
+    const api = await loadApi(deps);
+    const { tokens } = (await api.request('GET', '/tokens'));
+    if (opts.json)
+        return printJson(tokens);
+    if (!tokens.length)
+        return info('(no tokens)');
+    const rows = tokens.map((t) => [t.id, t.name, scopeColumn(t), t.access, day(t.expiresAt), day(t.lastUsedAt), t.revokedAt ? 'revoked' : '']);
+    for (const line of table([['id', 'name', 'scope', 'access', 'expires', 'last-used', ''], ...rows]))
+        info(line);
+}
+export async function tokensCreate(name, opts, deps = {}) {
+    if (opts.account && (opts.org || opts.project))
+        die('--account is mutually exclusive with --org / --project: an account-wide token has no org');
+    const expiresInDays = parseExpires(opts.expires ?? '90d'); // validated before any request
+    const api = await loadApi(deps);
+    const binding = opts.account ? {} : await resolveBinding(api, opts, deps.linked ?? linkedProject);
+    const body = {
+        name,
+        ...binding,
+        access: opts.readOnly ? 'read_only' : 'full',
+        ...(expiresInDays === undefined ? {} : { expiresInDays }),
+    };
+    const { token, record } = (await api.request('POST', '/tokens', body));
+    if (opts.json)
+        return printJson({ token, record });
+    // The plaintext ALONE on stdout, so `$(insta tokens create ci)` captures exactly the token; the
+    // note goes to stderr and never repeats the secret.
+    process.stdout.write(token + '\n');
+    const expiry = record.expiresAt ? `expires ${day(record.expiresAt)}` : 'never expires';
+    process.stderr.write(`created token ${record.id} (${record.name}: ${describeTokenScope(scopeOf(record))}; ${expiry}) — the plaintext above is shown once; store it now\n`);
+}
+// Default-org rule (spec §9.1 / §9.2), most explicit first: --project → its org; --org; the org an
+// org-scoped login is bound to (the only one it can mint in); the linked project's org; the caller's
+// only org. Several orgs — or none — stop here rather than guess: binding a CI token to the wrong
+// org is exactly the mistake the scope exists to prevent.
+async function resolveBinding(api, opts, linked) {
+    if (opts.project) {
+        const { project } = (await api.request('GET', `/projects/${encodeURIComponent(opts.project)}`));
+        // A pair the platform would 404 (project outside the org, spec §4.4) is caught here with the real reason.
+        if (opts.org && opts.org !== project.org_id)
+            die(`project ${opts.project} belongs to org ${project.org_id}, not --org ${opts.org}`);
+        return { orgId: project.org_id, projectId: project.id };
+    }
+    if (opts.org)
+        return { orgId: opts.org };
+    // A project-scoped login cannot mint at all (the platform answers 403 token_scope on POST /tokens);
+    // say so here rather than requesting an org token it could never be granted.
+    if (api.config.tokenScope?.projectId)
+        die(`this login is a project-scoped token (${describeTokenScope(api.config.tokenScope)}) and cannot mint tokens — log in with an org or account credential first`);
+    const bound = api.config.tokenScope?.orgId;
+    if (bound)
+        return { orgId: bound };
+    const link = await linked();
+    if (link?.orgId)
+        return { orgId: link.orgId };
+    const { orgs } = (await api.request('GET', '/orgs'));
+    if (orgs.length === 1)
+        return { orgId: orgs[0].id };
+    if (orgs.length === 0)
+        die('no org found — pass --account for an account-wide token, or create an org first: insta org create <name>');
+    const list = orgs.map((o) => `  ${o.id}  ${o.name}`).join('\n');
+    die(`several orgs — pass --org <id> to bind the token to one, or --account for an account-wide token:\n${list}`);
+}
+export async function tokensRevoke(id, opts, deps = {}) {
+    const api = await loadApi(deps);
+    await api.request('DELETE', `/tokens/${encodeURIComponent(id)}`);
+    if (opts.json)
+        return printJson({ ok: true, id });
+    info(`revoked token ${id}`);
+}
+//# sourceMappingURL=tokens.js.map

package/dist/config.js

@@ -60,6 +60,7 @@ export function pickApiUrl(parsed, env, cliOverride) {
         delete scrubbed.refreshToken;
         delete scrubbed.user;
         delete scrubbed.agentCredential;
+        delete scrubbed.tokenScope;
         return scrubbed;
     }
     return { ...parsed, apiUrl: override ?? persisted };

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { Command, Option } from 'commander';
 import { configureAgent, detectAgent } from './agent.js';
-import { setApiUrlOverride } from './config.js';
+import { readGlobal, setApiUrlOverride } from './config.js';
 import * as agentPolicy from './commands/agent-policy.js';
 import { ApiError, AgentApprovalRequired } from './api.js';
 import { CliCancel, CliExit, fail, relayedExitCode } from './util.js';
@@ -14,6 +14,7 @@ import * as setup from './commands/setup.js';
 import * as mcp from './commands/mcp.js';
 import * as runCmd from './commands/run.js';
 import * as org from './commands/org.js';
+import * as tokens from './commands/tokens.js';
 import * as project from './commands/project.js';
 import * as branch from './commands/branch.js';
 import * as services from './commands/services.js';
@@ -39,7 +40,7 @@ import { billing, billingUpgrade, billingPortal } from './commands/billing.js';
 import * as domainCmd from './commands/domain.js';
 import * as selfUpdate from './commands/upgrade.js';
 import * as feedbackCmd from './commands/feedback.js';
-function onError(e) {
+async function onError(e) {
     if (e instanceof AgentApprovalRequired) {
         if (process.argv.includes('--json'))
             process.stdout.write(JSON.stringify(e.body) + '\n');
@@ -50,8 +51,13 @@ function onError(e) {
     }
     if (e instanceof CliExit || e instanceof CliCancel)
         return;
-    if (e instanceof ApiError)
+    if (e instanceof ApiError) {
+        // A scope refusal is not a permissions problem (spec 2026-09-23-scoped-api-tokens §5.2): relay
+        // the platform's words and name the credential this login holds, so nobody goes checking roles.
+        if (e.body?.error === 'token_scope')
+            return fail(tokens.tokenScopeErrorLines(e.body, (await readGlobal()).tokenScope));
         return fail(`${e.message} (HTTP ${e.status})`);
+    }
     fail(e instanceof Error ? e.message : String(e));
 }
 // Wrap an async action so rejections surface as clean CLI errors.
@@ -64,7 +70,7 @@ const guard = (fn) => async (...a) => {
     }
     catch (e) {
         error = e;
-        onError(e);
+        await onError(e);
     }
     await trackCommand(a[a.length - 1], a.slice(0, -2), {
         error, durationMs: Date.now() - started, exitCode: Number(process.exitCode ?? 0), childExitCode: relayedExitCode(),
@@ -110,6 +116,18 @@ envCmd.command('use <name>').description(`Switch environment (${ENV_NAMES.join('
 const orgCmd = program.command('org').description('Manage organizations');
 orgCmd.command('list').option('--json').action(guard((o) => org.orgList(o)));
 orgCmd.command('create <name>').option('--json').action(guard((name, o) => org.orgCreate(name, o)));
+// ---- tokens ----
+const tk = program.command('tokens').description('Manage API tokens (account, org or project scoped)');
+tk.command('list').description('List your API tokens: scope, access, expiry, last use').option('--json').action(guard((o) => tokens.tokensList(o)));
+tk.command('create <name>').description('Mint a token; defaults to the current org — pass --account for an account-wide token. The plaintext is printed once')
+    .option('--org <id>', "bind to this org (default: linked project's org, or your only org)")
+    .option('--project <id>', 'bind to this project (implies its org)')
+    .option('--account', 'account-wide token: everything your account can do (mutually exclusive with --org/--project)')
+    .option('--read-only', 'GET only; cannot run SQL or change anything')
+    .option('--expires <dur>', '30d | 90d | 1y | never — any <n>d or <n>y works', '90d')
+    .option('--json')
+    .action(guard((name, o) => tokens.tokensCreate(name, o)));
+tk.command('revoke <id>').description('Revoke a token — it stops working immediately').option('--json').action(guard((id, o) => tokens.tokensRevoke(id, o)));
 // ---- project ----
 const pj = program.command('project').description('Manage projects');
 pj.command('create [name]').option('--org <id>', 'org to create under (default: personal)').option('--json').action(guard((name, o) => project.projectCreate(name, o)));
@@ -529,7 +547,7 @@ function withSetupAgentOptions(cmd) {
     return cmd
         .option('-y, --yes', 'non-interactive')
         .option('--env <prod|staging>', 'deployment to set this machine up for (default: prod — switches and persists, like `insta env use`)')
-        .option('--mcp-token', 'register Claude Code with a minted insta_ API token instead of OAuth (requires login and token-creation permission)')
+        .option('--mcp-token', 'register Claude Code with a minted account-wide insta_ API token (everything your account can do) instead of OAuth (requires login and token-creation permission)')
         .option('--project <id>', 'also link this directory to an existing project after setup (flows through login first if needed)')
         .option('--create [name]', 'also create a new project and link this directory after setup (default name: this directory; mutually exclusive with --project)')
         .action(guard((o) => setup.setupAgent(o)));
@@ -562,7 +580,7 @@ agent.command('events').description('Show the audit + agent-event timeline').opt
 const cfg = program.command('config').description('CLI configuration: register the remote MCP server with coding agents, list regions, auto-update');
 cfg.command('install-mcp').description('Register the remote MCP server with coding agents (default: Claude Code + all detected)')
     .option('--agent <slug>', 'one agent: claude-code, cursor, codex, opencode, copilot, factory-droid')
-    .option('--mcp-token', 'claude-code only: minted insta_ API token instead of OAuth (requires login and token-creation permission)')
+    .option('--mcp-token', 'claude-code only: a minted account-wide insta_ API token (everything your account can do) instead of OAuth (requires login and token-creation permission)')
     .action(guard((o) => mcp.mcpInstall(o)));
 cfg.command('regions').description('List regions available for postgres/compute services').option('--json').action(guard((o) => regions.regionsList(o)));
 cfg.command('autoupdate [mode]').description('Show or set auto-update: on | off (default: on while pre-1.0)').action(guard((mode) => selfUpdate.autoupdate(mode)));
@@ -574,7 +592,7 @@ const setupCompat = program.command('setup', { hidden: true }).description('Comp
 withSetupAgentOptions(setupCompat.command('agent').description('Alias of `insta agent setup`, kept for the console one-liner'));
 // ---- feedback (agent + human hurdle reports → the InstaCloud team) ----
 program.command('feedback')
-    .description('Report an InstaCloud-side hurdle (bug / missing feature / friction) to the InstaCloud team — about the insta toolkit itself, NEVER about the app you are building. Works logged-out and unlinked.')
+    .description('Report an InstaCloud-side hurdle (bug / missing feature / friction) to the InstaCloud team — about the insta toolkit itself, NEVER about the app you are building. On InstaCloud it needs `insta login`, so the team can reply; works unlinked.')
     .option('--type <type>', `what kind of hurdle: ${feedbackCmd.TYPES.join(' | ')}`)
     .option('--component <component>', `which part of the toolkit: ${feedbackCmd.COMPONENTS.join(' | ')}`)
     .option('--title <title>', 'one-line summary (≤200 chars)')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "insta",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "description": "InstaCloud CLI — a thin client of the platform control-plane API.",
   "keywords": [