36 added, 13 removed. Audit A to A.
---
name: cleye
- description: Type-safe CLI argument parsing with cleye. Use when writing CLI scripts, adding flags or parameters to Bun scripts, or parsing command-line arguments.
+ 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
```ts
#!/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._`:
```ts
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:
```ts
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
+ ## Help Text
- Pass to `cli()` via the `commands` array using the `command()` helper:
+ Set `help.description` on `cli()` for a summary line above the generated usage block:
```ts
- import { cli, command } from "cleye";
-
const argv = cli({
- name: "tool",
- commands: [
- command({ name: "build", flags: { watch: Boolean } }, (argv) => {
- console.log(argv.flags.watch);
- }),
- ],
+ name: "scan",
+ parameters: ["<path>"],
+ help: {
+ description: "Scan repository prose for AI writing tropes.",
+ },
+ flags: { ... },
});
```
- For manual dispatch (used in this codebase), pass `args` as the third argument:
+ ## 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:
+
```ts
- const argv = cli({ name: "errors", flags: { ... } }, undefined, args);
+ 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](https://github.com/privatenumber/cleye) (not `parseArgs` from `node:util`) for scripts that need `--help` generation