Completion Commands#

To simplify the user experience while using Simplicity Commander's command line interface (CLI), command completion (TAB completion) scripts can be generated using the completion generate command. The scripts can be used in your shell environment in order to provide completion for all available commands, sub commands and options. The scripts also provide automatic serial number completion for currently connected JLink devices when providing the --serialno option (or its short form, -s), as well as completions for device part numbers to the --device option (or its short form, -d).

Completion scripts can be generated for the following shells:

  • bash

  • zsh

  • fish

  • powershell

  • clink

Generating a completion script is fast, and thus running Simplicity Commander at the startup of the shell is a simple way to ensure that the TAB completions are available in the shell session. This will also ensure that with later releases of Simplicity Commander (assuming the previous application package is replaced by the newer version), any new commands, sub commands or options will be added to the TAB completion.

Use the completion script that matches your shell and environment:

  • For bash, source the script from your .bashrc file.

  • For zsh, source the script from your .zshrc file.

  • For fish, place the script in the completions directory in the fish configuration folder. On most systems, this directory is ~/.config/fish/completions.

  • For PowerShell, invoke the completion script from your PowerShell profile ($PROFILE).

  • For Clink, which provides TAB completion for Windows Command Prompt, place the generated Lua script in a completions directory under one of Clink's Lua script folders. Run clink info to locate these folders.

Generate Completion Script#

Simplicity Commander supports generating completion scripts using the completion generate command. You can provide an alternative alias for which the completions will trigger, using the --alias option. This is useful if you have an alias for your installation of Simplicity Commander already defined in your shell environment. Aliases must contain alphanumeric characters only (underscores are also allowed), and cannot start with a number. The default alias is 'commander'.

By default, this command will output the completion script directly to the console. If you instead want to save the output script to a file, you can provide the --outfile option.

If you have enabled CLI defaults (see Configure Commands), the defaults should be ignored when generating the completion script. Use the --ignore-defaults option to achieve this.

Command Line Syntax

$ commander completion generate <shell> [--alias <alias>] [--ignore-defaults] [--outfile <output file>]

Command Line Input Example

$ commander completion generate bash --alias cmder --outfile cmder-completion.sh

This command line generates a TAB completion script for bash, which will trigger for the 'cmder' keyword, and saves it to the file 'cmder-completion.sh'.

Command Line Output Example

Completion script saved at 'path/to/cmder-completion.sh'
DONE

Install Completion Script#

The following examples show how to install completion scripts for bash, zsh, fish, PowerShell, and Clink. These methods require the Simplicity Commander executable to be in your system PATH or otherwise accessible from your shell environment.

For bash, zsh, fish, and PowerShell, when you upgrade Simplicity Commander, replace the existing Commander application package with the new version. The completion scripts remain up to date, so you only need to install them once.

Clink loads its completion script from disk. Regenerate the Clink completion script after upgrading Simplicity Commander.

bash

Add the following line to your .bashrc configuration file:

source <(commander completion generate bash --ignore-defaults)

zsh

Add the following line to your .zshrc configuration file:

source <(commander completion generate zsh --ignore-defaults)

fish

Add the following line to your ~/.config/fish/config.fish configuration file:

commander completion generate fish --ignore-defaults > ~/.config/fish/completions/commander.fish

powershell

Add the following line to your PowerShell profile ($PROFILE):

commander completion generate powershell --ignore-defaults | Out-String | Invoke-Expression

clink

Run clink info to locate one of Clink's Lua script directories. If the directory does not already contain a completions directory, create one. Then generate the completion script and save it as commander.lua in the completions directory:

commander completion generate clink --ignore-defaults > commander.lua

For Clink versions older than v1.3.23, save the generated Lua file in the Clink profile directory instead.