citty

Case-Agnostic Access

Kebab-case arguments can be accessed using camelCase. For example, an argument defined as output-dir can be accessed via args.outputDir or args['output-dir'].

Boolean Negation

Boolean arguments support the --no- prefix for negation. The negative variant is automatically displayed in the help output if default: true is set or if a negativeDescription is provided.

Commands support setup and cleanup functions:

• setup(): Called before run().
• cleanup(): Called after run(). It is guaranteed to run even if run() throws an error.

Only the hooks of the specifically executed command (and its parents/plugins) will run.

const main = defineCommand({
  meta: { name: "hello", description: "My CLI App" },
  setup() {
    console.log("Setting up...");
  },
  cleanup() {
    console.log("Cleaning up...");
  },
  run() {
    console.log("Hello World!");
  },
});

For large CLIs, you can prevent loading all commands at once by providing a function that returns a Promise to the subCommands object. This ensures only the executed command is imported.

Additionally, meta, args, and subCommands all accept Resolvable<T> values (a value, Promise, function, or async function) for dynamic resolution.

const main = defineCommand({
  meta: { name: "hello", version: "1.0.0", description: "My Awesome CLI App" },
  subCommands: {
    sub: () => import("./sub.mjs").then((m) => m.default),
  },
});

Commands can be nested recursively using the subCommands property in the defineCommand configuration.

Sub-commands support:

• meta.alias: An array of short aliases (e.g., ["i", "add"]). Note: Aliases cannot be used for positional arguments.
• meta.hidden: true: Hides the sub-command from the help output.

import { defineCommand, runMain } from "citty";

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}!`);
  },
});

const main = defineCommand({
  meta: { name: "hello", version: "1.0.0", description: "My Awesome CLI App" },
  subCommands: { sub },
});

runMain(main);

Plugins allow you to reuse setup and cleanup logic across multiple commands. You define a plugin using defineCittyPlugin and include it in the plugins array of a command.

Execution Order:

• Plugin setup hooks run before the command's setup (in the order they are defined).
• Plugin cleanup hooks run after the command's cleanup (in reverse order).

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);

You can add citty to your project using your preferred package manager. For example, using nypm:

npx nypm add -D citty

Use defineCommand to define the metadata, arguments, and lifecycle hooks of your CLI, then pass the command object to runMain to execute it.

runMain handles usage support and graceful error handling automatically.

import { defineCommand, runMain } from "citty";

const main = defineCommand({
  meta: {
    name: "hello",
    version: "1.0.0",
    description: "My Awesome CLI App",
  },
  args: {
    name: {
      type: "positional",
      description: "Your name",
      required: true,
    },
    friendly: {
      type: "boolean",
      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}!`);
  },
});

runMain(main);

The following options can be used within an argument definition:

The following functions are exported by citty:

When defining args in defineCommand, you can specify the following types:

When parseArgs encounters validation failures, it throws a CLIError. You can catch this error to handle missing or invalid inputs gracefully.

Common error scenarios:

• Missing required argument: Throws CLIError with code EARG and message Missing required argument: --<name>.
• Missing required positional argument: Throws CLIError with code EARG and message Missing required positional argument: <NAME>.
• Invalid enum value: Throws CLIError with code EARG and a message specifying the expected options.

Error Code: EARG