diff --git a/src/hosted/setup.test.ts b/src/hosted/setup.test.ts
index 4884842f9..3da70c4ea 100644
--- a/src/hosted/setup.test.ts
+++ b/src/hosted/setup.test.ts
@@ -578,6 +578,28 @@ describe('webcmd setup', () => {
     expect(messages.join('')).toContain('--chrome-profile, --import-chrome-cookies, and --sync-to-chrome are only valid with --browser chrome');
   });
 
+  it.each([
+    ['--mode local', ['--mode', 'local', '--browser', 'cloak'], '--mode'],
+    ['--mode=local', ['--mode=local'], '--mode'],
+    ['--api-key', ['--api-key', 'sk-test'], '--api-key'],
+  ])('names the removed %s flag instead of listing every valid flag', async (_label, argv, flag) => {
+    tempDir = await mkdtemp(join(tmpdir(), 'webcmd-setup-removed-flag-'));
+    const messages: string[] = [];
+
+    await expect(runHostedSetup({
+      env: { WEBCMD_CONFIG_DIR: tempDir },
+      argv,
+      isTTY: false,
+      fetchDaemonStatus: async () => null,
+      write: message => { messages.push(message); },
+      stderr: new Writable({ write: (chunk, _enc, cb) => { messages.push(chunk.toString()); cb(); } }),
+    })).resolves.not.toBe(0);
+
+    const output = messages.join('');
+    expect(output).toContain(`\`setup\` no longer accepts ${flag}`);
+    expect(output).not.toContain(`unknown flag ${flag}`);
+  });
+
   it('reuses an existing SLAB app without downloading it again', async () => {
     tempDir = await mkdtemp(join(tmpdir(), 'webcmd-setup-slab-reuse-'));
     const events: string[] = [];
diff --git a/src/hosted/setup.ts b/src/hosted/setup.ts
index df54d1445..65a5c8f6b 100644
--- a/src/hosted/setup.ts
+++ b/src/hosted/setup.ts
@@ -79,6 +79,22 @@ const SETUP_HELP = [
   '',
 ].join('\n');
 
+/**
+ * Flags `setup` used to accept before it stopped configuring hosted mode. They
+ * still appear in older docs and in muscle memory, so name them instead of
+ * letting them fall through to the generic unknown-flag list.
+ */
+const REMOVED_SETUP_FLAGS: readonly { name: string; remediation: string }[] = [
+  {
+    name: '--mode',
+    remediation: `setup always configures local mode, so drop the flag and pick a browser with \`${CLI_COMMAND} setup --browser <cloak|chrome|slab|absolute-path>\``,
+  },
+  {
+    name: '--api-key',
+    remediation: 'setup no longer stores a Webcmd Cloud API key',
+  },
+];
+
 export async function runHostedSetup(io: SetupIo = {}): Promise<number> {
   const write = io.write
     ? async (message: string) => { await io.write!(message); }
@@ -399,6 +415,15 @@ function parseSetupArgs(argv: readonly string[]): {
       browser = parseLocalBrowser(value);
       continue;
     }
+    const removed = REMOVED_SETUP_FLAGS.find(
+      flag => token === flag.name || token.startsWith(`${flag.name}=`),
+    );
+    if (removed) {
+      throw new ArgumentError(
+        `\`setup\` no longer accepts ${removed.name}; ${removed.remediation}.`,
+        `${SETUP_USAGE}\n${SETUP_EXAMPLE}`,
+      );
+    }
 
     throw new ArgumentError(
       `unknown flag ${token} for \`setup\``,