@shardflux/cli 0.4.1 → 0.5.1

package/dist/account-commands.js

@@ -0,0 +1,1657 @@
+/**
+ * The account plane (0.5.0; docs/progress/account-cli.md §5): everything a person does in the web app, from a
+ * terminal. Sign-in and the account calls go through the SDK's ShardfluxAccount with the user session (ctx.account());
+ * egress and volumes through the project API key (ctx.cloud()) like the other workspace commands.
+ *
+ * - Secrets never come from arguments: passwords from standard input or a no-echo prompt (ctx.input); the session
+ *   and saved key live in the credentials file (credentials.ts) and are never printed. Deliberate exceptions: `shard
+ *   env` (for eval), `api-keys create` (the new key, once, unless --save), the TOTP secret of `auth totp enroll` and
+ *   recovery codes (the person must copy them), and the reset token of a verification that needs a password.
+ * - 403 step_up_required: on a terminal the password (and a code with two-factor authentication) is asked and the call
+ *   retried once; otherwise the error's hint names `shard auth step-up`.
+ * - Default organization/project: --org/--project (id or slug), else the saved default (orgs use, projects use,
+ *   setup), else the only one there is; with several the usage error lists them.
+ */
+import { chmod, writeFile } from 'node:fs/promises';
+import { API_KEY_TOOL_PERMISSIONS, CheckoutTimeoutError, Shardflux, ShardfluxAccount, ShardfluxApiError, fetchBillingCatalog, parseEmailToken } from '@shardflux/sdk';
+import { UUID, parseDuration, parsePositiveInt } from "./args.js";
+import { openUrl } from "./browser.js";
+import { fileExists, oneOf, out, parseSlugVersion, principal, readInput, resolveWorkspace, str, strs, waitTimeout } from "./commands.js";
+import { AuthConfigError, CheckoutEndedError, InterruptedError, MfaPendingError, NotFoundError, UsageError } from "./errors.js";
+import { apiKeyTable, attachmentTable, auditTable, authSessionTable, billingStatusText, dataExportText, egressVersionTable, invitationTable, invoiceTable, kv, memberTable, money, orgTable, overagePolicyText, planTable, projectEgressText, projectTable, table, time, toolsText, volumeDetail, volumeTable, workspaceEgressText, WORKSPACE_HEADERS, workspaceRow, } from "./format.js";
+export const DEFAULT_API_URL = 'https://api.shardflux.dev';
+const TOTP = /^\d{6}$/;
+const ROLES = ['owner', 'admin', 'member', 'billing'];
+const TOOL_NAMES = API_KEY_TOOL_PERMISSIONS;
+const DEFAULT_CHECKOUT_WAIT_MS = 15 * 60_000;
+const CHECKOUT_POLL_MS = 2_000;
+const NEXT_WORKSPACE = 'shard ws open demo --template python-node-browser';
+const SWITCHED_NOTE = 'note: another user was signed in here; their default organization, project and saved API key were removed from this profile (the key stays valid until revoked).\n';
+const pipe = (cmd) => `printf '%s\\n' "$PASSWORD" | ${cmd}`;
+function need(values, option, example) {
+    const v = str(values[option])?.trim();
+    if (!v)
+        throw new UsageError(`--${option} is required, e.g. ${example}`);
+    return v;
+}
+function emailArg(text, what) {
+    const e = text.trim();
+    if (!/^[^\s@]+@[^\s@]+$/.test(e))
+        throw new UsageError(`${what} must be an email address (got "${text}")`);
+    return e;
+}
+/** --code / --recovery-code (at most one). */
+function factorFlags(values) {
+    const code = str(values.code)?.trim();
+    const recovery = str(values['recovery-code'])?.trim();
+    if (code !== undefined && recovery !== undefined)
+        throw new UsageError('use --code or --recovery-code, not both');
+    if (code !== undefined) {
+        if (!TOTP.test(code))
+            throw new UsageError('--code must be the 6-digit code of your authenticator app');
+        return { code };
+    }
+    if (recovery !== undefined) {
+        if (recovery.length < 8)
+            throw new UsageError('--recovery-code must be one of your recovery codes');
+        return { recoveryCode: recovery };
+    }
+    return null;
+}
+/** An answer typed at the code prompt: six digits are a TOTP code, anything else a recovery code. */
+function factorOf(answer) {
+    const a = answer?.trim() ?? '';
+    if (a === '')
+        return null;
+    const digits = a.replace(/\s+/g, '');
+    return TOTP.test(digits) ? { code: digits } : { recoveryCode: a };
+}
+const factorParams = (f) => (f === null ? {} : 'code' in f ? { code: f.code } : { recoveryCode: f.recoveryCode });
+function linkToken(link) {
+    try {
+        return parseEmailToken(link);
+    }
+    catch (e) {
+        throw new UsageError((e instanceof Error ? e.message : String(e)).replace(/^parseEmailToken: /, ''));
+    }
+}
+async function mfaEnabled(account) {
+    const s = await account.auth.session();
+    return s.user?.mfa_enabled === true;
+}
+/**
+ * Step-up: the password (a prompt, or the next piped line) plus, with two-factor authentication, the factor from the
+ * flags, else a prompt (or the next piped line).
+ */
+async function stepUp(ctx, account, factor, command) {
+    const needsFactor = factor === null && (await mfaEnabled(account));
+    const password = await ctx.input.secret('Password: ', 'The password', pipe(command));
+    let f = factor;
+    if (needsFactor) {
+        f = factorOf(await ctx.input.answer('Authenticator code (or a recovery code): '));
+        if (f === null)
+            throw new UsageError('two-factor authentication is on: pass --code <totp> (or --recovery-code <code>)');
+    }
+    return account.auth.stepUp({ password, ...factorParams(f) });
+}
+/** Runs an account call; on 403 step_up_required on a terminal, steps up and retries once (else the error stands). */
+async function withStepUp(ctx, account, call) {
+    try {
+        return await call();
+    }
+    catch (err) {
+        if (!(err instanceof ShardfluxApiError && err.code === 'step_up_required') || !ctx.input.interactive)
+            throw err;
+        ctx.io.stderr.write('This needs your password again (a step-up, valid 10 minutes).\n');
+        await stepUp(ctx, account, null, 'shard auth step-up');
+        return call();
+    }
+}
+// ---- organization / project resolution ------------------------------------------------------------------------
+async function allOrgs(account) {
+    const rows = [];
+    for await (const o of account.organizations.listAll())
+        rows.push(o);
+    return rows;
+}
+async function allProjects(account, organizationId) {
+    const rows = [];
+    for await (const p of account.projects.listAll(organizationId))
+        rows.push(p);
+    return rows;
+}
+const choices = (rows) => rows.map((r) => `  ${r.id}  ${r.slug}  ${r.name}`).join('\n');
+function byRef(rows, ref) {
+    const exact = rows.find((r) => r.id === ref || r.slug === ref);
+    if (exact)
+        return exact;
+    const named = rows.filter((r) => r.name.toLowerCase() === ref.toLowerCase());
+    return named.length === 1 ? named[0] : undefined;
+}
+const gone = (err) => err instanceof ShardfluxApiError && (err.status === 404 || err.status === 403);
+async function findOrg(account, ref) {
+    if (UUID.test(ref))
+        return account.organizations.get(ref);
+    const hit = byRef(await allOrgs(account), ref);
+    if (!hit)
+        throw new NotFoundError(`No organization "${ref}" among yours.`, 'list them: shard orgs list');
+    return hit;
+}
+/** `ref` (a positional), else --org, else the saved default, else the only organization. */
+async function resolveOrg(ctx, account, values, ref) {
+    const given = ref ?? str(values.org);
+    if (given !== undefined)
+        return findOrg(account, given);
+    const saved = ctx.store.profile(ctx.apiUrl).organization_id;
+    if (saved) {
+        try {
+            return await account.organizations.get(saved);
+        }
+        catch (err) {
+            if (gone(err))
+                throw new NotFoundError(`The default organization ${saved} is no longer available to you.`, 'pick another: shard orgs use <org> (list: shard orgs list)');
+            throw err;
+        }
+    }
+    const orgs = await allOrgs(account);
+    if (orgs.length === 1)
+        return orgs[0];
+    if (orgs.length === 0)
+        throw new UsageError('You have no organization yet.', 'create one with a project and an API key: shard setup (or shard orgs create <name>)');
+    throw new UsageError(`You belong to ${orgs.length} organizations; pick one with --org <id|slug>:\n${choices(orgs)}\n`, 'or save a default: shard orgs use <id|slug>');
+}
+/** `ref` (a positional), else --project, else the saved default (unless --org names another), else the only project. */
+async function resolveProject(ctx, account, values, ref) {
+    const given = ref ?? str(values.project);
+    const orgFlag = str(values.org);
+    if (given !== undefined && UUID.test(given)) {
+        const p = await account.projects.get(given);
+        if (orgFlag !== undefined) {
+            const org = await findOrg(account, orgFlag);
+            if (p.organization_id !== org.id)
+                throw new UsageError(`project ${given} is not in organization ${org.slug}`);
+        }
+        return p;
+    }
+    const profile = ctx.store.profile(ctx.apiUrl);
+    if (given === undefined && profile.project_id && orgFlag === undefined) {
+        try {
+            return await account.projects.get(profile.project_id);
+        }
+        catch (err) {
+            if (gone(err))
+                throw new NotFoundError(`The default project ${profile.project_id} is no longer available to you.`, 'pick another: shard projects use <project> (list: shard projects list)');
+            throw err;
+        }
+    }
+    const org = await resolveOrg(ctx, account, values);
+    const projects = await allProjects(account, org.id);
+    if (given !== undefined) {
+        const hit = byRef(projects, given);
+        if (!hit)
+            throw new NotFoundError(`No project "${given}" in ${org.name} (${org.slug}).`, 'list them: shard projects list');
+        return hit;
+    }
+    const saved = profile.project_id ? projects.find((p) => p.id === profile.project_id) : undefined;
+    if (saved)
+        return saved;
+    if (projects.length === 1)
+        return projects[0];
+    if (projects.length === 0)
+        throw new UsageError(`${org.name} (${org.slug}) has no project yet.`, 'create one: shard projects create <name> (or shard setup)');
+    throw new UsageError(`${org.name} has ${projects.length} projects; pick one with --project <id|slug>:\n${choices(projects)}\n`, 'or save a default: shard projects use <id|slug>');
+}
+/** Removes a saved default (and the saved key) that pointed into an organization that is gone. */
+function forgetOrganization(ctx, organizationId, projectIds) {
+    ctx.store.update(ctx.apiUrl, (p) => {
+        if (p.organization_id === organizationId) {
+            delete p.organization_id;
+            delete p.project_id;
+        }
+        if (p.project_id && projectIds.includes(p.project_id))
+            delete p.project_id;
+        if (p.api_key && projectIds.includes(p.api_key.project_id))
+            delete p.api_key;
+    });
+}
+// ---- files ------------------------------------------------------------------------------------------------------
+/** Writes an export or download 0600, refusing to overwrite without --force. */
+async function writePrivate(path, text, force) {
+    if (!force && (await fileExists(path)))
+        throw new UsageError(`${path} exists; pass --force to overwrite it`);
+    await writeFile(path, text, { mode: 0o600, flag: force ? 'w' : 'wx' });
+    if (process.platform !== 'win32')
+        await chmod(path, 0o600);
+    return Buffer.byteLength(text);
+}
+/** An export is built when it is created; waits (bounded) should it not be ready yet, then downloads it. */
+async function downloadExport(ctx, account, created, get, download) {
+    let meta = created;
+    const deadline = Date.now() + 120_000;
+    while (meta.state !== 'ready') {
+        if (meta.state === 'expired')
+            throw new NotFoundError(`Export ${meta.id} expired before it was downloaded; run the command again.`);
+        if (Date.now() > deadline)
+            throw new UsageError(`export ${meta.id} is not ready after 120 s`);
+        await new Promise((r) => setTimeout(r, 1_000));
+        if (ctx.signal.aborted)
+            throw new InterruptedError('Interrupted.');
+        meta = await get(meta.id);
+    }
+    const text = await withStepUp(ctx, account, () => download(meta.id));
+    return { meta, text };
+}
+// ---- output pieces -------------------------------------------------------------------------------------------
+function userLine(u) {
+    return `${u.display_name ? `${u.display_name} <${u.email}>` : u.email} (user ${u.id})`;
+}
+/** What to do after signing in: verify, set up, or open a workspace. */
+function nextAfterSignIn(ctx, user, me) {
+    if (!user.email_verified)
+        return `shard auth verify-email '<link from the email>'   (a new link: shard auth resend-verification)`;
+    const profile = ctx.store.profile(ctx.apiUrl);
+    const hasKey = profile.api_key !== undefined || Boolean(ctx.io.env.SHARDFLUX_API_KEY?.trim());
+    if (!hasKey || !me || me.memberships.length === 0)
+        return 'shard setup   (an organization, a project and an API key, saved)';
+    return NEXT_WORKSPACE;
+}
+async function signedInReport(ctx, account, user, session, extra = {}) {
+    let me = null;
+    if (user.email_verified) {
+        try {
+            me = await account.me();
+        }
+        catch {
+            me = null;
+        }
+    }
+    const next = nextAfterSignIn(ctx, user, me);
+    const memberships = me?.memberships ?? null;
+    const human = `Signed in as ${userLine(user)}.\n` +
+        kv([
+            ['email', user.email_verified ? 'verified' : 'NOT verified: open the link we emailed you (workspaces and organizations need a verified email)'],
+            ['two-factor', user.mfa_enabled ? 'on' : 'off (turn it on: shard auth totp enroll)'],
+            ['session', `saved in ${ctx.store.file}${session.expires_at ? `, ends ${time(session.expires_at)} at the latest` : ''}`],
+            ['organizations', memberships === null ? '-' : memberships.length === 0 ? 'none yet' : memberships.map((m) => `${m.organization_name} (${m.organization_slug}, ${m.role})`).join(', ')],
+        ]) +
+        `next: ${next}\n`;
+    out(ctx, human, { status: 'authenticated', user, session: { expires_at: session.expires_at, credentials_file: ctx.store.file }, organizations: memberships, next, ...extra });
+    return 0;
+}
+/** Best effort: ends a replaced session server side so it does not linger for 30 days. */
+async function endQuietly(ctx, token) {
+    try {
+        const old = new ShardfluxAccount({ ...ctx.accountOptions(), sessionToken: token, maxRetries: 0, timeoutMs: 5_000 });
+        await old.auth.logout();
+    }
+    catch {
+        // Already ended, or unreachable: it expires on its own.
+    }
+}
+/** A key checked against /v1/me with its own client (SHARDFLUX_API_KEY does not interfere). */
+async function checkKey(ctx, token) {
+    try {
+        const cloud = new Shardflux({ ...ctx.accountOptions(), apiKey: token });
+        const me = await cloud.me();
+        if (me.type === 'api_key' && me.api_key)
+            return { ok: true, organizationId: me.api_key.organization_id, projectId: me.api_key.project_id };
+        return { ok: false, reason: 'not a project API key' };
+    }
+    catch (err) {
+        if (err instanceof ShardfluxApiError && err.status === 401)
+            return { ok: false, reason: 'revoked or expired' };
+        if (err instanceof Error && /apiKey must be/.test(err.message))
+            return { ok: false, reason: 'malformed' };
+        throw err;
+    }
+}
+function toolsFrom(values) {
+    const tools = strs(values.tool);
+    if (values['read-only'] === true) {
+        if (tools.length)
+            throw new UsageError('use --tool or --read-only, not both');
+        return [];
+    }
+    for (const t of tools)
+        if (!TOOL_NAMES.includes(t))
+            throw new UsageError(`--tool must be one of ${TOOL_NAMES.join(', ')} (got "${t}")`);
+    return tools.length ? [...new Set(tools)] : [...TOOL_NAMES];
+}
+/** `--expires 30d|90d|365d|never` (any 1-366 days). */
+function expiresFrom(values, now = Date.now()) {
+    const t = str(values.expires)?.trim().toLowerCase();
+    if (t === undefined || t === 'never')
+        return undefined;
+    const m = /^(\d+)d$/.exec(t);
+    const days = m ? Number(m[1]) : NaN;
+    if (!m || days < 1 || days > 366)
+        throw new UsageError(`--expires must be a number of days (1d-366d, e.g. 30d, 90d, 365d) or never (got "${str(values.expires)}")`);
+    return new Date(now + days * 86_400_000).toISOString();
+}
+const storedKey = (k, secret) => ({ token: secret, id: k.id, key_id: k.key_id, project_id: k.project_id, name: k.name });
+/**
+ * The organization name setup creates: "<display name or email local part>'s organization", within the API's rules
+ * for names (1-200 characters, no control characters or line breaks).
+ */
+export function defaultOrgName(user) {
+    const clean = (s) => (s ?? '').replace(/[\p{C}\p{Zl}\p{Zp}]+/gu, ' ').trim();
+    const who = [...(clean(user.display_name) || clean(user.email.split('@')[0]) || 'My')].slice(0, 180).join('').trim();
+    return `${who}'s organization`;
+}
+/** One line that sets `name` for `shell`, quoted so any value round-trips. */
+export function exportLine(shell, name, value) {
+    switch (shell) {
+        case 'fish':
+            return `set -gx ${name} '${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+        case 'powershell':
+            return `$env:${name} = '${value.replace(/'/g, "''")}'`;
+        default:
+            return `export ${name}='${value.replace(/'/g, `'\\''`)}'`;
+    }
+}
+// ---- audit filters ---------------------------------------------------------------------------------------------
+const AGO = /^(\d+)(m|h|d|w)$/;
+/** An RFC 3339 time, or a duration ago (`90m`, `24h`, `7d`, `2w`). */
+export function parseTime(text, option, now = Date.now()) {
+    const t = text.trim();
+    const m = AGO.exec(t);
+    if (m)
+        return new Date(now - Number(m[1]) * { m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 }[m[2]]).toISOString();
+    const ms = /^\d{4}-\d{2}-\d{2}/.test(t) ? Date.parse(t) : NaN;
+    if (Number.isNaN(ms))
+        throw new UsageError(`--${option} must be an RFC 3339 time (e.g. 2026-09-01T00:00:00Z) or a duration ago such as 24h or 7d (got "${text}")`);
+    return new Date(ms).toISOString();
+}
+function auditFilters(values) {
+    const f = {};
+    const source = oneOf(values, 'source', ['app', 'cell_tool']);
+    const actorType = oneOf(values, 'actor-type', ['user', 'api_key', 'system', 'operator', 'anonymous']);
+    const outcome = oneOf(values, 'outcome', ['success', 'failure', 'denied']);
+    if (source)
+        f.source = source;
+    if (actorType)
+        f.actorType = actorType;
+    if (outcome)
+        f.outcome = outcome;
+    const ids = [
+        ['actor', 'actorId'],
+        ['target', 'targetId'],
+        ['project-id', 'projectId'],
+        ['workspace', 'workspaceId'],
+        ['agent-session', 'agentSessionId'],
+    ];
+    for (const [option, key] of ids) {
+        const v = str(values[option]);
+        if (v === undefined)
+            continue;
+        if (!UUID.test(v))
+            throw new UsageError(`--${option} must be an id (UUID), got "${v}"`);
+        f[key] = v;
+    }
+    const action = str(values.action);
+    if (action !== undefined) {
+        if (!/^[a-z0-9_.]{1,120}$/.test(action))
+            throw new UsageError('--action must be an action prefix such as workspace. or tool.exec');
+        f.action = action;
+    }
+    const targetType = str(values['target-type']);
+    if (targetType !== undefined) {
+        if (!/^[a-z][a-z0-9_]{0,63}$/.test(targetType))
+            throw new UsageError('--target-type must be a type such as workspace or api_key');
+        f.targetType = targetType;
+    }
+    const from = str(values.from);
+    const to = str(values.to);
+    if (from !== undefined)
+        f.from = parseTime(from, 'from');
+    if (to !== undefined)
+        f.to = parseTime(to, 'to');
+    return f;
+}
+// ---- billing ---------------------------------------------------------------------------------------------------
+const OVERAGE_ACTIONS = ['status', 'on', 'off', 'cap'];
+/** A spend cap in dollars ("9", "9.5", "9.50", "$9") as minor units (cents); at most two decimals. */
+export function dollarsToMinor(text, what) {
+    const m = /^\$?(\d{1,7})(?:\.(\d{1,2}))?$/.exec(text.trim());
+    if (!m)
+        throw new UsageError(`${what} must be an amount in dollars such as 9 or 9.50 (got "${text}")`);
+    return Number(m[1]) * 100 + Number((m[2] ?? '').padEnd(2, '0'));
+}
+function purchasablePlans(catalog) {
+    return catalog.plans.filter((p) => p.prices.some((x) => x.purchasable)).map((p) => p.plan_key);
+}
+function priceText(catalog, planKey) {
+    const plan = catalog.plans.find((p) => p.plan_key === planKey);
+    const price = plan?.prices.find((x) => x.purchasable) ?? plan?.prices[0];
+    return price ? `${money(price.amount_minor, price.currency)}/${price.interval}` : '-';
+}
+/** Polls the checkout (the SDK's checkoutStatus) until active, ended, or the timeout; progress on stderr. */
+async function waitForCheckout(ctx, account, organizationId, checkout, timeoutMs) {
+    const started = Date.now();
+    let last = '';
+    const sleep = (ms) => new Promise((resolve) => {
+        const timer = setTimeout(done, ms);
+        function done() {
+            clearTimeout(timer);
+            ctx.signal.removeEventListener('abort', done);
+            resolve();
+        }
+        ctx.signal.addEventListener('abort', done, { once: true });
+    });
+    if (!ctx.json)
+        ctx.io.stderr.write(`Waiting for the payment (up to ${Math.round(timeoutMs / 1000)} s; Ctrl-C stops waiting, the checkout stays open)...\n`);
+    for (;;) {
+        let s;
+        try {
+            s = await account.billing.checkoutStatus(organizationId, checkout.id);
+        }
+        catch (err) {
+            if (ctx.signal.aborted)
+                throw new InterruptedError(`Interrupted; checkout ${checkout.id} stays open.`);
+            throw err;
+        }
+        const phase = s.subscription_active ? 'active' : s.status;
+        if (phase !== last && !ctx.json) {
+            const text = s.subscription_active ? 'subscription active' : s.status === 'completed' ? 'paid; waiting for Stripe to confirm the subscription' : s.status === 'open' ? 'checkout open, not paid yet' : `checkout ${s.status}`;
+            ctx.io.stderr.write(`  ${text}\n`);
+        }
+        last = phase;
+        if (s.subscription_active)
+            return s;
+        if (s.status === 'expired' || s.status === 'canceled' || s.status === 'failed')
+            throw new CheckoutEndedError(s);
+        const waited = Date.now() - started;
+        if (waited >= timeoutMs)
+            throw new CheckoutTimeoutError(s, waited);
+        await sleep(Math.min(CHECKOUT_POLL_MS, timeoutMs - waited));
+        if (ctx.signal.aborted)
+            throw new InterruptedError(`Interrupted; checkout ${checkout.id} stays open.`);
+    }
+}
+// ---- egress and volumes (project API key) ------------------------------------------------------------------------
+async function egressTarget(ctx, values) {
+    const ws = str(values.workspace);
+    const project = str(values.project);
+    if (ws !== undefined && project !== undefined)
+        throw new UsageError('use --project or --workspace, not both');
+    if (ws !== undefined)
+        return { kind: 'workspace', ws: await resolveWorkspace(ctx, ws) };
+    if (project !== undefined) {
+        if (!UUID.test(project))
+            throw new UsageError('--project must be a project id (UUID)');
+        return { kind: 'project', id: project };
+    }
+    return { kind: 'project', id: (await principal(ctx)).project_id };
+}
+const EGRESS_MODES = ['allow_all', 'allowlist', 'deny_all'];
+async function readPolicy(ctx, file) {
+    const text = Buffer.from(await readInput(ctx, file, 256 * 1024, '--file')).toString('utf8');
+    let doc;
+    try {
+        doc = JSON.parse(text);
+    }
+    catch (e) {
+        throw new UsageError(`--file: not valid JSON (${e instanceof Error ? e.message : String(e)})`);
+    }
+    if (typeof doc !== 'object' || doc === null || Array.isArray(doc))
+        throw new UsageError('--file: expected a JSON object {"mode": ..., "rules": [...], "cidrs": [...]}');
+    const mode = doc.mode;
+    if (typeof mode !== 'string' || !EGRESS_MODES.includes(mode))
+        throw new UsageError(`--file: "mode" must be one of ${EGRESS_MODES.join(', ')}`);
+    return doc;
+}
+function ifVersion(values) {
+    const v = str(values['if-version']);
+    if (v === undefined)
+        return {};
+    if (!/^\d+$/.test(v))
+        throw new UsageError('--if-version must be a version number (from shard egress get)');
+    return { ifMatch: Number(v) };
+}
+async function resolveVolume(ctx, ref) {
+    const cloud = ctx.cloud();
+    if (UUID.test(ref)) {
+        try {
+            return await cloud.volumes.get(ref);
+        }
+        catch (err) {
+            if (!(err instanceof ShardfluxApiError && err.status === 404))
+                throw err;
+        }
+    }
+    for await (const v of cloud.volumes.listAll({ includeOrgShared: true }))
+        if ((v.id === ref || v.name === ref) && v.deleted_at === null)
+            return v;
+    throw new NotFoundError(`No volume with id or name "${ref}" in this project.`, 'list them: shard volumes list --include-org-shared');
+}
+const volumeWait = (ctx, values) => (values.wait === false ? false : { timeoutMs: waitTimeout(values), signal: ctx.signal });
+async function waitedVolume(ctx, call) {
+    try {
+        return await call();
+    }
+    catch (err) {
+        if (ctx.signal.aborted)
+            throw new InterruptedError('Interrupted; the volume operation continues server side.', ctx.traces.operationId ?? undefined);
+        throw err;
+    }
+}
+// ---- handlers --------------------------------------------------------------------------------------------------
+export const ACCOUNT_HANDLERS = {
+    async 'auth register'(ctx, values) {
+        const email = emailArg(need(values, 'email', '--email you@example.com'), '--email');
+        const name = str(values.name)?.trim();
+        const password = await ctx.input.newPassword(`Choose a password for ${email}: `, 'The password', pipe(`shard auth register --email ${email}`));
+        const r = await ShardfluxAccount.register({ ...ctx.accountOptions(), email, password, ...(name ? { displayName: name } : {}) });
+        const next = [`shard auth verify-email '<link from the email>'`, `${pipe(`shard auth login --email ${email}`)}`];
+        out(ctx, `Registration received for ${email}.\n` +
+            `Check that inbox for a verification link (valid 24 hours). If the address already has an account, no new one is created: sign in instead.\n` +
+            `next:\n  1. open the link, or: ${next[0]}\n  2. ${next[1]}\n`, { status: r.status, email, next_steps: next });
+        return 0;
+    },
+    async 'auth verify-email'(ctx, _values, [link]) {
+        const token = linkToken(link);
+        const r = await ShardfluxAccount.verifyEmail(token, ctx.accountOptions());
+        const login = pipe('shard auth login --email <you@example.com>');
+        if (r.status === 'verified') {
+            out(ctx, `Email verified. Sign in: ${login}\n`, { status: 'verified', password_set: false, next_steps: [login] });
+            return 0;
+        }
+        // A resend link: the account needs a password before anyone can sign in.
+        const reset = r.reset_token ?? '';
+        ctx.addSecret(reset);
+        const later = `printf '%s\\n' "$NEW_PASSWORD" | shard auth password reset-confirm ${reset}`;
+        let password;
+        if (ctx.input.interactive)
+            password = await ctx.input.newPassword('Choose a new password: ', 'The new password', later);
+        else {
+            const line = await ctx.input.line();
+            password = line && line.length > 0 ? line : null;
+        }
+        if (password === null) {
+            out(ctx, `Email verified. The account needs a new password before you can sign in (the link was a resend). Set it with:\n  ${later}\n`, { status: 'password_reset_required', reset_token: reset, next_steps: [later, login] });
+            return 0;
+        }
+        await ShardfluxAccount.confirmPasswordReset({ token: reset, newPassword: password }, ctx.accountOptions());
+        out(ctx, `Email verified and the new password set. Sign in: ${login}\n`, { status: 'verified', password_set: true, next_steps: [login] });
+        return 0;
+    },
+    async 'auth resend-verification'(ctx) {
+        const account = ctx.account();
+        await account.auth.resendVerification();
+        out(ctx, 'A new verification link is on its way (unless the email is verified already). Then: shard auth verify-email \'<link>\'\n', { status: 'accepted' });
+        return 0;
+    },
+    async 'auth login'(ctx, values) {
+        const email = emailArg(need(values, 'email', '--email you@example.com'), '--email');
+        let factor = factorFlags(values);
+        const password = await ctx.input.secret(`Password for ${email}: `, 'The password', pipe(`shard auth login --email ${email}`));
+        let latest = null;
+        const { account, result } = await ShardfluxAccount.login({
+            ...ctx.accountOptions(),
+            email,
+            password,
+            onSessionToken: (s) => {
+                ctx.addSecret(s.token);
+                latest = s;
+            },
+        });
+        const replaced = ctx.store.profile(ctx.apiUrl).session?.token ?? null;
+        const session = () => ({ token: account.sessionToken ?? '', expires_at: latest?.expiresAt || result.session_expires_at || null, user: null, state: 'active' });
+        let user = result.user;
+        if (result.status === 'mfa_required') {
+            if (factor === null && ctx.input.interactive)
+                factor = factorOf(await ctx.input.answer('Authenticator code (or a recovery code): '));
+            if (factor === null) {
+                const { switched } = ctx.saveSession({ ...session(), state: 'pending_mfa' }, email);
+                if (replaced && replaced !== account.sessionToken)
+                    await endQuietly(ctx, replaced);
+                if (switched && !ctx.json)
+                    ctx.io.stderr.write(SWITCHED_NOTE);
+                throw new MfaPendingError(`Password accepted for ${email}; two-factor authentication is on, so the sign-in waits for your code (10 minutes). The pending session is saved in ${ctx.store.file}.`, 'shard auth mfa --code <code from your authenticator app>');
+            }
+            user = (await account.auth.completeMfa(factor)).user;
+        }
+        if (!user)
+            throw new UsageError('the API signed you in without a user; run shard auth status');
+        const saved = { ...session(), user: { id: user.id, email: user.email } };
+        const { switched } = ctx.saveSession(saved, email);
+        if (replaced && replaced !== saved.token)
+            await endQuietly(ctx, replaced);
+        if (switched && !ctx.json)
+            ctx.io.stderr.write(SWITCHED_NOTE);
+        return signedInReport(ctx, account, user, saved);
+    },
+    async 'auth mfa'(ctx, values) {
+        let factor = factorFlags(values);
+        if (factor === null && ctx.input.interactive)
+            factor = factorOf(await ctx.input.answer('Authenticator code (or a recovery code): '));
+        if (factor === null)
+            throw new UsageError('pass the code of your authenticator app: shard auth mfa --code <code> (or --recovery-code <code>)');
+        const account = ctx.account();
+        const r = await account.auth.completeMfa(factor);
+        const user = r.user;
+        if (!user)
+            throw new UsageError('the API completed the sign-in without a user; run shard auth status');
+        const saved = { token: account.sessionToken ?? '', expires_at: r.session_expires_at ?? null, user: { id: user.id, email: user.email }, state: 'active' };
+        ctx.saveSession(saved);
+        return signedInReport(ctx, account, user, saved);
+    },
+    async 'auth status'(ctx) {
+        const source = ctx.sessionSource();
+        let session = null;
+        const lines = [
+            ['api', ctx.apiUrl],
+            ['credentials', ctx.store.file],
+        ];
+        if (source === null) {
+            lines.push(['session', 'not signed in (shard auth login --email <you@example.com>)']);
+        }
+        else {
+            const account = ctx.account();
+            const s = await account.auth.session();
+            const from = source === 'env' ? 'SHARDFLUX_SESSION_TOKEN' : 'the credentials file';
+            if (s.state === 'anonymous') {
+                if (source === 'file') {
+                    ctx.store.update(ctx.apiUrl, (p) => {
+                        delete p.session;
+                    });
+                }
+                session = { source, state: 'invalid' };
+                lines.push(['session', `not signed in: the session from ${from} expired or was revoked${source === 'file' ? ' (removed)' : ''}; shard auth login --email <you@example.com>`]);
+            }
+            else if (s.state === 'mfa_required') {
+                session = { source, state: 'mfa_required', session: s.session };
+                lines.push(['session', `waiting for the second factor (from ${from}): shard auth mfa --code <code>`]);
+            }
+            else {
+                const u = s.user;
+                const x = s.session;
+                session = { source, state: 'authenticated', user: u, session: x };
+                lines.push(['session', `${userLine(u)}, from ${from}`], ['email', u.email_verified ? 'verified' : 'NOT verified (shard auth verify-email \'<link>\')'], ['two-factor', u.mfa_enabled ? 'on' : 'off'], ['expires', `${time(x.absolute_expires_at)} (idle expiry ${time(x.idle_expires_at)})`], ['step-up', x.step_up_valid_until && Date.parse(x.step_up_valid_until) > Date.now() ? `valid until ${time(x.step_up_valid_until)}` : 'none (shard auth step-up)']);
+            }
+        }
+        let apiKey = null;
+        try {
+            const k = ctx.apiKey();
+            const keyId = k.token.split('_')[1] ?? '';
+            const from = k.source === 'env' ? 'SHARDFLUX_API_KEY' : 'the credentials file';
+            let valid = null;
+            let info = {};
+            try {
+                const me = await ctx.cloud().me();
+                valid = me.type === 'api_key';
+                if (me.api_key)
+                    info = { organization_id: me.api_key.organization_id, project_id: me.api_key.project_id, tool_permissions: me.api_key.tool_permissions };
+            }
+            catch (err) {
+                if (!(err instanceof ShardfluxApiError && err.status === 401))
+                    throw err;
+                valid = false;
+            }
+            apiKey = { source: k.source, key_id: keyId, ...(k.saved ? { id: k.saved.id, name: k.saved.name } : {}), valid, ...info };
+            const where = info.project_id ? `, project ${info.project_id}` : k.saved ? `, project ${k.saved.project_id}` : '';
+            lines.push(['api key', `${keyId}${k.saved ? ` "${k.saved.name}"` : ''}${where}, from ${from}: ${valid ? `works (tools: ${toolsText(info.tool_permissions ?? [])})` : 'rejected (revoked or expired; shard setup --new-key)'}`]);
+        }
+        catch (err) {
+            if (!(err instanceof AuthConfigError))
+                throw err;
+            if (/is not set/.test(err.message))
+                lines.push(['api key', 'none (shard setup saves one)']);
+            else {
+                apiKey = { source: ctx.io.env.SHARDFLUX_API_KEY?.trim() ? 'env' : 'file', valid: false, error: err.message };
+                lines.push(['api key', err.message]);
+            }
+        }
+        const profile = ctx.store.profile(ctx.apiUrl);
+        const defaults = { organization_id: profile.organization_id ?? null, project_id: profile.project_id ?? null };
+        lines.push(['defaults', `organization ${defaults.organization_id ?? '-'}, project ${defaults.project_id ?? '-'}`]);
+        out(ctx, kv(lines), { api_url: ctx.apiUrl, credentials_file: ctx.store.file, session, api_key: apiKey, defaults });
+        return 0;
+    },
+    async 'auth logout'(ctx, values) {
+        const source = ctx.sessionSource();
+        if (source === null) {
+            out(ctx, 'Not signed in.\n', { signed_out: false, reason: 'not_signed_in' });
+            return 0;
+        }
+        const account = ctx.account();
+        let ended = true;
+        try {
+            if (values.all === true)
+                await account.auth.logoutAll();
+            else
+                await account.auth.logout();
+        }
+        catch (err) {
+            if (!(err instanceof ShardfluxApiError && err.status === 401))
+                throw err;
+            ended = false;
+        }
+        if (source === 'file') {
+            ctx.store.update(ctx.apiUrl, (p) => {
+                delete p.session;
+            });
+        }
+        const hasKey = ctx.store.profile(ctx.apiUrl).api_key !== undefined;
+        const human = `${ended ? 'Signed out' : 'The session had already ended'}${values.all === true && ended ? '; every session of your account ended' : ''}.\n` +
+            (hasKey ? 'The saved API key stays, so workspace commands keep working (remove it: shard api-keys revoke <id> --yes).\n' : '') +
+            (source === 'env' ? 'SHARDFLUX_SESSION_TOKEN is still set: unset it.\n' : '');
+        out(ctx, human, { signed_out: true, all: values.all === true, session_was_active: ended, api_key_kept: hasKey });
+        return 0;
+    },
+    async 'auth sessions'(ctx, values) {
+        const account = ctx.account();
+        const revoke = str(values.revoke);
+        if (revoke !== undefined) {
+            if (!UUID.test(revoke))
+                throw new UsageError('--revoke must be a session id (UUID) from shard auth sessions');
+            const current = (await account.auth.sessions()).data.find((s) => s.current);
+            await account.auth.revokeSession(revoke);
+            const self = current?.id === revoke;
+            if (self && ctx.sessionSource() === 'file') {
+                ctx.store.update(ctx.apiUrl, (p) => {
+                    delete p.session;
+                });
+            }
+            out(ctx, `Ended session ${revoke}${self ? ' (this one: you are signed out here)' : ''}.\n`, { revoked: revoke, current: self });
+            return 0;
+        }
+        const page = await account.auth.sessions();
+        out(ctx, page.data.length ? authSessionTable(page.data) : 'No live sessions.\n', { data: page.data, next_cursor: page.next_cursor });
+        return 0;
+    },
+    async 'auth step-up'(ctx, values) {
+        const account = ctx.account();
+        const r = await stepUp(ctx, account, factorFlags(values), 'shard auth step-up');
+        out(ctx, `Step-up confirmed until ${time(r.step_up_valid_until)}.\n`, { step_up_valid_until: r.step_up_valid_until });
+        return 0;
+    },
+    async 'auth password change'(ctx) {
+        const account = ctx.account();
+        const hint = `printf '%s\\n%s\\n' "$CURRENT" "$NEW" | shard auth password change`;
+        const current = await ctx.input.secret('Current password: ', 'The current password', hint);
+        const next = await ctx.input.newPassword('New password: ', 'The new password', hint);
+        await account.auth.changePassword({ currentPassword: current, newPassword: next });
+        out(ctx, 'Password changed. Your other sessions were signed out; this one continues.\n', { status: 'password_changed' });
+        return 0;
+    },
+    async 'auth password reset'(ctx, values) {
+        const email = emailArg(need(values, 'email', '--email you@example.com'), '--email');
+        await ShardfluxAccount.requestPasswordReset(email, ctx.accountOptions());
+        const next = `printf '%s\\n' "$NEW_PASSWORD" | shard auth password reset-confirm '<link from the email>'`;
+        out(ctx, `If ${email} has an account, a reset link is on its way. Then:\n  ${next}\n`, { status: 'accepted', email, next_steps: [next] });
+        return 0;
+    },
+    async 'auth password reset-confirm'(ctx, _values, [link]) {
+        const token = linkToken(link);
+        const password = await ctx.input.newPassword('New password: ', 'The new password', `printf '%s\\n' "$NEW_PASSWORD" | shard auth password reset-confirm '<link>'`);
+        await ShardfluxAccount.confirmPasswordReset({ token, newPassword: password }, ctx.accountOptions());
+        const login = pipe('shard auth login --email <you@example.com>');
+        out(ctx, `Password set; every session of the account was signed out. Sign in: ${login}\n`, { status: 'password_reset', next_steps: [login] });
+        return 0;
+    },
+    async 'auth email change'(ctx, values) {
+        const email = emailArg(need(values, 'email', '--email new@example.com'), '--email');
+        const account = ctx.account();
+        await withStepUp(ctx, account, () => account.auth.changeEmail(email));
+        out(ctx, `A confirmation link was sent to ${email}. Confirm with: shard auth email confirm '<link>'\n`, { status: 'accepted', email });
+        return 0;
+    },
+    async 'auth email confirm'(ctx, _values, [link]) {
+        const r = await ShardfluxAccount.confirmEmailChange(linkToken(link), ctx.accountOptions());
+        out(ctx, 'Your sign-in email is changed. Sign in with the new address from now on.\n', r);
+        return 0;
+    },
+    async 'auth totp enroll'(ctx) {
+        const account = ctx.account();
+        const e = await withStepUp(ctx, account, () => account.auth.totp.enroll());
+        ctx.addSecret(e.secret);
+        out(ctx, `Add this to your authenticator app (scan the URI as a QR code, or type the secret):\n` +
+            kv([
+                ['secret', e.secret],
+                ['uri', e.otpauth_uri],
+            ]) +
+            'Then turn it on with a current code: shard auth totp confirm --code <code>\n', e);
+        return 0;
+    },
+    async 'auth totp confirm'(ctx, values) {
+        const code = need(values, 'code', '--code 123456');
+        if (!TOTP.test(code))
+            throw new UsageError('--code must be the 6-digit code of your authenticator app');
+        const account = ctx.account();
+        const r = await account.auth.totp.confirm(code);
+        out(ctx, `Two-factor authentication is on. Recovery codes (each works once; store them now, they are not shown again):\n${r.recovery_codes.map((c) => `  ${c}`).join('\n')}\n`, { status: 'enabled', recovery_codes: r.recovery_codes });
+        return 0;
+    },
+    async 'auth totp disable'(ctx, values) {
+        const account = ctx.account();
+        const factor = factorFlags(values);
+        // Disabling needs a step-up with a second factor: done first when a code was given, else on demand.
+        if (factor !== null)
+            await stepUp(ctx, account, factor, 'shard auth totp disable --code <code>');
+        await withStepUp(ctx, account, () => account.auth.totp.disable());
+        out(ctx, 'Two-factor authentication is off; recovery codes stopped working and your other sessions were signed out.\n', { status: 'disabled' });
+        return 0;
+    },
+    async 'auth totp recovery-codes'(ctx) {
+        const account = ctx.account();
+        const r = await withStepUp(ctx, account, () => account.auth.totp.regenerateRecoveryCodes());
+        out(ctx, `New recovery codes (the old ones stopped working; store these now):\n${r.recovery_codes.map((c) => `  ${c}`).join('\n')}\n`, r);
+        return 0;
+    },
+    async setup(ctx, values) {
+        const account = ctx.account();
+        const me = await account.me();
+        if (me.type !== 'user' || !me.user)
+            throw new UsageError('setup needs a user session: shard auth login');
+        const tools = toolsFrom(values);
+        const profile = ctx.store.profile(ctx.apiUrl);
+        const created = { organization: false, project: false, api_key: false };
+        const flagged = str(values.org) !== undefined || str(values.project) !== undefined;
+        let keyCheck = null;
+        if (profile.api_key && values['new-key'] !== true) {
+            keyCheck = await checkKey(ctx, profile.api_key.token);
+            if (!keyCheck.ok && !ctx.json)
+                ctx.io.stderr.write(`note: the saved API key ${profile.api_key.key_id} no longer works (${keyCheck.reason}); creating a new one.\n`);
+        }
+        let org;
+        let project;
+        // The working saved key's own organization and project, when this user can see them.
+        let home = null;
+        if (keyCheck?.ok && !flagged) {
+            try {
+                home = { org: await account.organizations.get(keyCheck.organizationId), project: await account.projects.get(keyCheck.projectId) };
+            }
+            catch (err) {
+                if (!gone(err))
+                    throw err;
+                if (!ctx.json)
+                    ctx.io.stderr.write(`note: the saved API key ${profile.api_key.key_id} belongs to a project you cannot see; creating a key for your own.\n`);
+                keyCheck = { ok: false, reason: 'another account' };
+            }
+        }
+        if (home) {
+            org = home.org;
+            project = home.project;
+        }
+        else {
+            const orgs = await allOrgs(account);
+            const orgRef = str(values.org);
+            const savedOrg = profile.organization_id ? orgs.find((o) => o.id === profile.organization_id) : undefined;
+            if (orgRef !== undefined)
+                org = await findOrg(account, orgRef);
+            else if (savedOrg)
+                org = savedOrg;
+            else if (orgs.length === 1)
+                org = orgs[0];
+            else if (orgs.length === 0) {
+                org = await account.organizations.create({ name: str(values['org-name'])?.trim() || defaultOrgName(me.user) });
+                created.organization = true;
+            }
+            else
+                throw new UsageError(`You belong to ${orgs.length} organizations; pick one with --org <id|slug>:\n${choices(orgs)}\n`, 'or save a default first: shard orgs use <id|slug>');
+            const projects = created.organization ? [] : await allProjects(account, org.id);
+            const projectRef = str(values.project);
+            const savedProject = profile.project_id ? projects.find((p) => p.id === profile.project_id) : undefined;
+            if (projectRef !== undefined) {
+                const hit = byRef(projects, projectRef);
+                if (!hit)
+                    throw new NotFoundError(`No project "${projectRef}" in ${org.name} (${org.slug}).`, 'list them: shard projects list');
+                project = hit;
+            }
+            else if (savedProject)
+                project = savedProject;
+            else if (projects.length === 1)
+                project = projects[0];
+            else if (projects.length === 0) {
+                project = await account.projects.create(org.id, { name: str(values['project-name'])?.trim() || 'Default' });
+                created.project = true;
+            }
+            else
+                throw new UsageError(`${org.name} has ${projects.length} projects; pick one with --project <id|slug>:\n${choices(projects)}\n`, 'or save a default first: shard projects use <id|slug>');
+        }
+        const keep = keyCheck?.ok === true && profile.api_key?.project_id === project.id;
+        let key;
+        let permissions = tools;
+        if (keep)
+            key = profile.api_key;
+        else {
+            const name = (str(values['key-name'])?.trim() || `shard-cli ${ctx.hostname()}`).slice(0, 200);
+            const res = await account.apiKeys.create(project.id, { name, toolPermissions: tools });
+            ctx.addSecret(res.secret);
+            key = storedKey(res.api_key, res.secret);
+            permissions = res.api_key.tool_permissions;
+            created.api_key = true;
+        }
+        ctx.store.update(ctx.apiUrl, (p) => {
+            p.organization_id = org.id;
+            p.project_id = project.id;
+            p.api_key = key;
+        });
+        const check = keep ? keyCheck : await checkKey(ctx, key.token);
+        if (!check?.ok || check.projectId !== project.id)
+            throw new UsageError(`the API key ${key.key_id} was saved but does not authenticate for project ${project.id} (${check && !check.ok ? check.reason : 'another project'})`, 'try again: shard setup --new-key');
+        if (keep) {
+            const k = (await account.apiKeys.list(project.id, { limit: 200 })).data.find((x) => x.id === key.id);
+            if (k)
+                permissions = k.tool_permissions;
+        }
+        const tag = (made) => (made ? 'created' : 'existing');
+        const envNote = ctx.io.env.SHARDFLUX_API_KEY?.trim() ? 'note: SHARDFLUX_API_KEY is set in this environment and wins over the saved key; unset it to use the saved key.\n' : '';
+        out(ctx, (keep ? 'Already set up; the saved API key works.\n' : 'Set up.\n') +
+            kv([
+                ['organization', `${org.name} (${org.slug}, ${org.id}) ${tag(created.organization)}`],
+                ['project', `${project.name} (${project.slug}, ${project.id}) ${tag(created.project)}`],
+                ['api key', `"${key.name}" ${key.key_id} (tools: ${toolsText(permissions)}) ${keep ? 'saved earlier' : 'created'}, saved in ${ctx.store.file}`],
+            ]) +
+            envNote +
+            `next: ${NEXT_WORKSPACE}\n`, {
+            organization: org,
+            project,
+            api_key: { id: key.id, key_id: key.key_id, name: key.name, project_id: key.project_id, tool_permissions: permissions },
+            created,
+            credentials_file: ctx.store.file,
+            next: NEXT_WORKSPACE,
+        });
+        return 0;
+    },
+    env(ctx, values) {
+        // No request: the saved (or environment) key as shell commands. A throw inside the executor rejects.
+        return new Promise((resolve) => {
+            const shell = oneOf(values, 'shell', ['sh', 'fish', 'powershell']) ?? 'sh';
+            const key = ctx.apiKey();
+            const vars = [['SHARDFLUX_API_KEY', key.token]];
+            if (ctx.apiUrl !== DEFAULT_API_URL)
+                vars.push(['SHARDFLUX_API_URL', ctx.apiUrl]);
+            out(ctx, `${vars.map(([n, v]) => exportLine(shell, n, v)).join('\n')}\n`, { shell, variables: Object.fromEntries(vars) });
+            resolve(0);
+        });
+    },
+    async 'orgs list'(ctx) {
+        const rows = await allOrgs(ctx.account());
+        const def = ctx.store.profile(ctx.apiUrl).organization_id ?? null;
+        out(ctx, rows.length ? orgTable(rows, def) : 'No organizations yet (shard setup creates one).\n', { data: rows, next_cursor: null, default_organization_id: def });
+        return 0;
+    },
+    async 'orgs create'(ctx, values, [name]) {
+        const account = ctx.account();
+        const slug = str(values.slug);
+        const org = await account.organizations.create({ name: name, ...(slug !== undefined ? { slug } : {}) });
+        if (values.use === true) {
+            ctx.store.update(ctx.apiUrl, (p) => {
+                p.organization_id = org.id;
+                delete p.project_id;
+            });
+        }
+        out(ctx, `Created organization ${org.name} (${org.slug}, ${org.id}); you are its owner.\n${values.use === true ? 'It is now the default.\n' : `Make it the default: shard orgs use ${org.slug}\n`}`, org);
+        return 0;
+    },
+    async 'orgs get'(ctx, values, [ref]) {
+        const account = ctx.account();
+        const org = await resolveOrg(ctx, account, values, ref);
+        const ent = await account.organizations.entitlements(org.id);
+        out(ctx, kv([
+            ['id', org.id],
+            ['name', org.name],
+            ['slug', org.slug],
+            ['your role', org.role ?? '-'],
+            ['plan', ent.plan ? `${ent.plan.plan_key} (${ent.plan.source})` : '-'],
+            ['created', time(org.created_at)],
+        ]), { organization: org, plan: ent.plan });
+        return 0;
+    },
+    async 'orgs use'(ctx, values, [ref]) {
+        const org = await resolveOrg(ctx, ctx.account(), values, ref);
+        ctx.store.update(ctx.apiUrl, (p) => {
+            if (p.organization_id !== org.id)
+                delete p.project_id;
+            p.organization_id = org.id;
+        });
+        out(ctx, `Default organization: ${org.name} (${org.slug}, ${org.id}).\n`, { default_organization_id: org.id, organization: org });
+        return 0;
+    },
+    async 'orgs export'(ctx, values, [ref]) {
+        const account = ctx.account();
+        const org = await resolveOrg(ctx, account, values, ref);
+        const created = await withStepUp(ctx, account, () => account.organizations.exports.create(org.id));
+        const { meta, text } = await downloadExport(ctx, account, created, (id) => account.organizations.exports.get(org.id, id), (id) => account.organizations.exports.download(org.id, id, { signal: ctx.signal }));
+        const path = str(values.out) ?? `./organization-export-${meta.id}.json`;
+        const bytes = await writePrivate(path, text, values.force === true);
+        out(ctx, dataExportText(meta, path), { export: meta, out: path, bytes });
+        return 0;
+    },
+    async 'orgs workspaces'(ctx, values, [ref]) {
+        const account = ctx.account();
+        const org = await resolveOrg(ctx, account, values, ref);
+        const projects = await allProjects(account, org.id);
+        const projectRef = str(values.project);
+        const project = projectRef === undefined ? undefined : projects.find((p) => p.id === projectRef || p.slug === projectRef);
+        if (projectRef !== undefined && !project)
+            throw new NotFoundError(`No project "${projectRef}" in ${org.name} (${projects.map((p) => p.slug).join(', ') || 'none'}).`);
+        const limitText = str(values.limit);
+        const params = {
+            ...(project ? { projectId: project.id } : {}),
+            ...(str(values.state) ? { state: str(values.state) } : {}),
+            ...(str(values.prefix) ? { keyPrefix: str(values.prefix) } : {}),
+            ...(values.lifetime !== undefined ? { lifetime: oneOf(values, 'lifetime', ['persistent', 'session', 'any']) } : {}),
+            ...(values.purpose !== undefined ? { purpose: oneOf(values, 'purpose', ['standard', 'template_draft', 'template_test', 'any']) } : {}),
+            ...(values['include-deleted'] === true ? { includeDeleted: true } : {}),
+            ...(limitText ? { limit: parsePositiveInt(limitText, 'limit', 200) } : {}),
+        };
+        let views = [];
+        let cursor = str(values.cursor);
+        let next;
+        do {
+            const page = await account.organizations.workspaces(org.id, { ...params, ...(cursor ? { cursor } : {}) });
+            views = views.concat(page.data);
+            next = page.next_cursor;
+            cursor = next ?? undefined;
+            if (ctx.signal.aborted)
+                throw new InterruptedError('Interrupted.');
+        } while (values.all === true && next);
+        const slugOf = new Map(projects.map((p) => [p.id, p.slug]));
+        const text = views.length
+            ? table(['PROJECT', ...WORKSPACE_HEADERS], views.map((w) => [slugOf.get(w.project_id) ?? w.project_id, ...workspaceRow(w)]))
+            : `No workspaces in ${org.name}.\n`;
+        out(ctx, text, { organization_id: org.id, data: views, next_cursor: values.all === true ? null : next });
+        if (!ctx.json && values.all !== true && next)
+            ctx.io.stderr.write(`more: shard orgs workspaces ${org.slug} --cursor ${next}\n`);
+        return 0;
+    },
+    async 'orgs deletion'(ctx, values, [ref]) {
+        const account = ctx.account();
+        const org = await resolveOrg(ctx, account, values, ref);
+        const d = await account.organizations.deletion(org.id);
+        const c = d.counts;
+        const block = d.billing_block;
+        out(ctx, kv([
+            ['organization', `${org.name} (${org.slug})`],
+            ['request', d.request ? `${d.request.state} since ${time(d.request.requested_at)}; removed after ${time(d.request.finalize_after)}` : 'none'],
+            ['blocked by', block ? `${block.reason}${block.reason === 'subscription_active' ? ' (cancel it in the billing portal: shard billing portal)' : ' (an open checkout)'}` : 'nothing'],
+            ['would delete', `${c.live_workspaces} workspaces, ${c.projects} projects, ${c.active_api_keys} API keys, ${c.pending_invitations} invitations, ${c.organization_templates} templates`],
+            ['grace', `${Math.round(d.grace_seconds / 86_400)} days readable to owners/admins afterwards`],
+            ['kept', d.retained.join(', ') || '-'],
+        ]) + (block ? '' : `delete it: shard orgs delete ${org.slug} --confirm ${org.slug} --yes\n`), { organization: org, ...d });
+        return 0;
+    },
+    async 'orgs delete'(ctx, values, [ref]) {
+        if (values.yes !== true)
+            throw new UsageError('refusing to delete without --yes (every workspace is deleted, API keys are revoked and projects removed; irreversible)');
+        const confirm = need(values, 'confirm', '--confirm <organization slug>');
+        const account = ctx.account();
+        const org = await resolveOrg(ctx, account, values, ref);
+        if (confirm !== org.slug)
+            throw new UsageError(`--confirm must be the organization's slug "${org.slug}" (got "${confirm}")`);
+        const projectIds = (await allProjects(account, org.id)).map((p) => p.id);
+        const r = await withStepUp(ctx, account, () => account.organizations.delete(org.id, { confirmation: confirm }));
+        forgetOrganization(ctx, org.id, projectIds);
+        out(ctx, `Deleted organization ${org.name} (${org.slug}): ${r.workspace_operations.length} workspace deletions started, ${r.api_keys_revoked} API keys revoked, ${r.projects_deleted} projects deleted, ${r.invitations_revoked} invitations revoked. It stays readable to owners/admins until ${time(r.request.finalize_after)}.\n`, r);
+        return 0;
+    },
+    async 'projects list'(ctx, values) {
+        const account = ctx.account();
+        const org = await resolveOrg(ctx, account, values);
+        const rows = await allProjects(account, org.id);
+        const def = ctx.store.profile(ctx.apiUrl).project_id ?? null;
+        out(ctx, rows.length ? projectTable(rows, def) : `${org.name} has no projects yet (shard projects create <name>).\n`, { organization_id: org.id, data: rows, next_cursor: null, default_project_id: def });
+        return 0;
+    },
+    async 'projects create'(ctx, values, [name]) {
+        const account = ctx.account();
+        const org = await resolveOrg(ctx, account, values);
+        const slug = str(values.slug);
+        const p = await account.projects.create(org.id, { name: name, ...(slug !== undefined ? { slug } : {}) });
+        if (values.use === true) {
+            ctx.store.update(ctx.apiUrl, (x) => {
+                x.organization_id = p.organization_id;
+                x.project_id = p.id;
+            });
+        }
+        out(ctx, `Created project ${p.name} (${p.slug}, ${p.id}) in ${org.name}.\n${values.use === true ? 'It is now the default.\n' : `Make it the default: shard projects use ${p.id}\n`}`, p);
+        return 0;
+    },
+    async 'projects get'(ctx, values, [ref]) {
+        const p = await resolveProject(ctx, ctx.account(), values, ref);
+        out(ctx, kv([
+            ['id', p.id],
+            ['name', p.name],
+            ['slug', p.slug],
+            ['organization', p.organization_id],
+            ['created', time(p.created_at)],
+        ]), p);
+        return 0;
+    },
+    async 'projects use'(ctx, values, [ref]) {
+        const p = await resolveProject(ctx, ctx.account(), values, ref);
+        ctx.store.update(ctx.apiUrl, (x) => {
+            x.organization_id = p.organization_id;
+            x.project_id = p.id;
+        });
+        out(ctx, `Default project: ${p.name} (${p.slug}, ${p.id}) of organization ${p.organization_id}.\n`, { default_project_id: p.id, default_organization_id: p.organization_id, project: p });
+        return 0;
+    },
+    async 'api-keys list'(ctx, values) {
+        const account = ctx.account();
+        const project = await resolveProject(ctx, account, values);
+        const rows = [];
+        let cursor;
+        do {
+            const page = await account.apiKeys.list(project.id, { limit: 200, ...(cursor ? { cursor } : {}) });
+            rows.push(...page.data);
+            cursor = page.next_cursor ?? undefined;
+        } while (cursor);
+        const saved = ctx.store.profile(ctx.apiUrl).api_key?.id ?? null;
+        out(ctx, rows.length ? apiKeyTable(rows, saved) : `No API keys in ${project.name} (shard api-keys create <name>).\n`, { project_id: project.id, data: rows, next_cursor: null, saved_api_key_id: saved });
+        return 0;
+    },
+    async 'api-keys create'(ctx, values, [name]) {
+        const tools = toolsFrom(values);
+        const expiresAt = expiresFrom(values);
+        const account = ctx.account();
+        const project = await resolveProject(ctx, account, values);
+        const res = await account.apiKeys.create(project.id, { name: name, toolPermissions: tools, ...(expiresAt ? { expiresAt } : {}) });
+        ctx.addSecret(res.secret);
+        const k = res.api_key;
+        const what = `API key "${k.name}" ${k.key_id} (${k.id}) for project ${project.name} (${project.id}); tools: ${toolsText(k.tool_permissions)}; expires ${k.expires_at ? time(k.expires_at) : 'never'}`;
+        if (values.save === true) {
+            ctx.store.update(ctx.apiUrl, (p) => {
+                p.api_key = storedKey(k, res.secret);
+                p.project_id = project.id;
+                p.organization_id = project.organization_id;
+            });
+            out(ctx, `Created ${what}.\nSaved in ${ctx.store.file}: workspace commands use it (SHARDFLUX_API_KEY, when set, wins).\n`, { api_key: k, saved: true, credentials_file: ctx.store.file });
+            return 0;
+        }
+        if (ctx.json)
+            ctx.io.stdout.write(`${JSON.stringify({ api_key: k, secret: res.secret, saved: false }, null, 2)}\n`);
+        else {
+            // The key alone on stdout (KEY=$(shard api-keys create ...)); what it is on stderr.
+            ctx.io.stderr.write(`Created ${what}.\nThis is the only time the key is shown; store it now (or next time pass --save).\n`);
+            ctx.io.stdout.write(`${res.secret}\n`);
+        }
+        return 0;
+    },
+    async 'api-keys revoke'(ctx, values, [ref]) {
+        if (values.yes !== true)
+            throw new UsageError('refusing to revoke without --yes (API calls with the key stop at once, workspace tool tokens within 30 s)');
+        const account = ctx.account();
+        const project = await resolveProject(ctx, account, values);
+        let key;
+        let cursor;
+        do {
+            const page = await account.apiKeys.list(project.id, { limit: 200, ...(cursor ? { cursor } : {}) });
+            key = page.data.find((k) => k.id === ref || k.key_id === ref);
+            cursor = key ? undefined : (page.next_cursor ?? undefined);
+        } while (cursor);
+        if (!key)
+            throw new NotFoundError(`No API key "${ref}" in project ${project.name} (${project.id}).`, 'list them: shard api-keys list');
+        await account.apiKeys.revoke(project.id, key.id);
+        const wasSaved = ctx.store.profile(ctx.apiUrl).api_key?.id === key.id;
+        if (wasSaved) {
+            ctx.store.update(ctx.apiUrl, (p) => {
+                delete p.api_key;
+            });
+        }
+        out(ctx, `Revoked API key "${key.name}" ${key.key_id} (${key.id}).${wasSaved ? ' It was the saved key: removed from the credentials file (shard setup saves a new one).' : ''}\n`, { revoked: true, api_key: { ...key, revoked_at: new Date().toISOString() }, removed_from_credentials_file: wasSaved });
+        return 0;
+    },
+    async 'members list'(ctx, values) {
+        const account = ctx.account();
+        const org = await resolveOrg(ctx, account, values);
+        const rows = await allMembers(account, org.id);
+        out(ctx, memberTable(rows), { organization_id: org.id, data: rows, next_cursor: null });
+        return 0;
+    },
+    async 'members set-role'(ctx, values, [ref, role]) {
+        if (!ROLES.includes(role))
+            throw new UsageError(`<role> must be one of ${ROLES.join(', ')} (got "${role}")`);
+        const account = ctx.account();
+        const org = await resolveOrg(ctx, account, values);
+        const m = findMember(await allMembers(account, org.id), ref, org);
+        const updated = await account.members.update(org.id, m.user_id, { role: role });
+        out(ctx, `${updated.email} is now ${updated.role} of ${org.name}.\n`, updated);
+        return 0;
+    },
+    async 'members remove'(ctx, values, [ref]) {
+        if (values.yes !== true)
+            throw new UsageError('refusing to remove without --yes (they lose access to the organization at once)');
+        const account = ctx.account();
+        const org = await resolveOrg(ctx, account, values);
+        const m = findMember(await allMembers(account, org.id), ref, org);
+        const me = await account.me();
+        await account.members.remove(org.id, m.user_id);
+        const self = me.user?.id === m.user_id;
+        if (self)
+            forgetOrganization(ctx, org.id, []);
+        out(ctx, self ? `You left ${org.name}.\n` : `Removed ${m.email} from ${org.name}.\n`, { removed: true, member: m, organization_id: org.id, left: self });
+        return 0;
+    },
+    async 'invitations list'(ctx, values) {
+        const account = ctx.account();
+        const org = await resolveOrg(ctx, account, values);
+        const rows = await allInvitations(account, org.id);
+        out(ctx, rows.length ? invitationTable(rows) : 'No invitations.\n', { organization_id: org.id, data: rows, next_cursor: null });
+        return 0;
+    },
+    async 'invitations create'(ctx, values, [emailText]) {
+        const email = emailArg(emailText, '<email>');
+        const role = need(values, 'role', '--role member');
+        if (!ROLES.includes(role))
+            throw new UsageError(`--role must be one of ${ROLES.join(', ')} (got "${role}")`);
+        const account = ctx.account();
+        const org = await resolveOrg(ctx, account, values);
+        const inv = await account.invitations.create(org.id, { email, role: role });
+        out(ctx, `Invited ${inv.email} to ${org.name} as ${inv.role} (invitation ${inv.id}, expires ${time(inv.expires_at)}). They accept with: shard invitations accept '<link from the email>'\n`, inv);
+        return 0;
+    },
+    async 'invitations revoke'(ctx, values, [ref]) {
+        const account = ctx.account();
+        const org = await resolveOrg(ctx, account, values);
+        let id = ref;
+        if (!UUID.test(id)) {
+            const hit = (await allInvitations(account, org.id)).find((i) => i.status === 'pending' && i.email.toLowerCase() === id.toLowerCase());
+            if (!hit)
+                throw new NotFoundError(`No pending invitation "${ref}" in ${org.name}.`, 'list them: shard invitations list');
+            id = hit.id;
+        }
+        await account.invitations.revoke(org.id, id);
+        out(ctx, `Revoked invitation ${id}.\n`, { revoked: true, id, organization_id: org.id });
+        return 0;
+    },
+    async 'invitations accept'(ctx, values, [link]) {
+        const account = ctx.account();
+        const org = await account.invitations.accept(linkToken(link));
+        if (values.use === true) {
+            ctx.store.update(ctx.apiUrl, (p) => {
+                if (p.organization_id !== org.id)
+                    delete p.project_id;
+                p.organization_id = org.id;
+            });
+        }
+        out(ctx, `You joined ${org.name} (${org.slug}) as ${org.role ?? 'member'}.${values.use === true ? ' It is now the default.' : ` Make it the default: shard orgs use ${org.slug}`}\n`, org);
+        return 0;
+    },
+    async 'billing plans'(ctx) {
+        const catalog = await fetchBillingCatalog({ baseUrl: ctx.apiUrl, fetch: ctx.accountOptions().fetch ?? fetch });
+        out(ctx, planTable(catalog), catalog);
+        return 0;
+    },
+    async 'billing status'(ctx, values) {
+        const account = ctx.account();
+        const org = await resolveOrg(ctx, account, values);
+        const s = await account.billing.subscription(org.id);
+        const next = s.subscription ? 'manage it: shard billing portal' : s.purchase_available ? 'buy a plan: shard billing plans, then shard billing upgrade <plan>' : '';
+        out(ctx, `${billingStatusText(s, org)}${next ? `${next}\n` : ''}`, s);
+        return 0;
+    },
+    async 'billing upgrade'(ctx, values, [planKey]) {
+        const t = str(values.timeout);
+        const timeoutMs = t === undefined ? DEFAULT_CHECKOUT_WAIT_MS : parseDuration(t, 'timeout');
+        const catalog = await fetchBillingCatalog({ baseUrl: ctx.apiUrl, fetch: ctx.accountOptions().fetch ?? fetch });
+        const buyable = purchasablePlans(catalog);
+        const plan = catalog.plans.find((p) => p.plan_key === planKey);
+        const list = buyable.length ? buyable.join(', ') : '(none on this API)';
+        if (!plan)
+            throw new UsageError(`unknown plan "${planKey}"; purchasable plans: ${list} (shard billing plans)`);
+        // With no purchasable plan at all the API itself says why (e.g. billing not configured).
+        if (buyable.length > 0 && !buyable.includes(plan.plan_key))
+            throw new UsageError(`plan "${planKey}" cannot be bought; purchasable plans: ${list} (shard billing plans)`);
+        const account = ctx.account();
+        const org = await resolveOrg(ctx, account, values);
+        let checkout;
+        try {
+            checkout = await account.billing.checkout(org.id, { planKey: plan.plan_key });
+        }
+        catch (err) {
+            if (!(err instanceof ShardfluxApiError && err.code === 'conflict' && err.details?.reason === 'subscription_exists'))
+                throw err;
+            const portal = await account.billing.portal(org.id);
+            const opened = values.open === true && openUrl(portal.url, ctx.io.env);
+            out(ctx, `${org.name} already has a subscription: plan changes happen in the Stripe billing portal (it shows the new price before you confirm):\n${portal.url}\n${values.open === true ? (opened ? 'Opened it in your browser.\n' : 'Could not open a browser; open the URL yourself.\n') : ''}`, { subscription_exists: true, organization_id: org.id, plan_key: plan.plan_key, portal_url: portal.url, opened });
+            return 0;
+        }
+        if (!checkout.url && !checkout.subscription_active)
+            throw new UsageError(`checkout ${checkout.id} is ${checkout.status} and has no URL; start again: shard billing upgrade ${plan.plan_key}`);
+        const opened = values.open === true && checkout.url !== null && openUrl(checkout.url, ctx.io.env);
+        if (!ctx.json) {
+            ctx.io.stdout.write(`Checkout for ${plan.name} (${plan.plan_key}, ${priceText(catalog, plan.plan_key)}) for ${org.name}:\n${checkout.url ?? '-'}\n` +
+                `A person pays there (Stripe Checkout${checkout.expires_at ? `; the link works until ${time(checkout.expires_at)}` : ''}). The plan is active once Stripe confirms the payment${values.wait === true ? '.' : ': shard billing status'}\n` +
+                (values.open === true ? (opened ? 'Opened it in your browser.\n' : 'Could not open a browser; open the URL yourself.\n') : ''));
+        }
+        let final = checkout;
+        if (values.wait === true && !checkout.subscription_active)
+            final = await waitForCheckout(ctx, account, org.id, checkout, timeoutMs);
+        if (ctx.json) {
+            ctx.io.stdout.write(`${JSON.stringify({ subscription_exists: false, organization_id: org.id, plan_key: plan.plan_key, checkout: final, url: checkout.url, opened, subscription_active: final.subscription_active }, null, 2)}\n`);
+        }
+        else if (final.subscription_active)
+            ctx.io.stdout.write(`Subscription active: ${plan.name} for ${org.name}.\n`);
+        return 0;
+    },
+    async 'billing portal'(ctx, values) {
+        const account = ctx.account();
+        const org = await resolveOrg(ctx, account, values);
+        const portal = await account.billing.portal(org.id);
+        const opened = values.open === true && openUrl(portal.url, ctx.io.env);
+        out(ctx, `Billing portal of ${org.name} (plan changes, payment methods, invoices, cancellation; the link is short-lived):\n${portal.url}\n${values.open === true ? (opened ? 'Opened it in your browser.\n' : 'Could not open a browser; open the URL yourself.\n') : ''}`, { organization_id: org.id, url: portal.url, opened });
+        return 0;
+    },
+    async 'billing invoices'(ctx, values) {
+        const account = ctx.account();
+        const org = await resolveOrg(ctx, account, values);
+        const limitText = str(values.limit);
+        const limit = limitText ? parsePositiveInt(limitText, 'limit', 100) : undefined;
+        let rows = [];
+        let next = null;
+        if (values.all === true) {
+            let cursor;
+            do {
+                const page = await account.billing.invoices(org.id, { limit: limit ?? 100, ...(cursor ? { cursor } : {}) });
+                rows.push(...page.data);
+                cursor = page.next_cursor ?? undefined;
+            } while (cursor);
+        }
+        else {
+            const cursor = str(values.cursor);
+            const page = await account.billing.invoices(org.id, { ...(limit ? { limit } : {}), ...(cursor ? { cursor } : {}) });
+            rows = page.data;
+            next = page.next_cursor;
+        }
+        out(ctx, rows.length ? invoiceTable(rows) : 'No invoices.\n', { organization_id: org.id, data: rows, next_cursor: next });
+        if (!ctx.json && next)
+            ctx.io.stderr.write(`more: shard billing invoices --cursor ${next}\n`);
+        return 0;
+    },
+    async 'billing alerts'(ctx, values) {
+        const set = str(values.set);
+        const clear = values.clear === true;
+        if (set !== undefined && clear)
+            throw new UsageError('use --set or --clear, not both');
+        let thresholds = null;
+        if (clear)
+            thresholds = [];
+        else if (set !== undefined) {
+            const parts = set.split(',').map((x) => x.trim().replace(/%$/, ''));
+            if (parts.some((x) => !/^\d+$/.test(x) || Number(x) < 1 || Number(x) > 100))
+                throw new UsageError(`--set takes percentages from 1 to 100 separated by commas, e.g. 50,80,100 (got "${set}")`);
+            thresholds = [...new Set(parts.map(Number))].sort((a, b) => a - b);
+            if (thresholds.length > 5)
+                throw new UsageError('--set takes at most 5 thresholds');
+        }
+        const account = ctx.account();
+        const org = await resolveOrg(ctx, account, values);
+        const policy = thresholds === null ? await account.billing.spendPolicy(org.id) : await account.billing.setSpendPolicy(org.id, { alertThresholdsPercent: thresholds });
+        const now = policy.alert_thresholds.length ? `alerts at ${policy.alert_thresholds.map((p) => `${p}%`).join(', ')} of each allowance` : 'usage alerts are off';
+        out(ctx, `${org.name}: ${now}${thresholds === null ? '' : ' (saved)'}.\n`, policy);
+        return 0;
+    },
+    async 'billing overage'(ctx, values, [action = 'status', amount]) {
+        if (!OVERAGE_ACTIONS.includes(action))
+            throw new UsageError(`unknown action "${action}"; use status, on, off or cap (shard billing overage --help)`);
+        const capText = str(values.cap);
+        if (capText !== undefined && action !== 'on')
+            throw new UsageError(action === 'cap' ? 'give the cap as an argument: shard billing overage cap <dollars>' : `--cap goes with on: shard billing overage on --cap <dollars>`);
+        if (action === 'cap' && amount === undefined)
+            throw new UsageError('missing <dollars> for "shard billing overage cap" (e.g. shard billing overage cap 9)');
+        if (action !== 'cap' && amount !== undefined)
+            throw new UsageError(`unexpected argument "${amount}"${action === 'on' ? '; give the cap with --cap <dollars>' : ''}`);
+        const update = {};
+        if (action === 'on')
+            update.overageEnabled = true;
+        if (action === 'off')
+            update.overageEnabled = false;
+        if (action === 'on' && capText !== undefined)
+            update.spendCapMinor = dollarsToMinor(capText, '--cap');
+        if (action === 'cap')
+            update.spendCapMinor = dollarsToMinor(amount, 'the cap');
+        const version = str(values['if-version']);
+        if (version !== undefined) {
+            if (action === 'status')
+                throw new UsageError('--if-version goes with on, off or cap');
+            if (!/^\d+$/.test(version))
+                throw new UsageError('--if-version must be a policy version number (shard billing overage --json shows it)');
+            update.ifMatch = Number(version);
+        }
+        const account = ctx.account();
+        const org = await resolveOrg(ctx, account, values);
+        const policy = action === 'status' ? await account.billing.spendPolicy(org.id) : await account.billing.setSpendPolicy(org.id, update);
+        out(ctx, overagePolicyText(policy, org.name, action !== 'status'), policy);
+        return 0;
+    },
+    async 'audit list'(ctx, values) {
+        const filters = auditFilters(values);
+        const limitText = str(values.limit);
+        const limit = limitText ? parsePositiveInt(limitText, 'limit', 200) : undefined;
+        const account = ctx.account();
+        const org = await resolveOrg(ctx, account, values);
+        let rows = [];
+        let next = null;
+        if (values.all === true) {
+            for await (const e of account.audit.listAll(org.id, { ...filters, limit: limit ?? 200 })) {
+                rows.push(e);
+                if (ctx.signal.aborted)
+                    throw new InterruptedError('Interrupted.');
+            }
+        }
+        else {
+            const cursor = str(values.cursor);
+            const page = await account.audit.list(org.id, { ...filters, ...(limit ? { limit } : {}), ...(cursor ? { cursor } : {}) });
+            rows = page.data;
+            next = page.nextCursor;
+        }
+        out(ctx, rows.length ? auditTable(rows) : 'No audit events match.\n', { organization_id: org.id, data: rows, next_cursor: next });
+        if (!ctx.json && next)
+            ctx.io.stderr.write(`more: shard audit list --cursor ${next}\n`);
+        return 0;
+    },
+    async 'audit export'(ctx, values) {
+        const filters = auditFilters(values);
+        const format = oneOf(values, 'format', ['ndjson', 'csv']) ?? 'ndjson';
+        const account = ctx.account();
+        const org = await resolveOrg(ctx, account, values);
+        const text = await account.audit.export(org.id, { ...filters, format, signal: ctx.signal });
+        const dest = str(values.out);
+        const rows = text.split('\n').filter((l) => l.trim().length > 0).length - (format === 'csv' ? 1 : 0);
+        if (dest !== undefined) {
+            const bytes = await writePrivate(dest, text, values.force === true);
+            out(ctx, `Wrote ${Math.max(0, rows)} events (${format}, ${bytes} bytes) to ${dest}.\n`, { organization_id: org.id, format, out: dest, bytes, rows: Math.max(0, rows) });
+        }
+        else if (ctx.json)
+            ctx.io.stdout.write(`${JSON.stringify({ organization_id: org.id, format, rows: Math.max(0, rows), content: text }, null, 2)}\n`);
+        else
+            ctx.io.stdout.write(text);
+        return 0;
+    },
+    async 'account status'(ctx) {
+        const account = ctx.account();
+        const me = await account.me();
+        const d = await account.user.deletion();
+        const u = me.user;
+        const lines = [];
+        if (u)
+            lines.push(['user', userLine(u)], ['email', u.email_verified ? 'verified' : 'not verified'], ['two-factor', u.mfa_enabled ? 'on' : 'off']);
+        lines.push(['organizations', me.memberships.length ? me.memberships.map((m) => `${m.organization_name} (${m.organization_slug}, ${m.role})`).join(', ') : 'none']);
+        const r = d.request;
+        lines.push(['deletion', r && r.state === 'scheduled' ? `scheduled: runs after ${time(r.execute_after)} (cancel: shard account cancel-deletion)` : 'not scheduled']);
+        if (d.blocking_organizations.length)
+            lines.push(['blocked by', d.blocking_organizations.map((o) => `${o.name} (${o.slug}): ${o.reason === 'sole_owner' ? 'you are its only owner' : 'you are its only member'}`).join('; ')]);
+        if (d.api_keys_retained.length)
+            lines.push(['keys kept', `${d.api_keys_retained.length} API keys you created stay with their organizations`]);
+        out(ctx, kv(lines), { user: u, memberships: me.memberships, deletion: d });
+        return 0;
+    },
+    async 'account export'(ctx, values) {
+        const account = ctx.account();
+        const created = await withStepUp(ctx, account, () => account.user.exports.create());
+        const { meta, text } = await downloadExport(ctx, account, created, (id) => account.user.exports.get(id), (id) => account.user.exports.download(id, { signal: ctx.signal }));
+        const path = str(values.out) ?? `./account-export-${meta.id}.json`;
+        const bytes = await writePrivate(path, text, values.force === true);
+        out(ctx, dataExportText(meta, path), { export: meta, out: path, bytes });
+        return 0;
+    },
+    async 'account delete'(ctx, values) {
+        if (values.yes !== true)
+            throw new UsageError('refusing to schedule the deletion of your account without --yes');
+        const confirm = need(values, 'confirm', '--confirm you@example.com');
+        const account = ctx.account();
+        const me = await account.me();
+        if (!me.user || confirm.toLowerCase() !== me.user.email.toLowerCase())
+            throw new UsageError(`--confirm must be your email address${me.user ? ` (${me.user.email})` : ''}`);
+        const r = await withStepUp(ctx, account, () => account.user.scheduleDeletion({ confirmation: confirm }));
+        out(ctx, `Your account will be deleted after ${time(r.request.execute_after)}. Every other session was signed out. Cancel before then: shard account cancel-deletion\n`, r);
+        return 0;
+    },
+    async 'account cancel-deletion'(ctx) {
+        const r = await ctx.account().user.cancelDeletion();
+        out(ctx, 'The deletion of your account is canceled.\n', r);
+        return 0;
+    },
+    async 'egress get'(ctx, values) {
+        const target = await egressTarget(ctx, values);
+        const egress = ctx.cloud().egress;
+        if (target.kind === 'workspace') {
+            const p = await egress.getWorkspace(target.ws.id);
+            out(ctx, workspaceEgressText(p), p);
+        }
+        else {
+            const p = await egress.getProject(target.id);
+            out(ctx, projectEgressText(p), p);
+        }
+        return 0;
+    },
+    async 'egress set'(ctx, values) {
+        const file = need(values, 'file', '--file policy.json');
+        const policy = await readPolicy(ctx, file);
+        const opts = ifVersion(values);
+        const target = await egressTarget(ctx, values);
+        const egress = ctx.cloud().egress;
+        if (target.kind === 'workspace') {
+            const p = await egress.putWorkspace(target.ws.id, policy, opts);
+            out(ctx, `Saved the policy of ${target.ws.key} as version ${p.version}; the host applies it (enforcement: ${p.enforcement.state}).\n${workspaceEgressText(p)}`, p);
+        }
+        else {
+            const p = await egress.putProject(target.id, policy, opts);
+            out(ctx, `Saved the project policy as version ${p.version}; hosts apply it to the project's workspaces.\n${projectEgressText(p)}`, p);
+        }
+        return 0;
+    },
+    async 'egress history'(ctx, values) {
+        const limitText = str(values.limit);
+        const limit = limitText ? parsePositiveInt(limitText, 'limit', 200) : undefined;
+        const target = await egressTarget(ctx, values);
+        const egress = ctx.cloud().egress;
+        const page = target.kind === 'workspace' ? await egress.workspaceVersions(target.ws.id, limit ? { limit } : {}) : await egress.projectVersions(target.id, limit ? { limit } : {});
+        out(ctx, page.data.length ? egressVersionTable(page.data) : 'No policy versions yet (the platform default applies).\n', { data: page.data, next_cursor: page.nextCursor });
+        return 0;
+    },
+    async 'egress clear'(ctx, values) {
+        const ref = need(values, 'workspace', '--workspace acme/demo');
+        const ws = await resolveWorkspace(ctx, ref);
+        await ctx.cloud().egress.clearWorkspace(ws.id);
+        out(ctx, `Removed the policy of ${ws.key}: it follows the project policy again.\n`, { cleared: true, workspace_id: ws.id });
+        return 0;
+    },
+    async 'volumes list'(ctx, values) {
+        const cloud = ctx.cloud();
+        const params = { ...(values['include-org-shared'] === true ? { includeOrgShared: true } : {}), ...(values['include-deleted'] === true ? { includeDeleted: true } : {}) };
+        let rows = [];
+        let next = null;
+        if (values.all === true)
+            for await (const v of cloud.volumes.listAll(params))
+                rows.push(v);
+        else {
+            const page = await cloud.volumes.list(params);
+            rows = page.data;
+            next = page.nextCursor;
+        }
+        out(ctx, rows.length ? volumeTable(rows) : 'No volumes.\n', { data: rows, next_cursor: next });
+        if (!ctx.json && next)
+            ctx.io.stderr.write('more: shard volumes list --all\n');
+        return 0;
+    },
+    async 'volumes create'(ctx, values, [name]) {
+        const quota = parsePositiveInt(need(values, 'quota-gib', '--quota-gib 20'), 'quota-gib', 100_000);
+        const r = await waitedVolume(ctx, () => ctx.cloud().volumes.create({ name: name, quotaGib: quota, ...(values['org-shared'] === true ? { orgShared: true } : {}), wait: volumeWait(ctx, values) }));
+        out(ctx, `Volume ${r.volume.name} (${r.volume.id}) is ${r.volume.state}; operation ${r.operation.id} ${r.operation.state}.\n${volumeDetail(r.volume)}`, r);
+        return 0;
+    },
+    async 'volumes get'(ctx, _values, [ref]) {
+        const v = await resolveVolume(ctx, ref);
+        out(ctx, volumeDetail(v), v);
+        return 0;
+    },
+    async 'volumes delete'(ctx, values, [ref]) {
+        if (values.yes !== true)
+            throw new UsageError('refusing to delete without --yes (the volume and its data are deleted)');
+        const v = await resolveVolume(ctx, ref);
+        const r = await waitedVolume(ctx, () => ctx.cloud().volumes.delete(v.id, { ...(values.force === true ? { force: true } : {}), wait: volumeWait(ctx, values) }));
+        out(ctx, `Deleting volume ${v.name} (${v.id}): operation ${r.operation.id} ${r.operation.state}.\n`, r);
+        return 0;
+    },
+    async 'volumes attachments'(ctx, values, [ref]) {
+        const v = await resolveVolume(ctx, ref);
+        const page = await ctx.cloud().volumes.attachments(v.id, { limit: 200, ...(values['include-detached'] === true ? { includeDetached: true } : {}) });
+        out(ctx, page.data.length ? attachmentTable(page.data) : `${v.name} is not attached.\n`, { data: page.data, next_cursor: page.nextCursor });
+        return 0;
+    },
+    async 'volumes attach'(ctx, values, [wsRef, volRef]) {
+        const mount = need(values, 'mount', '--mount /mnt/data');
+        if (!mount.startsWith('/'))
+            throw new UsageError('--mount must be an absolute path, e.g. /mnt/data');
+        const ws = await resolveWorkspace(ctx, wsRef);
+        const v = await resolveVolume(ctx, volRef);
+        const r = await waitedVolume(ctx, () => ctx.cloud().volumes.attach(ws.id, { volumeId: v.id, mountPath: mount, mode: values['read-only'] === true ? 'ro' : 'rw', wait: volumeWait(ctx, values) }));
+        const a = r.attachment;
+        out(ctx, `Attached ${v.name} to ${ws.key} at ${a.mount_path} (${a.mode}): ${a.state}${a.mounted ? ', mounted' : ', mounted on the next start'}.\n`, r);
+        return 0;
+    },
+    async 'volumes detach'(ctx, values, [wsRef, volRef]) {
+        const ws = await resolveWorkspace(ctx, wsRef);
+        const v = await resolveVolume(ctx, volRef);
+        const r = await waitedVolume(ctx, () => ctx.cloud().volumes.detach(ws.id, v.id, { wait: volumeWait(ctx, values) }));
+        out(ctx, `Detaching ${v.name} from ${ws.key}: ${r.attachment.state}.\n`, r);
+        return 0;
+    },
+    async 'templates publish'(ctx, values, [ref]) {
+        const { slug, version } = parseSlugVersion(ref, '<slug@version>');
+        const account = ctx.account();
+        const org = await resolveOrg(ctx, account, values);
+        const t = await account.templates.publishVersion(org.id, slug, version);
+        out(ctx, `Published ${slug} v${version}: new workspaces of ${slug} use the latest published version (existing ones keep theirs).\n`, t);
+        return 0;
+    },
+    async 'templates archive'(ctx, values, [ref]) {
+        const { slug, version } = parseSlugVersion(ref, '<slug@version>');
+        const account = ctx.account();
+        const org = await resolveOrg(ctx, account, values);
+        const t = await account.templates.archiveVersion(org.id, slug, version);
+        out(ctx, `Archived ${slug} v${version}: new opens no longer use it; existing workspaces keep it.\n`, t);
+        return 0;
+    },
+};
+async function allMembers(account, organizationId) {
+    const rows = [];
+    let cursor;
+    do {
+        const page = await account.members.list(organizationId, { limit: 200, ...(cursor ? { cursor } : {}) });
+        rows.push(...page.data);
+        cursor = page.next_cursor ?? undefined;
+    } while (cursor);
+    return rows;
+}
+async function allInvitations(account, organizationId) {
+    const rows = [];
+    let cursor;
+    do {
+        const page = await account.invitations.list(organizationId, { limit: 200, ...(cursor ? { cursor } : {}) });
+        rows.push(...page.data);
+        cursor = page.next_cursor ?? undefined;
+    } while (cursor);
+    return rows;
+}
+function findMember(rows, ref, org) {
+    const hit = rows.find((m) => m.user_id === ref || m.email.toLowerCase() === ref.toLowerCase());
+    if (!hit)
+        throw new NotFoundError(`No member "${ref}" in ${org.name}.`, 'list them: shard members list');
+    return hit;
+}