@chrischall/mcp-host-cli 0.0.0-stage → 2.33.1

package/src/index.mjs

@@ -0,0 +1,1418 @@
+#!/usr/bin/env node
+// mcp-host admin CLI — a thin client for the gateway control API.
+//
+//   export MCP_HOST_URL=https://mcp.nullnet.app
+//   export MCP_HOST_ADMIN_TOKEN=...
+//
+//   mcp-host register            # no flags on a terminal: the interactive wizard (also `mcp-host wizard`)
+//   mcp-host register --slug setlist --npm setlist-mcp --secret-env SETLIST_API_KEY=SETLIST_API_KEY
+//   mcp-host register --slug thing --github owner/repo#main --build "npm run build"
+//   mcp-host register --slug fresh --npm some-pkg --follow   # daily cron follows the latest version
+//   mcp-host register --slug stateful --npm some-pkg --no-data-dir  # opt OUT of the persistent HOME a new registration now gets
+//   mcp-host register --slug kia --npm kiaaccess-mcp --per-user-child \
+//       --auth-flow ./kia-flow.json   # a login that answers back: steps, prompts, capture
+//   mcp-host register --slug gog --npm gogcli-mcp \
+//       --dep 'github:openclaw/gogcli@v0.37.0:gogcli_*_linux_amd64.tar.gz#gog'   # a binary on the child's PATH
+//       [--dep 'npm:<pkg>[@<version>]'] [--dep-sha256 '<asset>=<64hex>']      # sha256 only when GitHub has no digest
+//   mcp-host register --slug memory --npm @modelcontextprotocol/server-memory \
+//       --env 'MEMORY_FILE_PATH=~/memory.jsonl'   # a leading ~ (or ${HOME}) resolves to this registration's actual HOME at spawn time
+//   mcp-host register --slug thing --pypi markitdown-mcp[==0.0.1a4]   # a PyPI package: pinned to a version and its wheel's sha256
+//   mcp-host register --slug thing --mcpb ./thing.mcpb     # an MCPB bundle: uploaded (PUT /api/v1/bundles), then pinned by its sha256
+//   mcp-host register --slug thing --mcpb https://…/thing.mcpb   # fetched by the gateway; --mcpb sha256:<hex> names one already uploaded
+//   mcp-host bundles upload ./thing.mcpb   # upload alone; prints the sha256 to register later or reuse across registrations
+//   mcp-host preview --npm <pkg[@version]> | --github <owner/repo[#ref]> | --pypi <pkg[==version]> | --mcpb … [--dep …]   # resolve, write nothing (a --mcpb path still uploads)
+//   mcp-host list | get <id> | status <id> | logs <id>
+//   mcp-host set <id> --data-dir | --no-data-dir   # persistent HOME, after the fact
+//   mcp-host set <id> --state-store snapshot        # keep that HOME in R2, not on one machine's volume
+//   mcp-host set <id> --dep … | --no-deps           # replace or clear the dependencies
+//   mcp-host set <id> --deny destructive|non-read-only | --allow-all   # the tool policy, judged at the gateway (restarts nothing)
+//   mcp-host set <id> --ask send_mail,delete_event | --no-ask        # hold named tools for the owner's approval
+//   mcp-host set <id> --tools a,b | --all-tools     # narrow the allowlist, or lift it
+//   mcp-host approvals [ls] [--status all] | approvals approve <apr id> | approvals refuse <apr id>
+//   mcp-host me | me set --push-tenant-alerts on|off   # whether alerts about your MCPs are pushed to you
+//   mcp-host profile ls <id> | profile add <id> --label work --secret-env VAR=SECRET | profile set <id> <rpf id> … | profile rm <id> <rpf id>
+//   mcp-host connections rename <prn id> <label> | connections default <prn id> | connections undefault <prn id>
+//   mcp-host prewarm <id> | restart <id> | rm <id>
+//   mcp-host build <id> [--force] [--wait]  # ask the builder for a prebuilt install tree now (needs BUILDER_URL on the gateway); --force rebuilds a ready one (operator-only; a 403 from anyone else), --wait holds on for the manifest
+//   RUNNER_KEY=... mcp-host builder-key   # LEGACY: HMAC(master, 'builder'); the builder now holds BUILDER_KEY
+//   mcp-host secret set NAME --value ... | secret ls | secret rm NAME [--force]
+//       # sealed to the account's runner key BEFORE it leaves this process (docs/SEALED-SECRETS.md);
+//       # prints the fingerprint to compare later. --legacy sends the deprecated gateway-readable body.
+//   mcp-host secret set NAME                             # on a terminal: prompts, without echo
+//   mcp-host secret set KIA_PASSWORD --from-env          # reads $KIA_PASSWORD
+//   mcp-host secret set KIA_PASSWORD --from-env MY_PW    # reads $MY_PW
+//   mcp-host secret fingerprint NAME [--value v | --from-env [VAR]]   # "match" / "NO MATCH", computed locally; exit 0/1
+//   mcp-host connector [--account slug] [--json]   # the account's ONE connect URL, /c/<account>/all/mcp (URL alone on stdout)
+//   mcp-host connector connections | revoke <grant id> | revoke-all [--account slug]   # your aggregate connections, and ending them
+//   mcp-host set <id> --aggregate inline|search|exclude   # how it takes part in that connector (restarts nothing)
+//   mcp-host marketplace [rotate|revoke] [--account slug]
+//   mcp-host bridge [ls|revoke <id>] [--account slug]   # a browser connects from its extension (D18)
+//   mcp-host infra [--days N]     (super-admin: machines, the shared pool, resource totals)
+//   mcp-host infra sync           # bring the shared pool's machine set in step with Fly (#322 phase 4)
+//   mcp-host infra drain <machine id> | undrain <machine id>   # take a pool machine out of / back into placement
+//
+//   mcp-host help   # EVERY command: operations.mjs is the list, one row per
+//                   # control-API operation, held to openapi.json by tests/api-parity.test.ts
+//
+//   --insecure   # allow an http:// MCP_HOST_URL (a development gateway). Without it a
+//                # non-https URL is refused: every request carries the admin bearer.
+
+import { readFile } from 'node:fs/promises';
+import {
+  AGGREGATE_MODES,
+  INSECURE_FLAG,
+  approvalLines,
+  describeApproval,
+  MCPB_USAGE,
+  buildDependencies,
+  buildEnvMap,
+  bundleSummaryLines,
+  deriveMachineKey,
+  firstFlag,
+  flagPresent,
+  insecureGatewayRefusal,
+  mergeToolPolicy,
+  parseArgs,
+  parseGithubSpec,
+  parseMcpbSpec,
+  parseNpmSpec,
+  parseOnOff,
+  parsePypiSpec,
+  parseToolList,
+  readJsonDocument,
+  readSecretEnv,
+  toolPolicyChange,
+  wantsWizard,
+} from './lib.mjs';
+import { runLogin } from './login.mjs';
+import { COMMAND_FLAGS, commandUsage, flagName, helpFor, helpText, matchGeneric, pathParams, usageFor } from './operations.mjs';
+import { makePrompter } from './prompt.mjs';
+import { compareFingerprint, storeSecretSealed } from './secrets.mjs';
+import { runWizard } from './wizard.mjs';
+
+const BASE = (process.env.MCP_HOST_URL ?? '').replace(/\/$/, '');
+const TOKEN = process.env.MCP_HOST_ADMIN_TOKEN ?? '';
+
+/**
+ * `--insecure` is read here, off the whole command line, and REMOVED before
+ * any command parses its own flags — it is a property of where this process
+ * is talking, not of the verb, and every verb reaches the same gateway.
+ *
+ * Removing it is what makes that safe: `parseArgs` gives an undeclared flag
+ * the NEXT token as its value, so an `--insecure` left in `rest` would eat
+ * the flag after it (`register --insecure --slug x` would bind `--slug`).
+ * The one thing it costs is a flag VALUE spelled exactly `--insecure`, which
+ * is stripped wherever it appears — a secret with that value goes in by
+ * `--from-env` or stdin, which is the recommended route for a secret anyway.
+ */
+const INSECURE = process.argv.slice(2).includes(INSECURE_FLAG);
+const ARGV = process.argv.slice(2).filter((arg) => arg !== INSECURE_FLAG);
+/**
+ * `--help` is read the same way and for the same reason: anywhere on the
+ * line, before any command parses, because `parseArgs` would otherwise bind
+ * the next token to it (`list --help` was `--help needs a value`). The same
+ * cost too — a flag VALUE spelled exactly `--help` goes in by `--from-env` or
+ * stdin. `-h` is honoured only as the first word, where it cannot be a value.
+ */
+const HELP = ARGV.includes('--help') || ARGV[0] === '-h';
+
+/**
+ * A non-2xx from the control API, as an Error the caller may catch. Carries
+ * the status so a caller can tell a refusal from an outage; the message is
+ * the one line `fail` prints, so the two paths say the same thing.
+ */
+class ApiError extends Error {
+  constructor(method, path, status, detail) {
+    super(`${method} ${path} -> HTTP ${status}: ${detail}`);
+    this.name = 'ApiError';
+    this.status = status;
+  }
+}
+
+/**
+ * The request never got an answer: DNS, a refused connection, TLS — anything
+ * `fetch` throws rather than resolves (fleet-audit#1421). Its message is the
+ * one line `fail` prints, so a mistyped MCP_HOST_URL is a sentence naming the
+ * URL and the reason, not Node's uncaught-exception frame around `TypeError:
+ * fetch failed`.
+ */
+class GatewayUnreachable extends Error {
+  constructor(error) {
+    const cause = error?.cause;
+    // A dual-stack refusal is an AggregateError whose members carry the code.
+    const why = cause?.code ?? cause?.errors?.find((e) => e?.code)?.code ?? cause?.message ?? error?.message ?? String(error);
+    super(`could not reach ${BASE}: ${why}`);
+    this.name = 'GatewayUnreachable';
+  }
+}
+
+/** `fetch` and the body's text, with a transport failure as a GatewayUnreachable. */
+async function exchange(url, init) {
+  try {
+    const res = await fetch(url, init);
+    return { res, text: await res.text() };
+  } catch (error) {
+    throw new GatewayUnreachable(error);
+  }
+}
+
+/**
+ * One request to the control API; a non-2xx THROWS an ApiError. This is the
+ * variant the wizard gets, because the wizard has retry loops and a
+ * "your secrets already stored stay stored" epilogue that a `process.exit`
+ * mid-conversation would skip — with `api` (below) passed in, none of its
+ * catch blocks could ever run for an HTTP error.
+ */
+async function apiRequest(method, path, body) {
+  requireEnv();
+  const { res, text } = await exchange(`${BASE}${path}`, {
+    method,
+    headers: {
+      authorization: `Bearer ${TOKEN}`,
+      ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+    },
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  });
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    parsed = { raw: text };
+  }
+  if (!res.ok) throw new ApiError(method, path, res.status, parsed.error ?? text);
+  return parsed;
+}
+
+/** `apiRequest` for the one-shot commands: a non-2xx, or no answer at all, is `fail()`, exit 1. */
+async function api(method, path, body) {
+  try {
+    return await apiRequest(method, path, body);
+  } catch (error) {
+    if (error instanceof ApiError || error instanceof GatewayUnreachable) return fail(error.message);
+    throw error;
+  }
+}
+
+/**
+ * `PUT /api/v1/bundles` with a .mcpb read off disk — the ONE request this CLI
+ * makes that is not JSON. The body is the raw bytes under an explicit
+ * Content-Length, because the gateway judges the cap on the header before it
+ * reads a byte and refuses a body without one; a chunked upload would be
+ * refused, not capped. The whole file is read into memory first (64 MiB at
+ * most, by the same cap) so the length is known and the bytes hashed by the
+ * gateway are the bytes on disk. THROWS an ApiError like `apiRequest`, for
+ * the wizard's retry loop; the flags path wraps it in `fail`.
+ *
+ * @param {string} file
+ */
+async function uploadBundle(file) {
+  requireEnv();
+  let bytes;
+  try {
+    bytes = await readFile(file);
+  } catch (error) {
+    throw new Error(`--mcpb: cannot read ${file}: ${error.message}`);
+  }
+  const { res, text } = await exchange(`${BASE}/api/v1/bundles`, {
+    method: 'PUT',
+    headers: {
+      authorization: `Bearer ${TOKEN}`,
+      'content-type': 'application/octet-stream',
+      'content-length': String(bytes.length),
+    },
+    body: bytes,
+  });
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    parsed = { raw: text };
+  }
+  if (!res.ok) throw new ApiError('PUT', '/api/v1/bundles', res.status, parsed.error ?? text);
+  return parsed;
+}
+
+/** `uploadBundle` for the one-shot commands: a refusal is `fail()`, exit 1; the summary goes to stderr. */
+async function uploadBundleOrFail(file) {
+  let view;
+  try {
+    view = await uploadBundle(file);
+  } catch (error) {
+    // An ApiError and an unreadable file both end here: the one line is the message.
+    return fail(error.message);
+  }
+  for (const line of bundleSummaryLines(view)) console.error(line);
+  return view;
+}
+
+function fail(message) {
+  console.error(`mcp-host: ${message}`);
+  process.exit(1);
+}
+
+/**
+ * The env check every request makes — `apiRequest` and `uploadBundle` call
+ * it rather than repeating it — pulled forward for the interactive paths
+ * too: a wizard that asked nine questions and THEN said "set MCP_HOST_URL"
+ * would have wasted every one of them.
+ *
+ * Two things, in this order. The variables have to be SET; and the URL has
+ * to be one the admin bearer may be sent to, which is https unless
+ * `--insecure` says otherwise (`insecureGatewayRefusal` in lib.mjs carries
+ * the reasoning). Order matters for the sentence a person reads: an unset
+ * MCP_HOST_URL is "set it", never a complaint about the scheme of ''.
+ */
+function requireEnv() {
+  if (!BASE || !TOKEN) fail('set MCP_HOST_URL and MCP_HOST_ADMIN_TOKEN in the environment');
+  const refusal = insecureGatewayRefusal(BASE, INSECURE);
+  if (refusal) fail(refusal);
+}
+
+/**
+ * `mcp-host wizard`, and `register` with no flags on a terminal. Refused on
+ * a pipe rather than attempted: a script that hit this would hang on a
+ * prompt nobody is reading, and the flags it should have passed are the
+ * answer. The wizard prints the created registration on stdout exactly as
+ * `register` does, so `mcp-host wizard | jq` still works once the questions
+ * (all on stderr) are answered.
+ */
+async function wizard() {
+  if (!process.stdin.isTTY) fail('the wizard needs a terminal; pass flags instead');
+  requireEnv();
+  const prompter = makePrompter();
+  try {
+    // The THROWING variant: the wizard handles a refused preview, secret or
+    // create itself (re-asking, or saying what stayed stored) and rethrows
+    // only what it cannot recover from, which lands here as `fail`.
+    const { registration } = await runWizard(prompter, apiRequest, { uploadBundle });
+    if (registration) print(registration);
+  } catch (error) {
+    if (error instanceof ApiError) fail(error.message);
+    throw error;
+  } finally {
+    prompter.close();
+  }
+}
+
+/**
+ * The unpinned source named by `--npm`/`--github` (+ `--subdir`/`--build`) or
+ * `--mcpb`, shared by `register` and `preview` so the two cannot read the
+ * flags differently — a preview that resolved a different source from the
+ * one a create would send would be worse than no preview.
+ *
+ * Async for one reason: `--mcpb <path>` UPLOADS. The gateway pins a bundle
+ * by the sha256 of bytes it holds, so a file on this disk has to reach it
+ * before either command can name it — and that is true of `preview` too,
+ * which is the one way a preview writes (the row the upload records; the
+ * URL form writes the same row gateway-side). The summary the upload answers
+ * is printed here, on stderr, because it is the last thing to read before
+ * the create goes out. The other two `--mcpb` forms send what was typed and
+ * the gateway does the fetch or the lookup.
+ *
+ * The refusals for what a bundle cannot carry are the API's own sentences,
+ * so a script matching on them sees one wording whichever side answers.
+ */
+async function sourceFromFlags(parsed) {
+  const npmSpec = firstFlag(parsed, 'npm');
+  const githubSpec = firstFlag(parsed, 'github');
+  const mcpbSpec = firstFlag(parsed, 'mcpb');
+  const pypiSpec = firstFlag(parsed, 'pypi');
+  const named = [npmSpec, githubSpec, mcpbSpec, pypiSpec].filter((s) => s !== undefined).length;
+  if (named !== 1) {
+    fail(
+      `pass exactly one of --npm <pkg[@version]>, --github <owner/repo[#ref]>, --pypi <pkg[==version]> or ${MCPB_USAGE}`,
+    );
+  }
+  if (pypiSpec !== undefined) {
+    // The refusals are the API's own sentences, so a script matching on them
+    // sees one wording whichever side answers — the rule --mcpb already keeps.
+    if (firstFlag(parsed, 'subdir') !== undefined || firstFlag(parsed, 'build') !== undefined) {
+      fail('--subdir and --build are for --github; a PyPI source installs a venv from its resolved requirements');
+    }
+    if ((parsed.flags['dep'] ?? []).length > 0 || (parsed.flags['dep-sha256'] ?? []).length > 0) {
+      fail('a PyPI source installs a venv from its own resolved requirements; dependencies are not supported on it');
+    }
+    try {
+      return parsePypiSpec(pypiSpec);
+    } catch (error) {
+      return fail(error.message);
+    }
+  }
+  if (mcpbSpec !== undefined) {
+    if (firstFlag(parsed, 'subdir') !== undefined || firstFlag(parsed, 'build') !== undefined) {
+      fail('--subdir and --build are for --github; a bundle is unpacked and launched from its manifest');
+    }
+    if ((parsed.flags['dep'] ?? []).length > 0 || (parsed.flags['dep-sha256'] ?? []).length > 0) {
+      fail('an MCPB bundle ships its own tree; dependencies are not supported on it');
+    }
+    if (firstFlag(parsed, 'bin') !== undefined) {
+      fail("an MCPB bundle's command comes from its manifest; --bin is for npm and GitHub sources");
+    }
+    if (parsed.booleans.has('follow')) {
+      fail('an MCPB bundle has no channel to follow; upload a new bundle and PUT the source instead of updatePolicy: follow');
+    }
+    let spec;
+    try {
+      spec = parseMcpbSpec(mcpbSpec);
+    } catch (error) {
+      return fail(error.message);
+    }
+    if (spec.kind === 'url') return { type: 'mcpb', url: spec.url };
+    if (spec.kind === 'sha256') return { type: 'mcpb', sha256: spec.sha256 };
+    const view = await uploadBundleOrFail(spec.path);
+    return { type: 'mcpb', sha256: view.sha256 };
+  }
+  const source = npmSpec ? parseNpmSpec(npmSpec) : parseGithubSpec(githubSpec);
+  if (source.type === 'github') {
+    const subdir = firstFlag(parsed, 'subdir');
+    const build = firstFlag(parsed, 'build');
+    if (subdir) source.subdir = subdir;
+    if (build) source.build = build;
+  }
+  return source;
+}
+
+/** Repeated `--dep` (+ `--dep-sha256`) as the API's dependency input; [] when none. */
+function dependenciesFromFlags(parsed) {
+  try {
+    return buildDependencies(parsed.flags['dep'] ?? [], parsed.flags['dep-sha256'] ?? []);
+  } catch (error) {
+    return fail(error.message);
+  }
+}
+
+/**
+ * `--data-dir` / `--no-data-dir` as the create body's `dataDir`, or NOTHING
+ * when neither was passed.
+ *
+ * Three states rather than two, because the server's absent-value default is
+ * now `true` (docs/GLOBAL-REGISTRATIONS.md §5) and a CLI that collapsed
+ * "unsaid" into `false` would freeze the old default into every script that
+ * never mentioned the flag.
+ */
+function dataDirFromFlags(parsed) {
+  const on = parsed.booleans.has('data-dir');
+  const off = parsed.booleans.has('no-data-dir');
+  if (on && off) fail('pass one of --data-dir or --no-data-dir, not both');
+  if (!on && !off) return {};
+  return { dataDir: on };
+}
+
+/**
+ * The create body from `register`'s flags. Pulled out of the command so the
+ * wizard can build the identical body and so the flags-only path stays
+ * byte-identical: every key below is exactly what `register` always sent, in
+ * the order it sent it, and `dependencies` is omitted when there are none so
+ * a registration without `--dep` serialises as it did before the flag existed.
+ *
+ * There is no `runtime` here and never was: every registration runs on the
+ * shared pool, and since the isolated tier was retired (2026-09-11) that is
+ * the only runtime the API accepts from anybody.
+ *
+ * There is no `egress` either, and that is a fact about WHO this tool is
+ * rather than an omission. `requireEgressPolicy` refuses a create with no
+ * policy from a TENANT and leaves the operator's own rows unrestricted — and
+ * this CLI authenticates with `MCP_HOST_ADMIN_TOKEN` and nothing else, so its
+ * caller is always the operator, `--account` included (an operator scoped into
+ * somebody's account is still the operator deciding). A tenant's create is
+ * made in the portal, which asks. If this tool ever grows a session login, it
+ * grows the question with it.
+ */
+async function buildRegisterBody(parsed) {
+  const slug = firstFlag(parsed, 'slug') ?? fail('--slug is required');
+  // Parsed before the source, so a malformed --dep fails as a sentence
+  // about the grammar before any request — the upload included — is made.
+  const dependencies = dependenciesFromFlags(parsed);
+  const source = await sourceFromFlags(parsed);
+  const account = firstFlag(parsed, 'account');
+  const body = {
+    // Named only when --account scopes the create elsewhere. Absent, the
+    // create handler lands the row in the CALLER's own account (or its
+    // `?account=` scope); a slug defaulted here was a guess about what the
+    // deployment's operator account is called, and a wrong guess minted an
+    // account of that name (beta review 2026-09-10, I2).
+    ...(account !== undefined ? { account } : {}),
+    slug,
+    displayName: firstFlag(parsed, 'name'),
+    source,
+    env: buildEnvMap(parsed.flags['env'] ?? [], parsed.flags['secret-env'] ?? []),
+    enabledTools: parseToolList(firstFlag(parsed, 'tools')),
+    // --follow opts into the daily auto-update cron moving the pin to the
+    // latest published version; omitted, the server default stays 'pinned'.
+    ...(parsed.booleans.has('follow') ? { updatePolicy: 'follow' } : {}),
+    // --data-dir gives this MCP a persistent directory on the runner volume
+    // as its HOME (and MCP_DATA_DIR). Omitted, the SERVER decides, and since
+    // docs/GLOBAL-REGISTRATIONS.md §5 it decides ON: an MCP that keeps a
+    // device id or a session under `~/` was losing it on every scale-to-zero,
+    // and that reads as a broken MCP rather than as a setting nobody set.
+    // --no-data-dir is how somebody says no; the flag pair is sent as an
+    // explicit boolean, and absent stays absent so a scripted create never
+    // pins whatever the default was on the day it was written.
+    ...dataDirFromFlags(parsed),
+    // --per-user-child gives every caller their own child process, which is
+    // what lets the MCP hold THEIR credential rather than its owner's.
+    //
+    // Still a flag, but no longer the only way to get one: since
+    // docs/GLOBAL-REGISTRATIONS.md §5 the server DERIVES it from
+    // `authFields`/`authFlow`, which have always forced it anyway — so
+    // `--auth-flow` alone is enough, and this flag is for an MCP that reads a
+    // per-caller credential the host never sees the shape of.
+    ...(parsed.booleans.has('per-user-child') ? { perUserChild: true } : {}),
+    // --bridge routes this MCP's fetches through the owner's browser rather
+    // than out of the machine (docs/BROWSER-BRIDGE.md). A flag rather than
+    // something inferred from the package, for the reason the mint reader
+    // refuses it too: a registration is bridged because its OWNER said so.
+    // Worth pairing with --data-dir, though not for the reason this note
+    // used to give: the identity is host-provisioned outside the child's HOME
+    // since #655, so a cold start no longer changes the pair code. What a
+    // bridged child still loses without persistence is its other state — a
+    // captured token, a session cache — on every scale-to-zero.
+    ...(parsed.booleans.has('bridge') ? { bridge: true } : {}),
+    // --dep: tools the MCP shells out to that are not in its npm tree
+    // (docs/REGISTERING.md §Dependencies). Sent unresolved; the gateway pins.
+    ...(dependencies.length > 0 ? { dependencies } : {}),
+  };
+  // --auth-flow ./flow.json: the multi-step login (core/src/auth-flow.ts).
+  // Read locally, before anything is sent, so a typo'd path fails as a
+  // sentence about a FILE rather than as a 400 about a registration.
+  const authFlowPath = firstFlag(parsed, 'auth-flow');
+  if (authFlowPath !== undefined) {
+    try {
+      body.authFlow = readJsonDocument(authFlowPath, '--auth-flow');
+    } catch (error) {
+      fail(error.message);
+    }
+  }
+  const bin = firstFlag(parsed, 'bin');
+  if (bin) body.command = { bin };
+  // --data: every create field no flag names (egress, authFields, runtime
+  // args, a marketplace listing, …). The flags are applied OVER it, but only
+  // flags that were PASSED: `env` and `enabledTools` are built even when
+  // their flags are absent ({} and null, which is what the body has always
+  // carried), and spreading those over --data silently dropped its env and
+  // its tool narrowing (auto-review #919). With no --data the body is
+  // unchanged, defaults included.
+  const data = await readDataFlag(firstFlag(parsed, 'data'));
+  const unpassed = new Set();
+  if (parsed.flags['env'] === undefined && parsed.flags['secret-env'] === undefined) unpassed.add('env');
+  if (firstFlag(parsed, 'tools') === undefined) unpassed.add('enabledTools');
+  const said = Object.fromEntries(
+    Object.entries(body).filter(([key, value]) => value !== undefined && !(unpassed.has(key) && key in data)),
+  );
+  return { ...data, ...said };
+}
+
+/**
+ * `--data <json | @file | ->`: a JSON object for the body fields no flag
+ * names. Flags are applied OVER it, so `--data @base.json --limit 5` is the
+ * file with one field changed.
+ */
+async function readDataFlag(value) {
+  if (value === undefined) return {};
+  let text;
+  if (value === '-') text = await readStdin();
+  else if (value.startsWith('@')) {
+    try {
+      return readJsonDocument(value.slice(1), '--data');
+    } catch (error) {
+      return fail(error.message);
+    }
+  } else text = value;
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    return fail(`--data is not valid JSON: ${error.message}`);
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) fail('--data must be a JSON object');
+  return parsed;
+}
+
+/**
+ * `?a=…&b=…` from the `--kebab` flags for `names`, plus `name=1` for each
+ * bare flag in `booleans`; empty when none was passed. The bespoke commands'
+ * half of what runGeneric does, so a row's declared `query` is one call.
+ */
+function queryFor(parsed, names, booleans = []) {
+  const query = new URLSearchParams();
+  for (const name of names) {
+    const value = firstFlag(parsed, flagName(name));
+    if (value !== undefined) query.set(name, value);
+  }
+  for (const name of booleans) if (parsed.booleans.has(flagName(name))) query.set(name, '1');
+  return query.size > 0 ? `?${query}` : '';
+}
+
+/** The list-query names (core/src/list-query.ts), optionally under a prefix. */
+const LIST_QUERY = ['sort', 'order', 'q', 'page', 'perPage'];
+const listQuery = (prefix = '') => LIST_QUERY.map((n) => (prefix ? `${prefix}${n[0].toUpperCase()}${n.slice(1)}` : n));
+
+/** One typed body flag's value, or a failure naming the flag. */
+function coerceField(flag, type, raw) {
+  if (type === 'string') return raw;
+  if (type === 'integer' || type === 'number') {
+    const n = Number(raw);
+    if (raw.trim() === '' || !Number.isFinite(n) || (type === 'integer' && !Number.isInteger(n))) fail(`--${flag} takes ${type === 'integer' ? 'an integer' : 'a number'}, not ${raw}`);
+    return n;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    return fail(`--${flag} takes JSON: ${error.message}`);
+  }
+}
+
+/**
+ * Execute a GENERIC row of operations.mjs: the whole of what the CLI does for
+ * an operation that is one request and a printed answer. Positionals named in
+ * the path fill it (encoded); the rest are body fields; each declared query
+ * name is a `--kebab` flag, and so is each declared body field. A flag the row
+ * does not declare is REFUSED rather than ignored — `parseArgs` would bind the
+ * next token to it, and a typo'd `--linez 5` quietly tailing the default is
+ * exactly the silent option this table exists to stop.
+ */
+async function runGeneric(row, argv) {
+  const body = row.body ?? {};
+  const booleans = Object.entries(body).filter(([, t]) => t === 'boolean').map(([f]) => flagName(f));
+  const usage = `usage: mcp-host ${usageFor(row)}`;
+  const known = [...(row.query ?? []).map(flagName), ...Object.keys(body).map(flagName), ...(row.body ? ['data'] : [])];
+  const parsed = parseFlags(argv, known, booleans, [], usage);
+  refuseUnknownFlags(parsed, known, usage);
+  const args = row.args ?? [];
+  if (parsed.positionals.length !== args.length) fail(usage);
+
+  const [method, template] = row.op.split(' ');
+  const params = pathParams(row.op);
+  let path = template;
+  params.forEach((name, i) => {
+    path = path.replace(`{${name}}`, encodeURIComponent(parsed.positionals[i]));
+  });
+  const query = new URLSearchParams();
+  for (const name of row.query ?? []) {
+    const value = firstFlag(parsed, flagName(name));
+    if (value !== undefined) query.set(name, value);
+  }
+  if (query.size > 0) path += `?${query}`;
+
+  if (!row.body) return print(await api(method, path));
+  const payload = await readDataFlag(firstFlag(parsed, 'data'));
+  args.slice(params.length).forEach((field, i) => {
+    payload[field] = parsed.positionals[params.length + i];
+  });
+  for (const [field, type] of Object.entries(body)) {
+    const flag = flagName(field);
+    if (type === 'boolean') {
+      if (parsed.booleans.has(flag)) payload[field] = true;
+      continue;
+    }
+    const raw = firstFlag(parsed, flag);
+    if (raw !== undefined) payload[field] = coerceField(flag, type, raw);
+  }
+  return print(await api(method, path, payload));
+}
+
+/**
+ * `logs <id> [--lines N]`: the `/logs` route, printed as the bare array of
+ * lines this command has always printed (it read `status.instance.lastStderr`,
+ * a string[], before the route existed). Scripts parse that shape, so the
+ * route moved and the output did not; the timestamps are what `status` and the
+ * portal are for.
+ */
+async function logs(argv) {
+  const parsed = parseKnown(argv, 'logs');
+  const id = need(parsed.positionals[0], 'id');
+  const result = await api('GET', `/api/v1/registrations/${encodeURIComponent(id)}/logs${queryFor(parsed, ['lines'])}`);
+  return print((result.logs ?? []).map((entry) => entry.line));
+}
+
+/** Refuse any flag outside `known`, naming the usage line. */
+function refuseUnknownFlags(parsed, known, usage) {
+  for (const name of [...Object.keys(parsed.flags), ...parsed.booleans]) {
+    if (!known.includes(name)) fail(`unknown flag --${name}\n${usage}`);
+  }
+}
+
+/**
+ * `parseArgs`, with its throw as a `fail`. A flag outside `known` that fails
+ * to parse — `--typo` last on the line, which "needs a value" — is reported
+ * as what it is: an unknown flag.
+ */
+function parseFlags(argv, known, booleans, optional, usage) {
+  try {
+    return parseArgs(argv, new Set(booleans), new Set(optional));
+  } catch (error) {
+    const stranger = argv.find((arg) => arg.startsWith('--') && !known.includes(arg.slice(2)));
+    return fail(stranger ? `unknown flag ${stranger}\n${usage}` : error.message);
+  }
+}
+
+/** Every flag a COMMAND_FLAGS entry accepts. */
+const knownFlags = (spec) => [...(spec.values ?? []), ...(spec.booleans ?? []), ...(spec.optional ?? [])];
+
+/**
+ * Parse argv for a hand-written command that reads its SUBCOMMAND off the
+ * positionals, so which entry of COMMAND_FLAGS applies is known only after
+ * parsing: parse with the union of `keys`, then `refuseFor` the one it was.
+ */
+function parseCommand(argv, keys) {
+  const specs = keys.map((key) => COMMAND_FLAGS[key]);
+  const union = (field) => [...new Set(specs.flatMap((spec) => spec[field] ?? []))];
+  return parseFlags(argv, specs.flatMap(knownFlags), union('booleans'), union('optional'), commandUsage(keys[0]));
+}
+
+/** Refuse a flag the command `key` does not take, with that command's usage line. */
+function refuseFor(parsed, key) {
+  refuseUnknownFlags(parsed, knownFlags(COMMAND_FLAGS[key]), commandUsage(key));
+}
+
+/** Parse argv for the one command `key`, refusing any flag it does not take, before any request. */
+function parseKnown(argv, key) {
+  const parsed = parseCommand(argv, [key]);
+  refuseFor(parsed, key);
+  return parsed;
+}
+
+/**
+ * `approvals [ls]`: the tool calls a policy said to ASK about (spec 2026-10-19
+ * D3). The JSON on stdout is the listing as the API answered it; stderr gets
+ * one line per row — MCP, tool, argument preview, time left — because what a
+ * person does with this list is decide, and a JSON blob is not where the
+ * expiry of the request they are about to approve should have to be found.
+ */
+async function approvals(argv) {
+  if (argv[0] === 'approve') return approve(argv.slice(1));
+  const usage = commandUsage('approvals');
+  const parsed = parseKnown(argv, 'approvals');
+  const names = ['status', 'account', ...listQuery()];
+  const [sub, ...extra] = parsed.positionals;
+  if ((sub !== undefined && sub !== 'ls') || extra.length > 0) fail(usage);
+  const listed = await api('GET', `/api/v1/approvals${queryFor(parsed, names)}`);
+  print(listed);
+  const rows = listed.approvals ?? [];
+  if (rows.length === 0) {
+    console.error(`mcp-host: nothing waiting for approval${firstFlag(parsed, 'status') ? ` (status ${firstFlag(parsed, 'status')})` : ''}`);
+    return;
+  }
+  for (const line of approvalLines(rows)) console.error(line);
+  if (rows.some((row) => row.status === 'pending')) {
+    console.error('  mcp-host approvals approve <id>   |   mcp-host approvals refuse <id>');
+  }
+}
+
+/**
+ * `approvals approve <id> [--account slug] [--yes]` (fleet-audit#1454): the
+ * approval is READ first and shown — MCP, tool, argument preview, time left —
+ * because the id usually arrives from a notification and approving is what
+ * lets a call a policy held back go through. Then it needs `--yes`, or a "y"
+ * at a terminal; on a pipe without `--yes` nothing is approved. There is no
+ * one-approval read in the API, so the listing (every status, unpaged) is
+ * where it is found.
+ */
+async function approve(argv) {
+  const usage = commandUsage('approvals approve');
+  const parsed = parseKnown(argv, 'approvals approve');
+  if (parsed.positionals.length !== 1) fail(usage);
+  const [id] = parsed.positionals;
+  const read = new URLSearchParams({ status: 'all' });
+  const account = firstFlag(parsed, 'account');
+  if (account !== undefined) read.set('account', account);
+  const listed = await api('GET', `/api/v1/approvals?${read}`);
+  const found = (listed.approvals ?? []).find((row) => row.id === id);
+  if (!found) fail(`no approval ${id} here (\`mcp-host approvals ls --status all\` lists them); nothing approved`);
+  const { where, preview, when } = describeApproval(found);
+  console.error(`mcp-host: approving ${where}  ${preview || '(no arguments)'}  (${found.status}, ${when})`);
+  if (!parsed.booleans.has('yes')) {
+    if (!process.stdin.isTTY) fail('nothing approved: pass --yes to approve without a terminal');
+    const prompter = makePrompter();
+    let yes;
+    try {
+      yes = await prompter.confirm('Approve this call?', false);
+    } finally {
+      prompter.close();
+    }
+    if (!yes) fail('nothing approved');
+  }
+  return print(await api('POST', `/api/v1/approvals/${encodeURIComponent(id)}/approve${queryFor(parsed, ['account'])}`));
+}
+
+/**
+ * `me set --push-tenant-alerts on|off`: the owner's own switch for pushes
+ * about their MCPs (spec 2026-10-19 D4). Every other `me …` is a generic row
+ * and never reaches here. `--data` is kept because the generic row this
+ * replaced took a body (#1171); the flag wins over it, as in profileWrite.
+ */
+async function meSet(argv) {
+  const usage = commandUsage('me set');
+  const [sub, ...more] = argv;
+  if (sub !== 'set') {
+    console.error(helpText());
+    return process.exit(1);
+  }
+  const parsed = parseKnown(more, 'me set');
+  if (parsed.positionals.length > 0) fail(usage);
+  const body = await readDataFlag(firstFlag(parsed, 'data'));
+  const raw = firstFlag(parsed, 'push-tenant-alerts');
+  if (raw !== undefined) {
+    try {
+      body.pushTenantAlerts = parseOnOff(raw, '--push-tenant-alerts');
+    } catch (error) {
+      return fail(error.message);
+    }
+  }
+  if (Object.keys(body).length === 0) fail(`nothing to set: pass --push-tenant-alerts on|off\n${usage}`);
+  return print(await api('PUT', '/api/v1/me', body));
+}
+
+/**
+ * `profile add|set`: a profile's overlay from repeated `--secret-env
+ * VAR=SECRET` (the register spelling), or `--env <json>` for a script, plus
+ * `--label`. Naming both overlay forms is a mistake, not a precedence
+ * question. `--data` carries anything no flag names; the flags win over it.
+ * `profile ls|rm` are generic rows and never reach here.
+ */
+async function profileWrite(argv) {
+  const [sub, ...more] = argv;
+  if (sub !== 'add' && sub !== 'set') {
+    console.error(helpText());
+    return process.exit(1);
+  }
+  const usage = commandUsage(`profile ${sub}`);
+  const parsed = parseKnown(more, `profile ${sub}`);
+  const ids = parsed.positionals;
+  if (ids.length !== (sub === 'add' ? 1 : 2)) fail(usage);
+  const secretEnv = parsed.flags['secret-env'];
+  const envJson = firstFlag(parsed, 'env');
+  if (secretEnv !== undefined && envJson !== undefined) fail('pass --secret-env or --env, not both');
+  const body = await readDataFlag(firstFlag(parsed, 'data'));
+  const label = firstFlag(parsed, 'label');
+  if (label !== undefined) body.label = label;
+  if (secretEnv !== undefined) {
+    try {
+      body.env = buildEnvMap([], secretEnv);
+    } catch (error) {
+      return fail(error.message);
+    }
+  } else if (envJson !== undefined) {
+    body.env = coerceField('env', 'json', envJson);
+  }
+  if (sub === 'add') {
+    if (body.label === undefined) fail(`--label is required\n${usage}`);
+    if (body.env === undefined) fail(`pass --secret-env VAR=SECRET (repeatable) or --env <json>\n${usage}`);
+  } else if (Object.keys(body).length === 0) {
+    fail(`nothing to set: pass --label, --secret-env or --env\n${usage}`);
+  }
+  const [id, profileId] = ids.map((part) => encodeURIComponent(part));
+  const path = `/api/v1/registrations/${id}/profiles${sub === 'set' ? `/${profileId}` : ''}${queryFor(parsed, ['account'])}`;
+  return print(await api(sub === 'add' ? 'POST' : 'PUT', path, body));
+}
+
+function print(value) {
+  console.log(JSON.stringify(value, null, 2));
+}
+
+async function main() {
+  const [command, ...rest] = ARGV;
+
+  if (command === 'help' || HELP) {
+    console.log(helpFor(ARGV.filter((arg) => arg !== '--help' && arg !== '-h' && arg !== 'help')));
+    return;
+  }
+  // A one-request operation is a row of operations.mjs, executed by data.
+  const row = matchGeneric(ARGV);
+  if (row) return runGeneric(row, ARGV.slice(row.words.length));
+
+  switch (command) {
+    case 'wizard':
+      return wizard();
+    case 'builder-key': {
+      // LEGACY (audit 2026-09-01, finding 3). This prints HMAC(master,
+      // 'builder') — which is exactly the problem: every POOL machine holds
+      // the master, so every pool machine can mint the one identity allowed to
+      // publish an artifact the whole fleet executes. The builder's key is now
+      // BUILDER_KEY, an independent secret (`openssl rand -hex 32`,
+      // docs/DEPLOY.md §6), and the gateway REFUSES this derived value as soon
+      // as BUILDER_KEY is set.
+      //
+      // Kept because a deployment mid-migration still runs on it, and because
+      // an operator debugging a 401 needs to see the value the old builder is
+      // presenting. The note goes to STDERR: stdout stays the bare key so
+      // `$(mcp-host builder-key)` is unchanged for anyone still on it.
+      const master = process.env.RUNNER_KEY;
+      if (!master) fail('set RUNNER_KEY (the gateway\'s master runner key) in the environment');
+      console.error(
+        'warning: builder-key prints the LEGACY derived builder key. Every pool machine can mint it. ' +
+          'The builder now holds BUILDER_KEY, an independent secret — see docs/DEPLOY.md §6.',
+      );
+      console.log(deriveMachineKey(master, 'builder'));
+      return;
+    }
+    case 'register': {
+      const parsed = parseKnown(rest, 'register');
+      // No argv at all, and a person at a terminal: the wizard. Only then —
+      // any flag at all means the flags path (`--account x` with no slug is
+      // a mistyped command, not a request for questions that would discard
+      // the flag), whose errors (a missing --slug first) a script may be
+      // matching on, and a pipe keeps those errors byte-identical.
+      if (wantsWizard(rest, process.stdin.isTTY)) return wizard();
+      const body = await buildRegisterBody(parsed);
+      const created = await api('POST', '/api/v1/registrations', body);
+      print(created);
+      console.error('\nAdd to claude.ai: Settings -> Connectors -> Add custom connector ->');
+      // The short, account-free URL where the gateway offers one — it is
+      // resolved in the calling account, so it is the one to paste — falling
+      // back to the account-qualified URL an older gateway reports. Both work.
+      console.error(`  URL: ${created.shortConnectUrl ?? created.connectUrl}`);
+      console.error('  Sign in there and approve the connection — no key to paste.');
+      return;
+    }
+    case 'build': {
+      // Already built answers from the store; --force asks the builder anyway
+      // (operator-only — the gateway answers a 403 to anyone else, since the
+      // flag skips the short-circuit onto the fleet's one serial builder).
+      // The ask is QUEUED (202, "building") unless --wait, which holds on for
+      // the manifest — a github build with devDependencies can take minutes,
+      // so waiting is the option: `mcp-host status <id>` shows the outcome.
+      const parsed = parseKnown(rest, 'build');
+      const id = need(parsed.positionals[0], 'id');
+      const result = await api('POST', `/api/v1/registrations/${encodeURIComponent(id)}/build${queryFor(parsed, [], ['force', 'wait'])}`);
+      if (result.accepted === true) {
+        console.error(`mcp-host: build queued; \`mcp-host status ${id}\` shows artifact: ready|failed when it lands (or rerun with --wait)`);
+      }
+      return print(result);
+    }
+    case 'set': {
+      // Edit ONE registration in place. The control API's PUT is a partial
+      // patch — an omitted field is left alone — so this sends only what was
+      // asked for and is the extension point for the rest of the patch.
+      //
+      // `--data-dir` exists here and not only on `register` because the flag
+      // is one an owner reaches for AFTER the fact: an MCP that turns out to
+      // keep a cache or a session under `~/` is losing it on every idle stop
+      // (the runner says so on `status`), and the fix must not require
+      // hand-rolling a PUT.
+      const parsed = parseKnown(rest, 'set');
+      // From the positionals, never rest[0]: with the flag written first that
+      // would take `--data-dir` for the id.
+      const id = need(parsed.positionals[0], 'id');
+      // Every argv refusal BEFORE any request: the policy and allowlist flags
+      // below read the registration first, and a malformed flag must not cost
+      // a round trip (or, for --tools, a machine spawn) to be refused.
+      let policyChange;
+      let tools;
+      try {
+        policyChange = toolPolicyChange(parsed);
+        tools = parseToolList(firstFlag(parsed, 'tools'));
+      } catch (error) {
+        fail(error.message);
+      }
+      const allTools = parsed.booleans.has('all-tools');
+      if (allTools && tools !== null) fail('pass --tools or --all-tools, not both');
+      if (!AGGREGATE_MODES.includes(firstFlag(parsed, 'aggregate') ?? 'search')) {
+        fail('--aggregate takes inline, search or exclude');
+      }
+      const on = parsed.booleans.has('data-dir');
+      const off = parsed.booleans.has('no-data-dir');
+      if (on && off) fail('pass one of --data-dir or --no-data-dir, not both');
+      // --data: any PUT field no flag names (egress, env, enabledTools,
+      // authFields, status, …); the flags below are applied over it.
+      const patch = await readDataFlag(firstFlag(parsed, 'data'));
+      if (on || off) patch.dataDir = on;
+      // --state-store volume|snapshot: WHERE that directory lives (#521).
+      //
+      // `volume` is the machine-local one `dataDir` has always meant on
+      // fly-shared, and it is what every row reads until somebody changes it.
+      // `snapshot` moves the registration onto the sealed R2 archive the
+      // retired isolated tier used, so losing a pool machine stops losing its
+      // state —
+      // which is what a lost machine did to honeybook's fetchproxy identity,
+      // and therefore to its browser pairing.
+      //
+      // Moving OFF `snapshot` RETIRES the archive in the same write, because a
+      // snapshot nothing is writing goes stale and restoring it later would be
+      // a resurrection rather than a restore. The server does that; it is said
+      // here so the flag does not read as reversible bookkeeping.
+      const stateStore = firstFlag(parsed, 'state-store');
+      if (stateStore !== undefined) {
+        if (stateStore !== 'volume' && stateStore !== 'snapshot') {
+          fail('--state-store takes volume or snapshot');
+        }
+        patch.stateStore = stateStore;
+      }
+      // --dep REPLACES the list (the PUT takes the whole array, and a merge
+      // would leave no way to drop one), and --no-deps clears it. Naming both
+      // is a mistake rather than a precedence question.
+      const dependencies = dependenciesFromFlags(parsed);
+      const noDeps = parsed.booleans.has('no-deps');
+      if (dependencies.length > 0 && noDeps) fail('pass --dep or --no-deps, not both');
+      if (dependencies.length > 0) patch.dependencies = dependencies;
+      else if (noDeps) patch.dependencies = [];
+      // --follow / --no-follow: hand the daily auto-update cron permission to
+      // move this row's pin, or take it back. It exists on `set` and not only
+      // on `register` for the reason --data-dir does: it is a decision an owner
+      // makes AFTER the fact — a row that has fallen behind its siblings, or
+      // one that must hold a pin through a bad upstream release — and the fix
+      // should not require hand-rolling a PUT.
+      //
+      // `follow` does NOT loosen the pin: the row still names one exact
+      // version, and the cron re-resolves through the same resolver and writes
+      // through the same path a source PUT takes. It only decides who may move
+      // it. An `mcpb` source has no channel to follow and the server refuses
+      // it there; that refusal is left to the server, which is the only side
+      // that knows the source kind of a row this command has not fetched.
+      const follow = parsed.booleans.has('follow');
+      const noFollow = parsed.booleans.has('no-follow');
+      if (follow && noFollow) fail('pass one of --follow or --no-follow, not both');
+      if (follow || noFollow) patch.updatePolicy = follow ? 'follow' : 'pinned';
+      // --bridge-approval account|prompt (plan task B4, spec §4.5): how a
+      // browser attach is consented to. `prompt` makes every account
+      // attestation for this registration confirm-each; `account` lets an
+      // attach be silent once an owner has approved its scope. Setting it back
+      // to `account` as anyone but the scope's approver moves that approval
+      // back to a proposal — the server does that, and says so on
+      // `bridge-scope`.
+      const bridgeApproval = firstFlag(parsed, 'bridge-approval');
+      if (bridgeApproval !== undefined) {
+        if (bridgeApproval !== 'account' && bridgeApproval !== 'prompt') {
+          fail('--bridge-approval takes account or prompt');
+        }
+        patch.bridgeApproval = bridgeApproval;
+      }
+      // --deny destructive|non-read-only / --allow-all / --ask a,b / --no-ask:
+      // the tool POLICY (spec D1). Bookkeeping, not configuration — judged at
+      // the gateway, so saving it moves no configHash and restarts nothing.
+      // The PUT replaces it WHOLE, so a flag naming one half (deny classes, or
+      // the ask list) keeps the other: from `--data`'s toolPolicy when that
+      // names one, else read off the registration first. A change naming both
+      // halves has nothing stored to keep and reads nothing.
+      // --aggregate inline|search|exclude (plan task G4, spec D8): how this
+      // registration takes part in the account's aggregate connector
+      // (`mcp-host connector`). Bookkeeping like the policy — saving it moves
+      // no configHash and restarts nothing — and a whole value, so unlike the
+      // policy it has nothing stored to keep and reads nothing first.
+      const aggregate = firstFlag(parsed, 'aggregate');
+      if (aggregate !== undefined) patch.aggregate = aggregate;
+      if (policyChange !== null) {
+        const both = policyChange.deny !== undefined && policyChange.ask !== undefined;
+        const base =
+          patch.toolPolicy ??
+          (both ? undefined : (await api('GET', `/api/v1/registrations/${encodeURIComponent(id)}`)).toolPolicy);
+        patch.toolPolicy = mergeToolPolicy(base, policyChange);
+      }
+      // --tools a,b: narrow the allowlist (the gap this flag closes: it
+      // existed on `register` only). A save of the allowlist ACKNOWLEDGES the
+      // new-tools review for `reviewedTools ∪ enabledTools` — and with no
+      // `reviewedTools` at all, for every name the gateway holds, including
+      // ones this terminal never showed. So the menu is read and PRINTED first
+      // (the `tools <id>` read, which may start an idle child, as that command
+      // does), and exactly those names are sent. When the menu cannot be read
+      // (a disabled registration refuses it), only the named tools are
+      // acknowledged, and that is said.
+      if (tools !== null) {
+        let reviewed = tools;
+        try {
+          const menu = await apiRequest('GET', `/api/v1/registrations/${encodeURIComponent(id)}/tools`);
+          reviewed = (menu.tools ?? []).map((tool) => tool.name).filter((name) => typeof name === 'string');
+          console.error(`mcp-host: the tool menu (acknowledged as reviewed): ${reviewed.join(', ') || '(empty)'}`);
+        } catch (error) {
+          if (!(error instanceof ApiError)) throw error;
+          console.error(`mcp-host: the tool menu could not be read (${error.message}); acknowledging only the named tools`);
+        }
+        patch.enabledTools = tools;
+        patch.reviewedTools = reviewed;
+      }
+      // --all-tools: back to allow-all (`enabledTools: null`), the inverse
+      // --tools lacked. Nothing to acknowledge: allow-all serves every tool the
+      // child publishes, so there is no new-tools review left to answer, and
+      // nothing is read first.
+      if (allTools) patch.enabledTools = null;
+      // Toggling dataDir or the dependencies moves configHash and so restarts
+      // the child; a PUT that patches nothing would spend that restart for no change.
+      if (Object.keys(patch).length === 0)
+        fail(
+          'nothing to set: pass --data-dir, --no-data-dir, --state-store, --follow, --no-follow, --bridge-approval, --dep, --no-deps, ' +
+            '--deny, --allow-all, --ask, --no-ask, --tools, --all-tools, --aggregate or --data <json>',
+        );
+      return print(await api('PUT', `/api/v1/registrations/${encodeURIComponent(id)}`, patch));
+    }
+    case 'preview': {
+      // POST /api/v1/registrations/preview: everything a create WOULD resolve
+      // — the exact pin, each dependency's pin, the package's bins, proposed
+      // env — and it writes nothing (docs/REGISTERING.md §Preview). The same
+      // source and --dep flags as `register`, read by the same code, so what
+      // the preview resolved is what the register will send.
+      const parsed = parseKnown(rest, 'preview');
+      const dependencies = dependenciesFromFlags(parsed);
+      const source = await sourceFromFlags(parsed);
+      return print(
+        await api('POST', '/api/v1/registrations/preview', {
+          source,
+          ...(dependencies.length > 0 ? { dependencies } : {}),
+        }),
+      );
+    }
+    case 'bundles': {
+      // `bundles upload <path>`: the upload on its own. What it prints is
+      // the sha256 — the pin — so a bundle uploaded once can be registered
+      // later (`--mcpb sha256:<hex>`) or by several registrations, and THIS
+      // ACCOUNT uploading the same bytes twice answers `existed: true` with
+      // the same row. Scoped to the caller, never to the deployment: another
+      // account's identical bytes answer `existed: false`, because a
+      // fleet-wide flag is a hash oracle (2026-09-01 audit, finding 16).
+      const parsed = parseCommand(rest, ['bundles upload']);
+      const [sub, file] = parsed.positionals;
+      if (sub === 'upload') {
+        refuseFor(parsed, 'bundles upload');
+        const view = await uploadBundleOrFail(need(file, 'bundle path'));
+        print(view);
+        console.error(`\nRegister it: mcp-host register --slug <slug> --mcpb sha256:${view.sha256}`);
+        return;
+      }
+      return fail('bundles subcommands: upload <path.mcpb>');
+    }
+    case 'infra': {
+      // The super-admin infrastructure view: machines per Fly app, the shared
+      // pool's machine set, then the windowed per-registration resource spend
+      // and the deployment total. Parse FIRST and read the subcommand from the
+      // positionals, for the reason `marketplace` does: `infra --days 7` must
+      // stay the view, not bind `7` as a verb.
+      const parsed = parseCommand(rest, ['infra', 'infra sync', 'infra drain', 'infra undrain']);
+      const [sub, machineId] = parsed.positionals;
+      if (sub === undefined || sub === 'sync' || sub === 'drain' || sub === 'undrain') refuseFor(parsed, sub ? `infra ${sub}` : 'infra');
+      if (sub === 'sync') {
+        // The pool's set is what the gateway PLACES over, so a machine that
+        // `fly scale count` added serves nothing until it is synced in, and
+        // one destroyed without a drain keeps being placed until then (the
+        // first request to it heals that; the cron does it daily). Refused
+        // machines are listed with the reason — a machine with no volume is
+        // the usual one (docs/DEPLOY.md).
+        const outcome = await api('POST', '/api/v1/infra/shared-machines/sync');
+        print(outcome);
+        for (const r of outcome.refused) console.error(`refused ${r.machineId} (${r.name ?? '-'}): ${r.reason}`);
+        return;
+      }
+      if (sub === 'drain' || sub === 'undrain') {
+        if (!machineId) return fail(`usage: mcp-host infra ${sub} <machine id>`);
+        const out = await api('POST', `/api/v1/infra/shared-machines/${encodeURIComponent(machineId)}/${sub}`);
+        print(out);
+        if (sub === 'drain') {
+          console.error('\nIts registrations fall to their runner-up on their next request; nothing is moved for them.');
+          console.error('A dataDir registration leaves its /data/state behind on this machine (docs/DEPLOY.md).');
+        }
+        return;
+      }
+      if (sub !== undefined) return fail('infra subcommands: (none = view) | sync | drain <machine id> | undrain <machine id>');
+      const data = await api('GET', `/api/v1/infra${queryFor(parsed, ['account', 'days', ...listQuery('res')])}`);
+      // One section. There was a second, the isolated app's, and it went with
+      // that tier (2026-09-11); the loop stays a loop because the shape here is
+      // "one block per app" and the next app added is rendered the same way.
+      for (const [label, section] of [['shared runner', data.machines.shared]]) {
+        console.log(`# ${label} (${section.app ?? 'unconfigured'})`);
+        if (!section.available) {
+          console.log(`  unavailable: ${section.reason ?? 'unknown'}`);
+          continue;
+        }
+        if (section.machines.length === 0) console.log('  no machines');
+        for (const m of section.machines) {
+          console.log(
+            `  ${m.id}  ${m.state ?? '?'}  ${m.name ?? '-'}  ${m.region ?? '-'}  ` +
+              `${m.cpus ?? '?'}cpu/${m.memoryMb ?? '?'}MB  ${m.image ?? '-'}`,
+          );
+        }
+      }
+      // The pool: every row with its state, and the share each LIVE machine
+      // would receive if every enabled fly-shared registration asked now —
+      // a prediction from placement, not a ledger, which is why the column
+      // is called that. An empty set is the pre-pool behaviour (no pin).
+      const pool = data.sharedPool;
+      if (pool) {
+        console.log(`# shared pool (${pool.app ?? 'unconfigured'}): ${pool.placing} registrations placed`);
+        if (pool.machines.length === 0) console.log('  empty set: no pin sent, Fly picks (run `mcp-host infra sync` to join machines)');
+        for (const m of pool.machines) {
+          console.log(
+            `  ${m.machineId}  ${m.state}  ${m.name ?? '-'}  ${m.region ?? '-'}  ` +
+              `${m.registrations} would place here  seen ${m.lastSeenAt ?? '-'}`,
+          );
+        }
+      }
+      console.log(`# resources (last ${data.window.days}d)`);
+      for (const line of data.resources) {
+        console.log(
+          `  ${line.slug ?? line.registrationId}  ${line.requests} req` +
+            `${line.errors ? ` (${line.errors} err)` : ''}  up ${Math.round(line.upMs / 1000)}s  ` +
+            `cpu ${Math.round(line.cpuMs / 1000)}s  out ${line.egressBytesOut}B  ` +
+            `est $${(line.estimatedCents / 100).toFixed(4)}`,
+        );
+      }
+      const t = data.totals;
+      console.log(
+        `# total: ${t.requests} req, up ${Math.round(t.upMs / 1000)}s, cpu ${Math.round(t.cpuMs / 1000)}s, ` +
+          `est $${(t.estimatedCents / 100).toFixed(4)}`,
+      );
+      return;
+    }
+    case 'secret': {
+      // Parsed from the verb on, with the NAME taken from the positionals: a
+      // fixed `rest.slice(2)` assumed every verb has a name, which `ls` does
+      // not, so `secret ls --account x` would have dropped `--account`.
+      const sub = rest[0];
+      if (!['set', 'fingerprint', 'ls', 'rm'].includes(sub)) {
+        return fail(
+          'secret subcommands: set <NAME> [--value v | --from-env [VAR]] [--legacy] | fingerprint <NAME> [--value v | --from-env [VAR]] | ls | rm <NAME> [--force]',
+        );
+      }
+      const parsed = parseKnown(rest.slice(1), `secret ${sub}`);
+      const name = parsed.positionals[0];
+      const account = firstFlag(parsed, 'account');
+      if (sub === 'set' || sub === 'fingerprint') {
+        const secretName = need(name, 'secret name');
+        // Three sources, shared by `set` and `fingerprint` so the value is
+        // read the same way whether it is being stored or checked. Naming two
+        // at once is a mistake rather than a precedence question: silently
+        // preferring one would store (or check) a value the caller did not
+        // mean. The prompt and the env read leave the value out of the shell
+        // history and out of `ps`; `--value` is for scripts that accept that.
+        const value = await readSecretValue(parsed, secretName, sub === 'set' ? `Value for ${secretName}` : `Value to compare against ${secretName}`);
+        if (sub === 'fingerprint') {
+          // Compared HERE. The one request is the listing, which carries the
+          // salt and the stored fingerprint; the value is hashed locally and
+          // never sent — there is no server route that answers "is this the
+          // value", because that route would be an oracle.
+          let outcome;
+          try {
+            outcome = await compareFingerprint(apiRequest, secretName, value, { account });
+          } catch (error) {
+            return fail(error.message);
+          }
+          if (outcome.match) {
+            console.log('match');
+            return;
+          }
+          console.log(`NO MATCH (stored ${outcome.stored}, yours ${outcome.yours})`);
+          process.exit(1);
+        }
+        // Sealed to the account's runner key before it leaves this process
+        // (docs/SEALED-SECRETS.md): the gateway stores ciphertext it cannot
+        // open. --legacy sends the old {value} body and is told so. The
+        // THROWING api variant, so a 409 (the kid moved) can be retried once.
+        try {
+          const { stored } = await storeSecretSealed(apiRequest, secretName, value, { legacy: parsed.booleans.has('legacy'), account });
+          return print(stored);
+        } catch (error) {
+          if (error instanceof ApiError) return fail(error.message);
+          throw error;
+        }
+      }
+      if (sub === 'ls') {
+        const listed = await api('GET', `/api/v1/secrets${queryFor(parsed, ['account', ...listQuery()])}`);
+        print(listed);
+        // The fingerprint column, for a person: stdout stays the JSON a
+        // script parses. A row without one is a legacy (gateway-readable)
+        // row or one stored without; either way `secret set` re-stores it.
+        for (const s of listed.secrets ?? []) {
+          console.error(`  ${s.name.padEnd(28)} ${s.fingerprint ?? '(no fingerprint — legacy row; re-set to seal it)'}${s.kid ? `  kid ${s.kid}` : ''}`);
+        }
+        return;
+      }
+      if (sub === 'rm') {
+        return print(await api('DELETE', `/api/v1/secrets/${encodeURIComponent(need(name, 'secret name'))}${queryFor(parsed, ['account'], ['force'])}`));
+      }
+      return undefined;
+    }
+    case 'connector': {
+      // The account's ONE connect URL (plan task G4, spec D8): the aggregate
+      // `/c/<account>/all/mcp`, which reaches every registration not set to
+      // `--aggregate exclude`. The URL ALONE goes to stdout, so it can be
+      // spliced into a command (`claude mcp add --transport http all "$(…)"`);
+      // what it reaches goes to stderr for the person reading. The short
+      // account-free form where the gateway offers it — it resolves in the
+      // calling account, so it is the one to paste — else the qualified one.
+      const parsed = parseKnown(rest, 'connector');
+      const account = firstFlag(parsed, 'account');
+      const answer = await api('GET', `/api/v1/connector${account ? `?account=${encodeURIComponent(account)}` : ''}`);
+      if (parsed.booleans.has('json')) return print(answer);
+      const view = answer.connector;
+      if (!view) return fail('this deployment has no account yet: register an MCP first, and the connector covers it');
+      console.log(view.shortUrl ?? view.url);
+      const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+      console.error(`mcp-host: ${plural(view.registrations, 'MCP')} · ${plural(view.tools, 'tool')} through one connector`);
+      if (view.needsConnection > 0) {
+        console.error(`  ${view.needsConnection} need you to connect them first (each signs in as you, on its own URL)`);
+      }
+      if (view.uncached > 0) console.error(`  ${view.uncached} not used yet, so their tools are not listed until they are`);
+      if (view.excluded > 0) console.error(`  ${view.excluded} left out (\`mcp-host set <id> --aggregate search\` brings one in)`);
+      console.error('Add it in claude.ai: Settings -> Connectors -> Add custom connector, and approve once.');
+      return;
+    }
+    case 'marketplace': {
+      // The personal plugin marketplace (docs/MARKETPLACE.md): the account's
+      // enabled MCPs as a Claude Code marketplace behind a capability URL.
+      // The URL is shown exactly once, by `rotate` — the token is stored
+      // hashed, so a later `marketplace` can only report that a feed exists.
+      // Parse FIRST, then read the subcommand from the positionals:
+      // parseArgs consumes each flag's value, so `marketplace --account x`
+      // yields no positional (status form) rather than binding `--account` —
+      // or, as a hand-rolled scan here once did, `x` — as the subcommand.
+      const parsed = parseCommand(rest, ['marketplace', 'marketplace rotate', 'marketplace revoke']);
+      const [sub] = parsed.positionals;
+      if (sub === undefined || sub === 'rotate' || sub === 'revoke') refuseFor(parsed, sub ? `marketplace ${sub}` : 'marketplace');
+      const account = firstFlag(parsed, 'account');
+      const query = account ? `?account=${encodeURIComponent(account)}` : '';
+      if (sub === 'rotate') {
+        const minted = await api('POST', `/api/v1/marketplace/token${query}`);
+        print(minted);
+        console.error('\nSubscribe from Claude Code:');
+        console.error(`  ${minted.addCommand}`);
+        console.error('Then: /plugin — every enabled MCP appears as an installable plugin.');
+        console.error(minted.note);
+        return;
+      }
+      if (sub === 'revoke') {
+        return print(await api('DELETE', `/api/v1/marketplace/token${query}`));
+      }
+      if (sub === undefined) {
+        const status = await api('GET', `/api/v1/marketplace${query}`);
+        print(status);
+        if (status.marketplace) {
+          console.error('\nThe URL is shown only when minted. `mcp-host marketplace rotate` issues a fresh one');
+          console.error('(the old URL stops working immediately).');
+        } else {
+          console.error('\nNo marketplace URL yet. Mint one with: mcp-host marketplace rotate');
+        }
+        return;
+      }
+      return fail('marketplace subcommands: (none = status) | rotate | revoke');
+    }
+    case 'bridge': {
+      // Bridge credentials for the hosted browser bridge
+      // (docs/BROWSER-BRIDGE.md): one per browser, account-scoped, and able to
+      // do nothing but attach that browser. The CLI lists and revokes them; it
+      // cannot mint one — since D18 a browser connects from its own extension
+      // (Connect in the popup, one Confirm on the gateway page), and the old
+      // mint answers 410.
+      const parsed = parseCommand(rest, ['bridge', 'bridge revoke']);
+      const [sub, ...words] = parsed.positionals;
+      if (sub === 'revoke') refuseFor(parsed, 'bridge revoke');
+      else if (sub === undefined || sub === 'ls') refuseFor(parsed, 'bridge');
+      const account = firstFlag(parsed, 'account');
+      const query = account ? `?account=${encodeURIComponent(account)}` : '';
+      if (sub === 'new' || sub === 'pair') {
+        return fail(
+          'bridge new/pair are retired (D18): click Connect in the ContextMint extension, sign in if asked, and confirm on the page it opens',
+        );
+      }
+      if (sub === 'revoke') {
+        return print(await api('DELETE', `/api/v1/bridge-tokens/${encodeURIComponent(need(words[0], 'credential id'))}${query}`));
+      }
+      if (sub === undefined || sub === 'ls') {
+        return print(await api('GET', `/api/v1/bridge-tokens${queryFor(parsed, ['account', ...listQuery()])}`));
+      }
+      return fail('bridge subcommands: (none = ls) | ls | revoke <id>');
+    }
+    case 'logs':
+      return logs(rest);
+    case 'approvals':
+      return approvals(rest);
+    case 'me':
+      return meSet(rest);
+    case 'profile':
+      return profileWrite(rest);
+    case 'connections': {
+      // Only the two hand-written connection commands reach here; every other
+      // `connections …` is a generic row (operations.mjs).
+      const [sub, ...more] = rest;
+      if (sub === 'login') {
+        const parsed = parseKnown(more, 'connections login');
+        const id = need(parsed.positionals[0], 'principal id');
+        const interactive = Boolean(process.stdin.isTTY);
+        const prompter = interactive ? makePrompter() : undefined;
+        try {
+          const { result, exitCode } = await runLogin(api, id, { interactive, prompter });
+          print(result);
+          if (exitCode !== 0) process.exit(exitCode);
+        } finally {
+          prompter?.close();
+        }
+        return;
+      }
+      if (sub === 'secret' && more[0] === 'set') {
+        // The portal's Connections repair, for a mistyped credential: the
+        // alternative is revoke-and-reauthorize, which loses the grant and its
+        // usage history. Sent as `{value}` — a principal secret is one of the
+        // documented gateway-SEALED exceptions (docs/SEALED-SECRETS.md), as the
+        // portal sends it — and read like `secret set`'s, off the command line
+        // only when `--value` says so.
+        const parsed = parseKnown(more.slice(1), 'connections secret set');
+        const [id, name] = parsed.positionals;
+        need(id, 'principal id');
+        need(name, 'credential name');
+        const value = await readSecretValue(parsed, name, `Value for ${name}`);
+        return print(await api('PUT', `/api/v1/principals/${encodeURIComponent(id)}/secrets/${encodeURIComponent(name)}`, { value }));
+      }
+      console.error(helpText());
+      return process.exit(1);
+    }
+    default:
+      console.error(helpText());
+      process.exit(1);
+  }
+}
+
+/**
+ * The value for `secret set` / `secret fingerprint`: `--value`, `--from-env
+ * [VAR]`, a no-echo prompt on a terminal, else stdin. Fails with the env check
+ * BEFORE prompting, so a wizard-style question is never asked and then wasted.
+ */
+async function readSecretValue(parsed, secretName, prompt) {
+  const explicit = firstFlag(parsed, 'value');
+  const wantsEnv = flagPresent(parsed, 'from-env');
+  if (explicit !== undefined && wantsEnv) fail('pass one of --value or --from-env, not both');
+  let value;
+  if (wantsEnv) {
+    let resolved;
+    try {
+      resolved = readSecretEnv(secretName, firstFlag(parsed, 'from-env'));
+    } catch (error) {
+      fail(error.message);
+    }
+    if (resolved.warning) console.error(`mcp-host: warning: ${resolved.warning}`);
+    value = resolved.value;
+  } else if (explicit !== undefined) {
+    value = explicit;
+  } else if (process.stdin.isTTY) {
+    // A terminal and no value: ask for it without echo, so the secret
+    // stays out of the shell history, out of `ps`, and off the screen.
+    requireEnv();
+    const prompter = makePrompter();
+    try {
+      value = await prompter.secret(prompt);
+    } finally {
+      prompter.close();
+    }
+  } else {
+    value = await readStdin();
+  }
+  if (!value) fail('provide --value, --from-env [VAR], or pipe the secret on stdin');
+  return value;
+}
+
+function need(value, what) {
+  if (!value) fail(`${what} is required`);
+  return value;
+}
+
+async function readStdin() {
+  if (process.stdin.isTTY) return '';
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8').trim();
+}
+
+try {
+  await main();
+} catch (error) {
+  // The paths that call the THROWING `apiRequest` (the wizard, the sealed
+  // secret write) rethrow what they cannot handle; an outage or a refusal is
+  // still one line, never a stack.
+  if (error instanceof ApiError || error instanceof GatewayUnreachable) fail(error.message);
+  throw error;
+}