@push.rocks/smartcli

Build small, reactive command-line tools in TypeScript without hand-rolling argument dispatch. @push.rocks/smartcli parses the current runtime's user arguments, dispatches the first positional command into an RxJS Subject, exposes the parsed yargs-parser result to your handler, and gives you a clean fallback path when no command is provided.

It is ESM-first, ships TypeScript declarations, and handles user argument slicing across Node.js, Deno, Deno-compiled executables, Bun, tsx, and ts-node.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Install

pnpm add @push.rocks/smartcli

Why Use Smartcli

• Reactive command handlers: every command is an RxJS Subject, so command execution fits naturally into observable-based code.
• Tiny API surface: register commands, subscribe handlers, and call startParse().
• Runtime-aware argument handling: Node.js, Deno, Deno-compiled binaries, Bun, tsx, and ts-node get user-only arguments consistently.
• yargs-parser integration: flags and positional arguments arrive as a familiar parsed object.
• Built-in standard command, help command, version output, manual triggering, and parse completion hooks.

Quick Start

Create a CLI entrypoint, for example cli.ts:

#!/usr/bin/env node
import { Smartcli } from '@push.rocks/smartcli';

const cli = new Smartcli();

cli.addVersion('1.0.0');

cli.addHelp({
  helpText: `
Usage:
  demo greet --name Ada
  demo --version
  demo help

Commands:
  greet    Print a greeting
  help     Print this help text
`,
});

cli.addCommand('greet').subscribe((argv) => {
  const name = argv.name || 'World';
  console.log(`Hello, ${name}!`);
});

cli.standardCommand().subscribe(() => {
  console.log('Usage: demo greet --name Ada');
  console.log('Run "demo help" for details.');
});

cli.startParse();

When exposed as a package bin, the CLI behaves like this:

demo greet --name Ada
# Hello, Ada!

demo --version
# 1.0.0

demo help
# prints the configured help text

Terminal Task Rendering

Use SmartcliTerminal for long-running jobs that should render cleanly in both interactive and non-interactive environments. In a TTY, active tasks render below each other with a fixed row count, colored status symbols, and optional live timers/spinners. In CI, pipes, Docker logs, or TERM=dumb, the same calls become throttled append-only lifecycle logs where every message line is prefixed with its task name.

import { SmartcliTerminal } from '@push.rocks/smartcli';

const terminal = new SmartcliTerminal();

const buildTask = terminal.task('Build package', {
  rows: 3,
  showTimer: true,
  showSpinner: true,
});

buildTask.update('Installing dependencies');
buildTask.setProgress(1, 2, 'Running tsbuild');
buildTask.complete('Build finished');

const publishTask = terminal.createProcess({
  job: 'Publish package',
  rows: 4,
});

try {
  await publishPackage();
  publishTask.complete('Published');
} catch (error) {
  publishTask.attachError(error);
}

Completed tasks collapse into one permanent success line. Failed tasks collapse into one permanent failure line with error details. If an error should remain visible inside the live task area, use attachError(error, { keepOpen: true }).

showTimer renders a second-precision live counter using @push.rocks/smarttime, for example 4s or 1m 30s. showSpinner animates the running indicator in interactive terminals and is ignored for append-only output. The shorter aliases timer and spinner are also accepted.

For scoped work, task.run() completes or fails automatically:

await terminal.task('Generate assets').run(async (task) => {
  task.setProgress(1, 3, 'Reading source files');
  await readSourceFiles();
  task.setProgress(2, 3, 'Rendering assets');
  await renderAssets();
  task.setProgress(3, 3, 'Writing output');
}, { successMessage: 'Assets generated' });

Execution Model

