stow-cli 2.0.3 → 2.1.0

package/dist/cli.js

@@ -1,334 +1,12 @@
 #!/usr/bin/env node
+import {
+  CLI_DOCS,
+  renderCommandHelp
+} from "./chunk-XJDK2CBE.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) {
@@ -344,16 +22,16 @@ var program = new Command();
 program.name("stow").description(CLI_DOCS.root.description).version(VERSION).addHelpText("after", renderCommandHelp("root"));
 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-5TAWJU5N.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-5TAWJU5N.js");
       await uploadFile(file, options);
     } catch (err) {
       handleError(err);
@@ -362,34 +40,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-ESAOL6CH.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").addHelpText("after", renderCommandHelp("bucketsCreate")).action(
   async (name, options) => {
     try {
-      const { createBucket } = await import("./buckets-NXIVHPW5.js");
+      const { createBucket } = await import("./buckets-ESAOL6CH.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").addHelpText("after", renderCommandHelp("bucketsRename")).action(
+  async (name, newName, options) => {
+    try {
+      const { renameBucket } = await import("./buckets-ESAOL6CH.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-ESAOL6CH.js");
+    await deleteBucket(id, options);
   } catch (err) {
     handleError(err);
   }
@@ -401,7 +81,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-TDIGJDN3.js");
       await listFiles(bucket, options);
     } catch (err) {
       handleError(err);
@@ -410,16 +90,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-TDIGJDN3.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").addHelpText("after", renderCommandHelp("filesUpdate")).action(
   async (bucket, key, options) => {
     try {
-      const { updateFile } = await import("./files-E662TXUP.js");
+      const { updateFile } = await import("./files-TDIGJDN3.js");
       await updateFile(bucket, key, options);
     } catch (err) {
       handleError(err);
@@ -428,7 +108,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-TDIGJDN3.js");
     await enrichFile(bucket, key);
   } catch (err) {
     handleError(err);
@@ -437,7 +117,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-TDIGJDN3.js");
       await listMissing(bucket, type, options);
     } catch (err) {
       handleError(err);
@@ -503,24 +183,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-MCFL5M2J.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").addHelpText("after", renderCommandHelp("tagsCreate")).action(
+  async (name, options) => {
+    try {
+      const { createTag } = await import("./tags-MCFL5M2J.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-MCFL5M2J.js");
+    await deleteTag(id, options);
   } catch (err) {
     handleError(err);
   }
@@ -698,14 +380,16 @@ adminQueuesCmd.command("clean").description(CLI_DOCS.adminQueuesClean.descriptio
     }
   }
 );
-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-4JSVNETO.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");
@@ -722,6 +406,22 @@ 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-UFMXNNUB.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();

package/dist/delete-4JSVNETO.js

@@ -0,0 +1,34 @@
+import {
+  validateBucketName,
+  validateFileKey
+} from "./chunk-OHAFRKN5.js";
+import {
+  createStow
+} from "./chunk-5LU25QZK.js";
+import "./chunk-TOADDO2F.js";
+
+// src/commands/delete.ts
+async function deleteFile(bucket, key, options = {}) {
+  validateBucketName(bucket);
+  validateFileKey(key);
+  if (options.dryRun) {
+    console.log(
+      JSON.stringify(
+        {
+          dryRun: true,
+          action: "deleteFile",
+          details: { bucket, key }
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+  const stow = createStow();
+  await stow.deleteFile(key, { bucket });
+  console.log(`Deleted: ${key} from ${bucket}`);
+}
+export {
+  deleteFile
+};

package/dist/describe-UFMXNNUB.js

@@ -0,0 +1,79 @@
+import {
+  CLI_DOCS
+} from "./chunk-XJDK2CBE.js";
+import {
+  outputJson
+} from "./chunk-ELSDWMEB.js";
+
+// src/commands/describe.ts
+var COMMAND_MAP = {
+  upload: "upload",
+  drop: "drop",
+  delete: "delete",
+  whoami: "whoami",
+  open: "open",
+  buckets: "buckets",
+  "buckets.create": "bucketsCreate",
+  "buckets.rename": "bucketsRename",
+  "buckets.delete": "bucketsDelete",
+  files: "files",
+  "files.get": "filesGet",
+  "files.update": "filesUpdate",
+  "files.enrich": "filesEnrich",
+  "files.missing": "filesMissing",
+  search: "search",
+  "search.text": "searchText",
+  "search.similar": "searchSimilar",
+  "search.color": "searchColor",
+  "search.diverse": "searchDiverse",
+  tags: "tags",
+  "tags.create": "tagsCreate",
+  "tags.delete": "tagsDelete",
+  drops: "drops",
+  "drops.delete": "dropsDelete",
+  profiles: "profiles",
+  "profiles.create": "profilesCreate",
+  "profiles.get": "profilesGet",
+  "profiles.delete": "profilesDelete",
+  jobs: "jobs",
+  "jobs.retry": "jobsRetry",
+  "jobs.delete": "jobsDelete",
+  admin: "admin",
+  "admin.health": "adminHealth",
+  "admin.backfill": "adminBackfill",
+  "admin.cleanup-drops": "adminCleanupDrops",
+  "admin.purge-events": "adminPurgeEvents",
+  "admin.reconcile-files": "adminReconcileFiles",
+  "admin.retry-sync-failures": "adminRetrySyncFailures",
+  "admin.jobs": "adminJobs",
+  "admin.jobs.retry": "adminJobsRetry",
+  "admin.jobs.delete": "adminJobsDelete",
+  "admin.queues": "adminQueues",
+  "admin.queues.clean": "adminQueuesClean"
+};
+function describeCommand(commandPath) {
+  if (!commandPath) {
+    outputJson({
+      commands: Object.keys(COMMAND_MAP).sort()
+    });
+    return;
+  }
+  const docKey = COMMAND_MAP[commandPath];
+  if (!docKey || !CLI_DOCS[docKey]) {
+    console.error(`Unknown command: ${commandPath}`);
+    console.error(`Available: ${Object.keys(COMMAND_MAP).sort().join(", ")}`);
+    process.exit(1);
+    return;
+  }
+  const doc = CLI_DOCS[docKey];
+  outputJson({
+    command: commandPath,
+    description: doc.description,
+    usage: doc.usage,
+    examples: doc.examples,
+    notes: doc.notes ?? []
+  });
+}
+export {
+  describeCommand
+};