tab completion helpers, for node cli programs. Inspired by npm completion.
A node package to do some custom command line
<tab><tab> completion for any
system command, for Bash, Zsh, and Fish shells.
Made possible using the same technique as npm (whose completion is quite awesome) relying on a shell script bridge to do the actual completion from node's land.
npm install, gently asking the user for install location.
tabtab installin package.json install script creates the completion file on user system.
npm install tabtab --save
You can add completion pretty easily in your node cli script:
// Ex. bin/ entry point for a "program" packagevar tab = require'tabtab';// General handler. Gets called on `program <tab>` and `program stuff ... <tab>`tabon'program'// General handlerdonenull 'foo' 'bar';;// Specific handler. Gets called on `program list <tab>`tabon'list'donenull 'file.js' 'file2.js';;// Start must be called to register the completion commands and listen for// completion.tabstart;
These events are emitted whenever the command
program completion -- .. is
triggered, with special
COMP_* environment variables.
tab.start() will define one command:
completion for your program, which is
used by the Shell completion scripts.
data object holds interesting value to drive the output of the
line: full command being completed
words: number of word
point: cursor position
partial: tabing in the middle of a word: foo bar baz bar foobarrrrrrr
last: last word of the line
lastPartial: last partial of the line
prev: the previous word
// the String package name being completed, defaults to process.title// (if not node default) or will attempt to determine parent's// package.json location and extract the name from it.name: 'foobar'// Enable / Disable cache (defaults: true)cache: true// Cache Time To Live duration in ms (default: 5min)ttl: 1000 * 60 * 5;
Completion results are cached by default, for a duration of 5 minutes. Caching
is based on the value of the full command being completed (
While the EventEmitter API can offer fine control over what gets completed,
completion values can be defined directly in the
package.json file, using the
"tabtab":"nvm": "help" "use" "install" "uninstall" "run" "current" "ls" "ls-remote""use": "stable" "default" "iojs" "v5.11.0" "v6.0.0"
This still requires to initialize tabtab with:
Manually loading the completion for your cli app is done very much like npm does:
. <(tabtab install --stdout --name program)
It'll enables tab-completion for the
program executable. Adding it to your
~/.bashrc or ~/.zshrc will make the completions available everywhere (not only
the current shell).
tabtab install --stdout --name program >> ~/.bashrc # or ~/.zshrc
This requires an additional manual step for the user. Ideally we'd want it to be automatic, and define it at a system-level.
For completions to be active for a particular command/program, the user shell (bash, zsh or fish) must load a specific file when the shell starts.
Each shell have its own system, and different loading paths.
tabtab tries to
figure out the most appropriate directory depending on the
pkg-configfor completion directories if bash-completion is installed (defaults to
tabtab CLI provides an
install command to ease the process of installing a
completion script when the package is installed on the user system, using npm
Using npm's install/uninstall script, you can automatically manage completion for your program whenever it gets globally installed or removed.
On install, npm will execute the
tabtab install command automatically in the
context of your package.
Nothing is done's without asking confirmation,
tabtab install looks at the
$SHELL variable to determine the best possible locations and uses
Inquirer to ask the user what it
--auto flag can be used to bypass prompts and use the SHELL configuration file options by default:
This way, you can silently install / uninstall completion for a specific command without asking user to do so.
The uninstall command can be used to undo what has been done by
tabtab install --auto command.
todo: zsh / fish offers the ability to define description with each completion item, implemented with fish, have to adjust the same pattern to zsh.
--completer option allows you to delegate the completion part to another
program. Let's take nvm as an example.
The idea is to create a package named
nvm-complete, with an executable that
tabtab and handle the completion output of
// index.jsvar tabtab = require'tabtab';tabtabon'nvm'return donenull 'ls' 'ls-remote' 'install' 'use' ;;tabtabstart;
Alternatively, we can use tabtab property in package.json file to define static list of completion results:
For more control over the completion results, the JS api is useful for
returning specific values depdending on preceding words, like completing each
node versions on
nvm install <tab>.
var exex = require'child_process'exec;// To cache the list of versions returned by ls-remotevar versions = ;tabtabon'install'if versionslength return donenull versions;// Ask nvm the list of remote, and return each as a completion itemexec'nvm ls-remote'if err return doneerr;versions = versionsconcatstdoutsplit/\n/;return donenull versions;;;
On global installation of
nvm-complete, the user will be asked for
installation instruction (output to stdout, write to shell config, or a system
dir). The completion should be active on reload or next login (close / reopen
On completion trigger (hitting tab), any STDOUT output is used as a completion results, and STDERR is completely silenced.
To be able to log and debug completion scripts and functions, you can use
TABTAB_DEBUG environment variable. When defined, tabtab will redirect any
debug output to the file specified.
Trigger a completion, and
tail -f /tmp/tabtab.log to see debugging output.
to be able to use the logger in your own completion, you can
require('tabtab/lib/debug'). it is a thin wrapper on top of the debug module,
and has the same api and behavior, except when
const debug = require'tabtab/lib/debug''tabtab:name';
tabtab(1) - manage and discover completion on the user system.
it provides utilities for installing a completion file, to discover and enable additional completion etc.
$ tabtab <command> [options] options: -h, --help show this help output -v, --version show package version commands: install install and enable completion file on user system
$ tabtab install --help options: --stdout outputs script to console and writes nothing --name program name to complete --completer program that drives the completion (default: --name)
triggers the installation process and asks user for install location.
if not defined, is determined from
package.json name property.
can be used to delegate the completion to another program. ex.
$ tabtab install --name bower --completer bower-complete
tabtab install is not meant to be run directly, but rather used with your
npm does pretty amazing stuff with its completion feature. bash and zsh provides command tab-completion, which allow you to complete the names of commands in your $path. usually these functions means bash scripting, and in the case of npm, it is partially true.
there is a special
npm completion command you may want to look around,
if not already.
running this should dump this
to the console. this script works with both bash/zsh and map the correct
completion functions to the npm executable. these functions takes care
of parsing the
comp_* variables available when hitting tab to complete
a command, set them up as environment variables and run the
npm completion command followed by
-- words where words match value of
the command being completed.
this whole package/module is based entirely on npm's code and @isaacs work.