Cz is a bash script that provides a common interface to interactive line selection tools.
What is an "interactive line selection tool"? It's a kind of program that reads text input then presents an interactive menu for the user to select one line. Some line selection tools run only in the terminal and others are graphical - cz uses a tool appropriate for the situation.
Cz implements a plugin system. Each plugin defines lines from which to select, an output template, and a command template. Creating new plugins is quick and painless in any programming language.
Included are almost 300 plugins covering a variety of use cases. For example with some of the included plugins you can select from:
- files and directories
- items from bash's built-in completion
- Git branches, commits, tags, etc.
- Unicode characters
- pass(1) passwords
- elements from JSON/YAML/XML documents
- Docker components
- i3 window manager components
- Terraform elements
- Mpd tracks and tags
- Systemd units
- Tmux components
- Internet RFCs
- Magic: The Gathering cards
The following line selection tools are supported:
| Tool | Mode |
|---|---|
| choose | GUI |
| dmenu | GUI |
| dmenu-rs | GUI |
| fzf | TTY |
| fzy | TTY |
| gum | TTY |
| iselect | TTY |
| nfzf | TTY |
| pick | TTY |
| pipedial | TTY |
| rofi | GUI |
| selecta | TTY |
| sentaku | TTY |
| skim | TTY |
| vis-menu | TTY |
| zenity | GUI |
Many thanks to the authors of the above tools!
Aware of any other line selection tools? Let me know.
# just download the script to a directory on your path
curl -sS https://raw.githubusercontent.com/apathor/cz/master/bin/cz -o ~/bin/cz
# and make it executable
chmod -v +x ~/bin/czCz requires at least bash version 4. Mac OS users should `brew install bash`.
cz [OPTIONS] [PLUGIN...] [ARGS ...] [< LINES]
Select a line using an interactive line selection tool.
OPTIONS
These options print some information then exit:
-h : help : Show this help text or help text for plugin.
-H : example : List example commands.
-k : tools : List supported line selection tools.
-l : plugins : List detected plugins.
-v : version : Show version string.
-o : output : Only print input lines instead of selecting a line.
These options set the program mode. Select a line then... :
-p : print : Print the line. This is the default mode.
-q : quote : Print fields from the line in shell quotes.
-r : run : Run a templated command.
-s : simulate : Print a templated command.
-t : template : Print a templated string.
-u : unquote : Print fields from the line literally.
These options control input of selection lines:
-i IN-FILE : Set file from which to read selections instead of stdin.
-b : Buffer stdin and pass it to command set with '-e'.
-c : Do not use cached input lines.
-d DELIMITER : Set the field splitting characters.
-g PATTERN : Filter input to lines matching the given grep pattern.
-0 : Read null terminated lines from input.
These options control how lines are selected:
-n NUMBER : Select a line some number of times instead of just once.
-w : Select a line at random instead of any tool.
-x : Use a graphical line selection tool.
-y : Use a terminal line selection tool.
-z TOOL : Use the given line selection tool.
-j : Select each available line in sequence.
These options set output templates:
-e TEMPLATE : Set the command template used in run, template, and simulate modes.
-f FIELDS : Set the field template used in quote and unquote modes.
These options control debugging features:
-m : Print debugging information.
-M : Print timing information.
These options set tool-specific options:
-P PROMPT : Set the prompt in the line selection tool if possible.
PLUGINS
Plugins use cz for an application specific task. Each plugin defines input
lines, delimiter, and template options.
Run 'cz -l' to list plugins and 'cz -h PLUGIN' or 'cz help' for help text.
All commands starting with 'cz_' are considered plugins.
TEMPLATES
Sub-strings of TEMPLATE in the following formats are replaced with
one or more fields from a selected line split by DELIMITER.
{X} - field X
{X:} - fields X through end of fields
{X:Y} - fields X through X + Y
{X,Y,Z} - fields X, Y, and Z
Append @C, @E, @P, or @Q to transform selected fields:
{X@C} - Insert argument directly. This is risky for command strings!
{X@E} - Replace backslash escape sequences in arguments with bash $'...' quotes.
{X@P} - Expand arguments for use in prompt strings.
{X@Q} - Quote arguments for use in command input. This is the default.
ENVIRONMENT
CZ_GUI : Boolean whether to use a graphical selector (1=GUI 0=TTY).
CZ_BINS : A list of line selection tools in order of preference.
CZ_DMENU_COLOR : Colon separated colors for dmenu (NF:NB:SF:SB).
CZ_DMENU_FONT : The font to use for dmenu.
CZ_ROFI_THEME : The theme to use for rofi.
CZ_PROMPT : Prompt string to use for all prompts.
CZ_NO_PROMPT : If non-empty do not set a prompt.
To get the most out of cz users should consider binding shell and window manager keys.
Download this example bash config then copy it into your bashrc file.
The example config defines key bindings that run cz to provide interactive functionality.
Some of the key bindings use the included function `rleval` to do one of the following:
- Insert output from cz into the bash command buffer at cursor point.
- Replace the word at cursor point in the bash command buffer with output from cz.
- Run cz to launch an interactive program (like $EDITOR) using some part of the selection.
The example key bindings are as follows:
| Keys | Function |
|---|---|
| C-x x | Select a cz plugin, run it in quote mode, and insert one or more fields from the selection. |
| C-x X | Select a cz plugin, run it print mode, and insert the selection. |
| C-x z | Select a cz plugin, run it in run mode, and insert the output of the command. |
| C-x Z | Select a cz plguin, run it in simulate mode and insert the command templated with the selection. |
| C-x r | Select a command from bash history and insert it. |
| C-x u | Select a unicode character and insert it. |
| C-x g | Select an uncommitted file in current git repository and insert its path. |
| C-x G | Select a committed file in current git repository and insert its path. |
| C-x d | Using the current word as a directory, replace it with a selected descendant directory. |
| C-x D | Using the current word as a pattern, replace it with a selected matching descendant directory under $PWD. |
| C-x f | Using the current word as a directory, replace it with a selected descendant file. |
| C-x F | Using the current word as a pattern, replace it with a selected matching descendant file under $PWD. |
| C-x l | Using the current word as a pattern, replace it with a selected matching file from the locate database. |
| C-x e | Using the current word as a pattern, replace it with the path of a file matching it under $PWD. |
| C-x E | Using the current word as a pattern, run $EDITOR to open selected file matching it under $PWD. |
Download the example zsh config then copy it into your zshrc file.
The example config defines the same key bindings described in the bash section above.
Download the example i3 config then copy it into your i3 config.
The example config defines the following key bindings:
| Keys | Function |
|---|---|
| Mod x | Select a cz plugin, run it, and put fields from selected line into a clipboard. |
| Mod X | Select a cz plugin, run it, and put selected line into a clipboard. |
| Mod z | Select a cz plugin, run it, and put the command output into a clipboard. |
| Mod Z | Select a cz plguin, run it in simulate mode, and put the output into a clipboard. |
| Mod c | Select a command and run it. |
| Mod C | Select a clipboard and pipe its contents through the selected command. |
| Mod o | Select a clipboard then select a URL extracted from its contents to open in a browser. |
| Mod Shift Space | Select an i3 a tag and jump to the selected window. |
| Mod Tab | Select an i3 window and jump to it. |
| Mod Shift Tab | Select an i3 workspace and switch to it. |
seize
To fall or rush upon suddenly and lay hold of; to gripe or grasp suddenly;
*to reach and grasp*.