citty 0.2.0 → 0.2.2

package/README.md

@@ -10,32 +10,19 @@
 
 Elegant CLI Builder
 
-- Zero dependency
-- Fast and lightweight argument parser (based on native [node utils](arg parser](https://nodejs.org/api/util.html#utilparseargsconfig))
+- Zero dependency, fast and lightweight (based on native [`util.parseArgs`](https://nodejs.org/api/util.html#utilparseargsconfig))
 - Smart value parsing with typecast and boolean shortcuts
-- Nested sub-commands
-- Lazy and Async commands
-- Pluggable and composable API
-- Auto generated usage and help
+- Nested sub-commands with lazy and async loading
+- Pluggable and composable API with auto generated usage
 
 ## Usage
 
-Install package:
-
 ```sh
 npx nypm add -D citty
 ```
 
-Import:
-
 ```js
 import { defineCommand, runMain } from "citty";
-```
-
-Define main command to run:
-
-```ts
-import { defineCommand, runMain } from "citty";
 
 const main = defineCommand({
   meta: {
@@ -54,6 +41,12 @@ const main = defineCommand({
       description: "Use friendly greeting",
     },
   },
+  setup({ args }) {
+    console.log(`now setup ${args.command}`);
+  },
+  cleanup({ args }) {
+    console.log(`now cleanup ${args.command}`);
+  },
   run({ args }) {
     console.log(`${args.friendly ? "Hi" : "Greetings"} ${args.name}!`);
   },
@@ -62,35 +55,168 @@ const main = defineCommand({
 runMain(main);
 ```
 
-## Utils
+```sh
+node index.mjs john
+# Greetings john!
+```
 
-### `defineCommand`
+### Sub Commands
 
-`defineCommand` is a type helper for defining commands.
+Sub commands can be nested recursively. Use lazy imports for large CLIs to avoid loading all commands at once.
 
-### `runMain`
+```js
+import { defineCommand, runMain } from "citty";
 
-Runs a command with usage support and graceful error handling.
+const sub = defineCommand({
+  meta: { name: "sub", description: "Sub command" },
+  args: {
+    name: { type: "positional", description: "Your name", required: true },
+  },
+  run({ args }) {
+    console.log(`Hello ${args.name}!`);
+  },
+});
 
-### `createMain`
+const main = defineCommand({
+  meta: { name: "hello", version: "1.0.0", description: "My Awesome CLI App" },
+  subCommands: { sub },
+});
 
-Create a wrapper around command that calls `runMain` when called.
+runMain(main);
+```
+
+Subcommands support `meta.alias` (e.g., `["i", "add"]`) and `meta.hidden: true` to hide from help output.
+
+### Lazy Commands
+
+For large CLIs, lazy load sub commands so only the executed command is imported:
+
+```js
+const main = defineCommand({
+  meta: { name: "hello", version: "1.0.0", description: "My Awesome CLI App" },
+  subCommands: {
+    sub: () => import("./sub.mjs").then((m) => m.default),
+  },
+});
+```
+
+`meta`, `args`, and `subCommands` all accept `Resolvable<T>` values — a value, Promise, function, or async function — enabling lazy and dynamic resolution.
+
+### Hooks
+
+Commands support `setup` and `cleanup` functions called before and after `run()`. Only the executed command's hooks run. `cleanup` always runs, even if `run()` throws.
+
+```js
+const main = defineCommand({
+  meta: { name: "hello", version: "1.0.0", description: "My Awesome CLI App" },
+  setup() {
+    console.log("Setting up...");
+  },
+  cleanup() {
+    console.log("Cleaning up...");
+  },
+  run() {
+    console.log("Hello World!");
+  },
+});
+```
+
+### Plugins
+
+Plugins extend commands with reusable `setup` and `cleanup` hooks:
+
+```js
+import { defineCommand, defineCittyPlugin, runMain } from "citty";
+
+const logger = defineCittyPlugin({
+  name: "logger",
+  setup({ args }) {
+    console.log("Logger setup, args:", args);
+  },
+  cleanup() {
+    console.log("Logger cleanup");
+  },
+});
+
+const main = defineCommand({
+  meta: { name: "hello", description: "My CLI App" },
+  plugins: [logger],
+  run() {
+    console.log("Hello!");
+  },
+});
+
+runMain(main);
+```
+
+Plugin `setup` hooks run before the command's `setup` (in order), `cleanup` hooks run after (in reverse). Plugins can be async or factory functions.
+
+## Arguments
+
+### Argument Types
+
+| Type         | Description                              | Example                     |
+| ------------ | ---------------------------------------- | --------------------------- |
+| `positional` | Unnamed positional args                  | `cli <name>`                |
+| `string`     | Named string options                     | `--name value`              |
+| `boolean`    | Boolean flags, supports `--no-` negation | `--verbose`                 |
+| `enum`       | Constrained to `options` array           | `--level=info\|warn\|error` |
+
+### Common Options
+
+| Option        | Description                                                   |
+| ------------- | ------------------------------------------------------------- |
+| `description` | Help text shown in usage output                               |
+| `required`    | Whether the argument is required                              |
+| `default`     | Default value when not provided                               |
+| `alias`       | Short aliases (e.g., `["f"]`). Not for `positional`           |
+| `valueHint`   | Display hint in help (e.g., `"host"` renders `--name=<host>`) |
+
+### Example
+
+```js
+const main = defineCommand({
+  args: {
+    name: { type: "positional", description: "Your name", required: true },
+    friendly: { type: "boolean", description: "Use friendly greeting", alias: ["f"] },
+    greeting: { type: "string", description: "Custom greeting", default: "Hello" },
+    level: {
+      type: "enum",
+      description: "Log level",
+      options: ["debug", "info", "warn", "error"],
+      default: "info",
+    },
+  },
+  run({ args }) {
+    console.log(`${args.greeting} ${args.name}! (level: ${args.level})`);
+  },
+});
+```
 
-### `runCommand`
+### Boolean Negation
 
-Parses input args and runs command and sub-commands (unsupervised). You can access `result` key from returnd/awaited value to access command's result.
+Boolean args support `--no-` prefix. The negative variant appears in help when `default: true` or `negativeDescription` is set.
 
-### `parseArgs`
+### Case-Agnostic Access
 
-Parses input arguments and applies defaults.
+Kebab-case args can be accessed as camelCase: `args["output-dir"]` and `args.outputDir` both work.
 
-### `renderUsage`
+## Built-in Flags
 
-Renders command usage to a string value.
+`--help` / `-h` and `--version` / `-v` are handled automatically. Disabled if your command defines args with the same names or aliases.
 
-### `showUsage`
+## API
 
-Renders usage and prints to the console
+| Function                      | Description                                                                |
+| ----------------------------- | -------------------------------------------------------------------------- |
+| `defineCommand(def)`          | Type helper for defining commands                                          |
+| `runMain(cmd, opts?)`         | Run a command with usage support and graceful error handling               |
+| `createMain(cmd)`             | Create a wrapper that calls `runMain` when invoked                         |
+| `runCommand(cmd, opts)`       | Parse args and run command/sub-commands; access `result` from return value |
+| `parseArgs(rawArgs, argsDef)` | Parse input arguments and apply defaults                                   |
+| `renderUsage(cmd, parent?)`   | Render command usage to a string                                           |
+| `showUsage(cmd, parent?)`     | Render usage and print to console                                          |
+| `defineCittyPlugin(def)`      | Type helper for defining plugins                                           |
 
 ## Development
 

package/dist/THIRD-PARTY-LICENSES.md

@@ -0,0 +1,33 @@
+# Licenses of Bundled Dependencies
+
+The published artifact additionally contains code with the following licenses:
+MIT
+
+# Bundled Dependencies
+
+## scule
+
+License: MIT
+Repository: https://github.com/unjs/scule
+
+> MIT License
+> 
+> Copyright (c) Pooya Parsa <pooya@pi0.io>
+> 
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
+> 
+> The above copyright notice and this permission notice shall be included in all
+> copies or substantial portions of the Software.
+> 
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+> SOFTWARE.

package/dist/_chunks/libs/scule.mjs

@@ -63,6 +63,8 @@ function camelCase(str, opts) {
 function kebabCase(str, joiner) {
 	return str ? (Array.isArray(str) ? str : splitByCase(str)).map((p) => p.toLowerCase()).join(joiner ?? "-") : "";
 }
-
+function snakeCase(str) {
+	return kebabCase(str || "", "_");
+}
 //#endregion
-export { kebabCase as n, camelCase as t };
+export { kebabCase as n, snakeCase as r, camelCase as t };

package/dist/index.d.mts

@@ -52,12 +52,15 @@ interface CommandMeta {
   version?: string;
   description?: string;
   hidden?: boolean;
+  alias?: string | string[];
 }
 type SubCommandsDef = Record<string, Resolvable<CommandDef<any>>>;
 type CommandDef<T extends ArgsDef = ArgsDef> = {
   meta?: Resolvable<CommandMeta>;
   args?: Resolvable<T>;
+  default?: Resolvable<string>;
   subCommands?: Resolvable<SubCommandsDef>;
+  plugins?: Resolvable<CittyPlugin>[];
   setup?: (context: CommandContext<T>) => any | Promise<any>;
   cleanup?: (context: CommandContext<T>) => any | Promise<any>;
   run?: (context: CommandContext<T>) => any | Promise<any>;
@@ -69,6 +72,11 @@ type CommandContext<T extends ArgsDef = ArgsDef> = {
   subCommand?: CommandDef<T>;
   data?: any;
 };
+type CittyPlugin = {
+  name: string;
+  setup?(context: CommandContext<any>): void | Promise<void>;
+  cleanup?(context: CommandContext<any>): void | Promise<void>;
+};
 type Awaitable<T> = () => T | Promise<T>;
 type Resolvable<T> = T | Promise<T> | (() => T) | (() => Promise<T>);
 //#endregion
@@ -98,4 +106,7 @@ declare function createMain<T extends ArgsDef = ArgsDef>(cmd: CommandDef<T>): (o
 //#region src/args.d.ts
 declare function parseArgs<T extends ArgsDef = ArgsDef>(rawArgs: string[], argsDef: ArgsDef): ParsedArgs<T>;
 //#endregion
-export { Arg, ArgDef, ArgType, ArgsDef, Awaitable, BooleanArgDef, CommandContext, CommandDef, CommandMeta, EnumArgDef, ParsedArgs, PositionalArgDef, Resolvable, type RunCommandOptions, type RunMainOptions, StringArgDef, SubCommandsDef, _ArgDef, createMain, defineCommand, parseArgs, renderUsage, runCommand, runMain, showUsage };
+//#region src/plugin.d.ts
+declare function defineCittyPlugin(plugin: Resolvable<CittyPlugin>): Resolvable<CittyPlugin>;
+//#endregion
+export { Arg, ArgDef, ArgType, ArgsDef, Awaitable, BooleanArgDef, CittyPlugin, CommandContext, CommandDef, CommandMeta, EnumArgDef, ParsedArgs, PositionalArgDef, Resolvable, type RunCommandOptions, type RunMainOptions, StringArgDef, SubCommandsDef, _ArgDef, createMain, defineCittyPlugin, defineCommand, parseArgs, renderUsage, runCommand, runMain, showUsage };

package/dist/index.mjs

@@ -1,6 +1,5 @@
-import { n as kebabCase, t as camelCase } from "./_chunks/libs/scule.mjs";
+import { n as kebabCase, r as snakeCase, t as camelCase } from "./_chunks/libs/scule.mjs";
 import { parseArgs as parseArgs$1 } from "node:util";
-
 //#region src/_utils.ts
 function toArray(val) {
 	if (Array.isArray(val)) return val;
@@ -22,7 +21,6 @@ var CLIError = class extends Error {
 		this.code = code;
 	}
 };
-
 //#endregion
 //#region src/_parser.ts
 function parseRawArgs(args = [], opts = {}) {
@@ -50,6 +48,12 @@ function parseRawArgs(args = [], opts = {}) {
 		for (const alias of aliases) if (booleans.has(alias)) return "boolean";
 		return "string";
 	}
+	function isStringType(name) {
+		if (strings.has(name)) return true;
+		const aliases = mainToAliases.get(name) || [];
+		for (const alias of aliases) if (strings.has(alias)) return true;
+		return false;
+	}
 	const allOptions = new Set([
 		...booleans,
 		...strings,
@@ -93,15 +97,26 @@ function parseRawArgs(args = [], opts = {}) {
 	}
 	const out = { _: [] };
 	out._ = parsed.positionals;
-	for (const [key, value] of Object.entries(parsed.values)) out[key] = value;
-	for (const [name] of Object.entries(negatedFlags)) out[name] = false;
+	for (const [key, value] of Object.entries(parsed.values)) {
+		let coerced = value;
+		if (getType(key) === "boolean" && typeof value === "string") coerced = value !== "false";
+		else if (isStringType(key) && typeof value === "boolean") coerced = "";
+		out[key] = coerced;
+	}
+	for (const [name] of Object.entries(negatedFlags)) {
+		out[name] = false;
+		const mainName = aliasToMain.get(name);
+		if (mainName) out[mainName] = false;
+		const aliases = mainToAliases.get(name);
+		if (aliases) for (const alias of aliases) out[alias] = false;
+	}
 	for (const [alias, main] of aliasToMain.entries()) {
 		if (out[alias] !== void 0 && out[main] === void 0) out[main] = out[alias];
 		if (out[main] !== void 0 && out[alias] === void 0) out[alias] = out[main];
+		if (out[alias] !== out[main] && defaults[main] === out[main]) out[main] = out[alias];
 	}
 	return out;
 }
-
 //#endregion
 //#region src/_color.ts
 const noColor = /* @__PURE__ */ (() => {
@@ -113,7 +128,6 @@ const bold = /* @__PURE__ */ _c(1, 22);
 const cyan = /* @__PURE__ */ _c(36);
 const gray = /* @__PURE__ */ _c(90);
 const underline = /* @__PURE__ */ _c(4, 24);
-
 //#endregion
 //#region src/args.ts
 function parseArgs(rawArgs, argsDef) {
@@ -165,7 +179,14 @@ function resolveArgs(argsDef) {
 	});
 	return args;
 }
-
+//#endregion
+//#region src/plugin.ts
+function defineCittyPlugin(plugin) {
+	return plugin;
+}
+async function resolvePlugins(plugins) {
+	return Promise.all(plugins.map((p) => resolveValue(p)));
+}
 //#endregion
 //#region src/command.ts
 function defineCommand(def) {
@@ -180,36 +201,92 @@ async function runCommand(cmd, opts) {
 		data: opts.data,
 		cmd
 	};
-	if (typeof cmd.setup === "function") await cmd.setup(context);
+	const plugins = await resolvePlugins(cmd.plugins ?? []);
 	let result;
+	let runError;
 	try {
+		for (const plugin of plugins) await plugin.setup?.(context);
+		if (typeof cmd.setup === "function") await cmd.setup(context);
 		const subCommands = await resolveValue(cmd.subCommands);
 		if (subCommands && Object.keys(subCommands).length > 0) {
-			const subCommandArgIndex = opts.rawArgs.findIndex((arg) => !arg.startsWith("-"));
-			const subCommandName = opts.rawArgs[subCommandArgIndex];
-			if (subCommandName) {
-				if (!subCommands[subCommandName]) throw new CLIError(`Unknown command ${cyan(subCommandName)}`, "E_UNKNOWN_COMMAND");
-				const subCommand = await resolveValue(subCommands[subCommandName]);
-				if (subCommand) await runCommand(subCommand, { rawArgs: opts.rawArgs.slice(subCommandArgIndex + 1) });
-			} else if (!cmd.run) throw new CLIError(`No command specified.`, "E_NO_COMMAND");
+			const subCommandArgIndex = findSubCommandIndex(opts.rawArgs, cmdArgs);
+			const explicitName = opts.rawArgs[subCommandArgIndex];
+			if (explicitName) {
+				const subCommand = await _findSubCommand(subCommands, explicitName);
+				if (!subCommand) throw new CLIError(`Unknown command ${cyan(explicitName)}`, "E_UNKNOWN_COMMAND");
+				await runCommand(subCommand, { rawArgs: opts.rawArgs.slice(subCommandArgIndex + 1) });
+			} else {
+				const defaultSubCommand = await resolveValue(cmd.default);
+				if (defaultSubCommand) {
+					if (cmd.run) throw new CLIError(`Cannot specify both 'run' and 'default' on the same command.`, "E_DEFAULT_CONFLICT");
+					const subCommand = await _findSubCommand(subCommands, defaultSubCommand);
+					if (!subCommand) throw new CLIError(`Default sub command ${cyan(defaultSubCommand)} not found in subCommands.`, "E_UNKNOWN_COMMAND");
+					await runCommand(subCommand, { rawArgs: opts.rawArgs });
+				} else if (!cmd.run) throw new CLIError(`No command specified.`, "E_NO_COMMAND");
+			}
 		}
 		if (typeof cmd.run === "function") result = await cmd.run(context);
-	} finally {
-		if (typeof cmd.cleanup === "function") await cmd.cleanup(context);
+	} catch (error) {
+		runError = error;
+	}
+	const cleanupErrors = [];
+	if (typeof cmd.cleanup === "function") try {
+		await cmd.cleanup(context);
+	} catch (error) {
+		cleanupErrors.push(error);
 	}
+	for (const plugin of [...plugins].reverse()) try {
+		await plugin.cleanup?.(context);
+	} catch (error) {
+		cleanupErrors.push(error);
+	}
+	if (runError) throw runError;
+	if (cleanupErrors.length === 1) throw cleanupErrors[0];
+	if (cleanupErrors.length > 1) throw new Error("Multiple cleanup errors", { cause: cleanupErrors });
 	return { result };
 }
 async function resolveSubCommand(cmd, rawArgs, parent) {
 	const subCommands = await resolveValue(cmd.subCommands);
 	if (subCommands && Object.keys(subCommands).length > 0) {
-		const subCommandArgIndex = rawArgs.findIndex((arg) => !arg.startsWith("-"));
+		const subCommandArgIndex = findSubCommandIndex(rawArgs, await resolveValue(cmd.args || {}));
 		const subCommandName = rawArgs[subCommandArgIndex];
-		const subCommand = await resolveValue(subCommands[subCommandName]);
+		const subCommand = await _findSubCommand(subCommands, subCommandName);
 		if (subCommand) return resolveSubCommand(subCommand, rawArgs.slice(subCommandArgIndex + 1), cmd);
 	}
 	return [cmd, parent];
 }
-
+async function _findSubCommand(subCommands, name) {
+	if (name in subCommands) return resolveValue(subCommands[name]);
+	for (const sub of Object.values(subCommands)) {
+		const resolved = await resolveValue(sub);
+		const meta = await resolveValue(resolved?.meta);
+		if (meta?.alias) {
+			if (toArray(meta.alias).includes(name)) return resolved;
+		}
+	}
+}
+function findSubCommandIndex(rawArgs, argsDef) {
+	for (let i = 0; i < rawArgs.length; i++) {
+		const arg = rawArgs[i];
+		if (arg === "--") return -1;
+		if (arg.startsWith("-")) {
+			if (!arg.includes("=") && _isValueFlag(arg, argsDef)) i++;
+			continue;
+		}
+		return i;
+	}
+	return -1;
+}
+function _isValueFlag(flag, argsDef) {
+	const name = flag.replace(/^-{1,2}/, "");
+	const normalized = camelCase(name);
+	for (const [key, def] of Object.entries(argsDef)) {
+		if (def.type !== "string" && def.type !== "enum") continue;
+		if (normalized === camelCase(key)) return true;
+		if ((Array.isArray(def.alias) ? def.alias : def.alias ? [def.alias] : []).includes(name)) return true;
+	}
+	return false;
+}
 //#endregion
 //#region src/usage.ts
 async function showUsage(cmd, parent) {
@@ -232,17 +309,12 @@ async function renderUsage(cmd, parent) {
 	for (const arg of cmdArgs) if (arg.type === "positional") {
 		const name = arg.name.toUpperCase();
 		const isRequired = arg.required !== false && arg.default === void 0;
-		const defaultHint = arg.default ? `="${arg.default}"` : "";
-		posLines.push([
-			cyan(name + defaultHint),
-			arg.description || "",
-			arg.valueHint ? `<${arg.valueHint}>` : ""
-		]);
+		posLines.push([cyan(name + renderValueHint(arg)), renderDescription(arg, isRequired)]);
 		usageLine.push(isRequired ? `<${name}>` : `[${name}]`);
 	} else {
 		const isRequired = arg.required === true && arg.default === void 0;
-		const argStr = [...(arg.alias || []).map((a) => `-${a}`), `--${arg.name}`].join(", ") + (arg.type === "string" && (arg.valueHint || arg.default) ? `=${arg.valueHint ? `<${arg.valueHint}>` : `"${arg.default || ""}"`}` : "") + (arg.type === "enum" && arg.options ? `=<${arg.options.join("|")}>` : "");
-		argLines.push([cyan(argStr + (isRequired ? " (required)" : "")), arg.description || ""]);
+		const argStr = [...(arg.alias || []).map((a) => `-${a}`), `--${arg.name}`].join(", ") + renderValueHint(arg);
+		argLines.push([cyan(argStr), renderDescription(arg, isRequired)]);
 		/**
 		* print negative boolean arg variant usage when
 		* - enabled by default or has `negativeDescription`
@@ -250,9 +322,9 @@ async function renderUsage(cmd, parent) {
 		*/
 		if (arg.type === "boolean" && (arg.default === true || arg.negativeDescription) && !negativePrefixRe.test(arg.name)) {
 			const negativeArgStr = [...(arg.alias || []).map((a) => `--no-${a}`), `--no-${arg.name}`].join(", ");
-			argLines.push([cyan(negativeArgStr + (isRequired ? " (required)" : "")), arg.negativeDescription || ""]);
+			argLines.push([cyan(negativeArgStr), [arg.negativeDescription, isRequired ? gray("(Required)") : ""].filter(Boolean).join(" ")]);
 		}
-		if (isRequired) usageLine.push(argStr);
+		if (isRequired) usageLine.push(`--${arg.name}` + renderValueHint(arg));
 	}
 	if (cmd.subCommands) {
 		const commandNames = [];
@@ -260,8 +332,10 @@ async function renderUsage(cmd, parent) {
 		for (const [name, sub] of Object.entries(subCommands)) {
 			const meta = await resolveValue((await resolveValue(sub))?.meta);
 			if (meta?.hidden) continue;
-			commandsLines.push([cyan(name), meta?.description || ""]);
-			commandNames.push(name);
+			const aliases = toArray(meta?.alias);
+			const label = [name, ...aliases].join(", ");
+			commandsLines.push([cyan(label), meta?.description || ""]);
+			commandNames.push(name, ...aliases);
 		}
 		usageLine.push(commandNames.join("|"));
 	}
@@ -287,17 +361,33 @@ async function renderUsage(cmd, parent) {
 	}
 	return usageLines.filter((l) => typeof l === "string").join("\n");
 }
-
+function renderValueHint(arg) {
+	const valueHint = arg.valueHint ? `=<${arg.valueHint}>` : "";
+	const fallbackValueHint = valueHint || `=<${snakeCase(arg.name)}>`;
+	if (!arg.type || arg.type === "positional" || arg.type === "boolean") return valueHint;
+	if (arg.type === "enum" && arg.options?.length) return `=<${arg.options.join("|")}>`;
+	return fallbackValueHint;
+}
+function renderDescription(arg, required) {
+	const requiredHint = required ? gray("(Required)") : "";
+	const defaultHint = arg.default === void 0 ? "" : gray(`(Default: ${arg.default})`);
+	return [
+		arg.description,
+		requiredHint,
+		defaultHint
+	].filter(Boolean).join(" ");
+}
 //#endregion
 //#region src/main.ts
 async function runMain(cmd, opts = {}) {
 	const rawArgs = opts.rawArgs || process.argv.slice(2);
 	const showUsage$1 = opts.showUsage || showUsage;
 	try {
-		if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+		const builtinFlags = await _resolveBuiltinFlags(cmd);
+		if (builtinFlags.help.length > 0 && rawArgs.some((arg) => builtinFlags.help.includes(arg))) {
 			await showUsage$1(...await resolveSubCommand(cmd, rawArgs));
 			process.exit(0);
-		} else if (rawArgs.length === 1 && rawArgs[0] === "--version") {
+		} else if (rawArgs.length === 1 && builtinFlags.version.includes(rawArgs[0])) {
 			const meta = typeof cmd.meta === "function" ? await cmd.meta() : await cmd.meta;
 			if (!meta?.version) throw new CLIError("No version specified", "E_NO_VERSION");
 			console.log(meta.version);
@@ -313,6 +403,23 @@ async function runMain(cmd, opts = {}) {
 function createMain(cmd) {
 	return (opts = {}) => runMain(cmd, opts);
 }
-
+async function _resolveBuiltinFlags(cmd) {
+	const argsDef = await resolveValue(cmd.args || {});
+	const userNames = /* @__PURE__ */ new Set();
+	const userAliases = /* @__PURE__ */ new Set();
+	for (const [name, def] of Object.entries(argsDef)) {
+		userNames.add(name);
+		for (const alias of toArray(def.alias)) userAliases.add(alias);
+	}
+	return {
+		help: _getBuiltinFlags("help", "h", userNames, userAliases),
+		version: _getBuiltinFlags("version", "v", userNames, userAliases)
+	};
+}
+function _getBuiltinFlags(long, short, userNames, userAliases) {
+	if (userNames.has(long) || userAliases.has(long)) return [];
+	if (userNames.has(short) || userAliases.has(short)) return [`--${long}`];
+	return [`--${long}`, `-${short}`];
+}
 //#endregion
-export { createMain, defineCommand, parseArgs, renderUsage, runCommand, runMain, showUsage };
+export { createMain, defineCittyPlugin, defineCommand, parseArgs, renderUsage, runCommand, runMain, showUsage };

package/package.json

@@ -1,41 +1,42 @@
 {
   "name": "citty",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Elegant CLI Builder",
-  "repository": "unjs/citty",
   "license": "MIT",
-  "sideEffects": false,
+  "repository": "unjs/citty",
+  "files": [
+    "dist"
+  ],
   "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.mts",
   "exports": {
     ".": "./dist/index.mjs"
   },
-  "types": "./dist/index.d.mts",
-  "files": [
-    "dist"
-  ],
   "scripts": {
     "build": "obuild",
     "dev": "vitest dev",
-    "lint": "eslint --cache . && prettier -c src test",
-    "lint:fix": "eslint --cache . --fix && prettier -c src test -w",
+    "lint": "oxlint . && oxfmt --check",
+    "fmt": "oxlint . --fix && oxfmt",
     "prepack": "pnpm run build",
     "play": "node ./playground/cli.ts",
     "release": "pnpm test && pnpm build && changelogen --release --push && npm publish",
     "test": "pnpm lint && pnpm test:types && vitest run --coverage",
-    "test:types": "tsc --noEmit"
+    "test:types": "tsgo --noEmit"
   },
   "devDependencies": {
-    "@types/node": "^25.0.9",
-    "@vitest/coverage-v8": "^4.0.17",
-    "automd": "^0.4.2",
+    "@types/node": "^25.5.0",
+    "@typescript/native-preview": "^7.0.0-dev.20260401.1",
+    "@vitest/coverage-v8": "^4.1.2",
+    "automd": "^0.4.3",
     "changelogen": "^0.6.2",
-    "eslint": "^9.39.2",
     "eslint-config-unjs": "^0.6.2",
-    "obuild": "^0.4.18",
-    "prettier": "^3.8.0",
+    "obuild": "^0.4.32",
+    "oxfmt": "^0.43.0",
+    "oxlint": "^1.58.0",
     "scule": "^1.3.0",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.17"
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
   },
-  "packageManager": "pnpm@10.28.1"
+  "packageManager": "pnpm@10.33.0"
 }