@metabase/cli 0.1.5 → 0.1.7

package/dist/{archive-Dvzrmdbk.mjs → archive-De8jzzq7.mjs}

@@ -1,11 +1,11 @@
-import "./package-DFUprkSZ.mjs";
-import "./command-augment-D9pI9Vbh.mjs";
-import { renderItem } from "./render-DuoDUTVL.mjs";
-import "./predicates-CGO17Q15.mjs";
-import { connectionFlags, defineMetabaseCommand, outputFlags, profileFlag } from "./runtime-CDu6fykq.mjs";
-import { parseId } from "./parse-id-CysSaCbf.mjs";
-import "./field-B3gvaqpK.mjs";
-import { Card, cardView } from "./card-CQxvHeyP.mjs";
+import "./command-augment-BH9qgQ5u.mjs";
+import { connectionFlags, outputFlags, profileFlag } from "./error-ZsFeevV2.mjs";
+import { defineMetabaseCommand } from "./runtime-Duawf5lE.mjs";
+import "./capabilities-7e9MgquN.mjs";
+import { renderSummary } from "./render-0_GsapXa.mjs";
+import "./field-E0IBy4Uw.mjs";
+import { Card, cardView } from "./card-ezYiriML.mjs";
+import { parseId } from "./parse-id-0_tOPvfI.mjs";
 
 //#region src/commands/card/archive.ts
 var archive_default = defineMetabaseCommand({
@@ -13,6 +13,7 @@ var archive_default = defineMetabaseCommand({
 		name: "archive",
 		description: "Archive (soft-delete) a card by id"
 	},
+	capabilities: { minVersion: 58 },
 	args: {
 		...outputFlags,
 		...profileFlag,
@@ -32,7 +33,7 @@ var archive_default = defineMetabaseCommand({
 			method: "PUT",
 			body: { archived: true }
 		});
-		renderItem(updated, cardView, ctx);
+		renderSummary(updated, cardView, `Archived card ${updated.id} "${updated.name}".`, ctx);
 	}
 });
 

package/dist/auth-D9eAyVoG.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-enh9Yimb.mjs").then((m) => m.default),
+		status: () => import("./status-BNvFPemM.mjs").then((m) => m.default),
+		list: () => import("./list-C-oZe1_p.mjs").then((m) => m.default),
+		logout: () => import("./logout-BWLPLDh8.mjs").then((m) => m.default)
+	}
+});
+
+//#endregion
+export { auth_default as default };

package/dist/{body-XtR7-uCO.mjs → body-tcURGnGh.mjs}

@@ -1,6 +1,6 @@
-import { ConfigError } from "./predicates-CGO17Q15.mjs";
-import { readInput } from "./input-BQ-BZA8h.mjs";
-import { parseJson } from "./runtime-CDu6fykq.mjs";
+import { ConfigError } from "./command-augment-BH9qgQ5u.mjs";
+import { parseJson } from "./runtime-Duawf5lE.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-XUY4JY-X.mjs → branches-CIGkjXIk.mjs}

@@ -1,10 +1,10 @@
-import "./package-DFUprkSZ.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-CDu6fykq.mjs";
-import { REMOTE_SYNC_PATHS } from "./poll-task-BQe0NvJZ.mjs";
-import "./poll-p9Y7-JEQ.mjs";
+import "./command-augment-BH9qgQ5u.mjs";
+import { connectionFlags, listEnvelopeSchema, outputFlags, profileFlag, wrapList } from "./error-ZsFeevV2.mjs";
+import { defineMetabaseCommand } from "./runtime-Duawf5lE.mjs";
+import "./capabilities-7e9MgquN.mjs";
+import { renderList } from "./render-0_GsapXa.mjs";
+import { REMOTE_SYNC_PATHS } from "./poll-task-51WRdugU.mjs";
+import "./poll-4eoh5J0r.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-BrUVO_ax.mjs → cancel-pPsvgJ0Z.mjs}

