@clerc/plugin-completions

A plugin to add command-line autocompletion functionality to your CLI, based on @bomb.sh/tab.

📦 Installation

npm

$ npm install @clerc/plugin-completions

yarn

$ yarn add @clerc/plugin-completions

pnpm

$ pnpm add @clerc/plugin-completions

🚀 Usage

Import

import { completionsPlugin } from "@clerc/plugin-completions";
// Or import directly from clerc
import { completionsPlugin } from "clerc";

Basic Usage

const cli = Clerc.create()
  .scriptName("my-cli")
  .description("My CLI application")
  .version("1.0.0")
  .use(completionsPlugin()) // Add the autocompletion plugin
  .command("start", "Start the service")
  .on("start", (ctx) => {
    console.log("Service started");
  })
  .command("stop", "Stop the service")
  .on("stop", (ctx) => {
    console.log("Service stopped");
  })
  .parse();

Running Effect

# Generate autocompletion script for Bash
$ my-cli completions bash

# Execute directly to enable autocompletion
# PowerShell
$ my-cli completions powershell | Out-String | Invoke-Expression

# Bash
$ eval "$(my-cli completions bash)"

# Zsh
$ eval "$(my-cli completions zsh)"

# You can also specify the shell type with the --shell parameter
$ eval "$(my-cli completions --shell bash)"

📝 Features

Automatic Completion Script Generation

The plugin automatically generates a full autocompletion script for your CLI, supporting:

• Command autocompletion
• Flag autocompletion

Completion Logic

$ my-cli <TAB> # Complete available commands
$ my-cli command <TAB> # Complete subcommands of the specified command
$ my-cli -<TAB> # Complete all global short flags, e.g., -h, -V
$ my-cli --<TAB> # Complete all global long flags
$ my-cli command -<TAB> # Complete short flags for the specified command (including global flags), e.g., -h, -V
$ my-cli command --<TAB> # Complete all available flags for the specified command, including global flags

Supported Shells

• Bash - Default shell for Linux and macOS
• Zsh - Default shell for macOS Catalina and later versions
• Fish - A modern shell
• PowerShell - Default shell for Windows