@switchbot/openapi-cli 2.1.0 → 2.2.0

package/README.md

@@ -165,7 +165,8 @@ switchbot config show
 | `--no-retry`                | Disable automatic 429 retries                                            |
 | `--backoff <strategy>`      | Retry backoff: `exponential` (default) or `linear`                      |
 | `--no-quota`                | Disable local request-quota tracking                                     |
-| `--audit-log [path]`        | Append mutating commands to a JSONL audit log (default path: `~/.switchbot/audit.log`) |
+| `--audit-log`               | Append mutating commands to a JSONL audit log (default path: `~/.switchbot/audit.log`) |
+| `--audit-log-path <path>`   | Custom audit log path; use together with `--audit-log`                   |
 | `-V`, `--version`           | Print the CLI version                                                    |
 | `-h`, `--help`              | Show help for any command or subcommand                                  |
 
@@ -212,6 +213,11 @@ switchbot devices list --json | jq '.deviceList[].deviceId'
 # Physical: category = "physical"
 switchbot devices list --format=tsv --fields=deviceId,type,category
 
+# Filter devices by type / name / category / room (server-side filter keys)
+switchbot devices list --filter category=physical
+switchbot devices list --filter type=Bot
+switchbot devices list --filter name=living,category=physical
+
 # Filter by family / room (family & room info requires the 'src: OpenClaw'
 # header, which this CLI sends on every request)
 switchbot devices list --json | jq '.deviceList[] | select(.familyName == "Home")'
@@ -221,6 +227,16 @@ switchbot devices list --json | jq '[.deviceList[], .infraredRemoteList[]] | gro
 switchbot devices status <deviceId>
 switchbot devices status <deviceId> --json
 
+# Resolve device by fuzzy name instead of ID (status, command, describe, expand, watch)
+switchbot devices status --name "客厅空调"
+switchbot devices command --name "Office Light" turnOn
+switchbot devices describe --name "Kitchen Bot"
+
+# Batch status across multiple devices
+switchbot devices status --ids ABC,DEF,GHI
+switchbot devices status --ids ABC,DEF --fields power,battery  # only show specific fields
+switchbot devices status --ids ABC,DEF --format jsonl           # one JSON line per device
+
 # Send a control command
 switchbot devices command <deviceId> <cmd> [parameter] [--type command|customize]
 
@@ -229,7 +245,7 @@ switchbot devices describe <deviceId>
 switchbot devices describe <deviceId> --json
 
 # Discover what's supported (offline reference, no API call)
-switchbot devices types                 # List all device types + IR remote types
+switchbot devices types                 # List all device types + IR remote types (incl. role column)
 switchbot devices commands <type>       # Show commands, parameter formats, and status fields
 switchbot devices commands Bot
 switchbot devices commands "Smart Lock"
