refactor: declare channel add flags in manifests

extensions/bluebubbles/package.json

@@ -35,7 +35,13 @@
         "imessage"
       ],
       "systemImage": "bubble.left.and.text.bubble.right",
-      "order": 75
+      "order": 75,
+      "cliAddOptions": [
+        {
+          "flags": "--webhook-path <path>",
+          "description": "BlueBubbles webhook path"
+        }
+      ]
     },
     "install": {
       "npmSpec": "@openclaw/bluebubbles",

extensions/googlechat/package.json

@@ -49,7 +49,25 @@
         "groupModel": "route",
         "groupAllowFromFallbackToAllowFrom": false,
         "warnOnEmptyGroupSenderAllowlist": false
-      }
+      },
+      "cliAddOptions": [
+        {
+          "flags": "--webhook-path <path>",
+          "description": "Google Chat webhook path"
+        },
+        {
+          "flags": "--webhook-url <url>",
+          "description": "Google Chat webhook URL"
+        },
+        {
+          "flags": "--audience-type <type>",
+          "description": "Google Chat audience type (app-url|project-number)"
+        },
+        {
+          "flags": "--audience <value>",
+          "description": "Google Chat audience value (app URL or project number)"
+        }
+      ]
     },
     "install": {
       "npmSpec": "@openclaw/googlechat",

extensions/imessage/package.json

@@ -23,7 +23,21 @@
       "aliases": [
         "imsg"
       ],
-      "systemImage": "message.fill"
+      "systemImage": "message.fill",
+      "cliAddOptions": [
+        {
+          "flags": "--db-path <path>",
+          "description": "iMessage database path"
+        },
+        {
+          "flags": "--service <service>",
+          "description": "iMessage service (imessage|sms|auto)"
+        },
+        {
+          "flags": "--region <region>",
+          "description": "iMessage region (for SMS)"
+        }
+      ]
     }
   }
 }

extensions/matrix/package.json

@@ -48,6 +48,28 @@
         "groupAllowFromFallbackToAllowFrom": false,
         "warnOnEmptyGroupSenderAllowlist": true
       },
+      "cliAddOptions": [
+        {
+          "flags": "--homeserver <url>",
+          "description": "Matrix homeserver URL"
+        },
+        {
+          "flags": "--user-id <id>",
+          "description": "Matrix user ID"
+        },
+        {
+          "flags": "--access-token <token>",
+          "description": "Matrix access token"
+        },
+        {
+          "flags": "--device-name <name>",
+          "description": "Matrix device name"
+        },
+        {
+          "flags": "--initial-sync-limit <n>",
+          "description": "Matrix initial sync limit"
+        }
+      ],
       "persistedAuthState": {
         "specifier": "./auth-presence",
         "exportName": "hasAnyMatrixAuth"

extensions/nostr/package.json

@@ -32,7 +32,17 @@
       "docsLabel": "nostr",
       "blurb": "Decentralized protocol; encrypted DMs via NIP-04.",
       "order": 55,
-      "quickstartAllowFrom": true
+      "quickstartAllowFrom": true,
+      "cliAddOptions": [
+        {
+          "flags": "--private-key <key>",
+          "description": "Nostr private key (nsec... or hex)"
+        },
+        {
+          "flags": "--relay-urls <list>",
+          "description": "Nostr relay URLs (comma-separated)"
+        }
+      ]
     },
     "install": {
       "npmSpec": "@openclaw/nostr",

extensions/signal/package.json

@@ -21,7 +21,21 @@
       "docsLabel": "signal",
       "blurb": "signal-cli linked device; more setup (David Reagans: \"Hop on Discord.\").",
       "systemImage": "antenna.radiowaves.left.and.right",
-      "markdownCapable": true
+      "markdownCapable": true,
+      "cliAddOptions": [
+        {
+          "flags": "--signal-number <e164>",
+          "description": "Signal account number (E.164)"
+        },
+        {
+          "flags": "--http-host <host>",
+          "description": "Signal HTTP daemon host"
+        },
+        {
+          "flags": "--http-port <port>",
+          "description": "Signal HTTP daemon port"
+        }
+      ]
     }
   }
 }

extensions/tlon/package.json

