clipanion

Counters are boolean options that track how many times they are enabled. You can increase the count by repeating the shorthand (e.g., -vvv) and reset the counter to zero using the --no- prefix.

Example:

-vvvv
    => Command {"v": 4}
-vvvv --no-verbose
    => Command {"v": 0}

Boolean options are enabled by their presence. Clipanion automatically supports "Batches" for boolean options: if you have multiple boolean options with shorthands (e.g., -p, -i, -e), you can combine them into a single argument.

Example of boolean toggling:

--foo
    => Command {"foo": true}
--no-foo
    => Command {"foo": false}

Example of batching shorthands:

-pie
    => Command {"p": true, "i": true, "e": true}

Commands are created by extending the Command abstract base class. You must implement the execute method, which Clipanion calls when the command is run. The value returned by execute is used as the process exit code.

class SuccessCommand extends Command {
    async execute() {
        return 0;
    }
}

By default, Clipanion treats all commands as top-level, meaning they can be executed from the first token. For complex CLI applications (like yarn), you should use the static paths property on your command class to define specific command hierarchies.

A path is an array of strings that must appear in order for the command to be selected. You can provide multiple paths for a single command by using an array of arrays.

import {Command} from 'clipanion';

class InstallCommand extends Command {
    // This command matches either 'install' or 'i'
    static paths = [[`install`], [`i`]];
    async execute() {
        // ...
    }
}

Clipanion supports hierarchical command structures where one path is a prefix of another. It will select the most specific command that matches the input tokens.

For example, if FooCommand has path ['foo'] and FooBarCommand has path ['foo', 'bar']:

• Running foo bar executes FooBarCommand.
• Running foo executes FooCommand.

Ambiguity Note: You can have multiple commands with identical paths if they have different options. However, if the user invokes the command without specifying an option that distinguishes between them, Clipanion will throw an AmbiguousSyntaxError.

import {Command} from 'clipanion';

class FooCommand extends Command {
    static paths = [[`foo`]];
    async execute() {
        // ...
    }
}

class FooBarCommand extends Command {
    static paths = [[`foo`, `bar`]];
    async execute() {
        // ...
    }
}

Array options allow a single option key to be set multiple times, aggregating the values into an array. If you define the option as a tuple, each occurrence will be an array of strings.

Example of multiple string values:

--email foo@baz --email bar@baz
    => Command {"email": ["foo@baz", "bar@baz"]}

Example of tuples:

--point x1 y1 --point x2 y2
    => Command {"point": [["x1", "y1"], ["x2", "y2"]]}

In Clipanion, a context is an arbitrary object provided to all commands via this.context during execution. This allows you to pass environment options like cwd, user auth tokens, or configuration throughout your command hierarchy.

By default, the context includes standard I/O streams and environment information. Using streams instead of console.log allows commands to intercept and capture the output of other commands, enabling better composition.

To automatically route console.log calls to the correct streams (even during parallel execution), set enableCapture: true in your CLI configuration.

interface BaseContext {
    env: Record<string, string | undefined>;
    stdin: Readable;
    stdout: Writable;
    stderr: Writable;
    colorDepth: number;
}

Clipanion handles errors differently depending on whether you throw a standard Error, a UsageError, or return an exit code. Use the following rules of thumb to decide how to signal failure:

• Unexpected internal errors: Throw a standard Error. Clipanion will catch it and print the full stacktrace.
• Invalid user input/environment: Throw a UsageError. Clipanion will display only the provided message and the command usage line, suppressing the stacktrace.
• Expected non-zero exit conditions: Return 1 (or another non-zero integer) from your command. This is for cases where the command executed correctly but signaled a specific state to the caller (e.g., a linter finding errors or grep finding no matches). Clipanion will not print any additional error messages in this case.