@@ -268,6 +284,8 @@ Some commands require a packed string like `"26,2,2,on"`. `devices expand` build
 ```bash
 # Air Conditioner — setAll
 switchbot devices expand <acId> setAll --temp 26 --mode cool --fan low --power on
+# Resolve by name
+switchbot devices expand --name "客厅空调" setAll --temp 26 --mode cool --fan low --power on
 
 # Curtain / Roller Shade — setPosition
 switchbot devices expand <curtainId> setPosition --position 50 --mode silent
@@ -412,6 +430,40 @@ nohup switchbot events mqtt-tail --json >> ~/switchbot-events.log 2>&1 &
 
 Run `switchbot doctor` to verify MQTT credentials are configured correctly before connecting.
 
+#### `mqtt-tail` sinks — route events to external services
+
+By default `mqtt-tail` prints JSONL to stdout. Use `--sink` (repeatable) to route events to one or more destinations instead:
+
+| Sink | Required flags |
+|---|---|
+| `stdout` | (default when no `--sink` given) |
+| `file` | `--sink-file <path>` — append JSONL |
+| `webhook` | `--webhook-url <url>` — HTTP POST each event |
+| `openclaw` | `--openclaw-url`, `--openclaw-token` (or `$OPENCLAW_TOKEN`), `--openclaw-model` |
+| `telegram` | `--telegram-token` (or `$TELEGRAM_TOKEN`), `--telegram-chat <chatId>` |
+| `homeassistant` | `--ha-url <url>` + `--ha-webhook-id` (no auth) or `--ha-token` (REST event API) |
+
+```bash
+# Push events to an OpenClaw agent (replaces the SwitchBot channel plugin)
+switchbot events mqtt-tail \
+  --sink openclaw \
+  --openclaw-token <token> \
+  --openclaw-model my-home-agent
+
+# Write to file + push to OpenClaw simultaneously
+switchbot events mqtt-tail \
+  --sink file --sink-file ~/.switchbot/events.jsonl \
+  --sink openclaw --openclaw-token <token> --openclaw-model home
+
+# Generic webhook (n8n, Make, etc.)
+switchbot events mqtt-tail --sink webhook --webhook-url https://n8n.local/hook/abc
+
+# Forward to Home Assistant via webhook trigger
+switchbot events mqtt-tail --sink homeassistant --ha-url http://homeassistant.local:8123 --ha-webhook-id switchbot
+```
+
+Device state is also persisted to `~/.switchbot/device-history/<deviceId>.json` (latest + 100-entry ring buffer) regardless of sink configuration. This enables the `get_device_history` MCP tool to answer state queries without an API call.
+
 ### `completion` — shell tab-completion
 
 ```bash
@@ -498,7 +550,7 @@ switchbot history replay 7          # re-run entry #7
 switchbot --json history show --limit 50 | jq '.entries[] | select(.result=="error")'
 ```
 
-Reads the JSONL audit log (`~/.switchbot/audit.log` by default; override with `--audit-log`). Each entry records the timestamp, command, device ID, result, and dry-run flag. `replay` re-runs the original command with the original arguments.
+Reads the JSONL audit log (`~/.switchbot/audit.log` by default; override with `--audit-log --audit-log-path <path>`). Each entry records the timestamp, command, device ID, result, and dry-run flag. `replay` re-runs the original command with the original arguments.
 
 ### `catalog` — device type catalog
 

package/dist/commands/capabilities.js

@@ -26,32 +26,42 @@ const MCP_TOOLS = [
     'run_scene',
     'search_catalog',
     'account_overview',
+    'get_device_history',
 ];
 export function registerCapabilitiesCommand(program) {
     program
         .command('capabilities')
         .description('Print a machine-readable manifest of CLI capabilities (for agent bootstrap)')
-        .action(() => {
+        .option('--minimal', 'Omit per-subcommand flag details to reduce output size')
+        .action((opts) => {
         const catalog = getEffectiveCatalog();
-        const commands = program.commands
-            .filter((c) => c.name() !== 'capabilities')
-            .map((c) => ({
-            name: c.name(),
-            description: c.description(),
-            subcommands: c.commands.map((s) => ({
-                name: s.name(),
-                description: s.description(),
-                args: s.registeredArguments.map((a) => ({
-                    name: a.name(),
-                    required: a.required,
-                    variadic: a.variadic,
-                })),
-                flags: s.options.map((o) => ({
-                    flags: o.flags,
-                    description: o.description,
-                })),
-            })),
-        }));
+        const allCommands = [
+            ...program.commands,
+            // Commander adds 'help' implicitly; include it explicitly so it appears in the manifest
+            { name: () => 'help', description: () => 'Display help for a command', commands: [], options: [], registeredArguments: [] },
+        ];
+        const commands = allCommands.map((c) => {
+            const entry = {
+                name: c.name(),
+                description: c.description(),
+            };
+            if (!opts.minimal) {
+                entry.subcommands = c.commands.map((s) => ({
+                    name: s.name(),
+                    description: s.description(),
+                    args: s.registeredArguments.map((a) => ({
+                        name: a.name(),
+                        required: a.required,
+                        variadic: a.variadic,
+                    })),
+                    flags: s.options.map((o) => ({
+                        flags: o.flags,
+                        description: o.description,
+                    })),
+                }));
+            }
+            return entry;
+        });
         const globalFlags = program.options.map((opt) => ({
             flags: opt.flags,
             description: opt.description,

package/dist/commands/devices.js

@@ -66,20 +66,62 @@ Examples:
   $ switchbot devices list --format tsv --fields deviceId,deviceName,type,category
   $ switchbot devices list --json | jq '.deviceList[] | select(.familyName == "家里")'
   $ switchbot devices list --json | jq '[.deviceList[], .infraredRemoteList[]] | group_by(.familyName)'
+  $ switchbot devices list --filter type="Air Conditioner"
+  $ switchbot devices list --filter category=ir
+  $ switchbot devices list --filter name=living,category=physical
 `)
         .option('--wide', 'Show all columns (controlType, family, roomID, room, hub, cloud)')
         .option('--show-hidden', 'Include devices hidden via "devices meta set --hide"')
