cleye

Type-safe CLI argument parsing for Bun scripts. Used across plugin scripts for flags, parameters, and subcommands.

Basic Usage

#!/usr/bin/env bun

import { cli } from "cleye";

const argv = cli({
  name: "my-script",
  parameters: ["<file>"],
  flags: {
    output: {
      type: String,
      alias: "o",
      description: "Output path",
    },
    verbose: Boolean,
  },
});

console.log(argv._.file);       // string (required)
console.log(argv.flags.output); // string | undefined
console.log(argv.flags.verbose); // boolean | undefined

Parameters

Positional arguments mapped to named properties on argv._:

parameters: [
  "<required>",     // must be provided
  "[optional]",     // may be omitted
  "<files...>",     // required variadic (1+), must be last
  "[files...]",     // optional variadic (0+), must be last
]

Required parameters must precede optional. Variadic must be last.

Access: argv._.required, argv._.optional, argv._.files.

Flags

Flags accept a type constructor or a config object:

flags: {
  name: String,                    // shorthand
  count: {
    type: Number,
    alias: "n",
    default: 10,
    description: "Max results",
  },
  tags: {
    type: [String],                // array: -t foo -t bar
    description: "Tag names",
  },
  json: {
    type: Boolean,
    description: "Output as JSON",
  },
}

Kebab-case flags (--dry-run) become camelCase properties (argv.flags.dryRun).

Subcommands

Pass to cli() via the commands array using the command() helper:

import { cli, command } from "cleye";

const argv = cli({
  name: "tool",
  commands: [
    command({ name: "build", flags: { watch: Boolean } }, (argv) => {
      console.log(argv.flags.watch);
    }),
  ],
});

For manual dispatch (used in this codebase), pass args as the third argument:

const argv = cli({ name: "errors", flags: { ... } }, undefined, args);

Conventions

• Shebang: #!/usr/bin/env bun
• Entry point: wrap CLI logic in if (import.meta.main) so the module is importable
• Export core functions for programmatic use; keep CLI parsing at the entry point
• Use cleye (not parseArgs from node:util) for scripts that need --help generation