How to add autocompletion to my Node.js CLI tool with Omelette?

Install the package, define completion using template literals or event handlers, then call `init()`. For user setup, use `setupShellInitFile()` or provide manual shell config instructions from the README.

Omelette vs commander.js for autocompletion?

Omelette is focused solely on shell autocompletion with multi-shell support, while commander.js is a full CLI framework with parsing and help generation. Use Omelette if you need lightweight completion; commander.js for broader CLI features.

Can Omelette handle nested subcommands?

Yes, through its Tree API or event-based system, you can define hierarchical structures for subcommands, as shown in the tree examples with nested objects and functions.

Is Omelette compatible with TypeScript?

As a JavaScript library, it works with TypeScript, but you may need to check for type definitions. The Deno import uses TypeScript, ensuring typed usage in Deno projects.

How to debug Omelette when tab completion fails?

Run your program with the `--debug` flag to generate a debug function, then use `omelette-debug- ` to test aliases and completion logic interactively, as described in the Debugging section.

What shells does Omelette work with?

Omelette supports Bash, Zsh, and Fish shells natively, with automated or manual setup options for each, making it suitable for most Unix-like systems.

Open-Awesome

omelette

MITCoffeeScript0.4.15-2

A simple template-based autocompletion library for Node.js and Deno CLI tools with support for Bash, Zsh, and Fish.

GitHub

1.4k stars40 forks0 contributors

What is omelette?

Omelette is a library for adding shell autocompletion to Node.js and Deno command-line tools. It allows developers to define completion rules using templates, event handlers, or tree structures, making CLI tools more interactive and easier to use. It supports Bash, Zsh, and Fish shells with minimal setup.

Target Audience

Developers building CLI tools with Node.js or Deno who want to enhance user experience with shell autocompletion. It's particularly useful for tools with complex command structures or multiple arguments.

Value Proposition

Omelette stands out for its simple API, multi-shell support, and flexibility—offering template literals, async handlers, and tree-based completion without requiring deep shell scripting knowledge.

Overview

Omelette is a simple, template based autocompletion tool for Node and Deno projects with super easy API. (For Bash, Zsh and Fish)

Use Cases

Best For

Adding autocompletion to Node.js CLI tools
Building Deno-based command-line applications with shell completion
Creating complex CLI tools with nested command structures
Enhancing user experience for multi-argument CLI programs
Providing autocompletion for Bash, Zsh, and Fish shells simultaneously
Rapid prototyping of autocompletion features without extensive configuration

Not Ideal For

Projects requiring autocompletion for shells like PowerShell or Windows Command Prompt
Teams needing zero-user-intervention autocompletion with no setup steps
CLI tools with only a few static commands where manual typing is sufficient
Environments where JavaScript runtimes (Node.js/Deno) are not available or preferred

Pros & Cons

Pros

Simple Template API

Uses ES6 template literals like `omelette`github ${['pull', 'push']}`.init()` for rapid setup, minimizing configuration code as shown in the Quick Start.

Multi-Shell Support

Works with Bash, Zsh, and Fish out of the box, making it versatile across different user environments without extra shell-specific code.

Event-Driven Flexibility

Allows async handlers and dynamic reply functions, enabling real-time data fetching or filesystem access for completion options, demonstrated in the Async API section.

Tree Structure for Hierarchies

Supports nested autocompletion with the Tree API, ideal for complex command structures, as illustrated in the Advanced Tree Implementations example.

Cons

Deno Runtime Gaps

The README admits that automated setup and cleanup functions (`setupShellInitFile` and `cleanupShellInitFile`) are not available for Deno, forcing manual installation steps.

Async Handler Overhead

Using async handlers requires calling `complete.next` to resume the main workflow, adding complexity and potential for errors in flow control.

Shell Setup Dependencies

For Bash on macOS, users may need to install `bash-completion` via Homebrew, as noted in the manual installation, introducing external dependencies.

Frequently Asked Questions

Related Projects

A tool for writing better scripts

Stars45,623

Forks1,277

Last commit26 days ago

Ink

🌈 React for interactive command-line apps

Stars39,451

Forks1,028

Last commit8 days ago

chalk

🖍 Terminal string styling done right

A collection of common interactive command line user interfaces.

Stars21,610

Forks1,363