Registry / devops / citty

citty

JSON →
library0.2.2jsnpmunverified

citty is a modern, elegant, and highly performant CLI builder for Node.js, currently stable at version `0.2.2`. It distinguishes itself by being entirely zero-dependency since `v0.2.0`, leveraging Node.js's native `util.parseArgs` for its core argument parsing. This design choice results in a significantly reduced install size (from 267kB to 22.8kB as of `v0.2.0`) and fast execution, making it an excellent choice for lightweight command-line tools. `citty` provides a flexible and composable API that supports nested sub-commands, complete with options for lazy and asynchronous loading, which is crucial for building large-scale CLIs without incurring heavy startup costs. Recent enhancements in `v0.2.2` introduced a robust plugin system, allowing developers to extend command functionality with reusable `setup` and `cleanup` hooks. It also offers smart value parsing, type casting, boolean shortcuts, and automatically generates comprehensive usage information. The project maintains an active release cadence, frequently adding new features and addressing issues, demonstrating its ongoing development and commitment to a stable and feature-rich experience.

devopshttp-networking
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

import { defineCommand } from 'citty'

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

import { runMain } from 'citty'

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

import { defineCittyPlugin } from 'citty'

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);
citty --version
Debug
Known footguns
gotchaStarting 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.
gotchaPrior 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.
gotchaFeatures 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.
Upgrade
Version history

Breaking-change detection hasn't run for this library yet.

Audit
Security & dependencies

CVE tracking and dependency tree are planned for a later release.

Agent activity
0 hits · last 30 days

No traffic data recorded yet.

Resources