@@ -1,9 +1,9 @@
-import "./package-DFUprkSZ.mjs";
-import "./command-augment-D9pI9Vbh.mjs";
-import { renderItem } from "./render-DuoDUTVL.mjs";
-import "./predicates-CGO17Q15.mjs";
-import { connectionFlags, defineMetabaseCommand, outputFlags, profileFlag } from "./runtime-CDu6fykq.mjs";
-import { parseId } from "./parse-id-CysSaCbf.mjs";
+import "./command-augment-BH9qgQ5u.mjs";
+import { connectionFlags, outputFlags, profileFlag } from "./error-ZsFeevV2.mjs";
+import { defineMetabaseCommand } from "./runtime-Duawf5lE.mjs";
+import "./capabilities-7e9MgquN.mjs";
+import { renderSummary } from "./render-0_GsapXa.mjs";
+import { parseId } from "./parse-id-0_tOPvfI.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,
@@ -45,10 +46,10 @@ var cancel_default = defineMetabaseCommand({
 			method: "POST",
 			expectContentType: "binary"
 		});
-		renderItem({
+		renderSummary({
 			canceled: true,
 			id
-		}, transformCancelView, ctx);
+		}, transformCancelView, `Canceled the current run for transform ${id}.`, ctx);
 	}
 });
 

package/dist/{cancel-task-oXheTOB6.mjs → cancel-task-BLGE4UlL.mjs}

@@ -1,10 +1,10 @@
-import "./package-DFUprkSZ.mjs";
-import "./command-augment-D9pI9Vbh.mjs";
-import { renderItem } from "./render-DuoDUTVL.mjs";
-import "./predicates-CGO17Q15.mjs";
-import { connectionFlags, defineMetabaseCommand, outputFlags, profileFlag } from "./runtime-CDu6fykq.mjs";
-import { REMOTE_SYNC_PATHS, SyncTask, syncTaskView } from "./poll-task-BQe0NvJZ.mjs";
-import "./poll-p9Y7-JEQ.mjs";
+import "./command-augment-BH9qgQ5u.mjs";
+import { connectionFlags, outputFlags, profileFlag } from "./error-ZsFeevV2.mjs";
+import { defineMetabaseCommand } from "./runtime-Duawf5lE.mjs";
+import "./capabilities-7e9MgquN.mjs";
+import { renderSummary } from "./render-0_GsapXa.mjs";
+import { REMOTE_SYNC_PATHS, SyncTask, syncTaskView } from "./poll-task-51WRdugU.mjs";
+import "./poll-4eoh5J0r.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,
@@ -22,7 +26,7 @@ var cancel_task_default = defineMetabaseCommand({
 	async run({ ctx, getClient }) {
 		const client = await getClient();
 		const task = await client.requestParsed(SyncTask, REMOTE_SYNC_PATHS.cancelTask, { method: "POST" });
-		renderItem(task, syncTaskView, ctx);
+		renderSummary(task, syncTaskView, `Requested cancellation of ${task.sync_task_type} task #${task.id}.`, ctx);
 	}
 });
 

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-DDDrWcDU.mjs

@@ -0,0 +1,20 @@
+import { defineCommand } from "citty";
+
+//#region src/commands/card/index.ts
+var card_default = defineCommand({
+	meta: {
+		name: "card",
+		description: "Manage Metabase cards (questions, models, metrics)"
+	},
+	subCommands: {
+		list: () => import("./list-DfDZr55C.mjs").then((mod) => mod.default),
+		get: () => import("./get-sMpa-X4E.mjs").then((mod) => mod.default),
+		query: () => import("./query-DYVBnu9d.mjs").then((mod) => mod.default),
+		create: () => import("./create-BIphz0kO.mjs").then((mod) => mod.default),
+		update: () => import("./update-DCrOQ1PW.mjs").then((mod) => mod.default),
+		archive: () => import("./archive-De8jzzq7.mjs").then((mod) => mod.default)
+	}
+});
+
+//#endregion
+export { card_default as default };

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

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

