!tab CLI autocompletions demo

tab

Shell autocompletions are largely missing in the JavaScript CLI ecosystem. tab provides a simple API for adding autocompletions to any JavaScript CLI tool.

Additionally, tab supports autocompletions for pnpm, npm, yarn, and bun.

Modern CLI libraries like Gunshi include tab completion natively in their core.

As CLI tooling authors, if we can spare our users a second or two by not checking documentation or writing the -h flag, we're doing them a huge favor. The unconscious mind loves hitting the [TAB] key and always expects feedback. When nothing happens, it breaks the user's flow - a frustration apparent across the whole JavaScript CLI tooling ecosystem.

tab solves this complexity by providing autocompletions that work consistently across zsh, bash, fish, and powershell.

Installation

$3

> Note: Global install is recommended

``bash
npm install -g @bomb.sh/tab
`

Then enable completions permanently:

`bash


For zsh

echo 'source <(tab pnpm zsh)' >> ~/.zshrc
source ~/.zshrc

For bash

echo 'source <(tab pnpm bash)' >> ~/.bashrc
source ~/.bashrc

The same can be done for other shells!

`

$3

`bash
npm install @bomb.sh/tab


or

pnpm add @bomb.sh/tab

or

yarn add @bomb.sh/tab

or

bun add @bomb.sh/tab
`

Quick Start

Add autocompletions to your CLI tool:

`typescript
import t from '@bomb.sh/tab';

// Define your CLI structure
const devCmd = t.command('dev', 'Start development server');
devCmd.option('port', 'Specify port', (complete) => {
complete('3000', 'Development port');
complete('8080', 'Production port');
});

// Handle completion requests
if (process.argv[2] === 'complete') {
const shell = process.argv[3];
if (shell === '--') {
const args = process.argv.slice(4);
t.parse(args);
} else {
t.setup('my-cli', 'node my-cli.js', shell);
}
}
`

Test your completions:

`bash
node my-cli.js complete -- dev --port=


Output: --port=3000 Development port

--port=8080 Production port

`

Install for users:

`bash


One-time setup

source <(my-cli complete zsh)

Permanent setup

my-cli complete zsh > ~/.my-cli-completion.zsh
echo 'source ~/.my-cli-completion.zsh' >> ~/.zshrc
`

Package Manager Completions

As mentioned earlier, tab provides completions for package managers as well:

`bash


Generate and install completion scripts


tab pnpm zsh > ~/.pnpm-completion.zsh && echo 'source ~/.pnpm-completion.zsh' >> ~/.zshrc
tab npm bash > ~/.npm-completion.bash && echo 'source ~/.npm-completion.bash' >> ~/.bashrc
tab yarn fish > ~/.config/fish/completions/yarn.fish
tab bun powershell > ~/.bun-completion.ps1 && echo '. ~/.bun-completion.ps1' >> $PROFILE
`

Example in action:

`bash
pnpm install --reporter=


Shows: append-only, default, ndjson, silent

yarn add --emoji=


Shows: true, false


`

Framework Adapters

tab provides adapters for popular JavaScript CLI frameworks.

$3

`typescript
import cac from 'cac';
import tab from '@bomb.sh/tab/cac';

const cli = cac('my-cli');

// Define your CLI
cli
.command('dev', 'Start dev server')
.option('--port ', 'Specify port')
.option('--host ', 'Specify host');

// Initialize tab completions
const completion = await tab(cli);

// Add custom completions for option values
const devCommand = completion.commands.get('dev');
const portOption = devCommand?.options.get('port');
if (portOption) {
portOption.handler = (complete) => {
complete('3000', 'Development port');
complete('8080', 'Production port');
};
}

cli.parse();
`

$3

`typescript
import { defineCommand, createMain } from 'citty';
import tab from '@bomb.sh/tab/citty';

const main = defineCommand({
meta: { name: 'my-cli', description: 'My CLI tool' },
subCommands: {
dev: defineCommand({
meta: { name: 'dev', description: 'Start dev server' },
args: {
port: { type: 'string', description: 'Specify port' },
host: { type: 'string', description: 'Specify host' },
},
}),
},
});

// Initialize tab completions
const completion = await tab(main);

// Add custom completions
const devCommand = completion.commands.get('dev');
const portOption = devCommand?.options.get('port');
if (portOption) {
portOption.handler = (complete) => {
complete('3000', 'Development port');
complete('8080', 'Production port');
};
}

const cli = createMain(main);
cli();
`

$3

`typescript
import { Command } from 'commander';
import tab from '@bomb.sh/tab/commander';

const program = new Command('my-cli');
program.version('1.0.0');

// Define commands
program
.command('serve')
.description('Start the server')
.option('-p, --port ', 'port to use', '3000')
.option('-H, --host ', 'host to use', 'localhost')
.action((options) => {
console.log('Starting server...');
});

// Initialize tab completions
const completion = tab(program);

// Add custom completions
const serveCommand = completion.commands.get('serve');
const portOption = serveCommand?.options.get('port');
if (portOption) {
portOption.handler = (complete) => {
complete('3000', 'Default port');
complete('8080', 'Alternative port');
};
}

program.parse();
`

tab uses a standardized completion protocol that any CLI can implement:

`bash


Generate shell completion script

my-cli complete zsh

Parse completion request (called by shell)

my-cli complete -- install --port=""
`

Output Format:

`
--port=3000 Development port
--port=8080 Production port
:4
``

Documentation

See bombshell docs.

Contributing

We welcome contributions! tab's architecture makes it easy to add support for new package managers or CLI frameworks.

Acknowledgments

tab was inspired by the great Cobra project, which set the standard for CLI tooling in the Go ecosystem.

Adoption Support

We want to make it as easy as possible for the JS ecosystem to enjoy great autocompletions.
We at thundraa would be happy to help any open source CLI utility adopt tab.
If you maintain a CLI and would like autocompletions set up for your users, just drop the details in our _Adopting tab_ discussion.
We’ll gladly help and even open a PR to get you started.