oclif-plugin-completion

    0.6.0 • Public • Published

    oclif Plugin Version License

    oclif Plugin: completion

    oclif plugin for generating shell completions

    Completion Features

    Consider the following dummy CLI:

    Usage: dummy <COMMAND> [OPTION...]
    
    Commands:
    
      open   <ro|rw>      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:

    |- 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/<TAB> 042.dummy-with-id-042.json
    Directory Path completion dummy open --dir ./di<TAB> dir-one dir-two
    Dynamic Runtime completion dummy open --id <TAB> 109 110 111
    Dynamic Runtime completion dummy open -d ./dir-one --id <TAB> 042

    Feature Support Matrix

    👍 👎 🐛 ✔️
    Supported Unsupported Unknown Bug Implemented Partially Implemented Not Implemented
    oclif Feature Example Bash Zsh Fish
    👍 Positional argument ro 👍 ✔️
    👍 Basic Long --name john --age 42 --overwrite 👍 ✔️ 👍 ✔️ 👍 ✔️
    👍 Alternate Long --name=john --age=42 👍 ✔️ 👍 ✔️ 👍 ✔️
    👍 Basic Short -n john -a 42 -o 👍 ✔️ 👍 ✔️ 👍 ✔️
    👍 Alternative Short -njohn -a42 👍 👍 ✔️ 👍 ✔️
    👍 Stacking Short -ov 👍 ✔️ 👍 ✔️
    👍 Stacking Short with argument -ova 42 👍 ✔️ 👍 ✔️
    👍 Options / Enum --tag a 👍 ✔️ 👍 ✔️ 👍 ✔️
    👍 🐛 Multiple -t c --tag d 👍 👍 👍
    👎 File Path completion --file ... 👍 👍 👍
    👎 Directory Path completion --dir ... 👍 👍 👍
    👎 Dynamic Runtime completion --dir ./dummies --id 111 👍 👍 👍

    Supported Shells

    Bash

    Reference: Bash Completion

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

    Bash Usage

    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:

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

    vanilla (completions directory):

    Run the following command:

    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

    Zsh Usage

    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:

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

    vanilla (site-functions directory):

    Run the following command:

    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:

    echo $FPATH

    zinit:

    Run the following commands:

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

    Fish

    Reference: Fish Completion

    Fish Usage

    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:

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

    Commands

    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

    Install

    npm i oclif-plugin-completion

    DownloadsWeekly Downloads

    39,661

    Version

    0.6.0

    License

    MIT

    Unpacked Size

    264 kB

    Total Files

    32

    Last publish

    Collaborators

    • avatar