refactor keys, add completion

Author: gmethvin

README.md

@@ -172,6 +172,28 @@ Keys are stored securely using:
 - **Windows**: DPAPI encryption
 - **Linux**: File with restrictive permissions (`~/.iterable/keys.json`)
 
+### Shell Completion
+
+Enable tab completion for commands, subcommands, and flags:
+
+```bash
+iterable completion install    # auto-detects bash, zsh, or fish
+```
+
+After restarting your shell (or sourcing your profile), tab completion is active:
+
+```bash
+iterable <TAB>                 # shows categories
+iterable campaigns <TAB>       # shows commands
+iterable campaigns list <TAB>  # shows flags
+```
+
+To remove:
+
+```bash
+iterable completion uninstall
+```
+
 ## Development
 
 ```bash

package.json

@@ -65,6 +65,7 @@
     "chalk": "5.6.2",
     "cli-table3": "0.6.5",
     "inquirer": "13.3.2",
+    "omelette": "0.4.17",
     "ora": "9.3.0",
     "zod": "4.3.6",
     "zod-opts": "1.0.0"
@@ -77,6 +78,7 @@
     "@types/inquirer": "9.0.9",
     "@types/jest": "30.0.0",
     "@types/node": "25.5.0",
+    "@types/omelette": "0.4.5",
     "@typescript-eslint/eslint-plugin": "8.57.2",
     "@typescript-eslint/parser": "8.57.2",
     "eslint": "10.1.0",

pnpm-lock.yaml

@@ -0,0 +1,77 @@
+import omelette from "omelette";
+
+import {
+  findCommand,
+  getCategories,
+  getCommandsByCategory,
+} from "./commands/registry.js";
+import { OUTPUT_FORMATS } from "./output.js";
+import { describeCommand } from "./parser.js";
+import { FLAG_DEFS } from "./router.js";
+import { COMMAND_NAME, KEYS_SUBCOMMANDS } from "./utils/command-info.js";
+
+export const COMPLETION_SUBCOMMANDS = ["install", "uninstall"] as const;
+
+const SPECIAL_CATEGORIES: Record<string, readonly string[]> = {
+  keys: KEYS_SUBCOMMANDS,
+  completion: COMPLETION_SUBCOMMANDS,
+};
+
+const topLevelCompletions = [
+  ...getCategories(),
+  ...Object.keys(SPECIAL_CATEGORIES),
+];
+
+const globalFlagCompletions = FLAG_DEFS.flatMap((d) => d.aliases);
+
+const completion = omelette(COMMAND_NAME);
+
+completion.on("complete", (_fragment, { before, reply, line }) => {
+  const parts = line.trim().split(" ").slice(1);
+  // Trailing space means the current word is complete — user wants next arg
+  const depth = line.endsWith(" ") ? parts.length + 1 : parts.length;
+  const [category, action] = parts;
+
+  if (depth <= 1) {
+    reply([...topLevelCompletions, "--help", "--version"]);
+    return;
+  }
+
+  if (depth === 2) {
+    const special = category ? SPECIAL_CATEGORIES[category] : undefined;
+    if (special) {
+      reply([...special]);
+      return;
+    }
+    if (category) {
+      reply([...getCommandsByCategory(category).map((c) => c.name), "--help"]);
+      return;
+    }
+  }
+
+  if (category && action) {
+    if (before === "--output") {
+      reply([...OUTPUT_FORMATS]);
+      return;
+    }
+
+    if (before === "--key") {
+      import("./key-manager.js")
+        .then(({ getKeyManager }) => getKeyManager().listKeys())
+        .then((keys) => reply(keys.map((k) => k.name)))
+        .catch(() => reply([]));
+      return;
+    }
+
+    const cmd = findCommand(category, action);
+    if (cmd) {
+      const cmdFlags = describeCommand(cmd).map((f) => `--${f.name}`);
+      reply([...cmdFlags, ...globalFlagCompletions]);
+      return;
+    }
+  }
+
+  reply([]);
+});
+
+export { completion };

src/completion.ts

@@ -4,6 +4,7 @@ import chalk from "chalk";
 import { readFileSync } from "fs";
 import { z } from "zod";
 
+import { completion } from "./completion.js";
 import { createClient, loadCliConfig } from "./config.js";
 import { CliError, UsageError } from "./errors.js";
 import { formatOutput, getDefaultFormat } from "./output.js";
@@ -18,6 +19,8 @@ import {
 } from "./router.js";
 import { COMMAND_NAME } from "./utils/command-info.js";
 
+completion.init();
+
 const CLI_PAGINATION_DEFAULTS: Record<string, number> = {
   page: 1,
   pageSize: 10,
@@ -40,6 +43,44 @@ async function main(): Promise<void> {
     return;
   }
 
+  if (parsed.category === "completion") {
+    /* eslint-disable no-console */
+    // omelette exposes getDefaultShellInitFile() but @types/omelette omits it
+    let initFile: string | undefined;
+    try {
+      initFile = (
+        completion as unknown as { getDefaultShellInitFile: () => string }
+      ).getDefaultShellInitFile();
+    } catch {
+      // Shell detection failed — we'll still try the operation
+    }
+
+    let successMsg: string | undefined;
+
+    // Both setupShellInitFile and cleanupShellInitFile call process.exit(),
+    process.on("exit", () => {
+      if (!successMsg) return;
+      console.log(successMsg);
+      if (initFile) {
+        console.log(`  Modified: ${initFile}`);
+        console.log(`  Restart your shell or run: source ${initFile}`);
+      }
+    });
+
+    if (parsed.action === "install") {
+      successMsg = "Shell completion installed.";
+      completion.setupShellInitFile();
+    } else if (parsed.action === "uninstall") {
+      successMsg = "Shell completion removed.";
+      completion.cleanupShellInitFile();
+    } else {
+      console.log(`Usage: ${COMMAND_NAME} completion install|uninstall`);
+    }
+
+    /* eslint-enable no-console */
+    return;
+  }
+
   if (parsed.category === "keys") {
     const { handleKeysCommand } = await import("./keys-cli.js");
     await handleKeysCommand(

src/index.ts

@@ -71,13 +71,17 @@ enum StorageMethod {
   FILE = "file",
 }
 
-export interface ApiKeyMetadata {
+/** User-facing key identity — the fields shown in display/help output. */
+export interface ApiKeySummary {
   /** Unique identifier for this key */
   id: string;
   /** User-friendly name for this key */
   name: string;
   /** Iterable API base URL (e.g., https://api.iterable.com or https://api.eu.iterable.com) */
   baseUrl: string;
+}
+
+export interface ApiKeyMetadata extends ApiKeySummary {
   /** ISO timestamp when key was created */
   created: string;
   /** ISO timestamp when key was last updated */