.What is Clink? top

Clink combines the native Windows shell cmd.exe with the powerful command line editing features of the GNU Readline library, which provides rich completion, history, and line-editing capabilities. Readline is best known for its use in the Unix shell Bash, the standard shell for many Linux distributions.

.Feature Highlights up top

C:\dir>findstr_/s needle haystack\*

C:\repos\clink git main->origin *3 !1
> git merge --help_

.Usage top

.Installation up top

You can install Clink by running the setup EXE file from the releases page.

Or by using winget and running winget install clink.

Or by using scoop and running scoop install clink.

Or by downloading the ZIP file from releases page, and extracting the files to a directory of your choosing.

.Using Clink up top

Once installed, there are several ways to start Clink.

1. If Clink is configured for autorun, just start cmd.exe and Clink is automatically injected and ready to use.

The setup EXE has an option "Autorun when cmd.exe starts". If you didn't use the setup EXE, or if you want to enable or disable autorun later, you can run clink autorun install or clink autorun uninstall to change the autorun configuration. Run clink autorun --help for more info.

2. To manually start, run the Clink shortcut from the Start menu (or the clink.bat located in the install directory).
3. To establish Clink to an existing cmd.exe process, use clink inject.

If the Clink install directory isn't in the PATH, then use install_dir\clink in place of clink to run Clink commands. Once Clink is injected into a cmd.exe process, then it automatically sets an alias so that you can simply use clink.

Starting Clink injects it into a cmd.exe process, where it intercepts a handful of Windows API functions so that it can replace the prompt and input line editing with its own Readline-powered enhancements.

.Getting Started top

You can use Clink right away without configuring anything:

• Searchable command history will be saved between sessions.
• Suggestions are automatically offered as you type; press Right or End to insert a suggestion.
• Tab and Ctrl-Space provide match completion two different ways.
• Press Alt-H to see a list of the current key bindings.
• Press Alt-Shift-/ followed by another key to see what command is bound to the key.

There are three main ways of customizing Clink to your preferences: the Readline init file (the .inputrc file), the Clink settings (the clink set command), and Lua scripts.

.How Completion Works up top

"Completion" is for the word at the cursor; when you press Tab Clink tries to complete the word from a list of possible completions. Press Alt-= to see the list of possible completions.

"Suggestions" are for the whole command line; Clink offers an automatic suggestion for the whole input line, which you can insert by pressing Right or End. There is never more than one automatic suggestion at a time.

Some examples of what completions can offer:

• File names,
• Directories,
• Environment variables,
• Commands,
• Command arguments and flags,
• You can provide custom completion generators using Lua scripts that execute inside Clink (see Extending Clink With Lua and Popular Scripts).

.Completion Keys up top

Tab completes the word at the cursor:

• If you installed Clink with "Use enhanced defaults" or if you set clink.default_bindings to use "windows" defaults, then Tab cycles through the possible completions, replacing the word with the next possible completion each time.
• Otherwise, Tab performs completion the same way that bash does on Unix and Linux: When you press Tab, Clink finds matches for how to complete the word at the cursor. It automatically inserts the longest common prefix shared by the possible completions. If you press Tab again, it also lists the possible completions.

Ctrl-Space shows an interactive list of possible completions:

• You can use the arrow keys to choose which completion to insert, and you can type to filter the list.
• Pressing Enter in the list inserts the selected completion.
• Pressing Space in the list inserts the selected completion and makes sure a space follows it to allow typing a next argument.

See Completion Commands and Clink Commands for more available completion commands.

.Executable Completion up top

By default, Clink completes the first word of each command based on all executable programs on the system PATH and the current directory, but not non-executable files.

You can turn off the "executable completion" behavior by running clink set exec.enable false, or you can adjust its behavior by changing the various exec.* settings.

.Common Configuration up top

The following sections describe some ways to begin customizing Clink to your taste.

.Enhanced default settings up top

Clink can be installed with plain defaults, or it can be installed with enhanced default settings that enable more of Clink's enhancements by default.

If you install Clink with the setup program and "Use enhanced default settings" is checked, then the enhanced defaults are activated, and then in some places where this documentation refers to default settings the stated default may have been overridden.

If you install Clink from the .zip file then enhanced default settings are activated when the default_settings and default_inputrc files are present in the binaries directory or in the profile directory. The .zip file comes with the files, but their names have a _ prefix so that enhanced defaults won't automatically take effect. You can activate the enhanced default settings by renaming the files to remove the _ prefix.

Here are some of the enhanced defaults. Review the default_settings and default_inputrc files for the full list.

• Many color settings have colorful defaults.
• Uses Windows key bindings by default.
• The command history's default limit is increased to 25,000 entries.
• Completion expands environment variables (the match.expand_envvars setting).
• If no completions are found with a prefix search, then a substring search is used (the match.substring setting).
• Ctrl-D does not exit CMD (the cmd.ctrld_exits setting).
• History saves and shows time stamps.

.Create a .inputrc file up top

First you'll want to create a .inputrc file, and a good place is in your Windows user profile directory.

This file is used for some configuration, such as key bindings and colored completions.

Create the file by running this command at a CMD prompt:

notepad %userprofile%\.inputrc

You may want to copy/paste the following sample text into the file as a starting point, and then press Ctrl-S to save the file.

# Some common Readline config settings.

set colored-stats                 on   # Turn on completion colors.
set colored-completion-prefix     on   # Color the typed completion prefix.

# Some config settings that only work in Clink.

$if clink
set search-ignore-case            on   # Case insensitive history searches.
set completion-auto-query-items   on   # Prompt before showing completions if they'll exceed half the screen.
$endif

# Add your keybindings here...

See Init File for more information on Readline init files.

.Bash vs Windows up top

The default Clink key bindings are the same as in the "bash" shell for Unix/Linux. That makes some keys like Ctrl-A, Ctrl-F, and Ctrl-M behave differently than you might be used to in CMD.

To instead use the familiar Windows default key bindings you can run clink set clink.default_bindings windows.

Or, if you use the setup program with "Use enhanced default settings" checked then "windows" key bindings are the default, and you can run clink set clink.default_bindings bash to use the bash default key bindings.

Clink comes with many default key bindings. Use Alt-H to see all of the active key bindings, or use Alt-Shift-? to check what is bound to a specific key. See Key Bindings to get started configuring your own key bindings.

Here are the differences between the Windows defaults and the bash defaults:

.Auto-suggest up top

Clink can suggest command lines as you type, based on command history and completions.

You can turn off automatic suggestions with clink set autosuggest.enable false, or turn them on with clink set autosuggest.enable true.

When automatic suggestions are enabled and the cursor is at the end of the input line, a suggestion may appear in a muted color. If the suggestion isn't what you want, just ignore it. Or you can insert the whole suggestion with the Right arrow or End key, insert the next word of the suggestion with Ctrl-Right, or insert the next full word of the suggestion up to a space with Shift-Right.

Here's an example of how auto-suggestion works. Suppose you ran a command, so now it's in your command history:

C:\dir>findstr  /s needle haystack\*

Later, you start to type a new command, and it matches the earlier command from the history:

C:\dir>findstr _/s needle haystack\*

The muted text shows a suggestion that might be what you intend to type. You can insert the muted text into the input line by pressing the Right key.

If you press Tab then that invokes completion instead. Completion is something you manually invoke to offer possible completions for a word or argument position. Auto-suggestion automatically offers a suggestion for a whole input line, and the suggestion can come from the saved command history or from the list of possible completions. There can be many possible completions available, but there is never more than one auto-suggestion available.

The autosuggest.hint setting controls whether to show the [Right]=Insert Suggestion usage hint when a suggestion is available.

The autosuggest.strategy setting determines how suggestions are chosen.

.Colors up top

Clink has many configurable colors for match completions, input line coloring, popup lists, and more.

If you use the setup program with "Use enhanced default settings" checked then many of the color settings have more colorful default values.

See below for information on customizing colors yourself, or see Color Themes for information on applying color theme files (whose names end with ".clinktheme"). Clink comes with a few color theme files, and users can also share color themes online (or convert color themes from other shells).

.For completion up top

When performing completion (e.g. Tab or Ctrl-Space) Clink can add color to the possible completions.

