# tiny-bin

> A library for building tiny and beautiful command line apps.

Latest version **2.0.1** (published 2026-02-12) · MIT license · 0 weekly downloads

## Install

```sh
npm install tiny-bin
pnpm add tiny-bin
yarn add tiny-bin
bun add tiny-bin
```

## Health

**Score 65/100 (B)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.1 |
| Published | 2026-02-12 |
| First published | 2023-02-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 7 |
| Unpacked size | 55.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 194 |
| Maintainers | fabiospampinato |
| Keywords | tiny, bin, command, line, app, cli |

## Links

- npm: https://www.npmjs.com/package/tiny-bin
- Repository: https://github.com/fabiospampinato/tiny-bin
- Homepage: https://github.com/fabiospampinato/tiny-bin#readme
- Issues: https://github.com/fabiospampinato/tiny-bin/issues
- npm.io page: https://npm.io/package/tiny-bin

## Dependencies (7)

- [kasi](https://npm.io/package/kasi.md) ^2.0.1
- [ansi-purge](https://npm.io/package/ansi-purge.md) ^1.1.0
- [tiny-colors](https://npm.io/package/tiny-colors.md) ^2.2.2
- [tiny-parse-argv](https://npm.io/package/tiny-parse-argv.md) ^2.8.2
- [tiny-levenshtein](https://npm.io/package/tiny-levenshtein.md) ^1.1.0
- [fast-string-width](https://npm.io/package/fast-string-width.md) ^3.0.2
- [get-current-package](https://npm.io/package/get-current-package.md) ^1.0.1

## Alternatives

- [@salesforce/cli](https://npm.io/package/@salesforce/cli.md) — 389.7K weekly downloads
- [@mintlify/cli](https://npm.io/package/@mintlify/cli.md) — 208.9K weekly downloads
- [@grafana/e2e-selectors](https://npm.io/package/@grafana/e2e-selectors.md) — 128.7K weekly downloads
- [mintlify](https://npm.io/package/mintlify.md) — 112.0K weekly downloads
- [@intlayer/cli](https://npm.io/package/@intlayer/cli.md) — 22.8K weekly downloads

## Recent versions

- 2.0.1 (latest) — 2026-02-12
- 2.0.0 — 2026-01-26
- 1.11.3 — 2025-08-22
- 1.11.2 — 2025-08-04
- 1.11.1 — 2025-02-23
- 1.11.0 — 2025-02-21
- 1.10.3 — 2025-02-02
- 1.10.2 — 2024-09-12
- 1.10.1 — 2024-09-01
- 1.10.0 — 2024-09-01
- 1.9.0 — 2024-08-31
- 1.8.0 — 2024-05-27
- 1.7.1 — 2024-03-21
- 1.7.0 — 2023-12-13
- 1.6.3 — 2023-11-21
- … 19 more at https://npm.io/package/tiny-bin/versions

## README

<p align="center">
  <img src="./resources/demo_gitman.png" alt="Demo app" width="681px">
</p>

# Tiny Bin

A library for building tiny and beautiful command line apps.

## Features

At a high level this package provides:

- A tiny library, that has no third-party dependencies, that can be bundled, for great startup performance.
- Beautiful colored and detailed help pages. Colors can be turned off also.
- Automatic package name and version detection, so you don't even need to provide those.
- Automatic typo detection, it will suggest the closest command/option if you mistype one.
- Automatic options type inference from the provided options.
- Automatic `help` and `--help` handling, both for the bin and for each command.
- Automatic `--version` and `-v` handling.
- Automatic `--no-color` and `--no-colors` handling.

This library has 5 primitives -- bins, commands, options, arguments and actions:

- Bin:
  - A bin is the entry point of your command line app, you can define multiple bins.
  - Each bin has a name, a description, and a few built-in commands (default, help, version).
  - Each bin can have multiple custom commands.
  - The action for the default command is customizable.
- Command:
  - A command is the function that will be executed when running your bin.
  - Each command has a name, a description, and an automatically generated usage example.
  - Each command can optional have a section, which will be used to group commands in the help page.
  - Each command can optionally be hidden from the help page.
  - Each command can optionally have custom usage examples.
  - Each command can have multiple options.
  - Each command can have multiple arguments.
  - Each command has an action, which is your actual function that will called by the command.
- Option:
  - An option is a flag that can be passed to your command.
  - Each option has a name, a description, and an implicit type (boolean or string).
  - Each option can optional have a section, which will be used to group options in the help page.
  - Each option can optionally be hidden from the help page.
  - Each option can optionally be marked as deprecated, causing it to be dimmed in the help page.
  - Each option can optionally be marked as eager, so it will consume multiple consecutive values.
  - Each option can optionally be marked as incompatible with some others.
  - Each option can optionally be marked as required, so the library will error if it's not provided.
  - Each option can optionally be marked as explicitly overriding a previously defined option.
  - Each option can optionally have a default value.
  - Each option can optionally have an explicit list of allowed values.
  - Each option can have multiple longhands (e.g. `--foo`) and multiple shorthands (e.g. `-f`).
  - Each provided longhand and shorthand for an option is automatically aliased to all the others.
  - Each non-boolean option must receive at least one value.
  - Each variadic option can receive multiple values (e.g. `<values...>`).
- Argument:
  - An argument is a value that can be passed to your command.
  - Each argument has a name and a description.
  - Each argument can be marked as required, so the library will error if it's not provided.
  - Each variadic argument (e.g. `<args...>`) can receive multiple values.
- Action:
  - An action is the function that will be called when running your command.
  - It will receive the following arguments:
    - The options object, containing all options for which the library has a value.
    - The arguments array, contaning an array of strings passed to your command.
    - The passthrough arguments array, containing an array of strings passed to your command after the special `--` separator.

## Install

```sh
npm install tiny-bin
```

## Usage

```ts
import bin from 'tiny-bin';

bin ( 'gitman', 'A simple yet powerful opinionated tool for managing repositories' )
  /* BIN CONFIGURATION */
  .config ({
    package: '@fabiospampinato/gitman', // Manually set the package name
    version: '1.2.3', // Manually set the version number
    colors: false, // Turn off colored output
    autoExit: false // Turn off the automatic process.exit call after action execution
  })
  /* GLOBAL COMMAND OPTIONS */
  .option ( '--silent, -s', 'Silence all output' )
  .option ( '--verbose, -V', 'Verbose output' )
  .option ( '--provider, -p <provider>', 'The provider to use', { default: 'github', enum: ['github', 'gitlab'] } )
  .option ( '--token, -t <token>', 'GitHub/GitLab personal access token', { required: true } )
  .option ({ name: '--example, -e <foo>', description: 'An example option configuration provided as a single object' })
  /* DEFAULT COMMAND ARGUMENTS */
  .argument ( '[user]', 'The name of the user' )
  .argument ( '<repo>', 'The name of the repository' )
  /* DEFAULT COMMAND ACTION */
  .action ( ( options, args, passthroughArgs ) => {
    console.log ( 'Default command executed' );
    console.log ( options );
    console.log ( args );
    console.log ( passthroughArgs );
  })
  /* CUSTOM COMMAND */
  .command ( 'clone', 'Clone a repository' )
  /* CUSTOM COMMAND OPTIONS */
  .option ( '--submodules', 'Clone submodules too' )
  /* CUSTOM COMMAND ARGUMENTS */
  .argument ( '[user]', 'The name of the user' )
  .argument ( '<repo>', 'The name of the repository' )
  /* CUSTOM COMMAND ACTION */
  .action ( ( options, args, passthroughArgs ) => {
    console.log ( 'Clone command executed' );
    console.log ( options );
    console.log ( args );
    console.log ( passthroughArgs );
  })
  /* EXECUTING THE BIN */
  .run ();
```

## License

MIT © Fabio Spampinato

---
_Source: https://npm.io/package/tiny-bin · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._