Getting Started

Tab provides shell autocompletions for JavaScript CLI tools, making your CLI feel as polished as native tools like git. This guide will walk you through adding autocompletions to your CLI tool.

Installation

Install Tab using your preferred package manager:

npm

npm install @bombsh/tab

pnpm

pnpm add @bombsh/tab

Yarn

yarn add @bombsh/tab

Basic Usage

Here’s a simple example of how to add autocompletions to your CLI:

import { RootCommand } from '@bombsh/tab';

const t = new RootCommand();

// Add global options
t.option('--config', 'Use specified config file', function(complete) {
  complete('vite.config.ts', 'Vite config file');
  complete('vite.config.js', 'Vite config file');
}, 'c');

// Add commands with completions
const devCmd = t.command('dev', 'Start development server');
devCmd.option('--port', 'Port number', function(complete) {
  complete('3000', 'Development port');
  complete('8080', 'Production port');
}, 'p');

devCmd.option('--host', 'Hostname', function(complete) {
  complete('localhost', 'Localhost');
  complete('0.0.0.0', 'All interfaces');
}, 'H');

// Add positional arguments
t.command('copy', 'Copy files')
  .argument('source', function(complete) {
    complete('src/', 'Source directory');
    complete('dist/', 'Distribution directory');
  })
  .argument('destination', function(complete) {
    complete('build/', 'Build output');
    complete('release/', 'Release directory');
  });

// Handle completion requests
if (process.argv[2] === 'complete') {
  const shell = process.argv[3];
  if (shell && ['zsh', 'bash', 'fish', 'powershell'].includes(shell)) {
    t.setup('my-cli', process.execPath, shell);
  } else {
    // Parse completion arguments (everything after --)
    const separatorIndex = process.argv.indexOf('--');
    const completionArgs = separatorIndex !== -1 ? process.argv.slice(separatorIndex + 1) : [];
    t.parse(completionArgs);
  }
} else {
  // Regular CLI usage
  console.log('My CLI Tool');
  console.log('Use "complete" command for shell completion');
}

Understanding the API

RootCommand Class

The RootCommand class is the main entry point for defining your CLI structure:

const t = new RootCommand();

Adding Commands

Use the command() method to add commands with descriptions:

const devCmd = t.command('dev', 'Start development server');

Adding Options

Add options to commands with completion handlers:

devCmd.option('--port', 'Port number', function(complete) {
  complete('3000', 'Development port');
  complete('8080', 'Production port');
}, 'p'); // Short flag alias

Adding Arguments

Add positional arguments with completion handlers:

t.command('copy', 'Copy files')
  .argument('source', function(complete) {
    complete('src/', 'Source directory');
    complete('dist/', 'Distribution directory');
  });

Variadic Arguments

For commands that accept multiple arguments:

t.command('lint', 'Lint project')
  .argument('files', function(complete) {
    complete('main.ts', 'Main file');
    complete('src/', 'Source directory');
  }, true); // true = variadic argument

Shell Setup

After adding Tab to your CLI, users need to set up shell completion. Here are the recommended approaches for different shells:

Zsh

# Generate completion script
my-cli complete zsh > ~/completion-for-my-cli.zsh

# Add to your .zshrc
echo 'source ~/completion-for-my-cli.zsh' >> ~/.zshrc

Bash

# Generate completion script
my-cli complete bash > ~/.bash_completion.d/my-cli

# Add to your .bashrc
echo 'source ~/.bash_completion.d/my-cli' >> ~/.bashrc

Fish

# Generate completion script
my-cli complete fish > ~/.config/fish/completions/my-cli.fish

PowerShell

# Generate completion script
my-cli complete powershell > $PROFILE.CurrentUserAllHosts

Package Manager Integration

Tab also provides a standalone CLI tool that enhances package manager completions with automatic CLI discovery:

Installing the Tab CLI

npm install -g @bombsh/tab

Setting Up Package Manager Completions

# For pnpm
tab pnpm zsh > ~/.zsh_completions/tab-pnpm.zsh
echo 'source ~/.zsh_completions/tab-pnpm.zsh' >> ~/.zshrc

# For npm
tab npm zsh > ~/.zsh_completions/tab-npm.zsh
echo 'source ~/.zsh_completions/tab-npm.zsh' >> ~/.zshrc

# For yarn
tab yarn zsh > ~/.zsh_completions/tab-yarn.zsh
echo 'source ~/.zsh_completions/tab-yarn.zsh' >> ~/.zshrc

# For bun
tab bun zsh > ~/.zsh_completions/tab-bun.zsh
echo 'source ~/.zsh_completions/tab-bun.zsh' >> ~/.zshrc

This provides enhanced completions for all CLI tools that support Tab completions, automatically detecting and providing completions for tools like Vite, TypeScript, and any other Tab-compatible CLI.

How It Works

Tab works by adding a complete command to your CLI that generates shell-specific completion scripts. When users type my-cli complete zsh, Tab generates a completion script that the shell can source.

The completion script communicates with your CLI through the autocompletion server. When users press Tab, the shell calls your CLI with special arguments, and Tab returns the appropriate completions.

Autocompletion Server

Your CLI becomes an autocompletion server when you add Tab. The server responds to completion requests with suggestions and ends its output with :{Number} to indicate the number of completions.

For example:

my-cli complete -- --po
--port  Port number
:0

Next Steps

• Learn about Framework Adapters for easier integration with CAC, Citty, and Commander.js
• Explore Package Manager Integration for enhanced completions
• Check out Best Practices for implementing effective autocompletions
• Check out the API Reference for detailed documentation