@chrischall/mcp-host-cli 2.33.0 → 2.34.0

package/README.md

@@ -24,3 +24,24 @@ bearer token.
 Its version tracks the mcp-host release it was cut from, and its commands
 track that release's control API — keep it current with the deployment you
 point it at.
+
+## Upgrading from 2.33.0
+
+The release after 2.33.0 is stricter in two ways a script can notice. Both
+turn a silent mistake into an error, so they ship as a fix rather than a
+major version:
+
+- **Every command refuses a flag it does not take.** Before, ten commands
+  (`set`, `register`, `connector`, `build`, `preview`, `bundles`, `infra`,
+  `secret`, `marketplace`, `bridge`) dropped an unknown flag and ran anyway —
+  `set reg_1 --denny destructive` sent the update without the policy you
+  typed. Now it exits 1 with `unknown flag --denny` and the command's usage.
+  A script that passed a flag the command never read (for example
+  `preview --follow`, `secret rm --legacy`, `infra sync --days`) must drop it.
+- **`approvals approve <id>` asks before it approves.** It shows the tool,
+  the registration and the arguments, then needs a "y" at a terminal. Without
+  a terminal (a pipe, CI, a cron job) it approves nothing and exits 1 unless
+  you pass `--yes`, so add `--yes` to any script that approves calls.
+
+An unreachable gateway now prints one `mcp-host:` line and exits 1 instead of
+a `fetch failed` stack trace.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/mcp-host-cli",
-  "version": "2.33.0",
+  "version": "2.34.0",
   "type": "module",
   "description": "Admin CLI for mcp-host: register, list, inspect, and manage hosted MCPs via the gateway control API.",
   "license": "MIT",

package/src/index.mjs

@@ -35,7 +35,7 @@
 //   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
+//   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
@@ -62,6 +62,7 @@ import {
   AGGREGATE_MODES,
   INSECURE_FLAG,
   approvalLines,
+  describeApproval,
   MCPB_USAGE,
   buildDependencies,
   buildEnvMap,
@@ -84,7 +85,7 @@ import {
   wantsWizard,
 } from './lib.mjs';
 import { runLogin } from './login.mjs';
-import { flagName, helpFor, helpText, matchGeneric, pathParams, usageFor } from './operations.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';
@@ -128,6 +129,33 @@ class ApiError extends Error {
   }
 }
 
