@metabase/cli 0.1.4 → 0.1.6

package/dist/archive-lWgqiFAt.mjs

@@ -0,0 +1,40 @@
+import "./command-augment-BH9qgQ5u.mjs";
+import { connectionFlags, outputFlags, profileFlag } from "./error-C9S6PN3-.mjs";
+import { defineMetabaseCommand } from "./runtime-Dmv5VtUK.mjs";
+import "./capabilities-7e9MgquN.mjs";
+import { renderItem } from "./render-CfznwleY.mjs";
+import { parseId } from "./parse-id-lk_K-CEF.mjs";
+import { Collection, collectionView } from "./collection-B3sPXRLs.mjs";
+
+//#region src/commands/collection/archive.ts
+var archive_default = defineMetabaseCommand({
+	meta: {
+		name: "archive",
+		description: "Archive (soft-delete) a collection by id"
+	},
+	capabilities: { minVersion: 58 },
+	args: {
+		...outputFlags,
+		...profileFlag,
+		...connectionFlags,
+		id: {
+			type: "positional",
+			description: "Collection id",
+			required: true
+		}
+	},
+	outputSchema: Collection,
+	examples: ["mb collection archive 4", "mb collection archive 4 --json"],
+	async run({ args, ctx, getClient }) {
+		const id = parseId(args.id);
+		const client = await getClient();
+		const updated = await client.requestParsed(Collection, `/api/collection/${id}`, {
+			method: "PUT",
+			body: { archived: true }
+		});
+		renderItem(updated, collectionView, ctx);
+	}
+});
+
+//#endregion
+export { archive_default as default };

package/dist/auth-CzXb_zB2.mjs

@@ -0,0 +1,19 @@
+import { defineCommand } from "citty";
+
+//#region src/commands/auth/index.ts
+var auth_default = defineCommand({
+	meta: {
+		name: "auth",
+		description: "Authenticate against a Metabase instance"
+	},
+	default: "login",
+	subCommands: {
+		login: () => import("./login-Bm2AnCez.mjs").then((m) => m.default),
+		status: () => import("./status-B0_MiZEf.mjs").then((m) => m.default),
+		list: () => import("./list-D4sFiqX8.mjs").then((m) => m.default),
+		logout: () => import("./logout-BlyRJODO.mjs").then((m) => m.default)
+	}
+});
+
+//#endregion
+export { auth_default as default };

package/dist/{body-D6dHGjMT.mjs → body-DjdFxjpg.mjs}

