stow-cli 2.0.4 → 2.2.0

package/dist/cli.js

@@ -1,359 +1,62 @@
 #!/usr/bin/env node
+import {
+  CLI_DOCS,
+  renderCommandHelp
+} from "./chunk-XJDK2CBE.js";
+import {
+  InputValidationError
+} from "./chunk-PLZFHPLC.js";
+import {
+  outputError,
+  setForceHuman,
+  setGlobalFields,
+  setGlobalNdjson
+} from "./chunk-P2BKGBQE.js";
 
 // src/cli.ts
 import { StowError } from "@howells/stow-server";
 import { Command } from "commander";
-
-// src/lib/cli-docs.ts
-var CLI_DOCS = {
-  root: {
-    description: "CLI for Stow file storage",
-    usage: "stow [command] [options]",
-    examples: [
-      "stow whoami",
-      "stow upload ./photo.jpg --bucket photos",
-      "stow drop ./screenshot.png",
-      "stow buckets",
-      "stow files photos --limit 50",
-      "stow search text 'sunset beach'",
-      "stow admin health"
-    ],
-    notes: [
-      "Set STOW_API_KEY before running commands that call the API.",
-      "Set STOW_API_URL to target a non-default environment.",
-      "Set STOW_ADMIN_SECRET for admin commands."
-    ]
-  },
-  drop: {
-    description: "Upload a file and get a short URL (quick share)",
-    usage: "stow drop <file> [options]",
-    examples: ["stow drop ./video.mp4", "stow drop ./notes.txt --quiet"]
-  },
-  upload: {
-    description: "Upload a file to a bucket",
-    usage: "stow upload <file> [options]",
-    examples: [
-      "stow upload ./logo.png --bucket brand-assets",
-      "stow upload ./clip.mov --quiet"
-    ]
-  },
-  buckets: {
-    description: "List your buckets",
-    usage: "stow buckets",
-    examples: ["stow buckets"]
-  },
-  bucketsCreate: {
-    description: "Create a new bucket",
-    usage: "stow buckets create <name> [options]",
-    examples: [
-      "stow buckets create photos",
-      'stow buckets create docs --description "Product docs"',
-      "stow buckets create public-media --public"
-    ]
-  },
-  bucketsRename: {
-    description: "Rename a bucket",
-    usage: "stow buckets rename <name> <new-name> [options]",
-    examples: ["stow buckets rename old-name new-name --yes"],
-    notes: ["Renaming a bucket can break existing public URLs."]
-  },
-  bucketsDelete: {
-    description: "Delete a bucket by ID",
-    usage: "stow buckets delete <id>",
-    examples: ["stow buckets delete 8f3d1ab4-..."]
-  },
-  files: {
-    description: "List files in a bucket",
-    usage: "stow files <bucket> [options]",
-    examples: [
-      "stow files photos",
-      "stow files photos --search avatars/ --limit 100",
-      "stow files photos --json"
-    ]
-  },
-  filesGet: {
-    description: "Get details for a single file",
-    usage: "stow files get <bucket> <key>",
-    examples: [
-      "stow files get photos hero.png",
-      "stow files get photos hero.png --json"
-    ]
-  },
-  filesUpdate: {
-    description: "Update file metadata",
-    usage: "stow files update <bucket> <key> -m key=value",
-    examples: [
-      "stow files update photos hero.png -m alt='Hero image'",
-      "stow files update photos hero.png -m category=banner -m priority=high"
-    ]
-  },
-  filesMissing: {
-    description: "List files missing processing data",
-    usage: "stow files missing <bucket> <type>",
-    examples: [
-      "stow files missing brera dimensions",
-      "stow files missing brera embeddings --limit 200",
-      "stow files missing brera colors --json"
-    ],
-    notes: ["Valid types: dimensions, embeddings, colors"]
-  },
-  filesEnrich: {
-    description: "Generate title, description, and alt text for an image",
-    usage: "stow files enrich <bucket> <key>",
-    examples: [
-      "stow files enrich photos hero.jpg",
-      "stow files enrich next l5igro4iutep3"
-    ],
-    notes: [
-      "Triggers title, description, and alt text generation in parallel.",
-      "Requires a searchable bucket with image files."
-    ]
-  },
-  drops: {
-    description: "List your drops with usage info",
-    usage: "stow drops",
-    examples: ["stow drops"]
-  },
-  dropsDelete: {
-    description: "Delete a drop by ID",
-    usage: "stow drops delete <id>",
-    examples: ["stow drops delete drop_abc123"]
-  },
-  delete: {
-    description: "Delete a file from a bucket",
-    usage: "stow delete <bucket> <key>",
-    examples: ["stow delete photos hero/banner.png"]
-  },
-  whoami: {
-    description: "Show account info, usage stats, and API key details",
-    usage: "stow whoami",
-    examples: ["stow whoami"]
-  },
-  open: {
-    description: "Open a bucket in the browser",
-    usage: "stow open <bucket>",
-    examples: ["stow open photos"]
-  },
-  interactive: {
-    description: "Launch interactive TUI mode",
-    usage: "stow --interactive",
-    examples: ["stow", "stow --interactive"]
-  },
-  search: {
-    description: "Search files across buckets",
-    usage: "stow search <subcommand>",
-    examples: [
-      "stow search text 'sunset beach' -b photos",
-      "stow search similar --file hero.png -b photos",
-      'stow search color --hex "#ff0000" -b photos',
-      "stow search diverse -b photos"
-    ]
-  },
-  searchText: {
-    description: "Semantic text search",
-    usage: "stow search text <query> [options]",
-    examples: ["stow search text 'sunset beach' -b photos --limit 10 --json"]
-  },
-  searchSimilar: {
-    description: "Find files similar to a given file",
-    usage: "stow search similar --file <key> [options]",
-    examples: ["stow search similar --file hero.png -b photos"]
-  },
-  searchColor: {
-    description: "Search by color",
-    usage: 'stow search color --hex "#ff0000" [options]',
-    examples: ['stow search color --hex "#ff0000" -b photos --limit 20']
-  },
-  searchDiverse: {
-    description: "Diversity-aware search",
-    usage: "stow search diverse [options]",
-    examples: ["stow search diverse -b photos --limit 20"]
-  },
-  tags: {
-    description: "Manage tags",
-    usage: "stow tags",
-    examples: [
-      "stow tags",
-      "stow tags create 'Hero Images'",
-      "stow tags delete <id>"
-    ]
-  },
-  tagsCreate: {
-    description: "Create a new tag",
-    usage: "stow tags create <name> [options]",
-    examples: [
-      'stow tags create "Hero Images"',
-      'stow tags create "Featured" --color "#ff6600"'
-    ]
-  },
-  tagsDelete: {
-    description: "Delete a tag by ID",
-    usage: "stow tags delete <id>",
-    examples: ["stow tags delete tag_abc123"]
-  },
-  profiles: {
-    description: "Manage taste profiles",
-    usage: "stow profiles <subcommand>",
-    examples: [
-      'stow profiles create --name "My Profile"',
-      "stow profiles get <id>",
-      "stow profiles delete <id>"
-    ]
-  },
-  profilesCreate: {
-    description: "Create a taste profile",
-    usage: 'stow profiles create --name "My Profile" [options]',
-    examples: ['stow profiles create --name "My Profile" -b photos']
-  },
-  profilesGet: {
-    description: "Get a taste profile with clusters",
-    usage: "stow profiles get <id>",
-    examples: ["stow profiles get profile_abc123 --json"]
-  },
-  profilesDelete: {
-    description: "Delete a taste profile",
-    usage: "stow profiles delete <id>",
-    examples: ["stow profiles delete profile_abc123"]
-  },
-  jobs: {
-    description: "List processing jobs for a bucket",
-    usage: "stow jobs --bucket <id> [options]",
-    examples: [
-      "stow jobs --bucket <id>",
-      "stow jobs --bucket <id> --status failed",
-      "stow jobs --bucket <id> --queue extract-colors --json"
-    ]
-  },
-  jobsRetry: {
-    description: "Retry a failed job",
-    usage: "stow jobs retry <id> --queue <name> --bucket <id>",
-    examples: ["stow jobs retry job123 --queue generate-title --bucket <id>"]
-  },
-  jobsDelete: {
-    description: "Remove a job",
-    usage: "stow jobs delete <id> --queue <name> --bucket <id>",
-    examples: ["stow jobs delete job123 --queue extract-colors --bucket <id>"]
-  },
-  admin: {
-    description: "Admin commands (requires STOW_ADMIN_SECRET)",
-    usage: "stow admin <subcommand>",
-    examples: [
-      "stow admin health",
-      "stow admin backfill dimensions --bucket <id> --dry-run",
-      "stow admin cleanup-drops --dry-run"
-    ],
-    notes: ["Requires STOW_ADMIN_SECRET environment variable."]
-  },
-  adminHealth: {
-    description: "Check system health and queue depths",
-    usage: "stow admin health",
-    examples: ["stow admin health", "stow admin health --json"]
-  },
-  adminBackfill: {
-    description: "Backfill processing data for files",
-    usage: "stow admin backfill <type> [options]",
-    examples: [
-      "stow admin backfill dimensions --bucket <id> --dry-run",
-      "stow admin backfill colors --bucket <id> --limit 200",
-      "stow admin backfill embeddings --bucket <id> --limit 100 --json"
-    ],
-    notes: ["Valid types: dimensions, colors, embeddings"]
-  },
-  adminCleanupDrops: {
-    description: "Remove expired drops",
-    usage: "stow admin cleanup-drops [options]",
-    examples: ["stow admin cleanup-drops --max-age-hours 24 --dry-run"]
-  },
-  adminPurgeEvents: {
-    description: "Purge old webhook events",
-    usage: "stow admin purge-events [options]",
-    examples: ["stow admin purge-events --dry-run"]
-  },
-  adminReconcileFiles: {
-    description: "Reconcile files between R2 and database",
-    usage: "stow admin reconcile-files --bucket <id>",
-    examples: ["stow admin reconcile-files --bucket <id> --dry-run"]
-  },
-  adminRetrySyncFailures: {
-    description: "Retry failed S3 sync operations",
-    usage: "stow admin retry-sync-failures",
-    examples: ["stow admin retry-sync-failures"]
-  },
-  adminJobs: {
-    description: "List and manage processing jobs",
-    usage: "stow admin jobs [options]",
-    examples: [
-      "stow admin jobs",
-      "stow admin jobs --status failed",
-      "stow admin jobs --org <id> --queue generate-title",
-      "stow admin jobs --json"
-    ]
-  },
-  adminJobsRetry: {
-    description: "Retry a failed job",
-    usage: "stow admin jobs retry <id> --queue <name>",
-    examples: ["stow admin jobs retry job123 --queue generate-title"]
-  },
-  adminJobsDelete: {
-    description: "Remove a job",
-    usage: "stow admin jobs delete <id> --queue <name>",
-    examples: ["stow admin jobs delete job123 --queue extract-colors"]
-  },
-  adminQueues: {
-    description: "Show queue depths and counts",
-    usage: "stow admin queues",
-    examples: ["stow admin queues", "stow admin queues --json"]
-  },
-  adminQueuesClean: {
-    description: "Clean jobs from a queue",
-    usage: "stow admin queues clean <name> --failed|--completed",
-    examples: [
-      "stow admin queues clean generate-title --failed",
-      "stow admin queues clean extract-colors --completed --grace 3600"
-    ]
-  }
-};
-function renderCommandHelp(key) {
-  const doc = CLI_DOCS[key];
-  const lines = [
-    "",
-    `Usage: ${doc.usage}`,
-    "",
-    "Examples:",
-    ...doc.examples.map((example) => `  ${example}`)
-  ];
-  if (doc.notes?.length) {
-    lines.push("", "Notes:", ...doc.notes.map((note) => `  ${note}`));
-  }
-  return lines.join("\n");
-}
-
-// src/cli.ts
 var VERSION = "1.0.0";
 function handleError(err) {
   if (err instanceof StowError) {
-    console.error(`Error: ${err.message}`);
+    outputError(err.message, err.code, { status: err.status });
+  } else if (err instanceof InputValidationError) {
+    outputError(err.message, "INPUT_VALIDATION");
   } else if (err instanceof Error) {
-    console.error(`Error: ${err.message}`);
+    outputError(err.message);
   } else {
-    console.error(`Error: ${err}`);
+    outputError(String(err));
   }
-  process.exit(1);
 }
 var program = new Command();
