# Complete built-in

The complete built-in generates completion candidates. This built-in can only be executed from completion functions during command line completion.

## Syntax

- `complete [-A pattern] [-R pattern] [-T] [-P prefix] [-S suffix] [-abcdfghjkuv] [[-O] [-D description] word…]`

## Description

The built-in generates completion candidates according to the specified arguments. No matter how candidates are generated, only candidates that match the word being completed are generated.

## Options

`-A pattern`
`--accept=pattern`

  Only accept candidates that match the pattern specified by this option. When more than one of this option is specified, only candidates that match all of the patterns are generated.

`-D description`
`--description=description`

  Give a description of the word candidates. The description is shown beside the candidates in the candidate list.

`-O`
`--option`

  The candidates are treated as command line options. A hyphen is prepended to each candidate that is treated as an option.

`-P prefix`
`--prefix=prefix`

  Ignore prefix of the word being completed when generating candidates. The specified prefix must be initial part of the word.

  If the word being completed is `file:///home/user/docume` for example, the command line `complete -P file:// -f` will generate pathname candidates that complete `/home/user/docume`.

`-R pattern`
`--reject=pattern`

  Reject candidates that match the pattern specified by this option. When more than one of this option is specified, only candidates that match none of the patterns are generated.

`-S suffix`
`--suffix=suffix`

  Append suffix to each generated candidate.

`-T`
`--no-termination`

  Do not append a space after the word is completed. Without this option, a space is appended to the completed word so that you do not have to enter a space before the next word.

### Options that select candidate types

`-a`
`--alias`

  Aliases. (same as `--normal-alias --global-alias`)

`--array-variable`

  Arrays.

`--bindkey`

  Line-editing commands the `bindkey` built-in accepts.

`-b`
`--builtin-command`

  Built-in commands. (same as `--special-builtin --mandatory-builtin --elective-builtin --extension-builtin --substitutive-builtin`)

`-c`
`--command`

  Commands. (same as `--builtin-command --external-command --function`)

`-d`
`--directory`

  Directories.

`--dirstack-index`

  Valid indices of the directory stack.

`--elective-builtin`

  Elective built-in commands.

`--executable-file`

  Executable regular files.

`--extension-builtin`

  Extension built-in commands.

`--external-command`

  External commands.

`-f`
`--file`

  Files (including directories).

`--finished-job`

  Job IDs of finished jobs.

`--function`

  Functions.

`--global-alias`

  Global aliases.

`-g`
`--group`

  User groups.

`-h`
`--hostname`

  Host names.

`-j`
`--job`

  Job IDs.

`-k`
`--keyword`

  Keywords.

`--mandatory-builtin`

  Mandatory built-in commands.

`--normal-alias`

  Normal aliases.

`--regular-builtin`

  Obsolete synonym for `--extension-builtin --substitutive-builtin`.

`--running-job`

  Job IDs of jobs that are being executed.

`--scalar-variable`

  Variables that are not arrays.

`--semi-special-builtin`

  Obsolete synonym for `--mandatory-builtin --elective-builtin`.

`--signal`

  Signals.

`--special-builtin`

  Special built-in commands.

`--stopped-job`

  Job IDs of jobs that are suspended.

`--substitutive-builtin`

  Substitutive built-in commands.

`-u`
`--username`

  Users' log-in names.

`-v`
`--variable`

  Variables.

If the `-d` (`--directory`) option is specified without the `-f` (`--file`) option, the `-S / -T` options are assumed.

Generated candidates for job IDs do not have leading percent signs (`%`). If the word being completed starts with a percent sign, the `-P %` option should be specified.

## Operands

Operands are treated as completion candidates.

## Exit status

The exit status of the built-in is zero if one or more candidates were generated, one if no candidates were generated, or larger than one if an error occurred.

## Notes

The complete built-in is an elective built-in. It can be used in completion functions even in the POSIXly-correct mode because the mode is temporarily disabled during completion.