@@ -1,6 +1,6 @@
-import { ConfigError } from "./predicates-CGO17Q15.mjs";
-import { readInput } from "./input-BQ-BZA8h.mjs";
-import { parseJson } from "./runtime-Br8L4NPm.mjs";
+import { ConfigError } from "./command-augment-BH9qgQ5u.mjs";
+import { parseJson } from "./runtime-Dmv5VtUK.mjs";
+import { DEFAULT_FLAG_NAME, readInput } from "./input-cMSEqISy.mjs";
 
 //#region src/runtime/body.ts
 async function readBody(sources, schema) {
@@ -10,7 +10,7 @@ async function readBody(sources, schema) {
 }
 function assertSingleSource(sources) {
 	const provided = [];
-	if (sources.flag !== void 0 && sources.flag !== "") provided.push("--body");
+	if (sources.flag !== void 0 && sources.flag !== "") provided.push(DEFAULT_FLAG_NAME);
 	if (sources.file !== void 0 && sources.file !== "") provided.push("--file");
 	if (sources.positional !== void 0 && sources.positional !== "") provided.push("positional");
 	if (provided.length > 1) throw new ConfigError(`multiple body sources given (${provided.join(", ")}); pass exactly one`);

package/dist/{branches-Bpe40fEd.mjs → branches-B1WRfG7-.mjs}

@@ -1,10 +1,10 @@
-import "./package-D-aVYFKM.mjs";
-import "./command-augment-D9pI9Vbh.mjs";
-import { renderList } from "./render-DuoDUTVL.mjs";
-import "./predicates-CGO17Q15.mjs";
-import { connectionFlags, defineMetabaseCommand, listEnvelopeSchema, outputFlags, profileFlag, wrapList } from "./runtime-Br8L4NPm.mjs";
-import { REMOTE_SYNC_PATHS } from "./poll-task-0b1V6G-8.mjs";
-import "./poll-BCnrcUVf.mjs";
+import "./command-augment-BH9qgQ5u.mjs";
+import { connectionFlags, listEnvelopeSchema, outputFlags, profileFlag, wrapList } from "./error-C9S6PN3-.mjs";
+import { defineMetabaseCommand } from "./runtime-Dmv5VtUK.mjs";
+import "./capabilities-7e9MgquN.mjs";
+import { renderList } from "./render-CfznwleY.mjs";
+import { REMOTE_SYNC_PATHS } from "./poll-task-Cooi0lQV.mjs";
+import "./poll-DHKDpCiq.mjs";
 import { z } from "zod";
 
 //#region src/commands/git-sync/branches.ts
@@ -23,6 +23,10 @@ var branches_default = defineMetabaseCommand({
 		name: "branches",
 		description: "List branches on the configured git remote"
 	},
+	capabilities: {
+		minVersion: 60,
+		tokenFeature: "remote_sync"
+	},
 	args: {
 		...outputFlags,
 		...profileFlag,

package/dist/{cancel-BWTY6oYI.mjs → cancel-Dl_Ho056.mjs}

@@ -1,9 +1,9 @@
-import "./package-D-aVYFKM.mjs";
-import "./command-augment-D9pI9Vbh.mjs";
-import { renderItem } from "./render-DuoDUTVL.mjs";
-import "./predicates-CGO17Q15.mjs";
-import { connectionFlags, defineMetabaseCommand, outputFlags, profileFlag } from "./runtime-Br8L4NPm.mjs";
-import { parseId } from "./parse-id-B3B-0hUA.mjs";
+import "./command-augment-BH9qgQ5u.mjs";
+import { connectionFlags, outputFlags, profileFlag } from "./error-C9S6PN3-.mjs";
+import { defineMetabaseCommand } from "./runtime-Dmv5VtUK.mjs";
+import "./capabilities-7e9MgquN.mjs";
+import { renderItem } from "./render-CfznwleY.mjs";
+import { parseId } from "./parse-id-lk_K-CEF.mjs";
 import { z } from "zod";
 
 //#region src/commands/transform/cancel.ts
@@ -26,6 +26,7 @@ var cancel_default = defineMetabaseCommand({
 		name: "cancel",
 		description: "Cancel the current run for a transform"
 	},
+	capabilities: { minVersion: 59 },
 	args: {
 		...outputFlags,
 		...profileFlag,

package/dist/{cancel-task--BfiAXfS.mjs → cancel-task-CdigdCaO.mjs}

@@ -1,10 +1,10 @@
-import "./package-D-aVYFKM.mjs";
-import "./command-augment-D9pI9Vbh.mjs";
-import { renderItem } from "./render-DuoDUTVL.mjs";
-import "./predicates-CGO17Q15.mjs";
-import { connectionFlags, defineMetabaseCommand, outputFlags, profileFlag } from "./runtime-Br8L4NPm.mjs";
-import { REMOTE_SYNC_PATHS, SyncTask, syncTaskView } from "./poll-task-0b1V6G-8.mjs";
-import "./poll-BCnrcUVf.mjs";
+import "./command-augment-BH9qgQ5u.mjs";
+import { connectionFlags, outputFlags, profileFlag } from "./error-C9S6PN3-.mjs";
+import { defineMetabaseCommand } from "./runtime-Dmv5VtUK.mjs";
+import "./capabilities-7e9MgquN.mjs";
+import { renderItem } from "./render-CfznwleY.mjs";
+import { REMOTE_SYNC_PATHS, SyncTask, syncTaskView } from "./poll-task-Cooi0lQV.mjs";
+import "./poll-DHKDpCiq.mjs";
 
 //#region src/commands/git-sync/cancel-task.ts
 var cancel_task_default = defineMetabaseCommand({
@@ -12,6 +12,10 @@ var cancel_task_default = defineMetabaseCommand({
 		name: "cancel-task",
 		description: "Cancel the running git-sync task"
 	},
+	capabilities: {
+		minVersion: 60,
+		tokenFeature: "remote_sync"
+	},
 	args: {
 		...outputFlags,
 		...profileFlag,

package/dist/capabilities-7e9MgquN.mjs

@@ -0,0 +1,29 @@
+import { z } from "zod";
+
+//#region src/runtime/predicates.ts
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+//#endregion
+//#region src/output/notice.ts
+function warn(message) {
+	process.stderr.write(message + "\n");
+}
+function listTruncationNotice(bytes) {
+	return `… cut at ${bytes} bytes; rerun with --max-bytes 0`;
+}
+function itemOversizeMessage(bytes, maxBytes) {
+	return `output is ${bytes} bytes, over the ${maxBytes}-byte --max-bytes cap; narrow with --fields, or pass --max-bytes 0 to disable`;
+}
+
+//#endregion
+//#region src/runtime/capabilities.ts
+const Capabilities = z.object({
+	minVersion: z.number(),
+	tokenFeature: z.string().optional()
+});
+const BASELINE_CAPABILITIES = Object.freeze({ minVersion: 58 });
+
+//#endregion
+export { BASELINE_CAPABILITIES, Capabilities, isPlainObject, itemOversizeMessage, listTruncationNotice, warn };

package/dist/card-DP4rfoOi.mjs

@@ -0,0 +1,21 @@
+import { defineCommand } from "citty";
+
+//#region src/commands/card/index.ts
+var card_default = defineCommand({
+	meta: {
+		name: "card",
+		alias: "cards",
+		description: "Manage Metabase cards (questions, models, metrics)"
+	},
+	subCommands: {
+		list: () => import("./list-BI4zr8LW.mjs").then((mod) => mod.default),
+		get: () => import("./get-CP3Z3NiH.mjs").then((mod) => mod.default),
+		query: () => import("./query-AaKzYnTY.mjs").then((mod) => mod.default),
+		create: () => import("./create-BNiva__H.mjs").then((mod) => mod.default),
+		update: () => import("./update-DBi5U8zb.mjs").then((mod) => mod.default),
+		archive: () => import("./archive-BNinrUak.mjs").then((mod) => mod.default)
+	}
+});
+
+//#endregion
+export { card_default as default };

package/dist/{card-CQxvHeyP.mjs → card-DlCAaAPq.mjs}

@@ -1,4 +1,4 @@
-import { FieldBaseType, FieldSemanticType } from "./field-B3gvaqpK.mjs";
+import { FieldBaseType, FieldSemanticType } from "./field-yomXlkvl.mjs";
 import { z } from "zod";
 
 //#region src/domain/card.ts

package/dist/{cards-CVlFJxYh.mjs → cards-BGiJS675.mjs}

@@ -1,10 +1,10 @@
-import "./package-D-aVYFKM.mjs";
-import "./command-augment-D9pI9Vbh.mjs";
-import { renderList } from "./render-DuoDUTVL.mjs";
-import "./predicates-CGO17Q15.mjs";
-import { connectionFlags, defineMetabaseCommand, listEnvelopeSchema, outputFlags, profileFlag, wrapList } from "./runtime-Br8L4NPm.mjs";
-import { parseId } from "./parse-id-B3B-0hUA.mjs";
-import { DashboardDetail, DashcardCompact, dashcardView } from "./dashboard-CnMD04PQ.mjs";
+import "./command-augment-BH9qgQ5u.mjs";
+import { connectionFlags, listEnvelopeSchema, outputFlags, profileFlag, wrapList } from "./error-C9S6PN3-.mjs";
+import { defineMetabaseCommand } from "./runtime-Dmv5VtUK.mjs";
+import "./capabilities-7e9MgquN.mjs";
+import { renderList } from "./render-CfznwleY.mjs";
+import { parseId } from "./parse-id-lk_K-CEF.mjs";
+import { DashboardDetail, DashcardCompact, dashcardView } from "./dashboard-FY5UzJ_Z.mjs";
 
 //#region src/commands/dashboard/cards.ts
 const DashcardListEnvelope = listEnvelopeSchema(DashcardCompact);
@@ -13,6 +13,7 @@ var cards_default = defineMetabaseCommand({
 		name: "cards",
 		description: "List dashcards on a dashboard"
 	},
+	capabilities: { minVersion: 58 },
 	args: {
 		...outputFlags,
 		...profileFlag,

package/dist/cli.mjs

@@ -1,8 +1,55 @@
 #!/usr/bin/env node
-import { package_default } from "./package-D-aVYFKM.mjs";
-import { getMetabaseAugment } from "./command-augment-D9pI9Vbh.mjs";
+import { ConfigError, flagConsumesValue, getMetabaseAugment, normalizeFlag, resolveCitty, toAliasArray } from "./command-augment-BH9qgQ5u.mjs";
+import { connectionFlags, outputFlags, package_default, profileFlag, reportError } from "./error-C9S6PN3-.mjs";
 import { defineCommand, renderUsage, runMain } from "citty";
 
+//#region src/commands/global-flags.ts
+const ARGUMENT_SEPARATOR = "--";
+const NEGATION_PREFIX = "no-";
+const GLOBAL_FLAG_ARGS = {
+	...outputFlags,
+	...profileFlag,
+	...connectionFlags
+};
+const GLOBAL_FLAG_NAMES = buildGlobalFlagNames();
+function buildGlobalFlagNames() {
+	const names = new Set();
+	for (const [key, def] of Object.entries(GLOBAL_FLAG_ARGS)) {
+		names.add(normalizeFlag(key));
+		if ("alias" in def) for (const alias of toAliasArray(def.alias)) names.add(normalizeFlag(alias));
+	}
+	return names;
+}
+function isGlobalFlag(token) {
+	if (!token.startsWith("-") || token === ARGUMENT_SEPARATOR) return false;
+	const raw = token.includes("=") ? token.slice(0, token.indexOf("=")) : token;
+	const name = normalizeFlag(raw);
+	if (GLOBAL_FLAG_NAMES.has(name)) return true;
+	const bare = raw.replace(/^-+/, "");
+	if (bare.startsWith(NEGATION_PREFIX)) return GLOBAL_FLAG_NAMES.has(normalizeFlag(bare.slice(NEGATION_PREFIX.length)));
+	return false;
+}
+function hoistGlobalFlags(rawArgs) {
+	const leading = [];
+	let index = 0;
+	while (index < rawArgs.length) {
+		const token = rawArgs[index];
+		if (token === void 0 || !isGlobalFlag(token)) break;
+		leading.push(token);
+		index += 1;
+		if (flagConsumesValue(token, GLOBAL_FLAG_ARGS) && index < rawArgs.length) {
+			const value = rawArgs[index];
+			if (value !== void 0) {
+				leading.push(value);
+				index += 1;
+			}
+		}
+	}
+	if (leading.length === 0) return [...rawArgs];
+	return [...rawArgs.slice(index), ...leading];
+}
+
+//#endregion
 //#region src/main.ts
 const main = defineCommand({
 	meta: {
@@ -11,30 +58,29 @@ const main = defineCommand({
 		description: package_default.description
 	},
 	subCommands: {
-		auth: () => import("./auth-N4w5xtwW.mjs").then((mod) => mod.default),
-		license: () => import("./license-DLLTpFvP.mjs").then((mod) => mod.default),
-		db: () => import("./db-CObVU22j.mjs").then((mod) => mod.default),
-		table: () => import("./table-lCNGbvej.mjs").then((mod) => mod.default),
-		field: () => import("./field-CbljasCH.mjs").then((mod) => mod.default),
-		card: () => import("./card-4rZRb5bc.mjs").then((mod) => mod.default),
-		dashboard: () => import("./dashboard-BYBiA-IG.mjs").then((mod) => mod.default),
-		collection: () => import("./collection-Cp_B02I4.mjs").then((mod) => mod.default),
-		transform: () => import("./transform-BGAm1s4f.mjs").then((mod) => mod.default),
-		"transform-job": () => import("./transform-job-cNTJ30pm.mjs").then((mod) => mod.default),
-		setting: () => import("./setting-BDOi5fk_.mjs").then((mod) => mod.default),
-		search: () => import("./search-BT_TCcTd.mjs").then((mod) => mod.default),
-		"git-sync": () => import("./git-sync-BGkS8o5b.mjs").then((mod) => mod.default),
-		workspace: () => import("./workspace-DtcBldk0.mjs").then((mod) => mod.default),
-		setup: () => import("./setup-LjTvvlJy.mjs").then((mod) => mod.default),
-		"api-key": () => import("./api-key-9p1UPnXn.mjs").then((mod) => mod.default),
-		snippet: () => import("./snippet-BcgVYsoR.mjs").then((mod) => mod.default),
-		segment: () => import("./segment-C2ui5dSd.mjs").then((mod) => mod.default),
-		measure: () => import("./measure-B54VtKym.mjs").then((mod) => mod.default),
-		eid: () => import("./eid-Cr5r-t9B.mjs").then((mod) => mod.default),
-		query: () => import("./query-aba8MEe_.mjs").then((mod) => mod.default),
-		uuid: () => import("./uuid-BF20B59s.mjs").then((mod) => mod.default),
-		upgrade: () => import("./upgrade-D58rvXHM.mjs").then((mod) => mod.default),
-		__manifest: () => import("./manifest-CGM7XNLC.mjs").then((mod) => mod.createManifestCommand(main))
+		auth: () => import("./auth-CzXb_zB2.mjs").then((mod) => mod.default),
+		db: () => import("./db-DrQn_i3W.mjs").then((mod) => mod.default),
+		table: () => import("./table-e6h8SLVX.mjs").then((mod) => mod.default),
+		field: () => import("./field-Z6Pcxf4n.mjs").then((mod) => mod.default),
+		card: () => import("./card-DP4rfoOi.mjs").then((mod) => mod.default),
+		dashboard: () => import("./dashboard-ChM_Tu0l.mjs").then((mod) => mod.default),
+		collection: () => import("./collection-tY18ezvn.mjs").then((mod) => mod.default),
+		transform: () => import("./transform-BMYh1lsC.mjs").then((mod) => mod.default),
+		"transform-job": () => import("./transform-job-Cm7z5TfH.mjs").then((mod) => mod.default),
+		setting: () => import("./setting-D2p2MA7f.mjs").then((mod) => mod.default),
+		search: () => import("./search-BLrBXLUk.mjs").then((mod) => mod.default),
+		"git-sync": () => import("./git-sync-CiGAad76.mjs").then((mod) => mod.default),
+		workspace: () => import("./workspace-CKLZrR7l.mjs").then((mod) => mod.default),
+		setup: () => import("./setup-C9ikBRw_.mjs").then((mod) => mod.default),
+		snippet: () => import("./snippet-B7D0uWlz.mjs").then((mod) => mod.default),
+		segment: () => import("./segment-B3Uwwcsm.mjs").then((mod) => mod.default),
+		measure: () => import("./measure-C44EK_xt.mjs").then((mod) => mod.default),
+		eid: () => import("./eid-BXzaQh0o.mjs").then((mod) => mod.default),
+		query: () => import("./query-BlsVNZpD.mjs").then((mod) => mod.default),
+		uuid: () => import("./uuid-CMKnS8-z.mjs").then((mod) => mod.default),
+		upgrade: () => import("./upgrade-iAuvhX-W.mjs").then((mod) => mod.default),
+		skills: () => import("./skills-CUHIcQS6.mjs").then((mod) => mod.default),
+		__manifest: () => import("./manifest-BBR46KFM.mjs").then((mod) => mod.createManifestCommand(main))
 	}
 });
 var main_default = main;
@@ -42,36 +88,213 @@ var main_default = main;
 //#endregion
 //#region src/output/help.ts
 const ANSI_ESC = String.fromCharCode(27);
-const BREADCRUMB_SUFFIX = new RegExp(` \\([^()]*\\)(${ANSI_ESC}\\[\\d+m)?\\s*$`);
-async function showUsage(cmd, parent) {
-	const raw = await renderUsage(cmd, parent);
-	const [first, ...rest] = raw.split("\n");
-	const stripped = first === void 0 ? "" : first.replace(BREADCRUMB_SUFFIX, "$1");
-	const body = [stripped, ...rest].join("\n");
-	const examples = getMetabaseAugment(cmd)?.examples ?? [];
-	process.stdout.write(body + renderExamples(examples) + renderSchemaHint() + "\n");
+const ANSI_PATTERN = new RegExp(`${ANSI_ESC}\\[[0-9;]*m`, "g");
+const BREADCRUMB_SUFFIX = / \([^()]*\)\s*$/;
+const TRAILING_WHITESPACE = /[ \t]+$/;
+const ALIAS_PAIR = /-([a-z0-9]+(?:-[a-z0-9]+)+), --[A-Za-z0-9]+/g;
+const USAGE_PREFIX = "USAGE ";
+const OPTIONS_HEADER = "OPTIONS";
+const LINE_PREFIX = "  ";
+const COLUMN_GAP = "  ";
+const COMMAND_PLACEHOLDER = "<command> [options]";
+const MANIFEST_COMMAND = "__manifest";
+const CLI_NAME = "mb";
+const HELP_FLAG_SPEC = "-h, --help";
+const HELP_FLAG_DESCRIPTION = "Show help for this command";
+const GETTING_STARTED_HINT = `First time? Run \`${CLI_NAME} auth login\` to connect to a Metabase instance.`;
+async function showUsage(cmd, parent, breadcrumb) {
+	const raw = (await renderUsage(cmd, parent)).replace(ANSI_PATTERN, "");
+	const lines = raw.split("\n").map((line) => line.replace(TRAILING_WHITESPACE, ""));
+	const cmdMeta = await resolveCitty(cmd.meta);
+	const parentMeta = parent === void 0 ? void 0 : await resolveCitty(parent.meta);
+	const cmdName = cmdMeta?.name ?? "";
+	const cittyName = parentMeta?.name ? `${parentMeta.name} ${cmdName}` : cmdName;
+	const hasSubCommands = Boolean(cmd.subCommands);
+	const isRoot = parent === void 0 && hasSubCommands;
+	const isManifest = cmdName === MANIFEST_COMMAND;
+	const augment = getMetabaseAugment(cmd);
+	const details = augment?.details ?? null;
+	const examples = augment?.examples ?? [];
+	const transformed = transformBody(lines, {
+		cittyName,
+		breadcrumb: breadcrumb ?? cittyName,
+		hasSubCommands
+	});
+	const body = withDetails(transformed, details).join("\n").trimEnd();
+	const sections = [body];
+	if (examples.length > 0) sections.push(renderExamples(examples));
+	if (isRoot) sections.push(GETTING_STARTED_HINT);
+	if (!isManifest) sections.push(renderSchemaHint());
+	process.stdout.write(sections.join("\n\n") + "\n");
 }
-function renderExamples(examples) {
-	if (examples.length === 0) return "";
-	const lines = [
+function transformBody(lines, rewrite) {
+	const mapped = lines.map((line, index) => {
+		if (index === 0) return line.replace(BREADCRUMB_SUFFIX, "");
+		if (line.startsWith(USAGE_PREFIX)) return rewriteUsageLine(line, rewrite);
+		return fixAliasRow(line);
+	});
+	return injectHelpOption(mapped);
+}
+function rewriteUsageLine(line, rewrite) {
+	if (rewrite.hasSubCommands) return `${USAGE_PREFIX}${rewrite.breadcrumb} ${COMMAND_PLACEHOLDER}`;
+	const content = line.slice(USAGE_PREFIX.length);
+	if (!content.startsWith(rewrite.cittyName)) return line;
+	const rest = content.slice(rewrite.cittyName.length);
+	return `${USAGE_PREFIX}${rewrite.breadcrumb}${rest}`;
+}
+function fixAliasRow(line) {
+	return line.replace(ALIAS_PAIR, (match, kebab) => `--${kebab}`.padStart(match.length));
+}
+function injectHelpOption(lines) {
+	const headerIndex = lines.indexOf(OPTIONS_HEADER);
+	if (headerIndex < 0) return lines;
+	let firstRowIndex = headerIndex + 1;
+	while (firstRowIndex < lines.length && lines[firstRowIndex] === "") firstRowIndex += 1;
+	const sample = lines[firstRowIndex];
+	if (sample === void 0) return lines;
+	const layout = optionLayout(sample);
+	if (layout === null) return lines;
+	let endIndex = firstRowIndex;
+	while (endIndex < lines.length && lines[endIndex] !== "") endIndex += 1;
+	const helpRow = HELP_FLAG_SPEC.padStart(layout.flagEnd).padEnd(layout.descStart) + HELP_FLAG_DESCRIPTION;
+	return [
+		...lines.slice(0, endIndex),
+		helpRow,
+		...lines.slice(endIndex)
+	];
+}
+function optionLayout(row) {
+	const firstNonSpace = row.search(/\S/);
+	if (firstNonSpace < 0) return null;
+	const flagEnd = row.indexOf(COLUMN_GAP, firstNonSpace);
+	if (flagEnd < 0) return null;
+	const gapRemainder = row.slice(flagEnd).search(/\S/);
+	if (gapRemainder < 0) return null;
+	return {
+		flagEnd,
+		descStart: flagEnd + gapRemainder
+	};
+}
+function withDetails(lines, details) {
+	if (details === null) return lines;
+	const [first, ...rest] = lines;
+	if (first === void 0) return lines;
+	return [
+		first,
 		"",
-		"EXAMPLES",
-		""
+		details,
+		...rest
 	];
-	for (const example of examples) lines.push(`  ${example}`);
-	return lines.join("\n");
 }
-function renderSchemaHint() {
+function renderExamples(examples) {
 	return [
+		"EXAMPLES",
 		"",
+		...examples.map((example) => `${LINE_PREFIX}${example}`)
+	].join("\n");
+}
+function renderSchemaHint() {
+	return [
 		"SCHEMA",
 		"",
-		"  mb __manifest      # machine-readable command tree (flags, output, examples)"
+		`${LINE_PREFIX}${CLI_NAME} ${MANIFEST_COMMAND}      # machine-readable command manifest (flags, output, examples)`
 	].join("\n");
 }
+async function walkCommandPath(root, rawArgs) {
+	const rootMeta = await resolveCitty(root.meta);
+	const segments = rootMeta?.name === void 0 ? [] : [rootMeta.name];
+	let current = root;
+	let index = 0;
+	while (index < rawArgs.length) {
+		const subCommands = await resolveCitty(current.subCommands);
+		if (subCommands === void 0) break;
+		const argsDef = await resolveCitty(current.args) ?? {};
+		index = skipFlags(rawArgs, index, argsDef);
+		const token = rawArgs[index];
+		if (token === void 0) break;
+		const match = await findSubCommand(subCommands, token);
+		if (match === null) return {
+			segments,
+			unknownToken: token
+		};
+		segments.push(match.name);
+		current = match.command;
+		index += 1;
+	}
+	return {
+		segments,
+		unknownToken: null
+	};
+}
+async function resolveBreadcrumb(root, rawArgs) {
+	const { segments } = await walkCommandPath(root, rawArgs);
+	return segments.length > 0 ? segments.join(" ") : CLI_NAME;
+}
+async function findUnknownCommand(root, rawArgs) {
+	return (await walkCommandPath(root, rawArgs)).unknownToken;
+}
+function skipFlags(rawArgs, start, argsDef) {
+	let index = start;
+	while (index < rawArgs.length) {
+		const token = rawArgs[index];
+		if (token === void 0) return index;
+		if (token === "--") return rawArgs.length;
+		if (!token.startsWith("-")) return index;
+		if (flagConsumesValue(token, argsDef)) index += 1;
+		index += 1;
+	}
+	return index;
+}
+async function findSubCommand(subCommands, token) {
+	const direct = subCommands[token];
+	if (direct !== void 0) {
+		const command = await resolveCitty(direct);
+		if (command === void 0) return null;
+		const meta = await resolveCitty(command.meta);
+		return {
+			name: meta?.name ?? token,
+			command
+		};
+	}
+	for (const [key, loader] of Object.entries(subCommands)) {
+		const command = await resolveCitty(loader);
+		if (command === void 0) continue;
+		const meta = await resolveCitty(command.meta);
+		if (toAliasArray(meta?.alias).includes(token)) return {
+			name: meta?.name ?? key,
+			command
+		};
+	}
+	return null;
+}
 
 //#endregion
 //#region src/cli.ts
-runMain(main_default, { showUsage });
+const HELP_FLAGS = new Set(["--help", "-h"]);
+async function run() {
+	const rawArgs = hoistGlobalFlags(process.argv.slice(2));
+	const showUsageWithBreadcrumb = async (cmd, parent) => {
+		const breadcrumb = await resolveBreadcrumb(main_default, rawArgs);
+		await showUsage(cmd, parent, breadcrumb);
+	};
+	if (rawArgs.length === 0) {
+		await showUsageWithBreadcrumb(main_default);
+		return;
+	}
+	if (!rawArgs.some((arg) => HELP_FLAGS.has(arg))) {
+		const unknown = await findUnknownCommand(main_default, rawArgs);
+		if (unknown !== null) {
+			reportError(new ConfigError(`unknown command: ${unknown}`));
+			return;
+		}
+	}
+	await runMain(main_default, {
+		showUsage: showUsageWithBreadcrumb,
+		rawArgs
+	});
+}
+run().catch((error) => {
+	reportError(error);
+});
 
 //#endregion

package/dist/collection-tY18ezvn.mjs

@@ -0,0 +1,21 @@
+import { defineCommand } from "citty";
+
+//#region src/commands/collection/index.ts
+var collection_default = defineCommand({
+	meta: {
+		name: "collection",
+		alias: "collections",
+		description: "Manage Metabase collections"
+	},
+	subCommands: {
+		list: () => import("./list-Brgh-Z2v.mjs").then((mod) => mod.default),
+		get: () => import("./get-lb7q3JYs.mjs").then((mod) => mod.default),
+		items: () => import("./items-BWfvkY-J.mjs").then((mod) => mod.default),
+		tree: () => import("./tree-Des2ZG9d.mjs").then((mod) => mod.default),
+		create: () => import("./create-BTcpaop_.mjs").then((mod) => mod.default),
+		archive: () => import("./archive-lWgqiFAt.mjs").then((mod) => mod.default)
+	}
+});
+
+//#endregion
+export { collection_default as default };