@@ -34,7 +34,33 @@
       "docsLabel": "tlon",
       "blurb": "decentralized messaging on Urbit; install the plugin to enable.",
       "order": 90,
-      "quickstartAllowFrom": true
+      "quickstartAllowFrom": true,
+      "cliAddOptions": [
+        {
+          "flags": "--ship <ship>",
+          "description": "Tlon ship name (~sampel-palnet)"
+        },
+        {
+          "flags": "--code <code>",
+          "description": "Tlon login code"
+        },
+        {
+          "flags": "--group-channels <list>",
+          "description": "Tlon group channels (comma-separated)"
+        },
+        {
+          "flags": "--dm-allowlist <list>",
+          "description": "Tlon DM allowlist (comma-separated ships)"
+        },
+        {
+          "flags": "--auto-discover-channels",
+          "description": "Tlon auto-discover group channels"
+        },
+        {
+          "flags": "--no-auto-discover-channels",
+          "description": "Disable Tlon auto-discovery"
+        }
+      ]
     },
     "install": {
       "npmSpec": "@openclaw/tlon",

extensions/whatsapp/package.json

@@ -43,7 +43,13 @@
       "persistedAuthState": {
         "specifier": "./auth-presence",
         "exportName": "hasAnyWhatsAppAuth"
-      }
+      },
+      "cliAddOptions": [
+        {
+          "flags": "--auth-dir <path>",
+          "description": "WhatsApp auth directory override"
+        }
+      ]
     },
     "install": {
       "npmSpec": "@openclaw/whatsapp",

src/cli/channels-cli.ts

@@ -1,5 +1,6 @@
 import type { Command } from "commander";
 import { danger } from "../globals.js";
+import { listBundledPackageChannelMetadata } from "../plugins/bundled-package-channel-metadata.js";
 import { defaultRuntime } from "../runtime.js";
 import { formatDocsLink } from "../terminal/links.js";
 import { theme } from "../terminal/theme.js";
@@ -35,6 +36,31 @@ function getOptionNames(command: Command): string[] {
   return command.options.map((option) => option.attributeName());
 }
 
+function addChannelSetupOptions(command: Command): Command {
+  const seenFlags = new Set(command.options.map((option) => option.flags));
+  const channels = listBundledPackageChannelMetadata().toSorted((left, right) => {
+    const leftOrder = left.order ?? Number.MAX_SAFE_INTEGER;
+    const rightOrder = right.order ?? Number.MAX_SAFE_INTEGER;
+    return leftOrder === rightOrder
+      ? (left.id ?? "").localeCompare(right.id ?? "")
+      : leftOrder - rightOrder;
+  });
+  for (const channel of channels) {
+    for (const option of channel.cliAddOptions ?? []) {
+      if (seenFlags.has(option.flags)) {
+        continue;
+      }
+      seenFlags.add(option.flags);
+      if (option.defaultValue !== undefined) {
+        command.option(option.flags, option.description, option.defaultValue);
+      } else {
+        command.option(option.flags, option.description);
+      }
+    }
+  }
+  return command;
+}
+
 export function registerChannelsCli(program: Command) {
   const channelNames = formatCliChannelOptions();
   const channels = program
@@ -134,52 +160,29 @@ export function registerChannelsCli(program: Command) {
       });
     });
 
