oclif Plugin: completion

oclif plugin for generating shell completions

- oclif Plugin: completion
- Completion Features
- Supported Shells
- Commands

Completion Features

Consider the following dummy CLI:

``sh
Usage: dummy [OPTION...]

Commands:

open open a dummy (as read-only or read-write)
save save a dummy
search search a dummy

Options (open):

-i, --id dummy id
-f, --file path to dummy file
-d, --dir path to dummy directory (default: ./dummies)
-v, --verbose boolean flag

Options (save):

-n, --name dummy name
-a, --age dummy age
-t, --tag dummy tag, can be multiple (a/b/c/d)
-f, --file path to dummy file
-d, --dir path to dummy directory (default: ./dummies)
-o, --overwrite boolean flag
-v, --verbose boolean flag

Options (search):

-n, --name dummy name
-a, --age dummy age
-t, --tag dummy tag, can be multiple (a/b/c/d)
-v, --verbose boolean flag
`

Running on the current directory with tree:

`sh
|- dir-one/
| |- 042.dummy-with-id-042.json
|- dir-two/
|- dummies/
| |- 109.dummy-with-id-109.json
| |- 110.dummy-with-id-110.json
| |- 111.dummy-with-id-111.json
|- file-one.txt
|- file-two.txt
`

Features Description

File Path completion:

Completion will suggest the files on disk matching glob pattern.

Directory Path completion:

Completion will suggest the directories on disk matching glob pattern.

Dynamic Runtime completion:

Completion will generate the suggestion based on state of runtime environment and/or configuration.

Features Examples

| Feature | Input | Output |
| -------------------------- | ------------------------------------ | ---------------------------- |
| File Path completion | dummy open --file=./dir/one/ | 042.dummy-with-id-042.json |
| Directory Path completion | dummy open --dir ./di | dir-one dir-two |
| Dynamic Runtime completion | dummy open --id | 109 110 111 |
| Dynamic Runtime completion | dummy open -d ./dir-one --id | 042 |

Feature Support Matrix

| :+1: | :-1: | :grey_exclamation: | :bug: | :heavy_check_mark: | :heavy_minus_sign: | :x: |
| --------- | ----------- | ------------------ | ----- | ------------------ | --------------------- | --------------- |
| Supported | Unsupported | Unknown | Bug | Implemented | Partially Implemented | Not Implemented |

| oclif | Feature | Example | Bash | Zsh | Fish |
| ---------- | ---------------------------- | ---------------------------------- | ----------------------- | ----------------------- | ----------------------- |
| :+1: | Positional argument | ro | :grey_exclamation: :x: | :+1: :heavy_check_mark: | :grey_exclamation: :x: |
| :+1: | Basic Long | --name john --age 42 --overwrite | :+1: :heavy_check_mark: | :+1: :heavy_check_mark: | :+1: :heavy_check_mark: |
| :+1: | Alternate Long | --name=john --age=42 | :+1: :heavy_check_mark: | :+1: :heavy_check_mark: | :+1: :heavy_check_mark: |
| :+1: | Basic Short | -n john -a 42 -o | :+1: :heavy_check_mark: | :+1: :heavy_check_mark: | :+1: :heavy_check_mark: |
| :+1: | Alternative Short | -njohn -a42 | :+1: :x: | :+1: :heavy_check_mark: | :+1: :heavy_check_mark: |
| :+1: | Stacking Short | -ov | :grey_exclamation: :x: | :+1: :heavy_check_mark: | :+1: :heavy_check_mark: |
| :+1: | Stacking Short with argument | -ova 42 | :grey_exclamation: :x: | :+1: :heavy_check_mark: | :+1: :heavy_check_mark: |
| :+1: | Options / Enum | --tag a | :+1: :heavy_check_mark: | :+1: :heavy_check_mark: | :+1: :heavy_check_mark: |
| :+1: :bug: | Multiple | -t c --tag d | :+1: :heavy_minus_sign: | :+1: :heavy_minus_sign: | :+1: :heavy_minus_sign: |
| :-1: | File Path completion | --file ... | :+1: :heavy_minus_sign: | :+1: :x: | :+1: :heavy_minus_sign: |
| :-1: | Directory Path completion | --dir ... | :+1: :heavy_minus_sign: | :+1: :x: | :+1: :heavy_minus_sign: |
| :-1: | Dynamic Runtime completion | --dir ./dummies --id 111 | :+1: :x: | :+1: :x: | :+1: :x: |

Supported Shells

Bash

Reference: Bash Completion

You need to have bash-completion package installed on your system.

$3

You can enable completion for Bash using various methods. A few of them are mentioned below:

vanilla (.bashrc):

Add the following line in your .bashrc file:

`sh
eval "$(dummy completion:generate --shell bash);"
`

vanilla (completions directory):

Run the following command:

`sh
dummy completion:generate --shell bash | tee ~/.local/share/bash-completion/completions/dummy
`

Depending on you system, the completion script can also be put into one of these directories:

- ${XDG_DATA_HOME:-$HOME/.local/share}/bash-completion/completions (linux/macos)
- /usr/local/share/bash-completion/completions (macos)
- /usr/share/bash-completion/completions (linux)

Zsh

Reference: Zsh Completion System

$3

You can enable completion for Zsh using various methods. A few of them are mentioned below:

vanilla (.zshrc):

Add the following line in your .zshrc file:

`sh
eval "$(dummy completion:generate --shell zsh); compdef _dummy dummy;"
`

vanilla (site-functions directory):

Run the following command:

`sh
dummy completion:generate --shell zsh | tee "$(echo ${FPATH} | tr ':' '\n' | grep site-functions | head -n1)/_dummy"
`

The completion script can also be put into one of the directories present in $FPATH variable:

`sh
echo $FPATH
`

zinit:

Run the following commands:

`sh
dummy completion:generate --shell zsh > ~/.local/share/zsh/completions/_dummy
zinit creinstall ~/.local/share/zsh/completions
`

Fish

Reference: Fish Completion

$3

Reference: Where to put completions

You can enable completion for Fish using various methods. A few of them are mentioned below:

vanilla (completions directory):

Run the following command:

`sh
dummy completion:generate --shell fish | tee ~/.config/fish/completions/dummy.fish
`

Commands

- dummy completion
- dummy completion:generate
- dummy completion:generate:alias ALIAS

dummy completion

Generate shell completion script

`
USAGE
$ dummy completion

OPTIONS
-s, --shell=bash|fish|zsh (required) Name of shell

DESCRIPTION
Run this command to see instructions for your shell.

EXAMPLE
$ dummy completion --shell zsh
`

_See code: src/commands/completion/index.ts_

dummy completion:generate

Generates completion script

`
USAGE
$ dummy completion:generate

OPTIONS
-s, --shell=bash|fish|zsh (required) Name of shell

DESCRIPTION
Run the "completion" command to see instructions about how to use the script generated by this command.

EXAMPLE
$ dummy completion:generate --shell zsh
`

_See code: src/commands/completion/generate/index.ts_

dummy completion:generate:alias ALIAS

Generates completion script for alias

`
USAGE
$ dummy completion:generate:alias ALIAS

ARGUMENTS
ALIAS name of the alias

OPTIONS
-s, --shell=bash|fish (required) Name of shell

DESCRIPTION
This needs the completion script for the main command to be present.

Check the "completion:generate" command.
``

_See code: src/commands/completion/generate/alias.ts_