package/dist/{cards-CONTTAG9.mjs → cards-Dq3nx_9n.mjs}

@@ -1,10 +1,10 @@
-import "./package-DFUprkSZ.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-CDu6fykq.mjs";
-import { parseId } from "./parse-id-CysSaCbf.mjs";
-import { DashboardDetail, DashcardCompact, dashcardView } from "./dashboard-CnMD04PQ.mjs";
+import "./command-augment-BH9qgQ5u.mjs";
+import { connectionFlags, listEnvelopeSchema, outputFlags, profileFlag, wrapList } from "./error-ZsFeevV2.mjs";
+import { defineMetabaseCommand } from "./runtime-Duawf5lE.mjs";
+import "./capabilities-7e9MgquN.mjs";
+import { renderList } from "./render-0_GsapXa.mjs";
+import { parseId } from "./parse-id-0_tOPvfI.mjs";
+import { DashboardDetail, DashcardCompact, dashcardView } from "./dashboard-B4bn3z6t.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-DFUprkSZ.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-ZsFeevV2.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,31 +58,29 @@ const main = defineCommand({
 		description: package_default.description
 	},
 	subCommands: {
-		auth: () => import("./auth-DICRtJDy.mjs").then((mod) => mod.default),
-		license: () => import("./license-Cb6ewEJO.mjs").then((mod) => mod.default),
-		db: () => import("./db-qVK6NsdB.mjs").then((mod) => mod.default),
-		table: () => import("./table-BwX3Ib5f.mjs").then((mod) => mod.default),
-		field: () => import("./field-C0LE7RQI.mjs").then((mod) => mod.default),
-		card: () => import("./card-l-UmrUIo.mjs").then((mod) => mod.default),
-		dashboard: () => import("./dashboard-hbKDd36X.mjs").then((mod) => mod.default),
-		collection: () => import("./collection-oV0olVY-.mjs").then((mod) => mod.default),
-		transform: () => import("./transform-iaAi37V0.mjs").then((mod) => mod.default),
-		"transform-job": () => import("./transform-job-Bemonf82.mjs").then((mod) => mod.default),
-		setting: () => import("./setting-Czy4ws6h.mjs").then((mod) => mod.default),
-		search: () => import("./search-DObOsjbP.mjs").then((mod) => mod.default),
-		"git-sync": () => import("./git-sync-DV7YjniX.mjs").then((mod) => mod.default),
-		workspace: () => import("./workspace-BBsT0H0g.mjs").then((mod) => mod.default),
-		setup: () => import("./setup-DqBOe3HZ.mjs").then((mod) => mod.default),
-		"api-key": () => import("./api-key-BENHbTbV.mjs").then((mod) => mod.default),
-		snippet: () => import("./snippet-BCY4KHBU.mjs").then((mod) => mod.default),
-		segment: () => import("./segment-DfxZdJmR.mjs").then((mod) => mod.default),
-		measure: () => import("./measure-XhJuL77y.mjs").then((mod) => mod.default),
-		eid: () => import("./eid-CDFXX_6H.mjs").then((mod) => mod.default),
-		query: () => import("./query-C7zTlFJA.mjs").then((mod) => mod.default),
-		uuid: () => import("./uuid-CJz9TmHI.mjs").then((mod) => mod.default),
-		upgrade: () => import("./upgrade-CIgTr2CG.mjs").then((mod) => mod.default),
-		skills: () => import("./skills-C2rTVj0n.mjs").then((mod) => mod.default),
-		__manifest: () => import("./manifest-CGM7XNLC.mjs").then((mod) => mod.createManifestCommand(main))
+		auth: () => import("./auth-D9eAyVoG.mjs").then((mod) => mod.default),
+		db: () => import("./db-CWTFe_FZ.mjs").then((mod) => mod.default),
+		table: () => import("./table-J2f0STnB.mjs").then((mod) => mod.default),
+		field: () => import("./field-LL6W_c-c.mjs").then((mod) => mod.default),
+		card: () => import("./card-DDDrWcDU.mjs").then((mod) => mod.default),
+		dashboard: () => import("./dashboard-BLf1RZlk.mjs").then((mod) => mod.default),
+		collection: () => import("./collection-DkEvCDar.mjs").then((mod) => mod.default),
+		transform: () => import("./transform-q1LYWQtW.mjs").then((mod) => mod.default),
+		"transform-job": () => import("./transform-job-OW4SDhsQ.mjs").then((mod) => mod.default),
+		setting: () => import("./setting-DUa96KF3.mjs").then((mod) => mod.default),
+		search: () => import("./search-DYP3lOlq.mjs").then((mod) => mod.default),
+		"git-sync": () => import("./git-sync-CrWTo3YX.mjs").then((mod) => mod.default),
+		workspace: () => import("./workspace-ri6r3zWo.mjs").then((mod) => mod.default),
+		setup: () => import("./setup-BPlllnim.mjs").then((mod) => mod.default),
+		snippet: () => import("./snippet-dJ68tGsl.mjs").then((mod) => mod.default),
+		segment: () => import("./segment-B6HnNGDs.mjs").then((mod) => mod.default),
+		measure: () => import("./measure-CDlEPFtB.mjs").then((mod) => mod.default),
+		eid: () => import("./eid-CLY5X0Uw.mjs").then((mod) => mod.default),
+		query: () => import("./query-BBCAF-tG.mjs").then((mod) => mod.default),
+		uuid: () => import("./uuid-BSVUk8u2.mjs").then((mod) => mod.default),
+		upgrade: () => import("./upgrade-D-Rl_fH9.mjs").then((mod) => mod.default),
+		skills: () => import("./skills-SqbPo0BI.mjs").then((mod) => mod.default),
+		__manifest: () => import("./manifest-BNh0Lw6p.mjs").then((mod) => mod.createManifestCommand(main))
 	}
 });
 var main_default = main;