-  channels
-    .command("add")
-    .description("Add or update a channel account")
-    .option("--channel <name>", `Channel (${channelNames})`)
-    .option("--account <id>", "Account id (default when omitted)")
-    .option("--name <name>", "Display name for this account")
-    .option("--token <token>", "Bot token (Telegram/Discord)")
-    .option("--private-key <key>", "Nostr private key (nsec... or hex)")
-    .option("--token-file <path>", "Bot token file (Telegram)")
-    .option("--bot-token <token>", "Slack bot token (xoxb-...)")
-    .option("--app-token <token>", "Slack app token (xapp-...)")
-    .option("--signal-number <e164>", "Signal account number (E.164)")
-    .option("--cli-path <path>", "CLI path (signal-cli or imsg)")
-    .option("--db-path <path>", "iMessage database path")
-    .option("--service <service>", "iMessage service (imessage|sms|auto)")
-    .option("--region <region>", "iMessage region (for SMS)")
-    .option("--auth-dir <path>", "WhatsApp auth directory override")
-    .option("--http-url <url>", "Signal HTTP daemon base URL")
-    .option("--http-host <host>", "Signal HTTP host")
-    .option("--http-port <port>", "Signal HTTP port")
-    .option("--webhook-path <path>", "Webhook path (Google Chat/BlueBubbles)")
-    .option("--webhook-url <url>", "Google Chat webhook URL")
-    .option("--audience-type <type>", "Google Chat audience type (app-url|project-number)")
-    .option("--audience <value>", "Google Chat audience value (app URL or project number)")
-    .option("--homeserver <url>", "Matrix homeserver URL")
-    .option("--user-id <id>", "Matrix user ID")
-    .option("--access-token <token>", "Matrix access token")
-    .option("--password <password>", "Matrix password")
-    .option("--device-name <name>", "Matrix device name")
-    .option("--initial-sync-limit <n>", "Matrix initial sync limit")
-    .option("--ship <ship>", "Tlon ship name (~sampel-palnet)")
-    .option("--url <url>", "Tlon ship URL")
-    .option("--relay-urls <list>", "Nostr relay URLs (comma-separated)")
-    .option("--code <code>", "Tlon login code")
-    .option("--group-channels <list>", "Tlon group channels (comma-separated)")
-    .option("--dm-allowlist <list>", "Tlon DM allowlist (comma-separated ships)")
-    .option("--auto-discover-channels", "Tlon auto-discover group channels")
-    .option("--no-auto-discover-channels", "Disable Tlon auto-discovery")
-    .option("--use-env", "Use env token (default account only)", false)
-    .action(async (opts, command) => {
-      await runChannelsCommand(async () => {
-        const { channelsAddCommand } = await loadChannelsCommands();
-        const hasFlags = hasExplicitOptions(command, getOptionNames(command));
-        await channelsAddCommand(opts, defaultRuntime, { hasFlags });
-      });
+  addChannelSetupOptions(
+    channels
+      .command("add")
+      .description("Add or update a channel account")
+      .option("--channel <name>", `Channel (${channelNames})`)
+      .option("--account <id>", "Account id (default when omitted)")
+      .option("--name <name>", "Display name for this account")
+      .option("--token <token>", "Channel token or credential payload")
+      .option("--token-file <path>", "Read channel token or credential payload from file")
+      .option("--bot-token <token>", "Bot token")
+      .option("--app-token <token>", "App token")
+      .option("--password <password>", "Channel password or login secret")
+      .option("--cli-path <path>", "Channel CLI path")
+      .option("--url <url>", "Channel setup URL")
+      .option("--http-url <url>", "Channel HTTP service URL")
+      .option("--use-env", "Use env-backed credentials when supported", false),
+  ).action(async (opts, command) => {
+    await runChannelsCommand(async () => {
+      const { channelsAddCommand } = await loadChannelsCommands();
+      const hasFlags = hasExplicitOptions(command, getOptionNames(command));
+      await channelsAddCommand(opts, defaultRuntime, { hasFlags });
     });
+  });
 
   channels
     .command("remove")

src/plugins/bundled-package-channel-metadata.ts

@@ -28,7 +28,7 @@ function readPackageManifest(pluginDir: string): PackageManifest | undefined {
   }
 }
 
-function listBundledPackageChannelMetadata(): readonly PluginPackageChannel[] {
+export function listBundledPackageChannelMetadata(): readonly PluginPackageChannel[] {
   if (bundledPackageChannelMetadataCache) {
     return bundledPackageChannelMetadataCache;
   }

src/plugins/manifest.ts

@@ -960,6 +960,7 @@ export type PluginPackageChannel = {
     exportName?: string;
   };
   doctorCapabilities?: PluginPackageChannelDoctorCapabilities;
+  cliAddOptions?: readonly PluginPackageChannelCliOption[];
 };
 
 export type PluginPackageChannelDoctorCapabilities = {
@@ -969,6 +970,12 @@ export type PluginPackageChannelDoctorCapabilities = {
   warnOnEmptyGroupSenderAllowlist?: boolean;
 };
 
+export type PluginPackageChannelCliOption = {
+  flags: string;
+  description: string;
+  defaultValue?: boolean | string;
+};
+
 export type PluginPackageInstall = {
   npmSpec?: string;
   localPath?: string;