Get the FREE Ultimate OpenClaw Setup Guide →

cleye

Scanned
npx machina-cli add skill bendrucker/claude/cleye --openclaw
Files (1)
SKILL.md
2.4 KB

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

Source

git clone https://github.com/bendrucker/claude/blob/main/.claude/skills/cleye/SKILL.mdView on GitHub

Overview

cleye provides type-safe CLI argument parsing for Bun scripts, enabling robust handling of flags, parameters, and subcommands. It standardizes how you declare options and read argv, and supports built-in help generation.

How This Skill Works

Call cli() with a config object that defines name, parameters, and flags. It returns argv where positional values live at argv._ and flags at argv.flags; kebab-case flag names become camelCase properties. Subcommands are defined with a commands array via command(), and for manual dispatch you can pass a pre-parsed args array as the third parameter.

When to Use It

  • Building Bun-based CLI tools that require robust, type-safe argument parsing
  • Adding flags and parameters to Bun scripts for a consistent UX
  • Implementing subcommands with dedicated option sets
  • Leveraging built-in help generation for user-friendly CLIs
  • Integrating type-safe parsing into plugin scripts or automation workflows

Quick Start

  1. Step 1: Create a Bun script with a shebang and import { cli } from 'cleye';
  2. Step 2: Define a cli(...) config with name, parameters, and flags, then call it to parse argv.
  3. Step 3: Use argv._ and argv.flags in your script logic (e.g., console.log(argv._.file); console.log(argv.flags.output));

Best Practices

  • Use the shebang: #!/usr/bin/env bun at the top of your script
  • Wrap CLI logic in if (import.meta.main) so the module remains importable
  • Export core functions for programmatic use and keep parsing at the entry point
  • Choose cleye for --help generation and a typed interface rather than manual parsing
  • Keep your CLI configuration centralized in a single cli({...}) call

Example Use Cases

  • Basic usage: cli({ name: 'my-script', parameters: ['<file>'], flags: { output: { type: String, alias: 'o', description: 'Output path' }, verbose: Boolean } })
  • Access positional args with argv._, e.g., argv._.file for the provided <file> parameter
  • Access flags via argv.flags, e.g., argv.flags.output and argv.flags.verbose
  • Subcommands: cli({ name: 'tool', commands: [ command({ name: 'build', flags: { watch: Boolean } }, (argv) => { ... }) ] })
  • Manual dispatch: cli(..., undefined, args) to parse a pre-supplied argv-like array

Frequently Asked Questions

Add this skill to your agents
Sponsor this space

Reach thousands of developers ↗