To turn on colored completions, put a line set colored-stats on in the .inputrc file (if you copy/pasted the sample text, it's already there).

See the Completion Colors section for how to configure the colors for match completions.

.Other colors up top

Clink adds color to the input line by highlighting arguments, flags, doskey macros, and more. If you don't want input line colors, you can turn it off by running clink set clink.colorize_input false.

Here are examples, using the colors from the Use enhanced defaults installation option:

c:\dir>clink set --help
'clink' has an argmatcher
c:\dir>attrib
'attrib' is a CMD command
c:\dir>myalias
if 'myalias' is a doskey alias
c:\dir>control
'control' is an executable
c:\dir>xyzabc123
unrecognized
c:\dir>whatever
if executable and unrecognized colors are not set

To configure a color, run clink set colorname colorvalue. Match completions make it easy to change Clink settings: type clink set color. and then use completion (e.g. Tab or Ctrl-Space) to see the available color settings, and to fill in a color value.

See the Coloring the Input Text and Color Settings sections for more information on Clink color settings.

.Key Bindings up top

You can customize your key bindings (keyboard shortcuts) by assigning key bindings in the .inputrc file. See Customizing Key Bindings for more information.

Clink comes with many pre-configured key bindings that invoke named commands. Here are a few that you might find especially handy:

For a full list of commands available for key bindings, see Bindable Commands.

.Mouse Input up top

Clink can optionally respond to mouse input, instead of letting the terminal respond to mouse input (e.g. to select text on the screen). When mouse input is enabled in Clink, you can click in the input line or in popup lists, and the mouse wheel scrolls popup lists.

Use clink set terminal.mouse_input mode with one of the following modes to control whether Clink responds to mouse input:

Use clink set terminal.mouse_modifier modifiers or set CLINK_MOUSE_MODIFIER=modifiers to control which modifier keys must be held for Clink to respond to mouse input.

These select which modifier keys (Alt, Ctrl, Shift) must be held in order for Clink to respond to mouse input when mouse input is enabled by the terminal.mouse_input setting. modifiers is a text string that can list one or more modifier keys: "alt", "ctrl", and "shift". For example, setting it to "alt shift" causes Clink to only respond to mouse input when both Alt and Shift are held (and not Ctrl). If the %CLINK_MOUSE_MODIFIER% environment variable is set then its value supersedes the terminal.mouse_modifier setting. In Windows Terminal many modifier keys do special things with mouse clicks, so the modifier key combination that interferes least with built in Windows Terminal behaviors is Ctrl-Alt.

When mouse input is enabled in Clink, then mouse input works a little differently:

• You can bypass Clink mouse input and use the normal terminal mouse input by holding a different combination of modifier keys than listed in terminal.mouse_modifier or %CLINK_MOUSE_MODIFIER%.
• Windows Terminal treats Shift-RightClick specially and turns off line ending detection when copying the selected text to the clipboard. Hold Ctrl or Alt when right clicking to do the normal copy with line ending detection.
• In ConEmu, the mouse wheel always scrolls the terminal; Clink cannot use it to scroll popup lists.
• In the default Conhost terminal when Quick Edit mode is turned off then Clink will also respond to mouse input when no modifier keys are held.

.Startup Message up top

By default, Clink prints a startup message containing a copyright notice and the program version. This is shown so it's easy to tell whether Clink is active and what version is being used.

You can make the startup message shorter by running clink set clink.logo short.

You can remove the startup message by running clink set clink.logo none.

.Startup Cmd Script up top

When Clink is injected, it looks for a clink_start.cmd script in the binaries directory and profile directory. Clink automatically runs the script(s), if present, when the first CMD prompt is shown after Clink is injected and before any Lua scripts run. You can set the clink.autostart setting to run a different command, or set it to "nul" to run no command at all.

.Custom Prompt up top

If you want a customizable prompt with a bunch of styles and an easy-to-use configuration wizard, check out clink-flex-prompt. Also, if you've been disappointed by git making the prompt slow in other shells, try this prompt -- it makes the prompt appear instantly by running git commands in the background and refreshing the prompt once the background commands complete.

Other popular configurable prompts are oh-my-posh and starship.

See Customizing the Prompt for information on how to use Lua to customize the prompt.

.Upgrading from Clink v0.4.9 up top

The new Clink tries to be as backward compatible with Clink v0.4.9 as possible. However, in some cases upgrading may require a little bit of configuration work.

• Some key binding sequences have changed; see Customizing Key Bindings for more information.
• Match coloring works differently now and can do much more; see Completion Colors for more information.
• Old settings and history migrate automatically if you use the same profile directory when upgrading. If you use a different profile directory, then you can still migrate the old settings and history by copying certain files. See below for details.
• Script compatibility should be very good, but some scripts may still encounter problems. If you do encounter a compatibility problem you can look for an updated version of the script, update the script yourself, or visit the clink repo and open an issue describing details about the compatibility problem.
• Some match generator scripts might need adjustments to become fully compatible with the autosuggest.enable setting.
• Some settings have changed slightly, and there are many new settings. See Configuring Clink for more information.

.Migrating between different profile directories up top

All versions of Clink use the same default profile directory location. If you haven't overridden the profile directory, then your settings and history will automatically migrate when upgrading to newer versions of Clink.

If you choose to use a different profile directory, then you can still make migration happen by copying certain files:

1. When using Clink v0.4.9 you can use clink set to find the settings file path.
2. When using newer versions of Clink you can use clink info to find the profile directory.
3. Copy the settings and .history files from the old directory into the new directory.
4. If you already have a clink_settings or clink_history file in your new profile directory, then you'll need to rename them in order for migration to happen (e.g. add .txt to the names).
5. Close the Clink session(s) and open new ones.

.Configuring Clink top

Clink has two configuration systems, which is a result of using the Readline library to provide command history and key bindings.

The following sections describe how to configure Clink itself. To learn about the Readline configuration and key bindings, instead see Configuring Readline.

.Clink Settings up top

The easiest way to configure Clink is to use the clink set command to list, query, and set Clink's settings.

Run clink set --help from a Clink-installed cmd.exe process to learn more.

The following table describes the available Clink settings:

Note:

Some settings have alternative default values when Clink is installed with "Use enhanced default settings" checked in the setup program. This enables more of Clink's enhancements by default.

Compatibility Notes:

• The esc_clears_line setting has been replaced by a clink-reset-line command that is by default bound to the Escape key. See Customizing Key Bindings for more information.
• The match_colour setting has been removed, and Clink now supports Readline's completion coloring. See Completion Colors for more information.

.Color Settings up top

This section describes how to set a color.

For information on what color settings are available and how they're used, see the Coloring the Input Text section and the color.* settings.

.Friendly Color Names up top

The Clink color settings are the ones whose names begin with color.. Color settings use the following syntax:

[attributes] [foreground_color] [on [background_color]]

Optional attributes (can be abbreviated to 3 letters):

• bold or nobold adds or removes boldface (usually represented by forcing the color to use high intensity if it doesn't already; some terminal programs may also/instead use a bolder font weight).
• underline adds an underline (some terminal programs cannot display underlines).
• italic adds italics (some terminal programs cannot display italics). This keyword requires Clink v1.7.0 or newer; in older versions you can use the sgr keyword with the corresponding escape code sequence such as sgr 3.
• reverse swaps the foreground and background colors. This keyword requires Clink v1.7.0 or newer; in older versions you can use the sgr keyword with the corresponding escape code sequence such as sgr 7.

Optional colors for foreground_color and background_color (can be abbreviated to 3 letters):

• default or normal uses the default color as defined by the current color theme in the console window.
• black, red, green, yellow, blue, cyan, magenta, white are the basic colors names.
• bright can be combined with any of the other color names to make them bright (high intensity).
• #XXXXXX specifies a color using 24-bit RGB hex format; the first two digits are the red value, the next two digits are the green value, and the last two digits are the blue value (some terminal programs cannot display 24-bit colors, and will try to instead use the closest supported color). Requires Clink v1.7.0 or newer; in older versions you can use the sgr keyword with the corresponding escape code sequence such as sgr 38;2;255;80;160.
• #XXX specifies a color using a short RGB hex format; each digit is doubled so #3fc means #33ffcc. Requires Clink v1.7.0 or newer; in older versions you can use the sgr keyword with the corresponding escape code sequence such as sgr 38;2;255;80;160.

Examples (specific results may depend on the console host program):

• bri yel for bright yellow foreground on default background color.
• bold for bright default foreground on default background color.
• underline bright black on white for dark gray (bright black) foreground with underline on light gray (white) background.
• default on blue for default foreground color on blue background.
• bold underline green on #222 for bright green with underline on a dark gray background.

.Alternative SGR Syntax up top

It's also possible to set any ANSI SGR escape code using sgr SGR_parameters (for example sgr 7 is the code for reverse video, which swaps the foreground and background colors).

Be careful, since some escape code sequences might behave strangely.

.Color Themes up top

Clink has many color settings which can be set with clink set color.setting_name color_value.

Predefined color setting values can be grouped into a .clinktheme file to make it easy to save, apply, and share different color themes for Clink. These color theme files require Clink v1.7.0 or newer.

Clink looks for color theme files in these directories:

1. Any directories listed in the %CLINK_THEMES_DIR% environment variable (multiple directories may be separated by semicolons).
2. A themes\ subdirectory under each scripts directory listed by clink info (see Location of Lua Scripts).
3. A themes\ subdirectory under the Clink program directory and the Clink profile directory.
4. Or you can provide a full path name to a file, such as c:\mythemes\Colorful.clinktheme.

To apply a color theme, run clink config theme use theme_name which will apply the named theme and use it to replace color settings in the current Clink profile. Or set the CLINK_COLORTHEME environment variable to the name or full path and filename of a .clinktheme file. The environment variable causes the named theme to override color settings from the profile's settings file, which allows multiple concurrent Clink sessions to use different color themes.

Note: The clink config theme use command first saves the current color theme as "Previous Theme" to help avoid accidentally losing color settings.

To list available color themes, run clink config theme list. Clink includes a few theme files, and you can find more shared online by Clink users. One place to find more color themes for Clink is the clink-themes repo.

To show a demo of a what a color theme will look like, run clink config theme show theme_name.

To save the current profile's color settings into a .clinktheme file, run clink config theme save theme_name. The color settings are saved into a file named themes\theme_name.clinktheme under the current Clink profile directory.

See Coloring the Input Text for information on specific color settings.

Note: The .clinktheme files are Clink color themes for Clink-specific color settings. They are not terminal color themes and don't affect other programs or the terminal in general. Consult your terminal program's documentation for how to set terminal color themes for it.

.Custom Prompts up top

You can choose a custom prompt to use, or you can make your own prompt.

A custom prompt can be packaged into a .clinkprompt file to make it easy to choose which prompt to use, and easy to share custom prompts with other users.

Clink looks for custom prompt files in these directories:

1. Any directories listed in the %CLINK_THEMES_DIR% environment variable (multiple directories may be separated by semicolons).
2. A themes\ subdirectory under each scripts directory listed by clink info (see Location of Lua Scripts).
3. Or you can provide a full path name to a file, such as c:\mythemes\Fancy Prompt.clinkprompt.

To activate a custom prompt, run clink config prompt use prompt_name which will load and use the named prompt, as well as update the settings accordingly in the current Clink profile. Or set the CLINK_CUSTOMPROMPT environment variable to the name or full path and filename of a .clinkprompt file. The environment variable causes the named prompt to override the profile's settings file, and allows multiple concurrent Clink sessions to use different custom prompts.

To list available custom prompts, run clink config prompt list. Clink includes a few custom prompt files, and you can find more shared online by Clink users. Some places you can find more custom prompts for Clink are clink-flex-prompt, clink-themes, and oh-my-posh. Check here for quick info on using oh-my-posh prompt themes with Clink.

To show a demo of what a custom prompt will look like, run clink config prompt show prompt_name.

See Customizing the Prompt for information on writing your own custom prompts, and see Sharing Custom Prompts for information on optionally packaging them as "*.clinkprompt" files.

.Compatibility Between .clinkprompt Versus .lua Files up top

When you activate a .clinkprompt file via clink config prompt use you might see a garbled prompt, or still see your old prompt.

That can happen because activating a .clinkprompt file deactivates other .clinkprompt files, but it doesn't deactivate prompt filters registered from .lua files (it could break other things if it did).

So, if you have a custom prompt in a .lua file then you may need to update the .lua file to disable itself while a .clinkprompt file is active.

For most .lua custom prompts, you can simply rename its file to change the file extension from ".lua" to ".clinkprompt", and then it won't interfere with other .clinkprompt files.

Or, you can modify any prompt filter to automatically disable itself like this:

local your_prompt_filter = clink.promptfilter()

function your_prompt_filter:filter()
    -- Insert the following if..end line at the beginning of any .lua prompt filter to automatically
    -- disable it while a .clinkprompt file is active (but don't insert it in a .clinkprompt file).
    if clink.getclinkprompt and clink.getclinkprompt() then return end

    -- The rest of your prompt filter goes here...
end

.File Locations up top

Settings and history are persisted to disk from session to session. By default Clink uses the current user's non-roaming application data directory. This user directory is usually found in one of the following locations;

• Windows XP: c:\Documents and Settings\username\Local Settings\Application Data\clink
• Windows Vista onwards: c:\Users\username\AppData\Local\clink

All of the above locations can be overridden using the --profile path command line option which is specified when injecting Clink into cmd.exe using clink inject. Or with the %CLINK_PROFILE% environment variable if it is already present when Clink is injected (this envvar takes precedence over any other mechanism of specifying a profile directory, if more than one was used).

You can use clink info to find the directories and configuration files for the current Clink session.

Also see Location of Lua Scripts for details on where Clink looks for Lua scripts, and Themes Directories for details on where Clink looks for color theme files (*.clinktheme) and custom prompt files (*.clinkprompt).

Notes:

• Clink performs tilde expansion on the %CLINK_PROFILE% environment variable value. If the path begins with ~\ then it is replaced with the current user's home directory (%HOME% or %HOMEDRIVE%%HOMEPATH% or %USERPROFILE%).
• The --profile flag has a quirk for backward compatibility with older versions of Clink: ~\ in --profile is expanded to %LOCALAPPDATA% instead.

.Overriding the profile directory when installed for Autorun up top

If you've installed Clink using the setup program with the "Autorun when cmd.exe starts" box checked, then the profile directory has been explicitly set to %LOCALAPPDATA%\clink. That will take precedence over any other stored configuration.

You can override it via set CLINK_PROFILE=path after starting cmd.exe.

Or you can use clink autorun install -- --profile path to change which profile directory is specified (see clink autorun --help and clink autorun show).

Or if you want to use Autorun but also override the profile directory any of the usual ways, then run clink autorun uninstall and then clink autorun install. That will remove the explicit profile directory specification that was applied by the setup program.

.Files up top

.Command Line Options up top

Note: If the --profile path begins with ~\ then it is replaced with the current user's home directory (%HOME% or %HOMEDRIVE%%HOMEPATH% or %USERPROFILE%).

.Automatic Updates up top

By default, Clink periodically and automatically checks for new versions. When an update is available, Clink prints a message on startup. To apply an update, run clink update when convenient to do so.

The default interval between checks is 5 days, which means after Clink checks for an update it waits at least 5 days before checking again. You can control the frequency of update checks with clink set clink.update_interval days, where days is the minimum number of days between checking for updates.

You can control what happens when an update is available by using clink set clink.autoupdate mode, where mode is one of these:

Notes:

• The auto-updater settings are stored in the profile, so different profiles can be configured differently for automatic updates.
• The updater does nothing if the Clink program files are readonly.
• The updater requires PowerShell, which is present by default in Windows 7 and higher.
• Clink v1.5.5 added check, prompt, and auto. Before that, only false and true were available (and true behaved the same as check).

.Portable Configuration up top

Sometimes it's useful to run Clink from a flash drive or from a network share, especially if you want to use Clink on someone else's computer.

Here's how you can set up a portable configuration for Clink:

1. Put your Lua scripts and other tools in the same directory as the Clink executable files. For example fzf.exe, z.cmd, oh-my-posh.exe, starship.exe etc can all go in the same directory on a flash drive or network share.
2. Make a batch file such as portable.bat that injects Clink using a specific profile directory.
   • On a flash drive, you can have a portable profile in a subdirectory under the Clink directory.
   • On a network share, you'll want to copy some initial settings into a local profile directory (a profile directory on a network share will be slow).
3. In any cmd.exe window on any computer, you can then run the portable.bat script to inject Clink and have all your favorite settings and key bindings work.

Here are some sample scripts:

.portable.bat (on a flash drive) up top

This sample script assumes the portable.bat script is in the Clink directory, and it uses a clink_portable profile directory under the Clink directory.

@echo off
rem -- Do any other desired configuration here, such as loading a doskey macro file.
call "%~dp0clink.bat" inject --profile "%~dp0clink_portable" %1 %2 %3 %4 %5 %6 %7 %8 %9

.portable.bat (on a network share) up top

This sample script assumes the portable.bat script is in the Clink directory, and that there is a file portable_clink_settings with the settings you want to copy to the local profile directory.

@echo off
if not exist "%TEMP%\clink_portable" md "%TEMP%\clink_portable" >nul
if not exist "%TEMP%\clink_portable\clink_settings" copy "%~dp0portable_clink_settings" "%TEMP%\clink_portable\clink_settings" >nul
rem -- Do any other desired configuration here, such as loading a doskey macro file.
call "%~dp0clink.bat" inject --profile "%TEMP%\clink_portable" %1 %2 %3 %4 %5 %6 %7 %8 %9

.Configuring Readline top

Clink uses the GNU Readline library to provide line editing functionality, which can be configured to add custom keybindings and macros by creating a Readline init file. The Clink documentation includes an updated and tailored copy of the Readline documentation, below.

.The Basics up top

.Bare Essentials up top

To enter characters into the line, simply type them. The typed character appears where the cursor was, and then the cursor moves one space to the right. If you mistype a character, you can use Backspace to back up and delete the mistyped character.

Sometimes you may mistype a character, and not notice the error until you have typed several other characters. In that case, you can type Left (the left arrow key) to move the cursor to the left, and then correct your mistake. Afterwards, you can move the cursor to the right with Right (the right arrow key).

When you add text in the middle of a line, you will notice that characters to the right of the cursor are "pushed over" to make room for the text that you have inserted. Likewise, when you delete text behind the cursor, characters to the right of the cursor are "pulled back" to fill in the blank space created by the removal of the text. A list of the bare essentials for editing the text of an input line follows.

.Killing and Yanking up top

Killing text means to delete the text from the line, but to save it away for later use, usually by yanking (re-inserting) it back into the line. ("Cut" and "paste" are more recent jargon for "kill" and "yank", but killing and yanking do not affect the system's clipboard.)

If the description for a command says that it "kills" text, then you can be sure that you can get the text back in a different (or the same) place later.

When you use a kill command, the text is saved in a kill-ring. Any number of consecutive kills save all of the killed text together, so that when you yank it back, you get it all. The kill ring is not line specific; the text that you killed on a previously typed line is available to be yanked back later, when you are typing another line.

Here are some basic commands for killing text.

Here is how to yank the text back into the line. Yanking means to copy the most-recently-killed text from the kill buffer.

.Readline Arguments up top

You can pass numeric arguments to Readline commands. Sometimes the argument acts as a repeat count, other times it is the sign of the argument that is significant. If you pass a negative argument to a command which normally acts in a forward direction, that command will act in a backward direction. For example, to kill text back to the start of the line, you might type Alt-- Ctrl-k.

The general way to pass numeric arguments to a command is to type meta digits before the command. If the first "digit" typed is a minus sign (-), then the sign of the argument will be negative. Once you have typed one meta digit to get the argument started, you can type the remainder of the digits, and then the command. For example, to give the Del command an argument of 10, you could type Alt-1 0 Del, which will delete the next ten characters on the input line.

.Searching for Commands in the History up top

Readline provides commands for searching through the command history for lines containing a specified string. There are two search modes: incremental and non-incremental.

Incremental searches begin before the user has finished typing the search string. As each character of the search string is typed, Readline displays the next entry from the history matching the string typed so far. An incremental search requires only as many characters as needed to find the desired history entry. To search backward in the history for a particular string, type Ctrl-r. Typing Ctrl-s searches forward through the history. The characters present in the value of the isearch-terminators variable are used to terminate an incremental search. If that variable has not been assigned a value, then Esc or Ctrl-j will terminate an incremental search. Ctrl-g will abort an incremental search and restore the original line. When the search is terminated, the history entry containing the search string becomes the current line.

To find other matching entries in the history list, type Ctrl-r or Ctrl-s as appropriate. This will search backward or forward in the history for the next entry matching the search string typed so far. Any other key sequence bound to a Readline command will terminate the search and execute that command. For instance, Enter will terminate the search and accept the line, thereby executing the command from the history list. A movement command will terminate the search, make the last line found the current line, and begin editing.

Readline remembers the last incremental search string. If two Ctrl-r's are typed without any intervening characters defining a new search string, any remembered search string is used.

Non-incremental searches read the entire search string before starting to search for matching history lines. The search string may be typed by the user or be part of the contents of the current line. Type Alt-p or Alt-n to start a non-incremental search backwards or forwards.

To search backward in the history for a line starting with the text before the cursor, type PgUp. Or search forward by typing PgDn.

See Saved Command History for more information on how history works.

.Init File up top

You can customize key bindings and configuration variables by using an init file.

"Configuration variables" are customized in the init file, but "Clink settings" are customized with the clink set command.

.Init File Location up top

The Readline init file is named .inputrc or _inputrc. Clink searches the directories referenced by the following environment variables in the order listed here, and loads the first .inputrc or _inputrc file it finds:

• %CLINK_INPUTRC%
• The Clink profile directory (see the "state" line from clink info; by default this is the same as %USERPROFILE% but it can be overridden by the clink inject command).
• %USERPROFILE%
• %LOCALAPPDATA%
• %APPDATA%
• %HOME% or %HOMEDRIVE%%HOMEPATH%

Other software that also uses the Readline library will also look for the .inputrc file (and possibly the _inputrc file too). To set macros and keybindings intended only for Clink, one can use the Readline init file conditional construct like this; $if clink [...] $endif.

You can use clink info to find the directories and configuration file for the current Clink session.

Compatibility Notes:

• The clink_inputrc_base file from v0.4.8 is no longer used.
• For backward compatibility, clink_inputrc is also loaded from the above locations, but it has been deprecated and may be removed in the future.
• Clink v1.0.0a0 through Clink v1.2.27 accidentally loaded up to one Readline init file from each of the searched directories. That was incorrect behavior for loading Readline init files and has been fixed. If similar behavior is still desired, consider using the $include directive in the Readline init file, to load additional files.

.Init File Syntax up top

There are only a few basic constructs allowed in the Readline init file:

• Blank lines are ignored.
• Lines beginning with a # are comments.
• Lines beginning with a $ indicate conditional init constructs.
• Other lines denote Readline configuration variables and Readline key bindings.

.Readline configuration variables up top

You can modify the behavior of Readline by altering the values of configuration variables in Readline using the set command within the init file. The syntax is simple:

set variable value

Here, for example, is how to change from the default Emacs-like key binding to use vi line editing commands:

set editing-mode vi

Variable names and values, where appropriate, are recognized without regard to case. Unrecognized variable names are ignored.

Boolean variables (those that can be set to on or off) are set to on if the value is null or empty, on (case-insensitive), or 1. Any other value results in the variable being set to off.

Clink adds some new configuration variables for Readline:

Some configuration variables are deprecated in Clink:

.Readline key bindings up top

The syntax for controlling key bindings in the init file is simple. First you need to find the name of the command that you want to change. The following sections contain tables of the command name, the default keybinding, if any, and a short description of what the command does (see Bindable Commands).

Once you know the name of the command, simply place on a line in the init file the name of the key you wish to bind the command to, a colon, and then the name of the command. There can be no space between the key name and the colon (any space will be interpreted as part of the key name). The name of the key can be expressed in different ways, depending on what you find most comfortable.

In addition to command names, Readline allows keys to be bound to a string that is inserted when the key is pressed (a macro).

Names can be used to refer to simple keys like Space, Return, Tab, letters and digits (A, b, 1, ...), and most punctuation (!, @, ., _, ...). Names can also include modifier prefixes C- or Control- for the Ctrl key, or M- or Meta- for the Meta or Alt key. However, modifier prefixes don't work with simple key names; you can't use C-Space, instead a sequence is needed for special keys like that.

Sequences are surrounded by double quotes, and specify an entire sequence of input characters. Some special escape codes can be used:

Here are some examples to illustrate the differences between names and sequences:

Special keys like Up are represented by VT220 escape codes such as "\e[A". See Discovering Clink key sequences and Binding special keys for how to find the keyname for the key you want to bind.

• blah-blah binds to a function named "blah-blah".
• "blah-blah" is a macro that inserts the literal text "blah-blah" into the line.

When entering the text of a macro, single or double quotes must be used to indicate a macro definition. Unquoted text is assumed to be a function name. In the macro body, the backslash escapes described above are expanded. Backslash will quote any other character in the macro text, including " and '. For example, the following binding will make pressing Ctrl-x \ insert a single \ into the line:

"\C-x\\": "\\"

# Using key names.
C-u: universal-argument         # Bind Ctrl-u to invoke the universal-argument command.
C-o: "> output"                 # Bind Ctrl-o to insert the text "> output" into the line.

# Using key sequences.
"\C-u": universal-argument      # Bind Ctrl-u to invoke the universal-argument command.
"\C-x\C-r": clink-reload        # Bind Ctrl-x,Ctrl-r to reload the configuration and Lua scripts for Clink.
"\eOP": clink-popup-show-help   # Bind F1 to invoke the clink-popup-show-help command.

See Customizing Key Bindings for more information about binding keys in Clink.

.Conditional init constructs up top

Readline implements a facility similar in spirit to the conditional compilation features of the C preprocessor which allows key bindings and variable settings to be performed as the result of tests. There are four parser directives used.

$if mode == emacs
set show-mode-in-prompt on
$endif

$if version >= 7.0
set show-mode-in-prompt on
$endif

$if clink
# Quote the current or previous word
"\C-xq": "\eb\"\ef\""
$endif

$if clink_version >= 1.6.1
"\C-x\C-f": clink-dump-functions    # This function doesn't exist before Clink 1.6.1,
                                    # and would print an error in older versions.
$endif

$if editing-mode == emacs
set show-mode-in-prompt on
$endif

$include c:\dir\inputrc

.Sample .inputrc file up top

Here is a sample .inputrc file with some of the variables and key bindings that I use:

$if clink           # begin clink-only section

set colored-completion-prefix                       on
set colored-stats                                   on
set mark-symlinked-directories                      on
set visible-stats                                   off
set completion-auto-query-items                     on
set history-point-at-end-of-anchored-search         on
set menu-complete-wraparound                        off
set search-ignore-case                              on

# The following key bindings are for emacs mode.
set keymap emacs

"\e[27;8;72~":      clink-popup-show-help           # Alt-Ctrl-Shift-H

# Completion key bindings.
"\t":               old-menu-complete               # Tab
"\e[Z":             old-menu-complete-backward      # Shift-Tab
"\e[27;5;32~":      clink-select-complete           # Ctrl-Space

# Some key bindings I got used to from 4Dos/4NT/Take Command.
C-b:                                                # Ctrl-B (cleared because I redefined Ctrl-F)
C-d:                remove-history                  # Ctrl-D (replaces `delete-char`)
C-f:                clink-expand-doskey-alias       # Ctrl-F (replaces `forward-char`)
C-k:                add-history                     # Ctrl-K (replaces `kill-line`)
"\e[A":             history-search-backward         # Up (replaces `previous-history`)
"\e[B":             history-search-forward          # Down (replaces `next-history`)
"\e[5~":            clink-popup-history             # PgUp (replaces `history-search-backward`)
"\e[6~":                                            # PgDn (cleared because I redefined PgUp)
"\e[1;5F":          end-of-line                     # Ctrl-End (replaces `kill-line`)
"\e[1;5H":          beginning-of-line               # Ctrl-Home (replaces `backward-kill-line`)

# Some key bindings handy in default (conhost) console windows.
M-b:                                                # Alt-B (cleared because I redefined Alt-F)
M-f:                clink-find-conhost              # Alt-F for "Find..." from the console's system menu
M-m:                clink-mark-conhost              # Alt-M for "Mark" from the console's system menu

# Some key bindings for interrogating the Readline configuration.
"\C-x\C-f":         dump-functions                  # Ctrl-X, Ctrl-F
"\C-x\C-m":         dump-macros                     # Ctrl-X, Ctrl-M
"\C-x\C-v":         dump-variables                  # Ctrl-X, Ctrl-V

# Misc other key bindings.
"\e[27;2;32~":      clink-magic-suggest-space       # Shift-Space
"\e[5;6~":          clink-popup-directories         # Ctrl-Shift-PgUp
C-_:                kill-line                       # Ctrl-- (replaces `undo`)

$endif              # end clink-only section

.Bindable Commands up top

.Commands For Moving up top

.Commands For Manipulating The History up top

.Commands For Changing Text up top

.Killing And Yanking up top

.Specifying Numeric Arguments up top

.Completion Commands up top

.Keyboard Macros up top

.Some Miscellaneous Commands up top

.Readline vi Mode up top

While the Readline library does not have a full set of vi editing functions, it does contain enough to allow simple editing of the line. The Readline vi mode behaves as specified in the POSIX standard.

In order to switch interactively between emacs and vi editing modes, use the command Alt-Ctrl-j (bound to emacs-editing-mode when in vi mode and to vi-editing-mode in emacs mode). The Readline default is emacs mode.

When you enter a line in vi mode, you are already placed in "insertion" mode, as if you had typed an "i". Pressing Esc switches you into "command" mode, where you can edit the text of the line with the standard vi movement keys, move to previous history lines with "k" and subsequent lines with "j", and so forth.

.Other Readline Commands up top

These other commands are not very useful in Clink, but exist nevertheless.

.Clink Commands up top

Clink also adds some new commands, beyond what's normally provided by Readline.

Note: Some commands have alternative default key bindings when Clink is installed with "Use enhanced default settings" checked in the setup program or when clink.default_bindings is set to windows.

.Completion Colors up top

The match.coloring_rules setting provides a string that determines how match completions are displayed.

The string can contain a series of one or more rules separated by colons (:). If an environment variable %CLINK_MATCH_COLORS% exists, its value supersedes this setting.

Each rule is a series of one or more conditions separated by spaces, followed by an equals sign and then the SGR parameters for an ANSI escape code. All of the conditions must be true for the rule to match (in other words, a space is like an AND operator).

Each condition can be any of the following:

• A pattern, for example *.zip (for zip files). This is an fnmatch pattern (like .gitignore globbing patterns). The pattern is compared only to the filename portion after stripping the path. For example, *.zip.
• A type, for example di (for directories). The available types are listed below.
• A not operator, which negates the next condition. For example, not di applies to anything that isn't a directory, or not *.zip applies to any name that doesn't match *.zip.

Any quoted string is assumed to be a pattern, so "hi" is a pattern instead of the Hidden type, and etc.

Rules are evaluated in the order listed, with one exception: Rules with exactly one type and no patterns are evaluated last; this makes it easier to list the rules -- you can put the simple defaults first, followed by specializations.

For backward compatibility with %LS_COLORS%, either so or *.readline-colored-completion-prefix may be used to override thecolor.common_match_prefix setting.

Here is an example that defines colors for various types.

clink set match.coloring_rules  di=93:ro ex=1;32:ex=1:ro=32:di *.tmp=90

• di=93 uses bright yellow for directories.
• ro ex=1;32 uses bright green for readonly executable files.
• ex=1 uses bold for executable files (depending on the terminal's color theme, bold by itself usually ends up being bright white).
• ro=32 uses dark green for readonly files.
• di *.tmp=90 uses bright magenta for directory names ending in .tmp.

Note: The match.coloring_rules setting was added in Clink v1.6.1. It works similar to how the %LS_COLORS% environment variable works, except it adds "hi", "ro", "any", and "not", and patterns can be fnmatch patterns instead of just "*.ext" patterns.

.LS_COLORS (for backward compatibility) up top

The %LS_COLORS% environment variable is supported for backwards compatibility with Readline. It can provide color definitions as a series of color definitions separated by colons (:). Each definition is a either a two character type id or a file extension, followed by an equals sign and then the SGR parameters for an ANSI escape code. The two character type ids are listed below.

If either match.coloring_rules or %CLINK_MATCH_COLORS are set, then they take precedence and %LS_COLORS% is ignored.

When colored-stats is configured to on, then file completions are colored according to their file type or extension from %LS_COLORS%. Also, since %LS_COLORS% doesn't cover readonly files, hidden files, doskey aliases, or shell commands the color.readonly, color.hidden, color.doskey, and color.cmd Clink settings exist to cover those.

When colored-completion-prefix is configured to on, then the "so" color from %LS_COLORS% is used to color the common prefix when displaying possible completions. The default for "so" is bright magenta, but for example set LS_COLORS=so=90 sets the color to bright black (which shows up as a dark gray).

Here is an example where %LS_COLORS% defines colors for various types.

set LS_COLORS=so=90:fi=97:di=93:ex=92:*.pdf=30;105:*.md=4

• so=90 uses bright black (dark gray) for the common prefix for possible completions.
• fi=97 uses bright white for files.
• di=93 uses bright yellow for directories.
• ex=92 uses bright green for executable files.
• *.pdf=30;105 uses black on bright magenta for .pdf files.
• *.md=4 uses underline for .md files.

.Popup Windows up top

Some commands show a searchable popup window that lists the available completions, directory history, or command history.

For example, win-history-list (F7) and clink-popup-directories (Ctrl-Alt-PgUp) show popup windows.

Here's how the popup windows work:

Most of the popup windows also have incremental search:

The win-history-list command has a different search feature. Typing digits 0-9 jumps to the numbered history entry, or typing a letter jumps to the preceding history entry that begins with the typed letter. Left/Right inserts the highlighted command history entry without executing it. These are for compatibility with the F7 behavior built into Windows console prompts.

Use the clink-popup-history command instead if you prefer for typing to do an incremental search.

.Extending Clink With Lua top

Clink can be extended with Lua scripts to customize startup actions, create completion matches, customize the prompt, and more. The following sections describe these in more detail and show some examples.

.Location of Lua Scripts up top

Clink loads all Lua scripts it finds in these directories:

1. All directories listed in the clink.path setting, separated by semicolons.
2. If clink.path is not set, then the DLL directory and the profile directory are used (see File Locations for info about the profile directory).
3. All directories listed in the %CLINK_PATH% environment variable, separated by semicolons.
4. All directories registered by the clink installscripts command.

Lua scripts are loaded once and are only reloaded if forced because the scripts locations change or the clink-reload command is invoked (Ctrl-X,Ctrl-R).

Run clink info to see the script paths for the current session.

Notes:

• "completions" is a special reserved directory name: a "completions" directory under any of the Lua script directories listed in clink info has special meaning, and should not contain scripts unless they are specially written to be put in a "completions" directory. See Completion directories for more information.
• Clink performs tilde expansion on the Lua script directory names. If the path begins with ~\ then it is replaced with the current user's home directory (%HOME% or %HOMEDRIVE%%HOMEPATH% or %USERPROFILE%).

.Completion directories up top

You may optionally put Lua completion scripts in a completions\ directory when using Clink v1.3.23 and higher. That prevents them from being loaded when Clink starts, and instead they are only loaded when needed. That can make Clink load faster if you have a large quantity of Lua scripts that define argmatchers.

When a command name is typed, if a corresponding argmatcher is not already loaded then the completions directories are searched for a Lua script by the same name. If found, then the Lua script is loaded. This is similar to how completion scripts work in shells like bash, zsh, and fish.

For example, if you type xyz and an argmatcher for xyz is not yet loaded, then if xyz.lua exists in one of the completions directories it will be loaded.

Clink looks for completion scripts in these directories:

1. Any directories listed in the %CLINK_COMPLETIONS_DIR% environment variable (multiple directories may be separated by semicolons).
2. A completions\ subdirectory under each scripts directory listed by clink info (see Location of Lua Scripts).

In v1.5.3 and higher, when a completions\ script is loaded on demand the script receives as an argument the fully qualified path name to the typed program or file. The script can access the argument by using local fullname = ... (literally three dots). For example, that can be useful for checking whether it's a supported program, registering different argmatchers for different copies of the program or file, checking whether it's a supported program, and so on.

Note: If you download scripts, then don't put them in a "completions" directory unless they specifically say they can be put there.

If a script defines more than an argmatcher, then putting it in a completions directory may cause its other functionality to not work until a command is typed with the same name as the script. For example, if a script in a completions directory defines an argmatcher and also a prompt filter, the prompt filter won't be loaded until the corresponding command name is typed. Whether that is desirable depends on the script and on your preference.

For example, the scripts from the clink-completions project belong in a normal script directory, because they have other functionality besides just completions, and they won't work correctly in a "completions" directory.

.Writing Lua Scripts up top

Lua is a versatile and lightweight language. It's very approachable and easy to learn for beginners, but it also has powerful capabilities available if you need them.

Here are some tips for getting started writing Lua scripts:

• Clink uses Lua 5.2.
• Loading a Lua script executes it; so when Clink loads Lua scripts from the locations above, it executes the scripts.
• Code not inside a function is executed immediately when the script is loaded.
• Usually scripts will register functions to customize various behaviors:
  • Generate completion matches.
  • Apply color to input text.
  • Customize the prompt.
  • Perform actions before or after the user gets to edit each input line.
  • Provide new custom commands that can be bound to keys via the luafunc: key macro syntax.
• Often scripts will also define some functions and variables for use by itself and/or other scripts.
• Clink extends the Lua language by adding many new APIs and features for use within Clink.

.Argument Completion up top

Clink provides a framework for writing complex argument match generators in Lua. It works by creating a parser object that describes a command's arguments and flags and associating the parser with one or more commands. When Clink detects a parser is associated with the command being edited, it uses the parser to generate matches and apply input line coloring.

.The Basics up top

Here is an example of a simple parser for the command foobar;

clink.argmatcher("foobar")
:addarg({ "hello", "hi" })               -- Completions for arg #1.
:addarg({ "world", "wombles", "xyzzy" }) -- Completions for arg #2.
:addflags("-foo", "-bar")                -- Flags.

This parser describes a command that has two arguments, and some flags.

Arguments are positional. Each :addarg() adds a new argument position and defines the possible completions for that argument position.

Flags are position independent. Any :addflags() add to the set of possible flag completions. Any word that begins with the flag prefix character (in this example -) is considered to be a flag, even if it is not listed as a possible completion. The flags may be input at any position; before arguments, between arguments, and after arguments.

On the command line completion would look something like this, if Alt-= were pressed at the end of each input line below:

C:\>foobar -
-bar  -foo
C:\>foobar -bar hello
wombles  world  xyzzy
C:\>foobar -bar hello wo
wombles  world
C:\>foobar -bar hello wombles -
-bar  -foo
C:\>foobar -bar hello wombles -foo _

When displaying possible completions, flag matches are only shown if the flag character has been input. So foobar and Alt-= would list matches for the first argument position, or foobar some_word and Alt-= would list matches for the second argument position, or foobar - and Alt-= would list only flag matches.

If a command doesn't have an argmatcher but is a doskey macro, Clink automatically expands the doskey macro and looks for an argmatcher for the expanded command. A macro like gco=git checkout $* automatically reuses a git argmatcher and produces completions for its checkout argument. However, it only expands the doskey macro up to the first $, so complex aliases like foo=app 2$gnul text $* or foo=$2 $1 might behave strangely.

Also see clink.argmatcher(), :addflags() and :addarg().

.Automatic Filename Completion up top

A fresh, empty argmatcher provides no completions.

clink.argmatcher("foobar")               -- The "foobar" command provides no completions.

Once any flags or argument positions have been added to an argmatcher, then the argmatcher will provide completions.

clink.argmatcher("foobar")
:addarg({ "hello", "hi" })               -- Completions for arg #1.
:addarg({ "world", "wombles", "xyzzy" }) -- Completions for arg #2.
:addflags("-foo", "-bar")                -- Flags.

When completing a word that doesn't have a corresponding argument position the argmatcher will automatically use filename completion. For example, the foobar argmatcher has two argument positions, and completing a third word uses filename completion.

C:\>foobar hello world pro
Program Files\  Program Files(x86)\  ProgramData\
C:\>foobar hello world pro_

Use _argmatcher:nofiles() if you want to disable the automatic filename completion and "dead end" an argmatcher for extra words. This stops all further parsing for the command.

clink.argmatcher("foobar")
:addarg({ "hello", "hi" })               -- Completions for arg #1
:addarg({ "world", "wombles", "xyzzy" }) -- Completions for arg #2
:addflags("-foo", "-bar")                -- Flags
:nofiles()                               -- Using :nofiles() prevents further completions.

.Descriptions for Flags and Arguments up top

Flags and arguments may optionally have descriptions associated with them. The descriptions, if any, are displayed when listing possible completions.

Use _argmatcher:adddescriptions() to add descriptions for flags and/or arguments. Refer to its documentation for further details about how to use it, including how to also show arguments that a flag accepts.

For example, with the following matcher, typing foo -Alt-= will list all of the flags, plus descriptions for each.

clink.argmatcher("foo")
:addflags("-?", "-h", "-n", "-v", "--help", "--nothing", "--verbose")
:addarg("print", "delete")
:addarg(clink.filematches)
:nofiles()
:adddescriptions(
    { "-n", "--nothing",    description = "Do nothing; show what would happen without doing it" },
    { "-v", "--verbose",    description = "Verbose output" },
    { "-h", "--help", "-?", description = "Show help text" },
    { "print",              description = "Print the specified file" },
    { "delete",             description = "Delete the specified file" },
)

.More Advanced Stuff up top

.Linking Parsers up top

There are often situations where the parsing of a command's arguments is dependent on the previous words (git merge ... compared to git log ... for example). For these scenarios Clink allows you to link parsers to arguments' words using Lua's concatenation operator.

local a_parser = clink.argmatcher():addarg({ "foo", "bar" })
local b_parser = clink.argmatcher():addarg({ "abc", "123" })
local c_parser = clink.argmatcher()
c_parser:addarg({ "foobar" .. a_parser })   -- Arg #1 is "foobar", which has args "foo" or "bar".
c_parser:addarg({ b_parser })               -- Arg #2 is "abc" or "123".

As the example above shows, it is also possible to use a parser without concatenating it to a word.

When Clink follows a link to a parser it will only return to the previous parser when the linked parser runs out of arguments. Using :nofiles() prevents returning to the previous parser.

.Flags With Arguments up top

Parsers can be concatenated with flags, too.

Here's an example of a flag that takes an argument:

clink.argmatcher("git")
:addarg({
    "merge"..clink.argmatcher():addflags({
        "--strategy"..clink.argmatcher():addarg({
            "resolve",
            "recursive",
            "ours",
            "octopus",
            "subtree",
        })
    })
})

A : or = at the end of a flag indicates the flag takes an argument but requires no space between the flag and its argument. If such a flag is not linked to a parser, then it automatically gets linked to a parser to match files. Here's an example with a few flags that take arguments without a space in between:

clink.argmatcher("findstr")
:addflags({
    "/b", "/e", "/l", "/r", "/s", "/i", "/x", "/v", "/n", "/m", "/o", "/p", "/offline",
    "/a:"..clink.argmatcher():addarg( "attr" ),
    "/f:"..clink.argmatcher():addarg( clink.filematches ),
    "/c:"..clink.argmatcher():addarg( "search_string" ),
    "/g:", -- This is the same as linking with clink.argmatcher():addarg(clink.filematches).
    "/d:"..clink.argmatcher():addarg( clink.dirmatches )
})

.Functions As Argument Options up top

Argument options are not limited solely to strings. Clink also accepts functions too so more context-aware argument options can be used.

The function is called each time matches are generated for the argument position.

local function rainbow_function(word)
    return { "red", "white", "blue" }
end

local the_parser = clink.argmatcher()
the_parser:addarg({ "zippy", "bungle", "george" })
the_parser:addarg({ rainbow_function, "yellow", "green" })

The functions are passed five arguments:

• word is a partial string for the word under the cursor, corresponding to the argument for which matches are being generated: it is an empty string, or if a filename is being entered then it will be the path portion (e.g. for "dir1\dir2\pre" word will be "dir1\dir2").
• word_index is the word index in line_state, corresponding to the argument for which matches are being generated.
• line_state is a line_state object that contains the words for the associated command line.
• match_builder is a builder object (but for adding matches the function should return them in a table).
• user_data is a table that the argmatcher can use to help it parse the input line. See Responding to Arguments in Argmatchers for more information about the user_data table.

The functions can return any of the following:

• Return a table of potential matches (strings). The table may optionally also contain tables that describe the matches; the format is the same as in builder:addmatches().
• Return true to stop generating matches.
• Return false or nil (or don't return anything) to stop generating matches and use file completions.

Compatibility Note: When a function argument uses the old v0.4.9 clink.match_display_filter approach, then the word argument will be the full word under the cursor, for compatibility with the v0.4.9 API.

Some built-in matcher functions are available:

.Show a Usage Hint up top

A usage hint can be shown in the comment row (below the input line). Usage hints for argmatchers are only shown if both comment_row.show_hints (off by default) and argmatcher.show_hints (on by default) are enabled.

To use this, Clink v1.7.0 or higher is required.

Argmatchers can automatically supply input hints based on arginfo fields from match completions.

To supply a custom usage hint, an argmatcher can include either hint="text" or hint=function_name in the argument table.

clink.argmatcher("foo")
:addarg({ clink.filematches, hint="Argument expected:  filename" })

C:\dir>foo _
Argument expected:  filename

If a function name is supplied, then the function is passed five arguments:

• arg_index is the argument index in the argmatcher, corresponding to the argument being parsed. 0 means it is a flag, rather than an argument.
• word is a string containing the word being parsed. Note: when the cursor is between words or after the last word then word is an empty string.
• word_index is the word index in line_state, corresponding to the word being parsed. Note: when the cursor is between words then word_index is the index of the next word after the cursor, or when the cursor is after the last word then word_index is greater than line_state:getwordcount().
• line_state is a line_state object that contains the words for the associated command line.
• user_data is a table that the argmatcher can use to help it parse the input line. See Responding to Arguments in Argmatchers for more information about the user_data table.

The function returns a hint string, and an optional position in the line text where the hint refers to. If the position is omitted, then the offset to the beginning of the word is assumed.

local function foo_hint_func(arg_index, word, word_index, line_state, user_data)
    local hint = "Argument expected for '"..line_state:getword(word_index - 1).."':  filename"
    local pos = line_state:getwordinfo(word_index).offset   -- Shown for completeness, but this is automatically assumed if omitted.
    return hint, pos
end

clink.argmatcher("foo")
:addarg({ "add", "remove" })
:addarg({ clink.filematches, hint=foo_hint_func })

C:\dir>foo add _
Argument expected for 'add':  filename

.Generate Matches From History up top

An argument position can collect matches from the history file. When an argument table contains fromhistory=true then additional matches are generated by parsing the history file to find values for that argument slot from commands in the history file.

This example generates matches for arguments to a --host flag by parsing the history file for host names used in the past, and also includes the current computer name.

local host_parser = clink.argmatcher():addarg({ fromhistory=true, os.getenv("COMPUTERNAME") })
clink.argmatcher("program"):addflags({ "--host"..host_parser })

.Disable Sorting Matches up top

Match completions are normally listed in sorted order. In some cases it may be desirable to disable sorting and list match completions in a specific order. To disable sorting, include nosort=true in the argument table. When sorting is disabled, matches are listed in the order they were added.

local the_parser = clink.argmatcher()
the_parser:addarg({ nosort=true, "red", "orange", "yellow", "green", "blue", "indigo", "violet" })

.Fully Qualified Pathnames up top

Sometimes there may be more than one program installed with the same name. For example, there might be multiple versions of grep installed.

In Clink v1.3.38 and higher, you can define argmatchers using fully qualified pathnames. For example, this makes it possible to define one argmatcher for c:\EmployerTools\grep.exe and another for d:\PersonalTools\grep.exe, and the corresponding argmatcher will be used when appropriate.

In the example above, you could define an argmatcher for c:\EmployerTools\grep.exe, and also define an argmatcher for grep (or have a grep.lua file in a completions\ directory). The plain grep one would be used whenever the typed grep doesn't resolve to the EmployerTools copy.

.Delimited Arguments up top

In some cases an argument for programs may accept a list of values separated by ; or + or etc. Normally ; or + are argument separators (like space), and advance the argmatcher to the next argument slot.

In Clink v1.3.37 and higher, you can make them stay on the current argument slot by including loopchars=";" (or set loopchars= a list of value delimiters).

-- This argmatcher accepts syntax like "foo color filename".
-- Typing "foo red f" and pressing TAB generates completions for files.
-- Typing "foo red;" and pressing TAB generates completions for files.
clink.argmatcher("foo")
:addarg({"red", "green", "blue"})
:addarg(clink.filematches)

-- This argmatcher accepts syntax like "foo color[;color...] filename".
-- Typing "foo red f" and pressing TAB generates completions for files.
-- Typing "foo red;" and pressing TAB generates completions for colors (not files).
clink.argmatcher("foo")
:addarg({loopchars=";", "red", "green", "blue"})
:addarg(clink.filematches)

.Overcoming Word Breaks up top

Clink and parses the input line into a line_state by ending a word whenever one of the following characters is encountered (except when inside quotes). These are the same word break characters as CMD.exe uses.

• Whitespace characters SPACE, TAB, and NEWLINE.
• Punctuation symbols ', ‵, =, +, ;, and ,.
• Grouping symbols (, ), [, ], {, and }.

However, many programs parse their command line arguments using different word break characters than CMD does.

In Clink v1.5.17 and higher, argmatchers can override the word break rules for specific argument positions by including nowordbreakchars="," (or set nowordbreakchars= a list of characters that shouldn't denote word breaks). This can allow more accurate completions and input line coloring when these characters are present. But nowordbreakchars is always ignored for builtin CMD commands and Batch scripts (because CMD.exe itself always parses word breaks a specific way). Flags in argmatchers for anything other than builtin CMD commands and Batch scripts default to assuming nowordbreakchars="'‵+;,", but that can be overridden by setting nowordbreakchars= some other string.

-- This argmatcher accepts syntax like "wt --pos x,y --size cols,rows command".
clink.argmatcher("wt")
:addflags({
    "--pos" .. clink.argmatcher():addarg({fromhistory=true, nowordbreakchars=","}),
    "--size" .. clink.argmatcher():addarg({fromhistory=true, nowordbreakchars=","}),
})
:chaincommand()

It's also possible to combine nowordbreakchars and loopchars:

-- This argmatcher accepts syntax like "foo color[,color...] filename".
-- Typing "foo red " and pressing TAB generates completions for files.
-- Typing "foo red," and pressing TAB generates completions for colors (not files).
clink.argmatcher("foo")
:addarg({loopchars=",", nowordbreakchars=",", "red", "green", "blue"})
:addarg(clink.filematches)

.Adaptive Argmatchers up top

Some argmatchers may need to adapt on the fly. For example, a program may have different features available depending on the current directory, or may want to define its arguments and flags by parsing the --help text from running a program.

An argmatcher can define a "delayed initialization" callback function that gets calls when the argmatcher gets used, allowing it to defer potentially expensive initialization work until it's actually needed. An argmatcher can also define a separate "delayed initialization" function for each argument position.

.Delayed initialization for the argmatcher up top

You can use _argmatcher:setdelayinit() to set a function that performs delayed initialization for the argmatcher. The function receives up to two parameters:

• argmatcher is the argmatcher to be initialized.
• In Clink v1.3.12 and higher, command_word is the word in the command line that matched this argmatcher.

If the definition needs to adapt based on the current directory or other criteria, then the callback function should first test whether the definition needs to change. If so, first reset the argmatcher and then initialize it. To reset the argmatcher, use _argmatcher:reset() which resets it back to an empty, freshly created state.

local prev_dir = ""

-- Initialize the argmatcher.
-- v1.3.12 and higher receive a command_word parameter as well, which is the
-- word in the command line that matched this argmatcher.
local function init(argmatcher, command_word)
    local r = io.popen("some_command --help 2>nul")
    for line in r:lines() do
        -- PUT PARSING CODE HERE.
        -- Use the Lua string functions to parse the lines.
        -- Use argmatcher:addflags(), argmatcher:addarg(), etc to initialize the argmatcher.
    end
    r:close()
end

-- This function has the opportunity to reset and (re)initialize the argmatcher.
local function ondelayinit(argmatcher, command_word)
    local dir = os.getcwd()
    if prev_dir ~= dir then             -- When current directory has changed,
        prev_dir = dir                  -- Remember the new current directory,
        argmatcher:reset()              -- Reset the argmatcher,
        init(argmatcher, command_word)  -- And re-initialize it.
    end
end

-- Create the argmatcher and set up delayed initialization.
local m = clink.argmatcher("some_command")
if m.setdelayinit then        -- Can't use setdelayinit before Clink v1.3.10.
    m:setdelayinit(ondelayinit)
end

.Delayed initialization for an argument position up top

If the overall flags and meaning of the argument positions don't need to be updated, and only the possible values need to be updated within certain argument positions, then you can include delayinit=function in the argument table.

The function should return a table of matches which will be added to the values for the argument position. The table of matches supports the same syntax as _argmatcher:addarg(). The function receives two parameters:

• argmatcher is the current argmatcher.
• argindex is the argument position in the argmatcher (0 is flags, 1 is the first argument position, 2 is the second argument position, and so on).

The function is called only once, the first time the argument position is used. The only way for the function to be called again for that argmatcher is to use Delayed initialization for the argmatcher and reset the argmatcher and then re-initialize it.

Delayed initialization for an argument position is different from Functions As Argument Options. The delayinit function is called the first time the argmatcher is used, and the results are added to the matches for the rest of the Clink session. But a function as an argument option is called every time matches are generated for the argument position, and it is never called when applying input line coloring.

-- A function to delay-initialize argument values.
-- This function is used to delay-initialize two different argument positions,
-- and so it gets called up to two separate times (once for each position where
-- it is specified).
-- If the function needs to behave slightly differently for different
-- argmatchers or argument positions, it can use the two parameters it receives
-- to identify the specific context in which it is being called.
local function sc_init_dirs(argmatcher, argindex)
    return {
        path.join(os.getenv("USERPROFILE"), "Documents"),
        path.join(os.getenv("USERPROFILE"), "Pictures")
    }
end

-- A function to delay-initialize flag values.
local function sc_init_flags(argmatcher)
    -- This calls sc_init_dirs() when the '--dir=' flag is used.
    return { "--dir=" .. clink.argmatcher():addarg({ delayinit=sc_init_dirs }) }
end

-- Define an argmatcher with two argument positions, and the second one uses
-- delayed initialization.
local m = clink.argmatcher("some_command")
m:addarg({ "abc", "def", "ghi" })
m:addarg({ delayinit=sc_init_dirs }) -- This sc_init_dirs() when the second arg position is used.

-- You can also use delayinit with flags, but you must set the flag prefix
-- character(s) so that Clink can know when to call the delayinit function.
m:addflags({ delayinit=sc_init_flags })
m:setflagprefix("-")

.Responding to Arguments in Argmatchers up top

Argmatchers can be more involved in parsing the command line, if they wish.

An argmatcher can supply "on advance" or "on arg" functions to be called when the argmatcher parses an argument position. The functions can influence parsing the rest of the input line. For example, the presence of a flag --only-dirs might change what match completions should be provided somewhere else in the input line.

• An "on advance" function is called before parsing a word. It can influence which argument position will parse the word (it can advance to the next position before parsing, or it can repeat the same argument position for parsing both the current word and the next word).
• An "on alias" function is called before parsing a word. It can examine the word and return some other text to parse instead.
• An "on arg" function is called when parsing a word. It can examine the word and do custom processing.
• An "on link" function is called after parsing a word. It can examine the word and override what argmatcher it links to (see Linking Parsers).

All of these callback functions receive a user_data table. Your "on advance" and "on arg" and "on link" functions can set data into the table, and functions called later during parsing can get the data that was set by earlier functions (for example to keep track of what flags were specified earlier in the command line). When parsing begins for a command, the user_data is an empty table. Each time a flag or argument links to another argmatcher, the new argmatcher gets a separate new empty user_data table. In Clink v1.6.10 and higher, each user_data table contains a shared_user_data field which is a reference to another table. The user_data.shared_user_data enables linked argmatchers to share data with each other while parsing a command.

Note: These callback functions are called very often, so they need to be very fast or they can cause responsiveness problems while typing.

.The "on advance" function up top

Supply an "on advance" function by including onadvance=function in the argument table with _argmatcher:addarg(). The function can return an integer to choose how to advance through the argument positions.

To use this, Clink v1.5.14 or higher is required.

The function receives five arguments:

• arg_index is the argument index in the argmatcher, corresponding to the argument being parsed. 0 means it is a flag, rather than an argument.
• word is a string containing the word being parsed. If it's the word under the cursor, then the string will be empty, or if a filename is being entered then it will be the path portion (e.g. for "dir1\dir2\pre" word will be "dir1\dir2").
• word_index is the word index in line_state, corresponding to the argument being parsed.
• line_state is a line_state object that contains the words for the associated command line.
• user_data is a table that the argmatcher can use to help it parse the input line (see Responding to Arguments in Argmatchers for details).

The function may return any of the following values:

• Return 1 to advance to the next argument position before parsing the word (normally the parser advances after parsing a word). Multiple advances are possible for the same word: if the "on advance" functions for argument positions 2, 3, and 4 all return 1, then argument position 5 will parse the word.
• Return 0 to repeat using same argument position to parse both the current word and the next word. Multiple repetitions are possible for the same argument position: if the "on advance" function for argument position 3 returns 0 for three words in a row, then all three of the words are parsed using argument position 3.
• Return -1 to behave as though :chaincommand() were used, and start parsing a new command line beginning at word_index. To start at the next word index, see the "chain next" example below.
• Return nil (either return nil or just return) to advance to the next argument position after parsing the word (this is the default behavior).

In Clink v1.6.2 and higher, when returning -1 the function may also return a second value which is a string that lets Clink know how the command will get interpreted. The string is the same as the modes argument in :chaincommand().

This example demonstrates treating arg index 1 as an optional title string only if quoted:

local function maybe_string(arg_index, word, word_index, line_state, user_data)
    local info = line_state:getwordinfo(word_index)
    if not info.quoted then
        return 1    -- Advance; this arg position is optional and only accepts a
                    -- quoted string.  Anything else can't be parsed by this
                    -- argument position.
    end
end

clink.argmatcher("start")
:addarg({
    onadvance = maybe_string,
    fromhistory = true,
})
:addflags({
    "/min", "/max",
    "/wait", "/b",
    "/d"..clink.argmatcher():addarg(clink.dirmatches),
})
:chaincommand()

This example demonstrates how to chain on the next word, or also on the current word:

• foo chain bar chains starting at word 3 ("bar").
• foo whatever.exe chains starting at word 2 ("whatever.exe").

local function chain_on_word(arg_index, word, word_index, line_state, user_data)
    if user_data.do_chain then
        return -1                   -- Chain command because the "chain" keyword was seen previously.
    elseif word == "chain" then
        user_data.do_chain = true   -- Remember that the "chain" keyword was seen.
        return 0                    -- Use the same arg_index for the next word index.
    elseif path.getextension(word) ~= "" then
        return -1                   -- Chain command immediately when the word has an extension.
    end
end

clink.argmatcher("foo")
:addarg({
    onadvance=chain_on_keyword,
    "abc", "def", "ghi",
})
:nofiles()

.The "on alias" function up top

Supply an "on alias" function by including onalias=function in the argument table with _argmatcher:addarg(). The function can examine the word and return some other text to parse instead.

To use this, Clink v1.6.18 or higher is required.

The function receives five arguments:

• arg_index is the argument index in the argmatcher, corresponding to the argument being parsed. 0 means it is a flag, rather than an argument.
• word is a string containing the word being parsed.
• word_index is the word index in line_state, corresponding to the argument being parsed.
• line_state is a line_state object that contains the words for the associated command line.
• user_data is a table that the argmatcher can use to help it parse the input line (see Responding to Arguments in Argmatchers for details).