1. Create a Smartcli instance.
2. Register all commands before parsing.
3. Subscribe handlers to the returned command subjects.
4. Call startParse() once to parse the current runtime arguments.
5. startParse() parses user args with yargs-parser.
6. The first positional argument, argv._[0], is treated as the command name.
7. A matching command subject receives the parsed argv object through .next(argv).
8. If no command is provided, the subject from standardCommand() is triggered when it exists.
9. After normal dispatch, parseCompleted.promise resolves with the parsed argument object.

startParse() dispatches synchronously. If a handler starts asynchronous work, manage that lifecycle in your application code.

Commands and Options

Options are available directly on the parsed object handed to your subscription:

import { Smartcli } from '@push.rocks/smartcli';

const cli = new Smartcli();

cli.addCommand('deploy').subscribe((argv) => {
  const environment = argv.env || 'development';
  const force = Boolean(argv.force);

  console.log(`Deploying to ${environment}`);

  if (force) {
    console.log('Force mode enabled');
  }
});

cli.standardCommand().subscribe(() => {
  console.log('Usage: deployer deploy --env production [--force]');
});

cli.startParse();

Run it with:

deployer deploy --env production --force

The handler receives a yargs-parser result similar to:

{
  _: ['deploy'],
  env: 'production',
  force: true
}

Positional Arguments

The first positional argument selects the command. Additional positional values remain in argv._:

import { Smartcli } from '@push.rocks/smartcli';

const cli = new Smartcli();

cli.addCommand('run').subscribe((argv) => {
  const taskName = argv._[1];

  if (!taskName) {
    console.log('Usage: tool run <taskName>');
    return;
  }

  console.log(`Running task: ${taskName}`);
});

cli.startParse();

tool run build
# Running task: build

Standard Command

Use standardCommand() for the no-command case:

import { Smartcli } from '@push.rocks/smartcli';

const cli = new Smartcli();

cli.addCommand('status').subscribe(() => {
  console.log('Everything is operational.');
});

cli.standardCommand().subscribe(() => {
  console.log('Available commands: status');
});

cli.startParse();

If no standard command is registered and the user runs the CLI without a command, smartcli prints no smartcli standard task was created or assigned..

Help and Version Output

addVersion() enables -v and --version when no command is provided:

cli.addVersion('2.3.0');

tool --version
# 2.3.0

addHelp() registers a help command. It does not create a --help flag:

cli.addHelp({
  helpText: `
Usage:
  tool build --target app
  tool status
`,
});

tool help

Programmatic Dispatch

Use triggerCommand() when you want to invoke a registered command yourself, for example in orchestration code or focused tests:

import { Smartcli } from '@push.rocks/smartcli';

const cli = new Smartcli();

cli.addCommand('build').subscribe((argv) => {
  console.log(`Building ${argv.target}`);
});

cli.triggerCommand('build', {
  _: ['build'],
  target: 'docs',
});

triggerCommand() throws if the command has not been registered.

Testing CLIs

startParse() accepts an optional argv override. Pass a full runtime-style argument array for deterministic tests:

import { Smartcli } from '@push.rocks/smartcli';

const cli = new Smartcli();
const parsedPromise = cli.parseCompleted.promise;

cli.addCommand('publish').subscribe((argv) => {
  console.log(`Publishing with tag ${argv.tag}`);
});

cli.startParse(['node', 'test-cli.js', 'publish', '--tag', 'next']);

const parsed = await parsedPromise;
console.log(parsed.tag);
// next

Create a fresh Smartcli instance per parse. parseCompleted is a single deferred value on the instance and resolves once.

Cross-Runtime Argument Handling

smartcli uses getUserArgs() internally to remove runtime-specific executable and script entries before parsing:

| Runtime mode | Argument strategy | | --- | --- | | Deno without an explicit test argv | Uses Deno.args, which is already user-only. | | Node.js | Uses process.argv and skips executable plus script path for known launchers. | | Bun | Uses process.argv and skips executable plus script path for known launchers. | | tsx and ts-node | Treated as known launchers and parsed like Node.js. | | Unknown compiled executable | Skips only the executable path, keeping the first user argument intact. |

