Skip to content


Folders and files

Last commit message
Last commit date

Latest commit



76 Commits

Repository files navigation


complete-shell - Modern Tab Completion Everywhere


# Install the complete-shell software:
git clone
source /path/to/complete-shell/.rc

# Turn on the cool modern features (off by default):
complete-shell config modern_settings true

# Try tab completion:
complete-shell <tab><tab>

# Search for existing complete-shell packages:
complete-shell search

# Install the packages you like:
complete-shell install this-cmd
complete-shell install another-cmd

this-cmd <TAB><TAB>  # Completion should work!

# Write your own compdef files. (See below)
# Add your compdef files:
complete-shell add ./src/foo.comp

# Learn the other complete-shell commands:
complete-shell -h     # Quick reference
complete-shell help   # Complete documentation



  • Only works on Bash so far

  • Only tested on Mac and Ubuntu Linux so far

Pull Requests welcome!


CompleteShell adds command completion for everything, everywhere. It provides a framework to define command completion in a simple, single file format.

CompleteShell works in:

  • Bash

  • zsh (coming soon)

  • Fish (coming soon)

People can easily write complete-shell files for commands that don't yet have completion and share them with the world. They can also write their own custom files, or fine tune existing ones to their liking.

CompleteShell also does Bash completion like you've never seen it. It can show you completion descriptions, show command usage, show hints to help you along, and turn on the more modern Bash completion options (like pressing TAB once instead of twice). These things are configurable by you.


Run these commands:

# clone the Git repo:
git clone

# `source` the `.rc` file in your shell startup configuration file:
source /path/to/complete-shell/.rc

That's it!

You should also really try turning on the cool modern settings:

complete-shell config modern_settings true


Bash 3.2+

Even if you don't use Bash as your shell, complete-shell needs it because it is written in Bash. Fortunately most computers have Bash 3.2+ installed.


Git is used for getting compdef repos to install and also is used for its (totally awesome) command line options parsing facility.

Completion Subsystem

CompleteShell attempts to fit into your Shell's existing Completion system.

For Bash, there is system that almost everyone uses. It can usually be found in /usr/share/bash-completion/ or /etc/bash_completion* (older systems and Mac). CompleteShell will check to make sure this subsystem is in place.

For Zsh and Fish, completion facilities are first class parts of the shell. CompleteShell will compile to code that fits right in.

The complete-shell CLI

complete-shell help

Display the complete-shell manpage. Same as man complete-shell.

The -h option will display a quick reference help guide.

complete-shell config [<key> [<value>]]

With no arguments, show all settings. With 1 argument, print the value for a key. With 2 arguments, set a key to a value.

Config values are stored in $COMPLETE_SHELL_BASE/config/<shell> (usually ~/.complete-shell/config/bash).

See "Configuration Options" below.

complete-shell search [<search string>]

Find registered completion packages that are available online.

complete-shell list

List all your installed completion packages.

complete-shell show <compdef-name>

Show information about a completion definition.

complete-shell install <package>

Installs compdef files from git repos online. You can find these repos using the search command or use other ones that you know about. compdef-target can be a simple name (found in search) or a git repo URL.

complete-shell add <compdef-filepath>

Adds a local compdef file path to your installed completions. It will be enabled by default.

complete-shell delete <compdef-name>

Delete a compdef file from your configuration.

complete-shell disable <compdef-name>

