improve help

Author: gmethvin

COMMANDS.md

@@ -148,7 +148,7 @@ iterable campaigns list
 
 | Option | Type | Required | Description |
 |--------|------|----------|-------------|
-| `--campaignState` | enum[] | no | Filter campaigns by state. Can specify multiple states. Valid states: Draft, Ready, Scheduled, Running, Finished, Starting, Aborted, Recurring, Archived |
+| `--campaignState` | `Draft` \| `Ready` \| `Scheduled` \| `Running` \| `Finished` \| `Starting` \| `Aborted` \| `Recurring` \| `Archived` | no | Filter campaigns by state |
 | `--order` | `asc` \| `desc` | no | Sort direction (asc or desc) |
 | `--page` | number | no | Page number (starting at 1) |
 | `--pageSize` | number | no | Number of results to return per page (defaults to 20, maximum of 1000) |
@@ -1005,7 +1005,7 @@ iterable subscriptions bulk-update --action <action> --subscriptionGroup <subscr
 
 | Option | Type | Required | Description |
 |--------|------|----------|-------------|
-| `--action` | `subscribe` \| `unsubscribe` | **yes** | Action to perform: subscribe or unsubscribe |
+| `--action` | `subscribe` \| `unsubscribe` | **yes** | Action to perform |
 | `--subscriptionGroup` | `emailList` \| `messageType` \| `messageChannel` | **yes** | Type of subscription group |
 | `--subscriptionGroupId` | number | **yes** | Subscription Group Id |
 | `--users` | string[] | no | Users to subscribe/unsubscribe, identified by email |

package.json

@@ -59,7 +59,7 @@
     "update-commands": "node scripts/update-commands.js"
   },
   "dependencies": {
-    "@iterable/api": "0.10.0",
+    "@iterable/api": "0.10.1",
     "@primno/dpapi": "2.0.1",
     "boxen": "8.0.1",
     "chalk": "5.6.2",

pnpm-lock.yaml

@@ -109,6 +109,10 @@ function getZodTypeName(schema: z.ZodType): string {
 function getEnumValues(schema: z.ZodType): string[] | undefined {
   const inner = unwrapSchema(schema);
   if (inner instanceof z.ZodEnum) return inner.options as string[];
+  if (inner instanceof z.ZodArray) {
+    const element = unwrapSchema(inner.element as z.ZodType);
+    if (element instanceof z.ZodEnum) return element.options as string[];
+  }
   return undefined;
 }
 

src/parser.ts

@@ -197,14 +197,24 @@ function flagLabel(def: FlagDef): string {
   return def.helpArg ? `${names} ${def.helpArg}` : names;
 }
 
-function formatOptionLines(
-  options: { label: string; desc: string }[]
-): string[] {
+interface OptionLine {
+  label: string;
+  desc: string;
+  extra?: string | undefined;
+}
+
+function formatOptionLines(options: OptionLine[]): string[] {
   if (options.length === 0) return [];
   const maxLen = Math.max(...options.map((o) => o.label.length));
-  return options.map(
-    (o) => `  ${theme.accent(o.label.padEnd(maxLen + 2))} ${o.desc}`
-  );
+  const pad = maxLen + 4;
+  const lines: string[] = [];
+  for (const o of options) {
+    lines.push(`  ${theme.accent(o.label.padEnd(maxLen + 2))} ${o.desc}`);
+    if (o.extra) {
+      lines.push(`  ${"".padEnd(pad)}${theme.muted(o.extra)}`);
+    }
+  }
+  return lines;
 }
 
 const COMMAND_RELEVANT_FLAGS = new Set<string>(["output", "columns", "file"]);
@@ -222,19 +232,32 @@ export function showCommandHelp(
     command.description,
   ];
 
-  const options: { label: string; desc: string }[] = [];
+  const options: OptionLine[] = [];
 
   for (const f of fields) {
-    const label = f.isPositional
-      ? `<${f.name}>`
-      : f.enumValues
-        ? `--${f.name} <${f.enumValues.join("|")}>`
-        : `--${f.name} <${f.type}>`;
+    const isArray = f.type.endsWith("[]");
+    const enumInline = f.enumValues && f.enumValues.join("|").length <= 30;
+    let label: string;
+    if (f.isPositional) {
+      label = `<${f.name}>`;
+    } else if (f.enumValues && enumInline) {
+      label = `--${f.name} <${f.enumValues.join("|")}>`;
+    } else if (f.enumValues) {
+      label = isArray ? `--${f.name} <value ...>` : `--${f.name} <value>`;
+    } else if (isArray) {
+      label = `--${f.name} <${f.name} ...>`;
+    } else {
+      label = `--${f.name} <${f.type}>`;
+    }
     let desc = f.description;
     if (f.defaultValue !== undefined)
       desc += ` (default: ${JSON.stringify(f.defaultValue)})`;
     if (f.required) desc += theme.muted(" (required)");
-    options.push({ label, desc });
+    const extra =
+      f.enumValues && !enumInline
+        ? `[values: ${f.enumValues.join(", ")}]`
+        : undefined;
+    options.push({ label, desc, extra });
   }
 
   for (const def of FLAG_DEFS) {