Autocomplete

The autocomplete plugin catches COMMAND_NOT_FOUND errors and provides "Did you mean?" suggestions based on Levenshtein distance.

Usage

import { Crust } from "@crustjs/core";
import { autoCompletePlugin } from "@crustjs/plugins";

const main = new Crust("my-cli")
  .use(autoCompletePlugin())
  .run(() => { /* ... */ });

await main.execute();

$ my-cli buld
Unknown command "buld". Did you mean "build"?

Available commands: build, dev, deploy

Configuration

Error Mode (Default)

Prints the error to stderr and sets exit code to 1:

autoCompletePlugin()
// or
autoCompletePlugin({ mode: "error" })

Output (to stderr):

Unknown command "buld". Did you mean "build"?

Available commands: build, dev, deploy

Help Mode

Prints the suggestion and the parent command's help text to stdout:

autoCompletePlugin({ mode: "help" })

Output (to stdout):

Unknown command "buld". Did you mean "build"?

my-cli - My CLI tool

USAGE:
  my-cli <command> [options]

COMMANDS:
  build     Build the project
  dev       Start dev server
  deploy    Deploy to production

OPTIONS:
  -h, --help        Show help
  -v, --version     Show version number

How Suggestions Work

The plugin uses Levenshtein distance to find similar commands:

Prefix matches — If the input is a prefix of a command (or vice versa), it's considered a match with distance 0
Fuzzy matches — Commands within a Levenshtein distance of 3 are included
Sorting — Results are sorted by distance (closest first), then alphabetically

Only the top suggestion appears in the "Did you mean?" message. All available commands are listed separately (in error mode).

Plugin Order

The autocomplete plugin wraps the middleware chain in a try/catch. Place it before the help plugin so it can catch routing errors:

new Crust("my-cli")
  .use(versionPlugin("1.0.0"))
  .use(autoCompletePlugin({ mode: "help" }))
  .use(helpPlugin())

Non-Matching Errors

The plugin only handles COMMAND_NOT_FOUND errors. All other errors are re-thrown and handled normally by the middleware chain or .execute().

Type

interface AutoCompletePluginOptions {
  mode?: "error" | "help";  // Default: "error"
}

function autoCompletePlugin(options?: AutoCompletePluginOptions): CrustPlugin;

On this page