@naerth/commander-autocomplete

commander-autocomplete is a module that provides autocomplete for command-line interfaces built with the Commander.js library.

Installation

You can install commander-autocomplete using npm, yarn, or bun:

npm install commander @naerth/commander-autocomplete

yarn add commander @naerth/commander-autocomplete

bun install commander @naerth/commander-autocomplete

Usage

To use commander-autocomplete, you need to add the following code to your Commander.js-based CLI application.

commander-autocomplete supports both Javascript and TypeScript.

Autocomplete with subcommands

typescript

const { program } = require("@naerth/commander-autocomplete");
// or
import { program } from "@naerth/commander-autocomplete";

program.name("example");

const hello = program
  .command("hello")
  .action(() => {
    console.log("Hello");
  });

hello.command("world").action(() => {
  console.log("Hello, world!");
});

// automatically enable autocomplete
program.parse(process.argv);

Terminal

$ example hello<TAB>
world

Autocomplete with options

const { program } = require("@naerth/commander-autocomplete");
// or
import { program } from "@naerth/commander-autocomplete";

program.name("example");

const hello = program
  .command("hello")
  .option('-d, --debug')
  .action(() => {
    console.log("Hello");
  });

hello.command("world").action(() => {
  console.log("Hello, world!");
});

// automatically enable autocomplete
program.parse(process.argv);

Terminal

$ example hello<TAB>
-d       --debug  world

Autocomplete with arguments and options choices

Note: Argument and Option should be imported from commander, not from @naerth/commander-autocomplete.

const { program } = require("@naerth/commander-autocomplete");
// or
import { program } from "@naerth/commander-autocomplete";
import { Argument, Option } from 'commander';

const argument = new Argument('<repository>', 'Repository to clone')
argument.choices(['repo1', 'repo2', 'repo3'])

const typeOption = new Option('--type <type>', 'Type of clone');
typeOption.choices(['full', 'shallow']);

program
    .command('clone')
    .addArgument(argument)
    .addOption(typeOption)
    .action(() => {
        console.log('clone command executed');
    });


program.parse(process.argv);

Terminal

$ example clone repo<TAB>
repo1  repo2  repo3

$ example clone repo2 --type <TAB>
full     shallow

Autocomplete with dynamic suggestions

You can provide dynamic autocomplete suggestions for a command by using the .autocomplete method, which accepts a function (sync or async) that returns an array of possible completions.

const { program } = require("@naerth/commander-autocomplete");
// or
import { program } from "@naerth/commander-autocomplete";

program.name("example");

program
  .command("ls")
  .option("-l, --long", "long listing")
  .autocomplete(async () => ["world", "universe"]) // programmatic autocomplete
  .action(() => {
    console.log("Hello, world!");
  });


// automatically enable autocomplete
program.parse(process.argv)

Terminal

$ example ls<TAB>
-l        --long    universe  world 

Autocomplete in a terminal

To use autocomplete in a terminal:

$ example --setup
source ~/.bashrc

To disable autocomplete:

$ example --cleanup
source ~/.bashrc

Limitations

Currently, only Bash is supported. Support for other shells (such as Zsh or Fish) is not yet available, but contributions to add support for additional shells are welcome—please see the Contributing section if you would like to help.

Contributing

If you would like to contribute to commander-autocomplete, please fork the repository and submit a pull request.