Citty

Elegant CLI Builder

CLI
unjs/cittycitty

README

🌆 citty


Elegant CLI Builder

- Fast and lightweight argument parser based on mri
- Smart value parsing with typecast, boolean shortcuts and unknown flag handling
- Nested sub-commands
- Lazy and Async commands
- Plugable and composable API
- Auto generated usage and help

🚧 This project is under heavy development. More features are coming soon!

Usage


Install package:

  1. ```sh
  2. # npm
  3. npm install citty

  5. # yarn
  6. yarn add citty

  8. # pnpm
  9. pnpm install citty
  10. ```

Import:

  1. ```js
  2. // ESM
  3. import { defineCommand, runMain } from "citty";

  5. // CommonJS
  6. const { defineCommand, runMain } = require("citty");
  7. ```

Define main command to run:

  1. ```ts
  2. import { defineCommand, runMain } from "citty";

  4. const main = defineCommand({
  5.   meta: {
  6.     name: "hello",
  7.     version: "1.0.0",
  8.     description: "My Awesome CLI App",
  9.   },
  10.   args: {
  11.     name: {
  12.       type: "positional",
  13.       description: "Your name",
  14.       required: true,
  15.     },
  16.     friendly: {
  17.       type: "boolean",
  18.       description: "Use friendly greeting",
  19.     },
  20.   },
  21.   run({ args }) {
  22.     console.log(`${args.friendly ? "Hi" : "Greetings"} ${args.name}!`);
  23.   },
  24. });

  26. runMain(main);
  27. ```

Utils


defineCommand


defineCommand is a type helper for defining commands.

runMain


Runs a command with usage support and graceful error handling.

createMain


Create a wrapper around command that calls runMain when called.

runCommand


Parses input args and runs command and sub-commands (unsupervised). You can access result key from returnd/awaited value to access command's result.

parseArgs


Parses input arguments and applies defaults.

renderUsage


Renders command usage to a string value.

showUsage


Renders usage and prints to the console

Development


- Clone this repository
- Install latest LTS version of Node.js
- Enable Corepack usingcorepack enable
- Install dependencies using pnpm install
- Run interactive tests using pnpm dev

License


Made with 💛 Published under MIT License.

Argument parser is based on lukeed/mri by Luke Edwards (@lukeed).