# supercmd

> SuperCommand is a framework to build command-line interfaces in node.js.

Latest version **2.1.1** (published 2026-06-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install supercmd
pnpm add supercmd
yarn add supercmd
bun add supercmd
```

## Health

**Score 45/100 (D)** — status: active.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 2.1.1 |
| Published | 2026-06-04 |
| First published | 2018-10-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 7 |
| Unpacked size | 37 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Andi Heinkelein |
| Maintainers | andifeind, kippis, firetux |
| Keywords | cli, command, commander, shell, terminal, tty |

## Links

- npm: https://www.npmjs.com/package/supercmd
- Repository: git@gitlab.noname-media.com:Nodejs/supercmd
- npm.io page: https://npm.io/package/supercmd

## Dependencies (7)

- [fireio](https://npm.io/package/fireio.md) ^0.12.1
- [colorfy](https://npm.io/package/colorfy.md) ^2.4.0
- [logtopus](https://npm.io/package/logtopus.md) ^1.2.6
- [superimport](https://npm.io/package/superimport.md) ^1.4.1
- [superprompt](https://npm.io/package/superprompt.md) ^2.1.0
- [firescript-runtime](https://npm.io/package/firescript-runtime.md) ^0.3.13
- [firescript-lib-module](https://npm.io/package/firescript-lib-module.md) ^0.1.0

## 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.1.1 (latest) — 2026-06-04
- 2.1.0 — 2026-06-02
- 2.0.2 — 2025-09-26
- 2.0.1 — 2023-11-20
- 2.0.0 — 2022-03-24
- 1.2.0 — 2021-11-11
- 1.1.7 — 2021-01-26
- 1.1.6 — 2020-12-18
- 1.1.5 — 2020-12-15
- 1.1.4 — 2020-12-15
- 1.1.3 — 2020-10-13
- 1.1.2 — 2020-10-12
- 1.1.1 — 2020-06-12
- 1.1.0 — 2020-06-12
- 1.0.0 — 2020-06-01
- … 8 more at https://npm.io/package/supercmd/versions

## README

SuperCMD
============

SuperCMD is a framework to build command-line interfaces in Node.js

## Usage



```js
// commands/list.js
import { Command } from 'supercmd'

export const command = new Command()

command
  .cmd('list [options]')
  .description('List todos')
  .option('-s, --sort', 'Example of a boolean parameter')
  .option('-n, --num-items [num]', 'Example of an optional numeric parameter')
  .option('--filter [str]', 'Example of an optional string parameter')
  .action((ctx) => {
    // place command's code here
  })
```

```js
// commands/create.js
import { Command } from 'supercmd'

export const command = new Command()

command
  .cmd('create')
  .description('Create todo')
  .input('Enter a title', 'Example of an optional string parameter')
  .action((ctx) => {
    // place command's code here
  })
```

#### Command entrypoint

The entrypoint file loads the command files from a directory.

```js
#!/usr/bin/env node
require('firescript/register')
const {CommandsList} = require('supercmd')

const supercmd = new CommandsList()
supercmd.importFromDir(`${__dirname}/cli`).then((commandList) => {
  if (process.argv[2] === 'help') {
    commandList.printHelpPage(process.argv[3])
    return
  }

  if (process.argv[2] === 'commands') {
    commandList.printCommandsList(process.argv[3])
    return
  }

  commandList.callCommand(process.argv)
}).catch ((err) => {
  console.error(err)
  process.exit(1)
})
```

## API

#### .cmd(*str* command)

Register a subcommand. A subcommand can take 0 - n arguments.

Wrap argument types in `[` and `]`. An leading `?` marks it as optional.
Command types are either `str` or `num`

Example: `mycommand [str] [str?]`
This would register a command `mycommand` with two arguments. The second one is optional. Both arguments are handled as strings. You can access the arguments as second and third arguments in the action handler.

```js
.action((ctx, infile, outfile) => {

})
```

#### .cwd(*str* workingDir)
Set a working dir

#### .description(*str* description)
Describe what a program is for and what is does, show in the help page

#### .option(*str* arg, *str* description, *any* defaultValue, *func* func)

Register an option parameter. The `param` argument describes the parameter name, alias, value und value type. The syntax is `[alias] [name] [value]`.

Alias is an one char long shortcut of the parameter and it is prefixed by one minus char. Example: `-f`.  
Name is a parameter name. It is prefixed by two minus and its the only required part. A parameter can contain chars, numbers and a minus. Example: `--fruit, --fruit-banana`.
The third part describes the parameter value and if it is a mandatory parameter or not. The default type is `bool`.
The type must be enclosed by square bracets.
A leading `?` in the value type defines the parameter as optional.

Example for a required parameter of type boolean:
`-f --fruit [bool]`

Example for a optional parameter of type string:
`-b --banana [str?]`

Allowed types: `str`, `num`, `arr`, `bool`, `json`

#### .input(*str* name, *str* question, *str* type, *any* values)

Ask for input parameter. All input parameter are available as `ctx.input.<name>`

#### .usage(*str* description)

Describes program usage, shown in the help page.

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