Citty CLI Builder

Common errors

• Cannot find module 'citty'

  cause The `citty` package is not installed in your project, or your Node.js environment cannot resolve ESM imports correctly.
  fix Run `npm install citty` or `yarn add citty`. Ensure your package.json `type` is set to `module` or your file uses the `.mjs` extension for ESM imports.

• Error: Missing required argument: <arg_name>

  cause A command was executed without providing a value for an argument explicitly marked as `required: true` in its definition.
  fix Ensure all required positional or named arguments are supplied on the command line. For example, if 'name' is required, run `your-cli <value_for_name>`.

• Unknown argument: --invalid-option

  cause The CLI received an argument or option that was not explicitly defined in the `args` configuration for the executed command or any of its subcommands.
  fix Either define the argument in your command's `args` object with the correct type, or remove the unknown argument from the CLI call.

• TypeError: Cannot read properties of undefined (reading 'meta') or (reading 'run')

  cause This often occurs when a subcommand is expected to be a `Command` object but is instead `undefined` or a `Promise` that hasn't resolved, especially with lazy loading or incorrect dynamic imports.
  fix Verify that lazy-loaded subcommands correctly return the default export of a `defineCommand` result. Ensure promises for `Resolvable<T>` types are awaited or handled correctly, particularly in `subCommands` configurations.

Warnings

• gotcha Starting with `v0.2.0`, citty transitioned to a zero-dependency architecture by leveraging Node.js's native `util.parseArgs`. While this significantly reduces bundle size and improves performance, it might subtly alter argument parsing behavior compared to previous versions that relied on third-party dependencies.
  Fix: Review your CLI argument parsing logic, especially for edge cases or complex argument structures, if upgrading from versions prior to `v0.2.0`. This change generally simplifies the dependency graph.
• gotcha Prior to `v0.2.2`, handling user-defined arguments for common flags like `-h`, `--help`, `-v`, and `--version` could be unreliable or lead to unexpected behavior, as citty might implicitly handle these. User-defined arguments for these specific flags were not consistently respected.
  Fix: Upgrade to `v0.2.2` or higher. This version includes a fix that properly allows users to define and override these arguments within their command's `args` configuration, ensuring consistent behavior.
• gotcha Features such as subcommand aliases, default subcommands, and the plugin system were introduced or significantly enhanced in `v0.2.2`. Codebases relying on custom workarounds for these functionalities or attempting to use them in earlier versions might encounter errors or unexpected behavior.
  Fix: For full support and expected behavior of subcommand aliases, default subcommands, and the plugin system, ensure you are using `citty@0.2.2` or newer. Refactor any custom logic to utilize the new official APIs.

Install

• npm install citty npm
• yarn add citty yarn
• pnpm add citty pnpm

Imports

• defineCommand
  wrong:

  const { defineCommand } = require('citty')

  correct:

  import { defineCommand } from 'citty'

  While CommonJS `require` might work in some setups, ESM `import` is the primary and recommended usage, especially in modern Node.js CLI projects.
• runMain
  wrong:

  const { runMain } = require('citty')

  correct:

  import { runMain } from 'citty'

  This function is the entry point for executing your Citty CLI application. Ensure your main script is configured as an ESM module.
• defineCittyPlugin
  wrong:

  const { defineCittyPlugin } = require('citty')

  correct:

  import { defineCittyPlugin } from 'citty'

  Introduced in `v0.2.2`, `defineCittyPlugin` is used for creating reusable command plugins. Requires `v0.2.2` or newer.

Quickstart

This example demonstrates how to define a main command with positional and optional arguments, including `setup`, `run`, and `cleanup` hooks. It shows basic argument parsing and execution flow.

import { defineCommand, runMain } from 'citty';

// Define a simple command with a positional argument and an optional boolean flag
const mainCommand = defineCommand({
  meta: {
    name: 'greeter-app',
    version: '1.0.0',
    description: 'A simple CLI application to greet users based on arguments.'
  },
  args: {
    name: {
      type: 'positional',
      description: 'The name of the person to greet. This argument is required.',
      required: true,
      valueHint: '<your-name>'
    },
    friendly: {
      type: 'boolean',
      description: 'Use a friendly greeting like \'Hi\' instead of \'Greetings\'.',
      default: false
    },
    repeat: {
      type: 'string',
      description: 'Specify how many times to repeat the greeting.',
      default: '1'
    }
  },
  setup({ args }) {
    console.log(`[SETUP] Initializing greeter for command: ${this.meta.name}`);
    if (isNaN(Number(args.repeat))) {
        console.error("Warning: 'repeat' argument must be a number. Defaulting to 1.");
        args.repeat = "1"; // Ensure it's a number for run()
    }
  },
  async run({ args }) {
    const greeting = args.friendly ? 'Hi' : 'Greetings';
    const repeatCount = Number(args.repeat);
    for (let i = 0; i < repeatCount; i++) {
        console.log(`${greeting} ${args.name}!`);
    }
  },
  cleanup({ args }) {
    console.log(`[CLEANUP] Finished greeting ${args.name} ${args.repeat} time(s).`);
  }
});

// Run the main command. This should be the entry point of your CLI.
// Example usage: node cli.mjs John --friendly --repeat 3
runMain(mainCommand);