+        .option('--filter <expr>', 'Filter devices: "type=X", "name=X", "category=physical|ir", "room=X" (comma-separated key=value pairs)')
         .action(async (options) => {
         try {
             const body = await fetchDeviceList();
             const { deviceList, infraredRemoteList } = body;
             const fmt = resolveFormat();
             const deviceMeta = loadDeviceMeta();
+            const hubLocation = buildHubLocationMap(deviceList);
+            let listFilter = null;
+            if (options.filter) {
+                listFilter = {};
+                for (const pair of options.filter.split(',')) {
+                    const eq = pair.indexOf('=');
+                    if (eq === -1)
+                        throw new UsageError(`Invalid --filter pair "${pair.trim()}". Expected key=value.`);
+                    const k = pair.slice(0, eq).trim();
+                    const v = pair.slice(eq + 1).trim();
+                    if (!['type', 'name', 'category', 'room'].includes(k)) {
+                        throw new UsageError(`Unknown --filter key "${k}". Supported: type, name, category, room.`);
+                    }
+                    listFilter[k] = v.toLowerCase();
+                }
+            }
+            const matchesFilter = (entry) => {
+                if (!listFilter)
+                    return true;
+                if (listFilter.type && !entry.type.toLowerCase().includes(listFilter.type))
+                    return false;
+                if (listFilter.name && !entry.name.toLowerCase().includes(listFilter.name))
+                    return false;
+                if (listFilter.category && entry.category !== listFilter.category)
+                    return false;
+                if (listFilter.room && !entry.room.toLowerCase().includes(listFilter.room))
+                    return false;
+                return true;
+            };
             if (fmt === 'json' && process.argv.includes('--json')) {
-                printJson(body);
+                if (listFilter) {
+                    const filteredDeviceList = deviceList.filter((d) => matchesFilter({ type: d.deviceType || '', name: d.deviceName, category: 'physical', room: d.roomName || '' }));
+                    const filteredIrList = infraredRemoteList.filter((d) => {
+                        const inherited = hubLocation.get(d.hubDeviceId);
+                        return matchesFilter({ type: d.remoteType, name: d.deviceName, category: 'ir', room: inherited?.room || '' });
+                    });
+                    printJson({ ok: true, deviceList: filteredDeviceList, infraredRemoteList: filteredIrList });
+                }
+                else {
+                    printJson({ ok: true, ...body });
+                }
                 return;
             }
-            const hubLocation = buildHubLocationMap(deviceList);
             const narrowHeaders = ['deviceId', 'deviceName', 'type', 'category'];
             const wideHeaders = ['deviceId', 'deviceName', 'type', 'category', 'controlType', 'family', 'roomID', 'room', 'hub', 'cloud', 'alias'];
             const userFields = resolveFields();
@@ -88,6 +130,8 @@ Examples:
             for (const d of deviceList) {
                 if (!options.showHidden && deviceMeta.devices[d.deviceId]?.hidden)
                     continue;
+                if (!matchesFilter({ type: d.deviceType || '', name: d.deviceName, category: 'physical', room: d.roomName || '' }))
+                    continue;
                 rows.push([
                     d.deviceId,
                     d.deviceName,
@@ -106,6 +150,8 @@ Examples:
                 if (!options.showHidden && deviceMeta.devices[d.deviceId]?.hidden)
                     continue;
                 const inherited = hubLocation.get(d.hubDeviceId);
+                if (!matchesFilter({ type: d.remoteType, name: d.deviceName, category: 'ir', room: inherited?.room || '' }))
+                    continue;
                 rows.push([
                     d.deviceId,
                     d.deviceName,
@@ -121,13 +167,22 @@ Examples:
                 ]);
             }
             if (rows.length === 0 && fmt === 'table') {
-                console.log('No devices found');
+                console.log(listFilter ? 'No devices matched the filter.' : 'No devices found');
                 return;
             }
             const defaultFields = options.wide ? undefined : narrowHeaders;
-            renderRows(wideHeaders, rows, fmt, userFields ?? defaultFields);
+            // Accept API field names and short aliases alongside canonical column names
+            const DEVICE_LIST_ALIASES = {
+                name: 'deviceName', deviceType: 'type', type: 'type',
+                roomName: 'room', familyName: 'family',
+                hubDeviceId: 'hub', enableCloudService: 'cloud',
+            };
+            renderRows(wideHeaders, rows, fmt, userFields ?? defaultFields, DEVICE_LIST_ALIASES);
             if (fmt === 'table') {
-                console.log(`\nTotal: ${deviceList.length} physical device(s), ${infraredRemoteList.length} IR remote device(s)`);
+                const totalLabel = listFilter
+                    ? `${rows.length} match(es) (${deviceList.length} physical + ${infraredRemoteList.length} IR before filter)`
+                    : `${deviceList.length} physical device(s), ${infraredRemoteList.length} IR remote device(s)`;
+                console.log(`\nTotal: ${totalLabel}`);
                 console.log(`Tip: 'switchbot devices describe <deviceId>' shows a device's supported commands.`);
             }
         }
@@ -139,8 +194,9 @@ Examples:
     devices
         .command('status')
         .description('Query the real-time status of a specific device')
-        .argument('[deviceId]', 'Device ID from "devices list" (or use --name)')
+        .argument('[deviceId]', 'Device ID from "devices list" (or use --name or --ids)')
         .option('--name <query>', 'Resolve device by fuzzy name instead of deviceId')
+        .option('--ids <list>', 'Comma-separated device IDs for batch status (incompatible with --name)')
         .addHelpText('after', `
 Status fields vary by device type. To discover them without a live call:
 
@@ -155,25 +211,70 @@ Examples:
   $ switchbot devices status ABC123DEF456 --json
   $ switchbot devices status ABC123DEF456 --format yaml
   $ switchbot devices status ABC123DEF456 --format tsv --fields power,battery
-  $ switchbot devices status ABC123DEF456 --json | jq '.battery'
+  $ switchbot devices status ABC123DEF456 --json | jq '.data.battery'
+  $ switchbot devices status --ids ABC123,DEF456,GHI789
+  $ switchbot devices status --ids ABC123,DEF456 --fields power,battery
 `)
         .action(async (deviceIdArg, options) => {
         try {
+            // Batch mode: --ids id1,id2,id3
+            if (options.ids) {
+                if (options.name)
+                    throw new UsageError('--ids and --name cannot be used together.');
+                const ids = options.ids.split(',').map((s) => s.trim()).filter(Boolean);
+                if (ids.length === 0)
+                    throw new UsageError('--ids requires at least one device ID.');
+                const results = await Promise.allSettled(ids.map((id) => fetchDeviceStatus(id)));
+                const fetchedAt = new Date().toISOString();
+                const batch = results.map((r, i) => r.status === 'fulfilled'
+                    ? { deviceId: ids[i], ok: true, _fetchedAt: fetchedAt, ...r.value }
+                    : { deviceId: ids[i], ok: false, error: r.reason?.message ?? String(r.reason) });
+                const batchFmt = resolveFormat();
+                if (isJsonMode() || batchFmt === 'json') {
+                    printJson(batch);
+                }
+                else if (batchFmt === 'jsonl') {
+                    for (const entry of batch) {
+                        console.log(JSON.stringify(entry));
+                    }
+                }
+                else {
+                    const fields = resolveFields();
+                    for (const entry of batch) {
+                        const { deviceId, ok, error, _fetchedAt: ts, ...status } = entry;
+                        console.log(`\n─── ${String(deviceId)} ───`);
+                        if (!ok) {
+                            console.error(`  error: ${String(error)}`);
+                        }
+                        else {
+                            const displayStatus = fields
+                                ? Object.fromEntries(fields.map((f) => [f, status[f] ?? null]))
+                                : status;
+                            printKeyValue(displayStatus);
+                            console.error(`  fetched at ${String(ts)}`);
+                        }
+                    }
+                }
+                return;
+            }
             const deviceId = resolveDeviceId(deviceIdArg, options.name);
             const body = await fetchDeviceStatus(deviceId);
+            const fetchedAt = new Date().toISOString();
             const fmt = resolveFormat();
             if (fmt === 'json' && process.argv.includes('--json')) {
-                printJson(body);
+                printJson({ ...body, _fetchedAt: fetchedAt });
                 return;
             }
             if (fmt !== 'table') {
-                const allHeaders = Object.keys(body);
-                const allRows = [Object.values(body)];
+                const statusWithTs = { ...body, _fetchedAt: fetchedAt };
+                const allHeaders = Object.keys(statusWithTs);
+                const allRows = [Object.values(statusWithTs)];
                 const fields = resolveFields();
                 renderRows(allHeaders, allRows, fmt, fields);
                 return;
             }
             printKeyValue(body);
+            console.error(`\nfetched at ${fetchedAt}`);
         }
         catch (error) {
             handleError(error);
@@ -184,7 +285,7 @@ Examples:
         .command('command')
         .description('Send a control command to a device')
         .argument('[deviceId]', 'Target device ID (or use --name)')
-        .argument('<cmd>', 'Command name, e.g. turnOn, turnOff, setColor, setBrightness, setAll, startClean')
+        .argument('[cmd]', 'Command name, e.g. turnOn, turnOff, setColor, setBrightness, setAll, startClean')
         .argument('[parameter]', 'Command parameter. Omit for commands like turnOn/turnOff (defaults to "default"). Format depends on the command (see below).')
         .option('--name <query>', 'Resolve device by fuzzy name instead of deviceId')
         .option('--type <commandType>', 'Command type: "command" for built-in commands (default), "customize" for user-defined IR buttons', 'command')
@@ -235,60 +336,86 @@ Examples:
   $ switchbot devices command ABC123 "MyButton" --type customize
   $ switchbot devices command <lockId> unlock --yes
 `)
-        .action(async (deviceIdArg, cmd, parameter, options) => {
-        const deviceId = resolveDeviceId(deviceIdArg, options.name);
-        const validation = validateCommand(deviceId, cmd, parameter, options.type);
-        if (!validation.ok) {
-            const err = validation.error;
-            if (isJsonMode()) {
-                const obj = { code: 2, kind: 'usage', message: err.message };
-                if (err.hint)
-                    obj.hint = err.hint;
-                obj.context = { validationKind: err.kind };
-                console.error(JSON.stringify({ error: obj }));
+        .action(async (deviceIdArg, cmdArg, parameter, options) => {
+        try {
+            // BUG-FIX: When --name is provided, Commander misassigns the first positional
+            // to [deviceId] instead of [cmd]. Detect and shift positionals accordingly.
+            let cmd;
+            let effectiveDeviceIdArg;
+            if (options.name) {
+                if (deviceIdArg && cmdArg) {
+                    throw new UsageError('Provide either a deviceId argument or --name, not both.');
+                }
+                if (!deviceIdArg && !cmdArg) {
+                    throw new UsageError('Command name is required (e.g. turnOn, turnOff, setAll).');
+                }
+                // --name "x" turnOn  →  deviceIdArg="turnOn", cmdArg=undefined → shift
+                cmd = (deviceIdArg ?? cmdArg);
+                effectiveDeviceIdArg = undefined;
             }
             else {
-                console.error(`Error: ${err.message}`);
-                if (err.hint)
-                    console.error(err.hint);
-                if (err.kind === 'unknown-command') {
-                    const cached = getCachedDevice(deviceId);
-                    if (cached) {
-                        console.error(`Run 'switchbot devices commands ${JSON.stringify(cached.type)}' for parameter formats and descriptions.`);
-                        console.error(`(If the catalog is out of date, run 'switchbot devices list' to refresh the local cache, or pass --type customize for custom IR buttons.)`);
+                if (!cmdArg) {
+                    throw new UsageError('Command name is required (e.g. turnOn, turnOff, setAll).');
+                }
+                cmd = cmdArg;
+                effectiveDeviceIdArg = deviceIdArg;
+            }
+            const deviceId = resolveDeviceId(effectiveDeviceIdArg, options.name);
+            const validation = validateCommand(deviceId, cmd, parameter, options.type);
+            if (!validation.ok) {
+                const err = validation.error;
+                if (isJsonMode()) {
+                    const obj = { code: 2, kind: 'usage', message: err.message };
+                    if (err.hint)
+                        obj.hint = err.hint;
+                    obj.context = { validationKind: err.kind };
+                    console.error(JSON.stringify({ error: obj }));
+                }
+                else {
+                    console.error(`Error: ${err.message}`);
+                    if (err.hint)
+                        console.error(err.hint);
+                    if (err.kind === 'unknown-command') {
+                        const cached = getCachedDevice(deviceId);
+                        if (cached) {
+                            console.error(`Run 'switchbot devices commands ${JSON.stringify(cached.type)}' for parameter formats and descriptions.`);
+                            console.error(`(If the catalog is out of date, run 'switchbot devices list' to refresh the local cache, or pass --type customize for custom IR buttons.)`);
+                        }
                     }
                 }
+                process.exit(2);
             }
-            process.exit(2);
-        }
-        const cachedForGuard = getCachedDevice(deviceId);
-        if (!options.yes &&
-            !isDryRun() &&
-            isDestructiveCommand(cachedForGuard?.type, cmd, options.type)) {
-            const typeLabel = cachedForGuard?.type ?? 'unknown';
-            const reason = getDestructiveReason(cachedForGuard?.type, cmd, options.type);
-            if (isJsonMode()) {
-                console.error(JSON.stringify({
-                    error: {
-                        code: 2,
-                        kind: 'guard',
-                        message: `"${cmd}" on ${typeLabel} is destructive and requires --yes.`,
-                        hint: reason
-                            ? `Re-run with --yes to confirm. Reason: ${reason}`
-                            : 'Re-run with --yes to confirm, or --dry-run to preview without sending.',
-                        context: { command: cmd, deviceType: typeLabel, deviceId, ...(reason ? { destructiveReason: reason } : {}) },
-                    },
-                }));
+            const cachedForGuard = getCachedDevice(deviceId);
+            if (!options.yes &&
+                !isDryRun() &&
+                isDestructiveCommand(cachedForGuard?.type, cmd, options.type)) {
+                const typeLabel = cachedForGuard?.type ?? 'unknown';
+                const reason = getDestructiveReason(cachedForGuard?.type, cmd, options.type);
+                if (isJsonMode()) {
+                    console.error(JSON.stringify({
+                        error: {
+                            code: 2,
+                            kind: 'guard',
+                            message: `"${cmd}" on ${typeLabel} is destructive and requires --yes.`,
+                            hint: reason
+                                ? `Re-run with --yes to confirm. Reason: ${reason}`
+                                : 'Re-run with --yes to confirm, or --dry-run to preview without sending.',
+                            context: { command: cmd, deviceType: typeLabel, deviceId, ...(reason ? { destructiveReason: reason } : {}) },
+                        },
+                    }));
+                }
+                else {
+                    console.error(`Refusing to run destructive command "${cmd}" on ${typeLabel} without --yes.`);
+                    if (reason)
+                        console.error(`Reason: ${reason}`);
+                    console.error(`Re-run with --yes to confirm, or --dry-run to preview without sending.`);
+                }
+                process.exit(2);
             }
-            else {
-                console.error(`Refusing to run destructive command "${cmd}" on ${typeLabel} without --yes.`);
-                if (reason)
-                    console.error(`Reason: ${reason}`);
-                console.error(`Re-run with --yes to confirm, or --dry-run to preview without sending.`);
+            // Warn when --yes is given but the command is not destructive (no-op flag)
+            if (options.yes && !isDestructiveCommand(cachedForGuard?.type, cmd, options.type) && !isDryRun()) {
+                console.error(`Note: --yes has no effect; "${cmd}" is not a destructive command.`);
             }
-            process.exit(2);
-        }
-        try {
             // parameter may be a JSON object string (e.g. S10 startClean) or a plain string
             let parsedParam = parameter ?? 'default';
             if (parameter) {
@@ -311,14 +438,21 @@ Examples:
                 printJson(result);
                 return;
             }
-            console.log(`✓ Command sent: ${cmd}`);
-            if (isIr)
-                console.log('  Note: IR command sent — no device confirmation (fire-and-forget).');
-            if (body && typeof body === 'object' && Object.keys(body).length > 0) {
-                printKeyValue(body);
+            if (isIr) {
+                console.log(`→ IR signal sent: ${cmd} (no feedback — fire-and-forget)`);
+            }
+            else {
+                console.log(`✓ Command sent: ${cmd}`);
+                if (body && typeof body === 'object' && Object.keys(body).length > 0) {
+                    printKeyValue(body);
+                }
             }
         }
         catch (error) {
+            // Re-throw mock process.exit signals (Vitest intercepts process.exit as thrown
+            // Error('__exit__')) so they aren't double-handled and the exit code is preserved.
+            if (error instanceof Error && error.message === '__exit__')
+                throw error;
             handleError(error);
         }
     });
@@ -342,9 +476,10 @@ Examples:
                 printJson(catalog);
                 return;
             }
-            const headers = ['type', 'category', 'commands', 'aliases'];
+            const headers = ['type', 'role', 'category', 'commands', 'aliases'];
             const rows = catalog.map((e) => [
                 e.type,
+                e.role ?? '—',
                 e.category,
                 String(e.commands.length),
                 (e.aliases ?? []).join(', ') || '—',
@@ -535,6 +670,7 @@ function renderCatalogEntry(entry) {
     }
     else {
         console.log('\nCommands:');
+        const hasExamples = entry.commands.some((c) => c.exampleParams && c.exampleParams.length > 0);
         const rows = entry.commands.map((c) => {
             const flags = [];
             if (c.commandType === 'customize')
@@ -542,9 +678,13 @@ function renderCatalogEntry(entry) {
             if (c.destructive)
                 flags.push('!destructive');
             const label = flags.length > 0 ? `${c.command}  [${flags.join(', ')}]` : c.command;
-            return [label, c.parameter, c.description];
+            const base = [label, c.parameter, c.description];
+            return hasExamples ? [...base, (c.exampleParams ?? []).join(' | ') || ''] : base;
         });
-        printTable(['command', 'parameter', 'description'], rows);
+        const tableHeaders = hasExamples
+            ? ['command', 'parameter', 'description', 'example']
+            : ['command', 'parameter', 'description'];
+        printTable(tableHeaders, rows);
         const hasDestructive = entry.commands.some((c) => c.destructive);
         if (hasDestructive) {
             console.log('\n[!destructive] commands have hard-to-reverse real-world effects — confirm before issuing.');