Acclimate

A lightweight TypeScript framework for building type-safe command line
interfaces.

This library is not complete and is still missing a lot of functionality.
We do not recommend this library be used in production.

See the To Do section at the end for what is still missing.

Installation

``bash
npm install acclimate
`

Quick start

`ts
import { Acclimate } from "acclimate";

const cli = Acclimate.createCLI("demo-cli")
.description("A tiny demo CLI")
.action(() => {
console.log("Hello, world!");
});

Acclimate.run(cli);
`

API

Public exports from acclimate:

- Acclimate

$3

#### Acclimate.createCLI(name)

Create a new CLI instance.

`ts
Acclimate.createCLI(name: string): IAcclimateCLI
`

#### Acclimate.run(cli)

Run a CLI instance using process.argv.slice(2).

`ts
Acclimate.run(cli: IAcclimateCLI): void
`

$3

createCLI() returns an immutable builder. Each method returns a new CLI
instance with updated configuration.

#### cli.description(description)

`ts
cli.description(description: string): IAcclimateCLI
`

#### cli.action(action)

Set the function executed when the CLI matches (after parsing).

`ts
cli.action(
action: (args: FullCLIArgValues<...>) => void,
): IAcclimateCLI
`

#### cli.addPositionalArg(param)

Add a positional argument. Positional args are parsed in order.

`ts
cli.addPositionalArg(param: CLIPositionalParam): IAcclimateCLI
`

#### cli.addOption(param)

Add an option local to this CLI level.

`ts
cli.addOption(param: CLIOptionParam): IAcclimateCLI
`

#### cli.addGlobalOption(param)

Add an option that is available to this CLI and all sub-commands.

`ts
cli.addGlobalOption(param: CLIOptionParam): IAcclimateCLI
`

#### cli.addCommand(commandName, commandCLI)

Add a sub-command (a nested CLI). If the first positional token matches a
command name, parsing continues using that command's CLI.

`ts
cli.addCommand(
commandName: string,
commandCLI: IAcclimateCLI,
): IAcclimateCLI
`

#### cli.getCommandCLI(commandName)

Get a command CLI by name (throws if missing).

`ts
cli.getCommandCLI(commandName: string): IAcclimateCLI
`

$3

Acclimate uses config objects to describe positional args and options.

- Positional args: CLIPositionalParam
- name: string (prefer camelCase to match runtime parsing)
- type: "string" | "number" | "boolean"
- required: boolean
- description?: string
- defaultValue?: depends on type
- choices?: allowed values list
- parser?: (value: string) => value
- validator?: (value) => true | string

- Options: CLIOptionParam
- name: --${string} (example: --dry-run)
- aliases?: readonly ("--x" | "-x")[]
- required: boolean
- Same type, defaultValue, choices, parser, validator fields as a
positional arg

$3

- Positional args: validated and parsed in order; extra positional args
throw an error.
- Options: parsing starts at the first token that begins with -. Each
option consumes tokens until the next option; its raw value is the consumed
tokens joined with spaces.
- Option keys in action(args): option names are camel-cased, so
--dry-run becomes dryRun.
- Boolean flags: --flag with no value parses as true (only the
literal string false parses as false).
- Errors: missing required args/options (and invalid values) throw
CLIError.

Prerequisites

- Node.js 18+
- npm (bundled with Node)

Project Layout

- src/ — framework source code.
- examples/ — small usage samples; basic.ts is runnable via npm run demo.
- tests/ — Vitest suite.
- dist/ — build output generated by tsup.

Setup

Install dependencies:

`bash
npm install
`

Common Scripts

- npm run dev — build in watch mode with tsup.
- npm run build — produce CJS/ESM bundles and type declarations in dist/.
- npm run demo — execute the examples/basic.ts sample with tsx.
- npm test — run the Vitest suite once.
- npm run test:watch — run tests in watch mode.
- npm run lint / npm run lint:fix — check or auto-fix with ESLint.
- npm run format / npm run format:fix — check or write Prettier
formatting.
- npm run type - check typescript types

Running & Testing

1. Start a build (optional during development):

`bash
npm run dev
`

1. Run the sample CLI:

`bash
npm run demo
`

1. Execute tests:

`bash
npm test
`

The prepare script runs npm run build, so the package will compile
automatically when installed from a git dependency.

Examples

$3

Matches examples/basic.ts.

`ts
import { Acclimate } from "acclimate";

const cli = Acclimate.createCLI("demo-cli").action(() => {
console.log("Hello, world!");
});

Acclimate.run(cli);
`

$3

`ts
import { Acclimate } from "acclimate";

const cli = Acclimate.createCLI("greet")
.addPositionalArg({
name: "name",
type: "string",
required: true,
description: "Who to greet",
})
.addOption({
name: "--shout",
type: "boolean",
required: false,
aliases: ["-s"] as const,
description: "Uppercase the output",
defaultValue: false,
})
.action(({ name, shout }) => {
const message = Hello, ${name}!;
console.log(shout ? message.toUpperCase() : message);
});

Acclimate.run(cli);
`

$3

`ts
import { Acclimate } from "acclimate";

const initCmd = Acclimate.createCLI("init")
.description("Initialize a project")
.action(({ verbose }) => {
console.log(init (verbose=${verbose}));
});

const root = Acclimate.createCLI("acme")
.addGlobalOption({
name: "--verbose",
type: "boolean",
required: false,
aliases: ["-v"] as const,
defaultValue: false,
})
.addCommand("init", initCmd);

Acclimate.run(root);
`

To do

- [ ] Add semantic arguments: e.g. email (which has a default validator)
- [ ] Add default help command and --help option. This should show the CLI
description and all param documentation.
- [ ] Make the description actually get printed.
- [ ] Show all CLI param descriptions if command is run with no arguments or if
there is a param-related error.
- [ ] Add helper functions to log to stdout in different colors
- [ ] Add logic for askIfEmpty to enter an interactive mode to receive inputs
for different params.
- [ ] Add an option to only askIfEmptyAndRequired`.