This matters for compiled CLIs where process.argv[0] is the binary itself and the first user argument should not be mistaken for a script path.

Aliases

The class exposes addCommandAlias(original, alias) and the public aliasObject for keeping alias metadata:

cli.addCommandAlias('deploy', 'd');
console.log(cli.aliasObject.deploy);
// ['d']

Current command dispatch is exact-match based on argv._[0]. If you want executable aliases, register the alias as a command and subscribe it to the same handler:

import { Smartcli } from '@push.rocks/smartcli';

const cli = new Smartcli();

const deploy = (argv: any) => {
  console.log(`Deploying ${argv.target || 'default target'}`);
};

cli.addCommand('deploy').subscribe(deploy);
cli.addCommand('d').subscribe(deploy);
cli.addCommandAlias('deploy', 'd');

cli.startParse();

API Reference

| API | Purpose | | --- | --- | | new Smartcli() | Creates an isolated CLI parser and command registry. | | addCommand(commandName) | Registers a command and returns its RxJS Subject. If the command already exists, the existing subject is reused. | | standardCommand() | Registers and returns the fallback subject for runs without a command. | | startParse(testArgv?) | Parses current user args, or the provided full argv array, and dispatches to the matching command. | | triggerCommand(commandName, argvObject) | Manually emits an argv object into a registered command subject. | | getCommandSubject(commandName) | Returns the subject for a registered command or null. | | getOption(optionName) | Parses current runtime args and returns one option by name. Inside command handlers, prefer the provided argv object. | | addHelp({ helpText }) | Registers a help command that logs the provided help text. | | addVersion(version) | Stores the version printed by -v or --version when no command is selected. | | addCommandAlias(original, alias) | Stores alias metadata in aliasObject. Register alias command names separately for direct dispatch. | | parseCompleted.promise | Resolves with the parsed argv object after normal startParse() dispatch. |

Practical Example

This example wires a tiny task runner with commands, options, help, version output, and a standard fallback:

#!/usr/bin/env node
import { Smartcli } from '@push.rocks/smartcli';

const cli = new Smartcli();

const tasks = new Map<string, () => Promise<void> | void>([
  ['build', () => console.log('Building project...')],
  ['test', () => console.log('Running tests...')],
  ['release', () => console.log('Preparing release...')],
]);

cli.addVersion('1.4.0');

cli.addHelp({
  helpText: `
Task Runner

Usage:
  tasker list
  tasker run <taskName> [--dry]
  tasker --version

Available tasks:
  build
  test
  release
`,
});

cli.addCommand('list').subscribe(() => {
  for (const taskName of tasks.keys()) {
    console.log(taskName);
  }
});

cli.addCommand('run').subscribe(async (argv) => {
  const taskName = argv._[1];
  const dryRun = Boolean(argv.dry);

  if (!taskName) {
    console.log('Usage: tasker run <taskName> [--dry]');
    return;
  }

  const task = tasks.get(taskName);

  if (!task) {
    console.log(`Unknown task: ${taskName}`);
    return;
  }

  if (dryRun) {
    console.log(`Would run task: ${taskName}`);
    return;
  }

  await task();
});

cli.standardCommand().subscribe(() => {
  console.log('Usage: tasker <list|run|help>');
});

cli.startParse();

Sharp Edges Worth Knowing

• Register commands before calling startParse().
• startParse() dispatches once; create a new Smartcli instance for a second parse.
• addHelp() registers the help command, not a --help option.
• addVersion() prints only when no positional command is present.
• getOption() reads the current runtime args. In command subscriptions, use the argv object you receive for the most testable code.
• Alias metadata is stored, but aliases are not automatically dispatched unless you register the alias command name too.
• smartcli does not validate option schemas. Add validation in your own command handlers when inputs matter.

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the LICENSE file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

Company Information

Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at [email protected].

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.