-program.name("stow").description(CLI_DOCS.root.description).version(VERSION).addHelpText("after", renderCommandHelp("root"));
+program.name("stow").description(CLI_DOCS.root.description).version(VERSION).option("--human", "Force human-readable output (default when TTY)").option(
+  "--fields <fields>",
+  "Comma-separated fields to include in output (e.g. key,similarity)"
+).option("--ndjson", "Output as newline-delimited JSON (one object per line)").addHelpText("after", renderCommandHelp("root"));
+program.hook("preAction", () => {
+  const opts2 = program.opts();
+  if (opts2.human) {
+    setForceHuman(true);
+  }
+  if (opts2.fields) {
+    setGlobalFields(opts2.fields);
+  }
+  if (opts2.ndjson) {
+    setGlobalNdjson(true);
+  }
+});
 program.command("drop").description(CLI_DOCS.drop.description).argument("<file>", "File to upload").option("-q, --quiet", "Only output the URL").addHelpText("after", renderCommandHelp("drop")).action(async (file, options) => {
   try {
-    const { uploadDrop } = await import("./upload-5RIDB2C5.js");
+    const { uploadDrop } = await import("./upload-OS6Q6LW5.js");
     await uploadDrop(file, options);
   } catch (err) {
     handleError(err);
   }
 });