+/**
+ * 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
@@ -137,7 +165,7 @@ class ApiError extends Error {
  */
 async function apiRequest(method, path, body) {
   requireEnv();
-  const res = await fetch(`${BASE}${path}`, {
+  const { res, text } = await exchange(`${BASE}${path}`, {
     method,
     headers: {
       authorization: `Bearer ${TOKEN}`,
@@ -145,7 +173,6 @@ async function apiRequest(method, path, body) {
     },
     body: body !== undefined ? JSON.stringify(body) : undefined,
   });
-  const text = await res.text();
   let parsed;
   try {
     parsed = JSON.parse(text);
@@ -156,12 +183,12 @@ async function apiRequest(method, path, body) {
   return parsed;
 }
 
-/** `apiRequest` for the one-shot commands: a non-2xx is `fail()`, exit 1. */
+/** `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) return fail(error.message);
+    if (error instanceof ApiError || error instanceof GatewayUnreachable) return fail(error.message);
     throw error;
   }
 }
@@ -186,7 +213,7 @@ async function uploadBundle(file) {
   } catch (error) {
     throw new Error(`--mcpb: cannot read ${file}: ${error.message}`);
   }
-  const res = await fetch(`${BASE}/api/v1/bundles`, {
+  const { res, text } = await exchange(`${BASE}/api/v1/bundles`, {
     method: 'PUT',
     headers: {
       authorization: `Bearer ${TOKEN}`,
@@ -195,7 +222,6 @@ async function uploadBundle(file) {
     },
     body: bytes,
   });
-  const text = await res.text();
   let parsed;
   try {
     parsed = JSON.parse(text);
@@ -547,18 +573,11 @@ function coerceField(flag, type, raw) {
  */
 async function runGeneric(row, argv) {
   const body = row.body ?? {};
-  const booleans = new Set(Object.entries(body).filter(([, t]) => t === 'boolean').map(([f]) => flagName(f)));
-  let parsed;
-  try {
-    parsed = parseArgs(argv, booleans);
-  } catch (error) {
-    return fail(error.message);
-  }
+  const booleans = Object.entries(body).filter(([, t]) => t === 'boolean').map(([f]) => flagName(f));
   const usage = `usage: mcp-host ${usageFor(row)}`;
-  const known = new Set([...(row.query ?? []).map(flagName), ...Object.keys(body).map(flagName), ...(row.body ? ['data'] : [])]);
-  for (const name of [...Object.keys(parsed.flags), ...parsed.booleans]) {
-    if (!known.has(name)) fail(`unknown flag --${name}\n${usage}`);
-  }
+  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);
 
@@ -600,10 +619,7 @@ async function runGeneric(row, argv) {
  * portal are for.
  */
 async function logs(argv) {
-  const parsed = parseArgs(argv);
-  for (const name of [...Object.keys(parsed.flags), ...parsed.booleans]) {
-    if (name !== 'lines') fail(`unknown flag --${name}\nusage: mcp-host logs <id> [--lines N]`);
-  }
+  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));
@@ -616,6 +632,46 @@ function refuseUnknownFlags(parsed, known, 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
@@ -624,15 +680,10 @@ function refuseUnknownFlags(parsed, known, usage) {
  * expiry of the request they are about to approve should have to be found.
  */
 async function approvals(argv) {
-  const usage = 'usage: mcp-host approvals [ls] [--status pending|approved|refused|consumed|expired|all] [--account slug] [--sort v] [--order v] [--q v] [--page v] [--per-page v]';
-  let parsed;
-  try {
-    parsed = parseArgs(argv);
-  } catch (error) {
-    return fail(error.message);
-  }
+  if (argv[0] === 'approve') return approve(argv.slice(1));
+  const usage = commandUsage('approvals');
+  const parsed = parseKnown(argv, 'approvals');
   const names = ['status', 'account', ...listQuery()];
-  refuseUnknownFlags(parsed, names.map(flagName), usage);
   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)}`);
@@ -648,6 +699,42 @@ async function approvals(argv) {
   }
 }
 
+/**
+ * `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
@@ -655,19 +742,13 @@ async function approvals(argv) {
  * replaced took a body (#1171); the flag wins over it, as in profileWrite.
  */
 async function meSet(argv) {
-  const usage = 'usage: mcp-host me set --push-tenant-alerts on|off [--data <json>]';
+  const usage = commandUsage('me set');
   const [sub, ...more] = argv;
   if (sub !== 'set') {
     console.error(helpText());
     return process.exit(1);
   }
-  let parsed;
-  try {
-    parsed = parseArgs(more);
-  } catch (error) {
-    return fail(error.message);
-  }
-  refuseUnknownFlags(parsed, ['push-tenant-alerts', 'data'], usage);
+  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');
@@ -695,17 +776,8 @@ async function profileWrite(argv) {
     console.error(helpText());
     return process.exit(1);
   }
-  const usage =
-    sub === 'add'
-      ? 'usage: mcp-host profile add <id> --label <label> (--secret-env VAR=SECRET … | --env <json>) [--account slug] [--data <json>]'
-      : 'usage: mcp-host profile set <id> <profileId> [--label <label>] [--secret-env VAR=SECRET … | --env <json>] [--account slug] [--data <json>]';
-  let parsed;
-  try {
-    parsed = parseArgs(more);
-  } catch (error) {
-    return fail(error.message);
-  }
-  refuseUnknownFlags(parsed, ['label', 'secret-env', 'env', 'account', 'data'], usage);
+  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'];
@@ -775,7 +847,7 @@ async function main() {
       return;
     }
     case 'register': {
-      const parsed = parseArgs(rest, new Set(['follow', 'data-dir', 'no-data-dir', 'per-user-child', 'bridge']));
+      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
@@ -800,7 +872,7 @@ async function main() {
       // 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 = parseArgs(rest, new Set(['force', 'wait']));
+      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) {
@@ -818,10 +890,7 @@ async function main() {
       // 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 = parseArgs(
-        rest,
-        new Set(['data-dir', 'no-data-dir', 'no-deps', 'follow', 'no-follow', 'allow-all', 'no-ask', 'all-tools']),
-      );
+      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');
@@ -971,7 +1040,7 @@ async function main() {
       // 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 = parseArgs(rest);
+      const parsed = parseKnown(rest, 'preview');
       const dependencies = dependenciesFromFlags(parsed);
       const source = await sourceFromFlags(parsed);
       return print(
@@ -989,9 +1058,10 @@ async function main() {
       // 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 = parseArgs(rest);
+      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}`);
@@ -1005,8 +1075,9 @@ async function main() {
       // 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 = parseArgs(rest);
+      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
@@ -1084,7 +1155,12 @@ async function main() {
       // 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];
-      const parsed = parseArgs(rest.slice(1), new Set(['legacy']), new Set(['from-env']));
+      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') {
@@ -1138,11 +1214,9 @@ async function main() {
         return;
       }
       if (sub === 'rm') {
-        return print(await api('DELETE', `/api/v1/secrets/${encodeURIComponent(need(name, 'secret name'))}${queryFor(parsed, ['account'])}`));
+        return print(await api('DELETE', `/api/v1/secrets/${encodeURIComponent(need(name, 'secret name'))}${queryFor(parsed, ['account'], ['force'])}`));
       }
-      return fail(
-        'secret subcommands: set <NAME> [--value v | --from-env [VAR]] [--legacy] | fingerprint <NAME> [--value v | --from-env [VAR]] | ls | rm <NAME>',
-      );
+      return undefined;
     }
     case 'connector': {
       // The account's ONE connect URL (plan task G4, spec D8): the aggregate
@@ -1152,7 +1226,7 @@ async function main() {
       // 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 = parseArgs(rest, new Set(['json']));
+      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);
@@ -1178,8 +1252,9 @@ async function main() {
       // 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 = parseArgs(rest);
+      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') {
@@ -1214,8 +1289,10 @@ async function main() {
       // 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 = parseArgs(rest);
+      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') {
@@ -1244,7 +1321,7 @@ async function main() {
       // `connections …` is a generic row (operations.mjs).
       const [sub, ...more] = rest;
       if (sub === 'login') {
-        const parsed = parseArgs(more);
+        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;
@@ -1264,7 +1341,7 @@ async function main() {
         // 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 = parseArgs(more.slice(1), new Set(), new Set(['from-env']));
+        const parsed = parseKnown(more.slice(1), 'connections secret set');
         const [id, name] = parsed.positionals;
         need(id, 'principal id');
         need(name, 'credential name');
@@ -1330,4 +1407,12 @@ async function readStdin() {
   return Buffer.concat(chunks).toString('utf8').trim();
 }
 
-await main();
+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;
+}

package/src/lib.mjs

@@ -510,23 +510,33 @@ function timeLeft(ms) {
  */
 export function approvalLines(approvals, now = Date.now()) {
   return approvals.map((a) => {
-    const where = `${a.registrationSlug ?? a.registrationId} · ${a.tool}`;
-    const preview =
-      typeof a.argsPreview === 'string' && a.argsPreview.length > ARGS_PREVIEW_CHARS
-        ? `${a.argsPreview.slice(0, ARGS_PREVIEW_CHARS - 1)}…`
-        : (a.argsPreview ?? '');
-    let when;
-    if (a.status === 'pending' || a.status === 'approved') {
-      const left = Date.parse(a.expiresAt) - now;
-      when = Number.isFinite(left) && left > 0 ? `expires in ${timeLeft(left)}` : 'expired';
-      if (a.status === 'approved') when = `approved${a.decidedBy ? ` by ${a.decidedBy}` : ''}, ${when}`;
-    } else {
-      when = a.decidedBy ? `${a.status} by ${a.decidedBy}` : String(a.status);
-    }
+    const { where, preview, when } = describeApproval(a, now);
     return `  ${String(a.id).padEnd(14)} ${String(a.status).padEnd(9)} ${where}  ${preview}  ${when}`;
   });
 }
 
+/**
+ * One approval's parts as a person reads them — which MCP and tool, the
+ * argument preview (shortened), and the time left or who decided — shared by
+ * the `approvals` listing and the echo `approvals approve` prints first.
+ */
+export function describeApproval(a, now = Date.now()) {
+  const where = `${a.registrationSlug ?? a.registrationId} · ${a.tool}`;
+  const preview =
+    typeof a.argsPreview === 'string' && a.argsPreview.length > ARGS_PREVIEW_CHARS
+      ? `${a.argsPreview.slice(0, ARGS_PREVIEW_CHARS - 1)}…`
+      : (a.argsPreview ?? '');
+  let when;
+  if (a.status === 'pending' || a.status === 'approved') {
+    const left = Date.parse(a.expiresAt) - now;
+    when = Number.isFinite(left) && left > 0 ? `expires in ${timeLeft(left)}` : 'expired';
+    if (a.status === 'approved') when = `approved${a.decidedBy ? ` by ${a.decidedBy}` : ''}, ${when}`;
+  } else {
+    when = a.decidedBy ? `${a.status} by ${a.decidedBy}` : String(a.status);
+  }
+  return { where, preview, when };
+}
+
 /**
  * `on`/`off` (or `true`/`false`, `yes`/`no`) as a boolean, for a switch flag
  * that must be able to say false — a bare boolean flag can only say true.

package/src/operations.mjs

@@ -133,7 +133,13 @@ export const OPERATIONS = [
   // and applies nothing — acting on an ask is still `set` or a PUT
   // (docs/MINT-MANIFEST.md §9).
   { op: 'POST /api/v1/registrations/{id}/manifest-check', words: ['manifest-check'], args: ['id'], summary: 'read this registration\'s mint.yaml now' },
-  { op: 'POST /api/v1/registrations/{id}/manifest-ack', words: ['manifest-ack'], args: ['id'], summary: 'record that the package\'s asks have been read' },
+  {
+    op: 'POST /api/v1/registrations/{id}/manifest-ack',
+    words: ['manifest-ack'],
+    args: ['id'],
+    body: { digest: 'string' },
+    summary: 'record that the package\'s asks carrying --digest have been read (409 if it is not the current one)',
+  },
   // Accepting a `losing state` warning for the files it names — no flag
   // flips and nothing restarts; `--names '[".cache"]'` names what is accepted,
   // and without it the open finding's names are (core `state-loss-ack.ts`).
@@ -254,7 +260,18 @@ export const OPERATIONS = [
     summary: 'tool calls waiting for approval: MCP, tool, argument preview, time left',
     example: ['approvals', 'ls'],
   },
-  { op: 'POST /api/v1/approvals/{id}/approve', words: ['approvals', 'approve'], args: ['id'], query: ['account'], summary: 'let one waiting tool call through, once' },
+  // Bespoke so that it SHOWS the call before letting it through (fleet-audit
+  // #1454): an id pasted from a notification was approved without this
+  // terminal ever naming the MCP, the tool or the arguments.
+  {
+    op: 'POST /api/v1/approvals/{id}/approve',
+    bespoke: true,
+    words: ['approvals', 'approve'],
+    usage: 'approvals approve <id> [--account slug] [--yes]   (shows the call first; asks, unless --yes)',
+    query: ['account'],
+    summary: 'let one waiting tool call through, once, after showing which MCP, tool and arguments',
+    example: ['approvals', 'approve', 'apr_1', '--yes'],
+  },
   { op: 'POST /api/v1/approvals/{id}/refuse', words: ['approvals', 'refuse'], args: ['id'], query: ['account'], summary: 'refuse one waiting tool call' },
 
   // ── connections (principals) ─────────────────────────────────────────────
@@ -298,7 +315,7 @@ export const OPERATIONS = [
     op: 'PUT /api/v1/me',
     bespoke: true,
     words: ['me', 'set'],
-    usage: 'me set --push-tenant-alerts on|off',
+    usage: 'me set --push-tenant-alerts on|off [--data <json>]',
     summary: 'set your own preferences (whether alerts about your MCPs are pushed to your devices)',
     example: ['me', 'set', '--push-tenant-alerts', 'off'],
   },
@@ -354,9 +371,10 @@ export const OPERATIONS = [
   {
     op: 'DELETE /api/v1/secrets/{name}',
     bespoke: true,
-    usage: 'secret rm <NAME> [--account slug]',
+    usage: 'secret rm <NAME> [--force] [--account slug]   (--force deletes one a registration or profile still uses)',
     query: ['account'],
-    summary: 'delete a secret',
+    booleanQuery: ['force'],
+    summary: 'delete a secret (refused while in use unless --force)',
     example: ['secret', 'rm', 'NAME'],
   },
   { op: 'GET /api/v1/secrets/public-key', words: ['secret', 'public-key'], query: ['account'], summary: 'the account seal key' },
@@ -476,6 +494,65 @@ export const OPERATIONS = [
   },
 ];
 
+const kebabList = (prefix = '') => LIST.map((n) => flagName(prefix ? `${prefix}${n[0].toUpperCase()}${n.slice(1)}` : n));
+
+/**
+ * The flags each HAND-WRITTEN command accepts (fleet-audit#1407), keyed by the
+ * words that name it. A generic row's flags are derived from the row; a
+ * bespoke command's were whatever its code happened to read, so a typo beside
+ * a valid flag was dropped and the request still sent. index.mjs parses each
+ * of these commands against its entry and REFUSES anything outside it, with
+ * the usage line of the row named by `op`.
+ *
+ * `values` take a value, `booleans` take none, `optional` may take one
+ * (`--from-env [VAR]`). Held to an enumeration in tests/bespoke-flags.test.ts.
+ *
+ * @type {Record<string, { op: string, values?: string[], booleans?: string[], optional?: string[] }>}
+ */
+export const COMMAND_FLAGS = {
+  register: {
+    op: 'POST /api/v1/registrations',
+    values: ['slug', 'npm', 'github', 'pypi', 'mcpb', 'subdir', 'build', 'bin', 'dep', 'dep-sha256', 'account', 'name', 'env', 'secret-env', 'tools', 'auth-flow', 'data'],
+    booleans: ['follow', 'data-dir', 'no-data-dir', 'per-user-child', 'bridge'],
+  },
+  set: {
+    op: 'PUT /api/v1/registrations/{id}',
+    values: ['data', 'state-store', 'dep', 'dep-sha256', 'bridge-approval', 'deny', 'ask', 'tools', 'aggregate'],
+    booleans: ['data-dir', 'no-data-dir', 'no-deps', 'follow', 'no-follow', 'allow-all', 'no-ask', 'all-tools'],
+  },
+  logs: { op: 'GET /api/v1/registrations/{id}/logs', values: ['lines'] },
+  build: { op: 'POST /api/v1/registrations/{id}/build', booleans: ['force', 'wait'] },
+  preview: { op: 'POST /api/v1/registrations/preview', values: ['npm', 'github', 'pypi', 'mcpb', 'subdir', 'build', 'dep', 'dep-sha256'] },
+  'bundles upload': { op: 'PUT /api/v1/bundles' },
+  approvals: { op: 'GET /api/v1/approvals', values: ['status', 'account', ...kebabList()] },
+  'approvals approve': { op: 'POST /api/v1/approvals/{id}/approve', values: ['account'], booleans: ['yes'] },
+  'me set': { op: 'PUT /api/v1/me', values: ['push-tenant-alerts', 'data'] },
+  'profile add': { op: 'POST /api/v1/registrations/{id}/profiles', values: ['label', 'secret-env', 'env', 'account', 'data'] },
+  'profile set': { op: 'PUT /api/v1/registrations/{id}/profiles/{profileId}', values: ['label', 'secret-env', 'env', 'account', 'data'] },
+  'connections login': { op: 'POST /api/v1/principals/{id}/login' },
+  'connections secret set': { op: 'PUT /api/v1/principals/{id}/secrets/{name}', values: ['value'], optional: ['from-env'] },
+  'secret set': { op: 'PUT /api/v1/secrets/{name}', values: ['value', 'account'], booleans: ['legacy'], optional: ['from-env'] },
+  'secret fingerprint': { op: 'GET /api/v1/secrets', values: ['value', 'account'], optional: ['from-env'] },
+  'secret ls': { op: 'GET /api/v1/secrets', values: ['account', ...kebabList()] },
+  'secret rm': { op: 'DELETE /api/v1/secrets/{name}', values: ['account'], booleans: ['force'] },
+  bridge: { op: 'GET /api/v1/bridge-tokens', values: ['account', ...kebabList()] },
+  'bridge revoke': { op: 'DELETE /api/v1/bridge-tokens/{id}', values: ['account'] },
+  connector: { op: 'GET /api/v1/connector', values: ['account'], booleans: ['json'] },
+  marketplace: { op: 'GET /api/v1/marketplace', values: ['account'] },
+  'marketplace rotate': { op: 'POST /api/v1/marketplace/token', values: ['account'] },
+  'marketplace revoke': { op: 'DELETE /api/v1/marketplace/token', values: ['account'] },
+  infra: { op: 'GET /api/v1/infra', values: ['account', 'days', ...kebabList('res')] },
+  'infra sync': { op: 'POST /api/v1/infra/shared-machines/sync' },
+  'infra drain': { op: 'POST /api/v1/infra/shared-machines/{id}/drain' },
+  'infra undrain': { op: 'POST /api/v1/infra/shared-machines/{id}/undrain' },
+};
+
+/** `usage: mcp-host …` for a COMMAND_FLAGS key: its row's usage line, so the refusal and `--help` say one thing. */
+export function commandUsage(key) {
+  const row = OPERATIONS.find((r) => r.op === COMMAND_FLAGS[key].op);
+  return `usage: mcp-host ${usageFor(row)}`;
+}
+
 /** `perPage` → `per-page`: the flag spelling of a query or body field name. */
 export function flagName(field) {
   return field.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);