Completion Commands

Command	Description
none	No completion, but specifies that an argument is required
integer	Complete an integer
float	Complete a floating point number
combine	Combine multiple completion commands
file	Complete a file
directory	Complete a directory
choices	Complete from a set of values
value_list	Complete a list
exec	Complete by the output of a command or function
exec_fast	Complete by the output of a command or function (fast and unsafe)
exec_internal	Complete by a function that uses the shell’s internal completion mechanisms
range	Complete a range of integers
signal	Complete a signal
hostname	Complete a hostname
process	Complete a process
pid	Complete a PID
command	Complete a command
user	Complete a user
group	Complete a group
service	Complete a SystemD service
variable	Complete a shell variable
environment	Complete an environment variable

none

Disables autocompletion for this option but still marks it as requiring an argument.

Without specifying complete, the option would not take an argument.

prog: "example"
options:
  - option_strings: ["--none"]
    complete: ["none"]

integer

Complete an integer.

NOTE: This completion currently serves as documentation and does not provide actual functionality.

If you want to complete a range of integers, see range.

prog: "example"
options:
  - option_strings: ["--integer"]
    complete: ["integer"]

float

Complete a floating point number.

NOTE: This completion currently serves as documentation and does not provide actual functionality.

prog: "example"
options:
  - option_strings: ["--float"]
    complete: ["float"]

combine

Combine two or more completion commands.

prog: "example"
options:
  - option_strings: ["--combine"]
    complete: ["combine", [["user"], ["pid"]]]

file

Complete a file.

You can restrict completion to a specific directory by adding {"directory": ...}.

prog: "example"
options:
  - option_strings: ["--file"]
    complete: ["file"]
  - option_strings: ["--file-tmp"]
    complete: ["file", {"directory": "/tmp"}]

Example:

$ example --file=<TAB>
dir1/  dir2/  file1  file2

directory

Complete a directory.

You can restrict completion to a specific directory by adding {"directory": ...}.

prog: "example"
options:
  - option_strings: ["--directory"]
    complete: ["directory"]
  - option_strings: ["--directory-tmp"]
    complete: ["directory", {"directory": "/tmp"}]

Example:

$ example --directory=<TAB>
dir1/  dir2/

choices

Complete a list of items.

Items can be a list or a dictionary.

If a dictionary is supplied, the keys are used as items and the values are used as description.

prog: "example"
options:
  - option_strings: ["--choices-1"]
    complete: ["choices", ["Item 1", "Item 2"]]
  - option_strings: ["--choices-2"]
    complete: ["choices", {"Item 1": "Description 1", "Item 2": "Description 2"}]

Example:

$ example --choices-2=<TAB>
Item 1  (Description 1)  Item 2  (Description 2)

value_list

Complete one or more items from a list of items. Similar to mount -o.

Arguments with assignable values (mount -o uid=1000) aren’t supported.

Arguments are supplied by adding {"values": ...}.

A separator can be supplied by adding {"separator": ...} (the default is “,”).

prog: "example"
options:
  - option_strings: ["--value-list-1"]
    complete: ["value_list", {"values": ["exec", "noexec"]}]
  - option_strings: ["--value-list-2"]
    complete: ["value_list", {"values": {"one": "Description 1", "two": "Description 2"}}]

Example:

$ example --value-list-1=<TAB>
exec    noexec
$ example --value-list-1=exec,<TAB>
exec    noexec
$ example --value-list-2=<TAB>
one  -- Description 1
two  -- Description 2

exec

Execute a command and parse the output.

The output must be in form of:

<item_1>\t<description_1>\n
<item_2>\t<description_2>\n
[...]

An item and its description are delimited by a tabulator.

These pairs are delimited by a newline.

prog: "example"
options:
  - option_strings: ["--exec"]
    complete: ["exec", "printf '%s\\t%s\\n' 'Item 1' 'Description 1' 'Item 2' 'Description 2'"]

Example:

$ example --exec=<TAB>
Item 1  (Description 1)  Item 2  (Description 2)

exec_fast

Faster version of exec for handling large amounts of data.

This implementation requires that the items of the parsed output do not include special shell characters or whitespace.

prog: "example"
options:
  - option_strings: ["--exec-fast"]
    complete: ["exec_fast", "printf '%s\\t%s\\n' 1 one 2 two"]

exec_internal

Execute a function that internally modifies the completion state.

This is useful if a more advanced completion is needed.

prog: "example"
options:
  - option_strings: ["--exec-internal"]
    complete: ["exec_internal", "my_completion_func"]

Examples:

Bash:

my_completion_func() {
    COMPREPLY=( $(compgen -W "foo bar baz") )
}

Zsh:

my_completion_func() {
    local items=( foo bar baz )
    _describe '' items
}

Fish:

function my_completion_func
    printf '%s\n' foo bar baz
end

range

Complete a range of integers.

prog: "example"
options:
  - option_strings: ["--range-1"]
    complete: ["range", 1, 9]
  - option_strings: ["--range-2"]
    complete: ["range", 1, 9, 2]

Example:

$ example --range-1=<TAB>
1  2  3  4  5  6  7  8  9
$ example --range-2=<TAB>
1  3  5  7  9

signal

Complete signal names (INT, KILL, TERM, etc.).

prog: "example"
options:
  - option_strings: ["--signal"]
    complete: ["signal"]

Example:

$ example --signal=<TAB>
ABRT    -- Process abort signal
ALRM    -- Alarm clock
BUS     -- Access to an undefined portion of a memory object
[...]

hostname

Complete a hostname.

prog: "example"
options:
  - option_strings: ["--hostname"]
    complete: ["hostname"]

Example:

$ example --hostname=<TAB>
localhost

process

Complete a process name.

prog: "example"
options:
  - option_strings: ["--process"]
    complete: ["process"]

Example:

$ example --process=s<TAB>
scsi_eh_0   scsi_eh_1  sudo  systemd  [...]

pid

Complete a PID.

prog: "example"
options:
  - option_strings: ["--pid"]
    complete: ["pid"]

Example:

$ example --pid=<TAB>
1  13  166  19  [...]

command

Complete a command.

prog: "example"
options:
  - option_strings: ["--command"]
    complete: ["command"]

Example:

$ example --command=bas<TAB>
base32  base64  basename  basenc  bash  bashbug

user

Complete a username.

prog: "example"
options:
  - option_strings: ["--user"]
    complete: ["user"]

Example:

$ example --user=<TAB>
avahi  bin  braph  [...]

group

Complete a group.

prog: "example"
options:
  - option_strings: ["--group"]
    complete: ["group"]

Example:

$ example --group=<TAB>
adm  audio  avahi  [...]

service

Complete a SystemD service.

prog: "example"
options:
  - option_strings: ["--service"]
    complete: ["service"]

Example:

$ example --service=<TAB>
TODO

variable

Complete a shell variable name.

To complete an environment variable, use environment.

prog: "example"
options:
  - option_strings: ["--variable"]
    complete: ["variable"]

Example:

$ example --variable=HO<TAB>
HOME  HOSTNAME  HOSTTYPE

environment

Complete a shell environment variable name.

prog: "example"
options:
  - option_strings: ["--environment"]
    complete: ["environment"]

Example:

$ example --environment=X<TAB>
XDG_RUNTIME_DIR  XDG_SESSION_TYPE  [...]