Disable a compdef (but don't delete it). Use this to turn off a specific command completion temporarily. Use the enable command to turn it back on.

complete-shell enable <compdef-name>

Enable a compdef. Usually only after you have disabled it.

complete-shell update <compdef-name>

Update specific compdef to their latest version.

complete-shell upgrade

Upgrade your complete-shell installation to the latest version.

complete-shell compile <compdef-name-or-path>

Compdef files are themselves valid shell files. (A common subset of Bash, Zsh and Fish!). They get compiled into leaner shell-specific files that are tuned for the tab completion facilities of the particular shell.

`complete-shell alias <compdef-name> <alias-name>

This command will create an alias completion for an existing alias of a command. command completion. Try making the alias cs for the command complete-shell:

alias cs=complete-shell
complete-shell alias complete-shell cs

Configuration Options

These options all default to false. To turn on an option:

complete-shell config <option> true

Disable CompleteShell tab completion altogether.


An umbrella option to always use the most modern CompleteShell settings. Effectively set these to true: single_tab, no_prompt, show_descriptions, show_usage, show_hints, use_fzf.


Only require a single TAB press to trigger completion. By default, Bash requires you to press TAB twice.


Disable prompt for more than 100 completions. When text is too big for the screen it will start a pager.


CompleteShell completions can have short descriptions. Set this option if you want to see them.


Some commands have a defined usage, which is helpful to have when writing the command. Turn this on to see them.


CompleteShell can give you hints about certain things when it thinks they'll be useful. Use this to enable them.


Recent Bash versions allow for completions to be sorted horizontally, which is usually better. We turn that on for you if available. Use this to keep the Bash default.


Use fzf selector (if installed) when appropriate. Avoids the terrible Bash completion pager for large result sets.

Environment Variables

CompleteShell has environment variables that you can use to customize various things. Usually you don't need to worry about these at all.


The location of the complete-shell software being used.

This variable is required and set automatically for you at shell startup.

If you use source /path/to/complete-shell/.rc to enable complete-shell, it is set to /path/to/complete-shell.


The directory where your completions are installed and your configuration lives.

Defaults to the last directory in COMPLETE_SHELL_PATH.


A colon separated path variable for finding installed completions.

Defaults to $HOME/.complete-shell


Your config file, managed by complete-shell config ....



Directory where installed completions go.

Defaults to $COMPLETE_SHELL_BASE/comp.


Directory where completion source repositories are installed (cloned) into.

Defaults to $COMPLETE_SHELL_BASE/src.


Directory where completions are compiled into (for Bash).

Defaults to $COMPLETE_SHELL_BASE/bash-completion/completions.


Your shell. ('bash', 'zsh', 'fish').

The compdef File

A complete-shell "command completion definition" ("compdef" for short) file is a minimal DSL that allows people to specify how command completion should work for a given command:

Here is a simple example. Define a file called foo.comp:

# Required header declaring the API version:
CompleteShell v0.2

# Command name:
N foo  0.0.1  ..The mighty foo CLI

# Command options:
O --aaa       ..The aaa option
O --bbb =file \
      ..The bbb option

# Sub-commands:
C bar +str            ..Do the bar
C baz +num +dir       ..Do the baz

Then run:

complete-shell add foo.comp

Now you have command completion for the foo command!

The complete-shell command itself comes with a compdef file that you can find in /path/to/complete-shell/share/complete-shell.comp.

compdef File Guidelines

  • compdef files are named <name>.comp

  • The name should be either:

    • The name of the CLI command for which it adds support

    • The name of a project that has multiple commands

  • Shell specific functions go in <name>.<shell>

    • Bash uses <name>.bash or <name>.sh

    • Zsh uses <name>.zsh or <name>.sh

    • Fish uses <name>.fish

    • A <name>.sh is POSIX shell code that works in Bash or Zsh

  • A compdef file can define completions for one or more commands

  • A compdef Git repo contains one or more compdef files

    • A set of compdef files is called a package

  • A compdef file uses the syntax described in the next section

The compdef Language

The compdef files are written in a simple DSL. The DSL has a set of simple commands that are usually a single capital letter. Blank lines and # comments are supported.

The DSL happens to a common subset of the Bash, Zsh and Fish shell languages, but compdef files should not contain any statements that are not documented by the DSL.

The DSL is versioned and can change over time. It is designed to be forward and backward compatible. ie People can use compdef files of any DSL version, and authors can not worry about their compdefs breaking with future complete-shell releases. Users will need to upgrade complete- shell to at least the version of the most modern compdef file's API version that they want to use.

The compdef v0.2 Syntax

A compdef files consists of comments, blank lines and single-line command statements.

Note: the single-line commands can actually span multiple lines by using \ continuation.

This is a list of the compdef statement commands:

CompleteShell v0.2

The first statement in every compdef file must be CompleteShell and must have a version argument as shown above. The version is used to invoke the appropriate compiler and runtime for that file.

N <name> [<version-number>] [..<description>]

The name of the statement for which completion is being defined. This is the second statement in the file. All other statements apply to this name until the end of file or another N command starts a new definition. Version numbers must be of the form #.#.#.

O <--option>

This defines an option that applies to the CLI command. O is also used to define options that are specific to a sub-command (when they follow the sub- command's C command).

A <+arg-type>...

This defines the arguments and their types. An arg type always starts with a + character. For example, +file-path called a function named file- path to list the completions that can happen for that argument. A can be used for a normal command, or for sub-commands.

C <subcommand name>

This defines a subcommand that applies to the CLI command.

V @<var-name> = <set of command words>

For the purposes of reusing common definitions, V lets you define variables. The variables always begin with a @.

Sharing compdef Files

Sharing compdef files is simple. Create a Git repo for your compdef files:

ReadMe          # Describe your repo
foo.comp        # compdef for the foo command          # Helper shell functions for `foo` completion
bars.comp       # compdef for the (several) bar commands

Then push it to a public Git host, like GitHub or BitBucket.

If you want it to be found in the complete-shell search command, then register it with complete-shell:

Copyright and License

Copyright 2019. Ingy döt Net <>.

CompleteShell is released under the MIT license.

See the file LICENSE for more details.


No description, website, or topics provided.







No packages published