OpenParable
Skip to content
← Back to skills

Cleye

Development
cleye

Cleye is an Agent Skill for development published in the privatenumber/cleye repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

cleye CLI development tool — argv parsing with typed parameters, flags, commands, and auto-generated help. Use when building Node.js CLI scripts with cleye or when the user imports `cli` or `command` from `cleye`.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/privatenumber/cleye/blob/HEAD/skills/cleye/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/cleye, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

cleye

Quick Patterns

TaskPattern
Basic CLIcli({ name, parameters, flags })
Named commandcommand({ name, parameters, flags }, callback)
Register commandscli({ commands: [cmd1, cmd2] })
Async callbackawait cli({ ... }, async (argv) => { ... })
Raw argvcli({ ... }, callback, process.argv.slice(2))

Parameters

Positional arguments mapped to named properties on argv._.

FormatDescription
<name>Required
[name]Optional
<name...>Required spread (1+)
[name...]Optional spread (0+)
--End-of-flags separator
const argv = cli({
    parameters: ['<required>', '[optional]', '[rest...]']
})
argv._.required // string
argv._.optional // string | undefined
argv._.rest // string[]
argv._['--'] // string[] — everything after --

Multi-word names use camelCase on argv._: '<first name>' → argv._.firstName.

Flags

const argv = cli({
    flags: {
        verbose: Boolean, // shorthand
        output: {
            type: String,
            alias: 'o',
            default: 'dist',
            description: 'Output directory',
            placeholder: '<path>'
        },
        count: {
            type: [Number], // array: -n 1 -n 2
            alias: 'n'
        }
    }
})

argv.flags.verbose // boolean | undefined
argv.flags.output // string
argv.flags.count // number[]

Flag name is camelCase; parsed from kebab-case CLI input (--output-dir → outputDir).

Delimiters — =, :, and . all work as value separators:

--flag=value   --flag:value   --flag.value

Use : when the value itself contains = (e.g. --define:KEY=VALUE).

Counting flags — use [Boolean] and check .length:

cli({
    flags: {
        verbose: {
            type: [Boolean],
            alias: 'v'
        }
    }
})
// -vvv → argv.flags.verbose.length === 3

Optional value — custom type returns true when no value is given:

const OptionalString = (value: string) => value || true
cli({ flags: { tag: OptionalString } })
// --tag        → true
// --tag beta   → 'beta'

Boolean Flag Negation

By default, set a boolean flag to false using the = operator:

--verbose=false   # → false
--verbose false   # → true (false treated as separate argument)

To also support the --no-<flag> convention, enable booleanFlagNegation (additive — =false still works):

cli({
    flags: { verbose: Boolean },
    booleanFlagNegation: true
})
// --no-verbose     → false
// --verbose=false  → false (still works)
// Last-wins: --verbose --no-verbose → false

Commands inherit booleanFlagNegation from the parent cli() but can override it.

Strict Flags

cli({
    flags: { foo: Boolean },
    strictFlags: true
})
// --baz → Error: Unknown flag: --baz. (Did you mean --foo?)

Commands inherit strictFlags but can override it.

Commands

// install-command.ts
export const installCommand = command({
    name: 'install',
    alias: ['i', 'add'],
    parameters: ['<package name>'],
    flags: { saveDev: Boolean }
}, (argv) => {
    argv._.packageName // string
    argv.flags.saveDev // boolean | undefined
})

// main.ts
cli({
    name: 'npm',
    version: '1.0.0',
    commands: [installCommand]
})

When a command is matched, argv.command narrows the type for type-safe branching.

Help & Version

cli({
    name: 'my-script',
    version: '1.2.3', // enables --version; also shown in --help
    help: {
        description: 'Does things',
        usage: 'my-script [flags] <file>',
        examples: ['my-script foo.txt', 'my-script --output=dist foo.txt'],
        version: '1.2.3' // show version in --help without handling --version
    }
})
// help: false  — disables --help handling; call argv.showHelp() manually

Tip: import name, version, and description from package.json to avoid keeping them in sync manually:

import { name, version, description } from './package.json' with { type: 'json' }

cli({
    name,
    version,
    help: { description }
})

Custom Flag Types

Any function (value: string) => T works as a flag type — the return type is inferred.

// Validation + narrowing
const Port = (value: string) => {
    const n = Number(value)
    if (!Number.isInteger(n) || n < 1 || n > 65_535) { throw new Error(`Invalid port: ${value}`) }
    return n
}
// argv.flags.port → number

// Enum
const sizes = ['small', 'medium', 'large'] as const
const Size = (v: string) => {
    if (!(sizes as readonly string[]).includes(v)) { throw new Error(`Expected: ${sizes.join(', ')}`) }
    return v as typeof sizes[number]
}
// argv.flags.size → 'small' | 'medium' | 'large'

// Comma-separated list
const List = (v: string) => v.split(',')
// --tags a,b,c → argv.flags.tags === ['a', 'b', 'c']

// Inline JSON
cli({ flags: { data: JSON.parse } })
// --data '{"key":1}' → argv.flags.data === { key: 1 }

// Dot-nested object (combine with . delimiter)
const Env = (v: string): Record<string, string | true> => {
    const [k, value] = v.split('=')
    return { [k]: value ?? true }
}
cli({ flags: { env: [Env] } })
// --env.TOKEN=abc --env.CI → merge to { TOKEN: 'abc', CI: true }

Type Helpers (cleye/formats)

cleye/formats ships composable, tree-shakable type-function helpers. Import only what you need.

import {
    oneOf, commaList, integer, float, range, url
} from 'cleye/formats'
  • oneOf('a', 'b', 'c') — infers 'a' | 'b' | 'c'; throws if the value is not in the list.
  • commaList(itemType) — splits "a,b,c" → T[]; trims whitespace; composes with other helpers (e.g. commaList(integer())).
  • integer() — base-10 integer; throws on floats/non-numeric.
  • float() — finite float; throws on Infinity/non-numeric.
  • range(min, max) — returns (input: string) => number; validates input parses to a number in [min, max].
  • url() — parses with new URL(); returns a URL object (not a string).

Help Customization

cli({
    help: {
        render(nodes, renderers) {
            nodes.push('\nDocs: https://example.com')
            renderers.flagOperator = () => '=' // --flag=<value>
            return renderers.render(nodes)
        }
    }
})

Default renderers: /src/render-help/renderers.ts.

ignoreArgv

cli({
    ignoreArgv(type, flagOrArgv, value) {
        if (type === 'unknown-flag') { return true } // silently skip unknown flags
    }
})

type: 'known-flag' | 'unknown-flag' | 'argument'

Return Type

type ParsedArgv = {
    _: string[] & Parameters
    flags: { [name: string]: InferredType }
    unknownFlags: { [name: string]: (string | boolean)[] }
    showVersion: () => void
    showHelp: (options?: HelpOptions) => void
}

TypeScript Exports

import type { Flags, Renderers, TypeFlag } from 'cleye'
TypeUse
FlagsType for the flags option object
RenderersHelp renderer class type for help.render customization
TypeFlagRe-export from type-flag for portable type declarations