@@ -43,38 +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*$`);
+const ANSI_PATTERN = new RegExp(`${ANSI_ESC}\\[[0-9;]*m`, "g");
+const BREADCRUMB_SUFFIX = / \([^()]*\)\s*$/;
 const TRAILING_WHITESPACE = /[ \t]+$/;
-async function showUsage(cmd, parent) {
-	const raw = await renderUsage(cmd, parent);
+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 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;
-	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");
+	if (first === void 0) return lines;
+	return [
+		first,
+		"",
+		details,
+		...rest
+	];
 }
 function renderExamples(examples) {
-	if (examples.length === 0) return "";
-	const lines = [
-		"",
+	return [
 		"EXAMPLES",
-		""
-	];
-	for (const example of examples) lines.push(`  ${example}`);
-	return lines.join("\n");
+		"",
+		...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-DkEvCDar.mjs

@@ -0,0 +1,20 @@
+import { defineCommand } from "citty";
+
+//#region src/commands/collection/index.ts
+var collection_default = defineCommand({
+	meta: {
+		name: "collection",
+		description: "Manage Metabase collections"
+	},
+	subCommands: {
+		list: () => import("./list-CU6sOfI-.mjs").then((mod) => mod.default),
+		get: () => import("./get-CRvbChoX.mjs").then((mod) => mod.default),
+		items: () => import("./items-C94eW2Yd.mjs").then((mod) => mod.default),
+		tree: () => import("./tree-mvq9gM9w.mjs").then((mod) => mod.default),
+		create: () => import("./create-w3mQg9n4.mjs").then((mod) => mod.default),
+		archive: () => import("./archive-DTN9tLGT.mjs").then((mod) => mod.default)
+	}
+});
+
+//#endregion
+export { collection_default as default };