-program.command("upload").description(CLI_DOCS.upload.description).argument("<file>", "File to upload").option("-b, --bucket <name>", "Bucket name or ID").option("-q, --quiet", "Only output the URL").addHelpText("after", renderCommandHelp("upload")).action(
+program.command("upload").description(CLI_DOCS.upload.description).argument("<file>", "File to upload").option("-b, --bucket <name>", "Bucket name or ID").option("-q, --quiet", "Only output the URL").option("--dry-run", "Preview without uploading").addHelpText("after", renderCommandHelp("upload")).action(
   async (file, options) => {
     try {
-      const { uploadFile } = await import("./upload-5RIDB2C5.js");
+      const { uploadFile } = await import("./upload-OS6Q6LW5.js");
       await uploadFile(file, options);
     } catch (err) {
       handleError(err);
@@ -362,34 +65,36 @@ program.command("upload").description(CLI_DOCS.upload.description).argument("<fi
 );
 var bucketsCmd = program.command("buckets").description(CLI_DOCS.buckets.description).addHelpText("after", renderCommandHelp("buckets")).action(async () => {
   try {
-    const { listBuckets } = await import("./buckets-NXIVHPW5.js");
+    const { listBuckets } = await import("./buckets-ZHP3LBLC.js");
     await listBuckets();
   } catch (err) {
     handleError(err);
   }
 });
-bucketsCmd.command("create").description(CLI_DOCS.bucketsCreate.description).argument("<name>", "Bucket name").option("-d, --description <text>", "Bucket description").option("--public", "Make bucket public").addHelpText("after", renderCommandHelp("bucketsCreate")).action(
+bucketsCmd.command("create").description(CLI_DOCS.bucketsCreate.description).argument("<name>", "Bucket name").option("-d, --description <text>", "Bucket description").option("--public", "Make bucket public").option("--dry-run", "Preview without creating").option("--input-json <json>", "Raw JSON payload").addHelpText("after", renderCommandHelp("bucketsCreate")).action(
   async (name, options) => {
     try {
-      const { createBucket } = await import("./buckets-NXIVHPW5.js");
+      const { createBucket } = await import("./buckets-ZHP3LBLC.js");
       await createBucket(name, options);
     } catch (err) {
       handleError(err);
     }
   }
 );
-bucketsCmd.command("rename").description(CLI_DOCS.bucketsRename.description).argument("<name>", "Current bucket name").argument("<new-name>", "New bucket name").option("-y, --yes", "Skip confirmation warning").addHelpText("after", renderCommandHelp("bucketsRename")).action(async (name, newName, options) => {
-  try {
-    const { renameBucket } = await import("./buckets-NXIVHPW5.js");
-    await renameBucket(name, newName, options);
-  } catch (err) {
-    handleError(err);
+bucketsCmd.command("rename").description(CLI_DOCS.bucketsRename.description).argument("<name>", "Current bucket name").argument("<new-name>", "New bucket name").option("-y, --yes", "Skip confirmation warning").option("--dry-run", "Preview without renaming").option("--input-json <json>", "Raw JSON payload").addHelpText("after", renderCommandHelp("bucketsRename")).action(
+  async (name, newName, options) => {
+    try {
+      const { renameBucket } = await import("./buckets-ZHP3LBLC.js");
+      await renameBucket(name, newName, options);
+    } catch (err) {
+      handleError(err);
+    }
   }
-});
-bucketsCmd.command("delete").description(CLI_DOCS.bucketsDelete.description).argument("<id>", "Bucket ID").addHelpText("after", renderCommandHelp("bucketsDelete")).action(async (id) => {
+);
+bucketsCmd.command("delete").description(CLI_DOCS.bucketsDelete.description).argument("<id>", "Bucket ID").option("--dry-run", "Preview without deleting").addHelpText("after", renderCommandHelp("bucketsDelete")).action(async (id, options) => {
   try {
-    const { deleteBucket } = await import("./buckets-NXIVHPW5.js");
-    await deleteBucket(id);
+    const { deleteBucket } = await import("./buckets-ZHP3LBLC.js");
+    await deleteBucket(id, options);
   } catch (err) {
     handleError(err);
   }
@@ -401,7 +106,7 @@ var filesCmd = program.command("files").description(CLI_DOCS.files.description).
       return;
     }
     try {
-      const { listFiles } = await import("./files-E662TXUP.js");
+      const { listFiles } = await import("./files-UQODXWNT.js");
       await listFiles(bucket, options);
     } catch (err) {
       handleError(err);
@@ -410,16 +115,16 @@ var filesCmd = program.command("files").description(CLI_DOCS.files.description).
 );
 filesCmd.command("get").description(CLI_DOCS.filesGet.description).argument("<bucket>", "Bucket name").argument("<key>", "File key").option("--json", "Output as JSON").addHelpText("after", renderCommandHelp("filesGet")).action(async (bucket, key, options) => {
   try {
-    const { getFile } = await import("./files-E662TXUP.js");
+    const { getFile } = await import("./files-UQODXWNT.js");
     await getFile(bucket, key, options);
   } catch (err) {
     handleError(err);
   }
 });
-filesCmd.command("update").description(CLI_DOCS.filesUpdate.description).argument("<bucket>", "Bucket name").argument("<key>", "File key").option("-m, --metadata <kv...>", "Metadata key=value pairs").option("--json", "Output as JSON").addHelpText("after", renderCommandHelp("filesUpdate")).action(
+filesCmd.command("update").description(CLI_DOCS.filesUpdate.description).argument("<bucket>", "Bucket name").argument("<key>", "File key").option("-m, --metadata <kv...>", "Metadata key=value pairs").option("--json", "Output as JSON").option("--dry-run", "Preview without updating").option("--input-json <json>", "Raw JSON payload").addHelpText("after", renderCommandHelp("filesUpdate")).action(
   async (bucket, key, options) => {
     try {
-      const { updateFile } = await import("./files-E662TXUP.js");
+      const { updateFile } = await import("./files-UQODXWNT.js");
       await updateFile(bucket, key, options);
     } catch (err) {
       handleError(err);
@@ -428,7 +133,7 @@ filesCmd.command("update").description(CLI_DOCS.filesUpdate.description).argumen
 );
 filesCmd.command("enrich").description(CLI_DOCS.filesEnrich.description).argument("<bucket>", "Bucket name").argument("<key>", "File key").addHelpText("after", renderCommandHelp("filesEnrich")).action(async (bucket, key) => {
   try {
-    const { enrichFile } = await import("./files-E662TXUP.js");
+    const { enrichFile } = await import("./files-UQODXWNT.js");
     await enrichFile(bucket, key);
   } catch (err) {
     handleError(err);
@@ -437,7 +142,7 @@ filesCmd.command("enrich").description(CLI_DOCS.filesEnrich.description).argumen
 filesCmd.command("missing").description(CLI_DOCS.filesMissing.description).argument("<bucket>", "Bucket name").argument("<type>", "dimensions | embeddings | colors").option("-l, --limit <count>", "Max files to return").option("--json", "Output as JSON").addHelpText("after", renderCommandHelp("filesMissing")).action(
   async (bucket, type, options) => {
     try {
-      const { listMissing } = await import("./files-E662TXUP.js");
+      const { listMissing } = await import("./files-UQODXWNT.js");
       await listMissing(bucket, type, options);
     } catch (err) {
       handleError(err);
@@ -446,7 +151,7 @@ filesCmd.command("missing").description(CLI_DOCS.filesMissing.description).argum
 );
 var dropsCmd = program.command("drops").description(CLI_DOCS.drops.description).addHelpText("after", renderCommandHelp("drops")).action(async () => {
   try {
-    const { listDrops } = await import("./drops-RD55IDZ4.js");
+    const { listDrops } = await import("./drops-5VIEW3XZ.js");
     await listDrops();
   } catch (err) {
     handleError(err);
@@ -454,7 +159,7 @@ var dropsCmd = program.command("drops").description(CLI_DOCS.drops.description).
 });
 dropsCmd.command("delete").description(CLI_DOCS.dropsDelete.description).argument("<id>", "Drop ID").addHelpText("after", renderCommandHelp("dropsDelete")).action(async (id) => {
   try {
-    const { deleteDrop } = await import("./drops-RD55IDZ4.js");
+    const { deleteDrop } = await import("./drops-5VIEW3XZ.js");
     await deleteDrop(id);
   } catch (err) {
     handleError(err);
@@ -464,7 +169,7 @@ var searchCmd = program.command("search").description(CLI_DOCS.search.descriptio
 searchCmd.command("text").description(CLI_DOCS.searchText.description).argument("<query>", "Search query").option("-b, --bucket <name>", "Bucket name").option("-l, --limit <count>", "Max results").option("--json", "Output as JSON").addHelpText("after", renderCommandHelp("searchText")).action(
   async (query, options) => {
     try {
-      const { textSearch } = await import("./search-DV4VV62L.js");
+      const { textSearch } = await import("./search-TRTPX2SQ.js");
       await textSearch(query, options);
     } catch (err) {
       handleError(err);
@@ -474,7 +179,7 @@ searchCmd.command("text").description(CLI_DOCS.searchText.description).argument(
 searchCmd.command("similar").description(CLI_DOCS.searchSimilar.description).requiredOption("--file <key>", "File key to search from").option("-b, --bucket <name>", "Bucket name").option("-l, --limit <count>", "Max results").option("--json", "Output as JSON").addHelpText("after", renderCommandHelp("searchSimilar")).action(
   async (options) => {
     try {
-      const { similarSearch } = await import("./search-DV4VV62L.js");
+      const { similarSearch } = await import("./search-TRTPX2SQ.js");
       await similarSearch(options);
     } catch (err) {
       handleError(err);
@@ -484,7 +189,7 @@ searchCmd.command("similar").description(CLI_DOCS.searchSimilar.description).req
 searchCmd.command("color").description(CLI_DOCS.searchColor.description).requiredOption("--hex <color>", "Hex color code").option("-b, --bucket <name>", "Bucket name").option("-l, --limit <count>", "Max results").option("--json", "Output as JSON").addHelpText("after", renderCommandHelp("searchColor")).action(
   async (options) => {
     try {
-      const { colorSearch } = await import("./search-DV4VV62L.js");
+      const { colorSearch } = await import("./search-TRTPX2SQ.js");
       await colorSearch(options);
     } catch (err) {
       handleError(err);
@@ -494,7 +199,7 @@ searchCmd.command("color").description(CLI_DOCS.searchColor.description).require
 searchCmd.command("diverse").description(CLI_DOCS.searchDiverse.description).option("-b, --bucket <name>", "Bucket name").option("-l, --limit <count>", "Max results").option("--json", "Output as JSON").addHelpText("after", renderCommandHelp("searchDiverse")).action(
   async (options) => {
     try {
-      const { diverseSearch } = await import("./search-DV4VV62L.js");
+      const { diverseSearch } = await import("./search-TRTPX2SQ.js");
       await diverseSearch(options);
     } catch (err) {
       handleError(err);
@@ -503,24 +208,26 @@ searchCmd.command("diverse").description(CLI_DOCS.searchDiverse.description).opt
 );
 var tagsCmd = program.command("tags").description(CLI_DOCS.tags.description).option("--json", "Output as JSON").addHelpText("after", renderCommandHelp("tags")).action(async (options) => {
   try {
-    const { listTags } = await import("./tags-URHK2YH5.js");
+    const { listTags } = await import("./tags-VH44BGQL.js");
     await listTags(options);
   } catch (err) {
     handleError(err);
   }
 });
-tagsCmd.command("create").description(CLI_DOCS.tagsCreate.description).argument("<name>", "Tag name").option("--color <hex>", "Tag color (hex)").option("--json", "Output as JSON").addHelpText("after", renderCommandHelp("tagsCreate")).action(async (name, options) => {
-  try {
-    const { createTag } = await import("./tags-URHK2YH5.js");
-    await createTag(name, options);
-  } catch (err) {
-    handleError(err);
+tagsCmd.command("create").description(CLI_DOCS.tagsCreate.description).argument("<name>", "Tag name").option("--color <hex>", "Tag color (hex)").option("--json", "Output as JSON").option("--dry-run", "Preview without creating").option("--input-json <json>", "Raw JSON payload").addHelpText("after", renderCommandHelp("tagsCreate")).action(
+  async (name, options) => {
+    try {
+      const { createTag } = await import("./tags-VH44BGQL.js");
+      await createTag(name, options);
+    } catch (err) {
+      handleError(err);
+    }
   }
-});
-tagsCmd.command("delete").description(CLI_DOCS.tagsDelete.description).argument("<id>", "Tag ID").addHelpText("after", renderCommandHelp("tagsDelete")).action(async (id) => {
+);
+tagsCmd.command("delete").description(CLI_DOCS.tagsDelete.description).argument("<id>", "Tag ID").option("--dry-run", "Preview without deleting").addHelpText("after", renderCommandHelp("tagsDelete")).action(async (id, options) => {
   try {
-    const { deleteTag } = await import("./tags-URHK2YH5.js");
-    await deleteTag(id);
+    const { deleteTag } = await import("./tags-VH44BGQL.js");
+    await deleteTag(id, options);
   } catch (err) {
     handleError(err);
   }
@@ -529,7 +236,7 @@ var profilesCmd = program.command("profiles").description(CLI_DOCS.profiles.desc
 profilesCmd.command("create").description(CLI_DOCS.profilesCreate.description).requiredOption("--name <name>", "Profile name").option("-b, --bucket <id>", "Bucket ID").option("--json", "Output as JSON").addHelpText("after", renderCommandHelp("profilesCreate")).action(
   async (options) => {
     try {
-      const { createProfile } = await import("./profiles-C6SCFXS6.js");
+      const { createProfile } = await import("./profiles-CHBGKQOE.js");
       await createProfile(options);
     } catch (err) {
       handleError(err);
@@ -538,7 +245,7 @@ profilesCmd.command("create").description(CLI_DOCS.profilesCreate.description).r
 );
 profilesCmd.command("get").description(CLI_DOCS.profilesGet.description).argument("<id>", "Profile ID").option("--json", "Output as JSON").addHelpText("after", renderCommandHelp("profilesGet")).action(async (id, options) => {
   try {
-    const { getProfile } = await import("./profiles-C6SCFXS6.js");
+    const { getProfile } = await import("./profiles-CHBGKQOE.js");
     await getProfile(id, options);
   } catch (err) {
     handleError(err);
@@ -546,7 +253,7 @@ profilesCmd.command("get").description(CLI_DOCS.profilesGet.description).argumen
 });
 profilesCmd.command("delete").description(CLI_DOCS.profilesDelete.description).argument("<id>", "Profile ID").addHelpText("after", renderCommandHelp("profilesDelete")).action(async (id) => {
   try {
-    const { deleteProfile } = await import("./profiles-C6SCFXS6.js");
+    const { deleteProfile } = await import("./profiles-CHBGKQOE.js");
     await deleteProfile(id);
   } catch (err) {
     handleError(err);
@@ -555,7 +262,7 @@ profilesCmd.command("delete").description(CLI_DOCS.profilesDelete.description).a
 var jobsCmd = program.command("jobs").description(CLI_DOCS.jobs.description).requiredOption("-b, --bucket <id>", "Bucket ID (required)").option("-s, --status <status>", "Filter by status").option("-q, --queue <name>", "Filter by queue name").option("-l, --limit <count>", "Max jobs to return").option("--json", "Output as JSON").addHelpText("after", renderCommandHelp("jobs")).action(
   async (options) => {
     try {
-      const { listJobs } = await import("./jobs-CLXYKZ3B.js");
+      const { listJobs } = await import("./jobs-PTV2W5PJ.js");
       await listJobs(options.bucket, options);
     } catch (err) {
       handleError(err);
@@ -564,7 +271,7 @@ var jobsCmd = program.command("jobs").description(CLI_DOCS.jobs.description).req
 );
 jobsCmd.command("retry").description(CLI_DOCS.jobsRetry.description).argument("<id>", "Job ID").requiredOption("-q, --queue <name>", "Queue name").requiredOption("-b, --bucket <id>", "Bucket ID").addHelpText("after", renderCommandHelp("jobsRetry")).action(async (id, options) => {
   try {
-    const { retryJob } = await import("./jobs-CLXYKZ3B.js");
+    const { retryJob } = await import("./jobs-PTV2W5PJ.js");
     await retryJob(id, options);
   } catch (err) {
     handleError(err);
@@ -572,7 +279,7 @@ jobsCmd.command("retry").description(CLI_DOCS.jobsRetry.description).argument("<
 });
 jobsCmd.command("delete").description(CLI_DOCS.jobsDelete.description).argument("<id>", "Job ID").requiredOption("-q, --queue <name>", "Queue name").requiredOption("-b, --bucket <id>", "Bucket ID").addHelpText("after", renderCommandHelp("jobsDelete")).action(async (id, options) => {
   try {
-    const { deleteJob } = await import("./jobs-CLXYKZ3B.js");
+    const { deleteJob } = await import("./jobs-PTV2W5PJ.js");
     await deleteJob(id, options);
   } catch (err) {
     handleError(err);
@@ -581,7 +288,7 @@ jobsCmd.command("delete").description(CLI_DOCS.jobsDelete.description).argument(
 var adminCmd = program.command("admin").description(CLI_DOCS.admin.description).addHelpText("after", renderCommandHelp("admin"));
 adminCmd.command("health").description(CLI_DOCS.adminHealth.description).option("--json", "Output as JSON").addHelpText("after", renderCommandHelp("adminHealth")).action(async (options) => {
   try {
-    const { health } = await import("./health-6LWM7KAT.js");
+    const { health } = await import("./health-RICGWQGN.js");
     await health(options);
   } catch (err) {
     handleError(err);
@@ -591,7 +298,7 @@ var backfillCmd = adminCmd.command("backfill").description(CLI_DOCS.adminBackfil
 backfillCmd.command("dimensions").description("Backfill image dimensions").option("--bucket <id>", "Bucket ID").option("-l, --limit <count>", "Max files to enqueue").option("--dry-run", "Preview without enqueuing").option("--json", "Output as JSON").action(
   async (options) => {
     try {
-      const { backfillDimensions } = await import("./backfill-G57M2BRA.js");
+      const { backfillDimensions } = await import("./backfill-EVZT7RH6.js");
       await backfillDimensions(options);
     } catch (err) {
       handleError(err);
@@ -601,7 +308,7 @@ backfillCmd.command("dimensions").description("Backfill image dimensions").optio
 backfillCmd.command("colors").description("Backfill color extraction").option("--bucket <id>", "Bucket ID").option("-l, --limit <count>", "Max files to enqueue").option("--dry-run", "Preview without enqueuing").option("--json", "Output as JSON").action(
   async (options) => {
     try {
-      const { backfillColors } = await import("./backfill-G57M2BRA.js");
+      const { backfillColors } = await import("./backfill-EVZT7RH6.js");
       await backfillColors(options);
     } catch (err) {
       handleError(err);
@@ -611,7 +318,7 @@ backfillCmd.command("colors").description("Backfill color extraction").option("-
 backfillCmd.command("embeddings").description("Backfill embedding generation").option("--bucket <id>", "Bucket ID").option("-l, --limit <count>", "Max files to enqueue").option("--dry-run", "Preview without enqueuing").option("--json", "Output as JSON").action(
   async (options) => {
     try {
-      const { backfillEmbeddings } = await import("./backfill-G57M2BRA.js");
+      const { backfillEmbeddings } = await import("./backfill-EVZT7RH6.js");
       await backfillEmbeddings(options);
     } catch (err) {
       handleError(err);
@@ -621,7 +328,7 @@ backfillCmd.command("embeddings").description("Backfill embedding generation").o
 adminCmd.command("cleanup-drops").description(CLI_DOCS.adminCleanupDrops.description).option("--max-age-hours <hours>", "Max age in hours").option("--dry-run", "Preview without deleting").option("--json", "Output as JSON").addHelpText("after", renderCommandHelp("adminCleanupDrops")).action(
   async (options) => {
     try {
-      const { cleanupDrops } = await import("./maintenance-7LOAGG6J.js");
+      const { cleanupDrops } = await import("./maintenance-ZJW2ES4L.js");
       await cleanupDrops(options);
     } catch (err) {
       handleError(err);
@@ -630,7 +337,7 @@ adminCmd.command("cleanup-drops").description(CLI_DOCS.adminCleanupDrops.descrip
 );
 adminCmd.command("purge-events").description(CLI_DOCS.adminPurgeEvents.description).option("--dry-run", "Preview without deleting").option("--json", "Output as JSON").addHelpText("after", renderCommandHelp("adminPurgeEvents")).action(async (options) => {
   try {
-    const { purgeEvents } = await import("./maintenance-7LOAGG6J.js");
+    const { purgeEvents } = await import("./maintenance-ZJW2ES4L.js");
     await purgeEvents(options);
   } catch (err) {
     handleError(err);
@@ -639,7 +346,7 @@ adminCmd.command("purge-events").description(CLI_DOCS.adminPurgeEvents.descripti
 adminCmd.command("reconcile-files").description(CLI_DOCS.adminReconcileFiles.description).requiredOption("--bucket <id>", "Bucket ID").option("--dry-run", "Preview without reconciling").option("--json", "Output as JSON").addHelpText("after", renderCommandHelp("adminReconcileFiles")).action(
   async (options) => {
     try {
-      const { reconcileFiles } = await import("./maintenance-7LOAGG6J.js");
+      const { reconcileFiles } = await import("./maintenance-ZJW2ES4L.js");
       await reconcileFiles(options);
     } catch (err) {
       handleError(err);
@@ -648,7 +355,7 @@ adminCmd.command("reconcile-files").description(CLI_DOCS.adminReconcileFiles.des
 );
 adminCmd.command("retry-sync-failures").description(CLI_DOCS.adminRetrySyncFailures.description).option("--json", "Output as JSON").addHelpText("after", renderCommandHelp("adminRetrySyncFailures")).action(async (options) => {
   try {
-    const { retrySyncFailures } = await import("./maintenance-7LOAGG6J.js");
+    const { retrySyncFailures } = await import("./maintenance-ZJW2ES4L.js");
     await retrySyncFailures(options);
   } catch (err) {
     handleError(err);
@@ -657,7 +364,7 @@ adminCmd.command("retry-sync-failures").description(CLI_DOCS.adminRetrySyncFailu
 var adminJobsCmd = adminCmd.command("jobs").description(CLI_DOCS.adminJobs.description).option("--org <id>", "Filter by org ID").option("--bucket <id>", "Filter by bucket ID").option("-s, --status <status>", "Filter by status").option("-q, --queue <name>", "Filter by queue name").option("-l, --limit <count>", "Max jobs to return").option("--json", "Output as JSON").addHelpText("after", renderCommandHelp("adminJobs")).action(
   async (options) => {
     try {
-      const { listAdminJobs } = await import("./jobs-K3LTNETU.js");
+      const { listAdminJobs } = await import("./jobs-ZWSEXNFA.js");
       await listAdminJobs(options);
     } catch (err) {
       handleError(err);
@@ -666,7 +373,7 @@ var adminJobsCmd = adminCmd.command("jobs").description(CLI_DOCS.adminJobs.descr
 );
 adminJobsCmd.command("retry").description(CLI_DOCS.adminJobsRetry.description).argument("<id>", "Job ID").requiredOption("-q, --queue <name>", "Queue name").addHelpText("after", renderCommandHelp("adminJobsRetry")).action(async (id, options) => {
   try {
-    const { retryAdminJob } = await import("./jobs-K3LTNETU.js");
+    const { retryAdminJob } = await import("./jobs-ZWSEXNFA.js");
     await retryAdminJob(id, options);
   } catch (err) {
     handleError(err);
@@ -674,7 +381,7 @@ adminJobsCmd.command("retry").description(CLI_DOCS.adminJobsRetry.description).a
 });
 adminJobsCmd.command("delete").description(CLI_DOCS.adminJobsDelete.description).argument("<id>", "Job ID").requiredOption("-q, --queue <name>", "Queue name").addHelpText("after", renderCommandHelp("adminJobsDelete")).action(async (id, options) => {
   try {
-    const { deleteAdminJob } = await import("./jobs-K3LTNETU.js");
+    const { deleteAdminJob } = await import("./jobs-ZWSEXNFA.js");
     await deleteAdminJob(id, options);
   } catch (err) {
     handleError(err);
@@ -682,7 +389,7 @@ adminJobsCmd.command("delete").description(CLI_DOCS.adminJobsDelete.description)
 });
 var adminQueuesCmd = adminCmd.command("queues").description(CLI_DOCS.adminQueues.description).option("--json", "Output as JSON").addHelpText("after", renderCommandHelp("adminQueues")).action(async (options) => {
   try {
-    const { listQueues } = await import("./queues-2GJAMMNF.js");
+    const { listQueues } = await import("./queues-EZ2VZGXQ.js");
     await listQueues(options);
   } catch (err) {
     handleError(err);
@@ -691,24 +398,26 @@ var adminQueuesCmd = adminCmd.command("queues").description(CLI_DOCS.adminQueues
 adminQueuesCmd.command("clean").description(CLI_DOCS.adminQueuesClean.description).argument("<name>", "Queue name").option("--failed", "Clean failed jobs").option("--completed", "Clean completed jobs").option("--grace <seconds>", "Grace period in seconds").addHelpText("after", renderCommandHelp("adminQueuesClean")).action(
   async (name, options) => {
     try {
-      const { cleanQueue } = await import("./queues-2GJAMMNF.js");
+      const { cleanQueue } = await import("./queues-EZ2VZGXQ.js");
       await cleanQueue(name, options);
     } catch (err) {
       handleError(err);
     }
   }
 );
-program.command("delete").description(CLI_DOCS.delete.description).argument("<bucket>", "Bucket name").argument("<key>", "File key").addHelpText("after", renderCommandHelp("delete")).action(async (bucket, key) => {
-  try {
-    const { deleteFile } = await import("./delete-GEX3O7YS.js");
-    await deleteFile(bucket, key);
-  } catch (err) {
-    handleError(err);
+program.command("delete").description(CLI_DOCS.delete.description).argument("<bucket>", "Bucket name").argument("<key>", "File key").option("--dry-run", "Preview without deleting").addHelpText("after", renderCommandHelp("delete")).action(
+  async (bucket, key, options) => {
+    try {
+      const { deleteFile } = await import("./delete-YEXSMG4I.js");
+      await deleteFile(bucket, key, options);
+    } catch (err) {
+      handleError(err);
+    }
   }
-});
+);
 program.command("whoami").description(CLI_DOCS.whoami.description).addHelpText("after", renderCommandHelp("whoami")).action(async () => {
   try {
-    const { whoami } = await import("./whoami-5IYRZKWS.js");
+    const { whoami } = await import("./whoami-TVRKBM74.js");
     await whoami();
   } catch (err) {
     handleError(err);
@@ -722,10 +431,26 @@ program.command("open").description(CLI_DOCS.open.description).argument("<bucket
     handleError(err);
   }
 });
+program.command("describe").argument("[command]", "Command path (dot notation, e.g. search.text)").description("Show command schema for AI agents").action(async (command) => {
+  try {
+    const { describeCommand } = await import("./describe-J4ZMUXK7.js");
+    describeCommand(command ?? "");
+  } catch (err) {
+    handleError(err);
+  }
+});
+program.command("mcp").description("Start MCP stdio server for AI agent integration").action(async () => {
+  try {
+    const { startMcpServer } = await import("./mcp-RZT4TJEX.js");
+    await startMcpServer();
+  } catch (err) {
+    handleError(err);
+  }
+});
 program.option("-i, --interactive", CLI_DOCS.interactive.description).addHelpText("after", renderCommandHelp("interactive"));
 program.parse();
 var opts = program.opts();
 var args = process.argv.slice(2);
 if (args.length === 0 || args.length === 1 && opts.interactive) {
-  import("./app-DTW2LNXW.js").then(({ startInteractive }) => startInteractive()).catch(handleError);
+  import("./app-Q6EW7VSM.js").then(({ startInteractive }) => startInteractive()).catch(handleError);
 }