cleye

name	cleye
description	Type-safe CLI argument parsing with cleye, the standard parser for this repo's Bun scripts. Use when writing or editing any script that takes arguments (flags, positional parameters, subcommands, --help) instead of reading existing scripts for the pattern.

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

Help Text

Set help.description on cli() for a summary line above the generated usage block:

const argv = cli({
  name: "scan",
  parameters: ["<path>"],
  help: {
    description: "Scan repository prose for AI writing tropes.",
  },
  flags: { ... },
});

Subcommands

Define each subcommand as a named command() const with its callback, pass them via the commands array, and give the root cli() a callback that shows help when no subcommand matches:

import { cli, command } from "cleye";

const replyCmd = command(
  {
    name: "reply",
    parameters: ["<thread-id>"],
    flags: {
      body: { type: String, description: "Reply text" },
    },
  },
  async (parsed) => {
    console.log(parsed._.threadId, parsed.flags.body);
  },
);

cli(
  {
    name: "review-threads",
    commands: [replyCmd],
  },
  (parsed) => {
    parsed.showHelp();
  },
);

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