11 releases (7 stable)
✓ Uses Rust 2018 edition
|new 2.1.0||May 31, 2020|
|2.0.0||May 22, 2020|
|1.3.0||Jan 14, 2018|
|1.2.0||Nov 15, 2017|
|0.8.0||May 14, 2017|
#40 in Command line utilities
86 downloads per month
Scout is a small fuzzy finder for your terminal built in Rust.
The main features of
- Async architecture thanks to the
async-stdlibrary. This means that it won't block the UI to wait for the
STDINto finish, you can start typing right away.
- Customizable UI. You can change the colors and symbols of all the elements in the UI.
- Fast fuzzy matching algorithm based on the
fuzzaldrin-plugpackage used in the Atom editor.
This tool uses the system's pseudo terminal located in
/dev/tty to print the UI and capture inputs, which means it only works on UNIX systems (like Linux or macOS) as far as I know.
Each release, since version
v1.0.0 (not included), has a package with
scout compiled for different architectures. You can try to donwload and install the package that match your architecture.
You can find the releases in their GitHub page.
Scout is in the main crates repository, so you can install it with
$ cargo install scout
Remember to put
cargo bin path to the main
$PATH env variable:
You can use my custom tap repository to install
scout with homebrew:
$ brew tap jhbabon/tap $ brew install scout
scout is a Rust project, you will need to have Rust installed in your system. Check
rustup to see how to install Rust. To build
scout you will need Rust
v1.43 or higher.
Clone the repository and run
cargo install from it:
$ git clone https://github.com/jhbabon/scout.git path/to/scout $ cd path/to/scout $ cargo install --path .
You can also run
cargo build --release if you just want to play with it. The binary file will be in the
The main idea behind
scout, or any other fuzzy finder, is to filter a list of items (for example a list of paths to files) and then do something with the selection. For that you run a command, pipe its output to
scout and then pipe
scout's output to another command.
For example, you can try to find a file and
cat its contents:
$ find * -type f | scout | cat
scout has a set of options that allows you to control how it looks. It also supports a set of control sequences and keys to navigate the UI.
You can see these options in the main help of the program with the
scout 2.0.0 Your friendly fuzzy finder USAGE: scout [FLAGS] [OPTIONS] FLAGS: -f, --full-screen Show scout in full screen (default) -h, --help Prints help information -i, --inline Show scout under the current line -V, --version Prints version information OPTIONS: -c, --config <FILE> Uses a custom config file -l, --lines <LINES> Number of lines to display in inline mode, including prompt -s, --search <QUERY> Start searching with the given query SUPPORTED KEYS: - Enter to select the current highlighted match and print it to STDOUT - ^u to clear the prompt - ^n or Down arrow key to select the next match - ^p or Up arrow key to select the previous match - ^e to go to the end of the prompt - ^a to go to the beginning of the prompt - Left arrow key to move the cursor to the left in the prompt - Right arrow key to move the cursor to the right in the prompt - ESC to quit without selecting a match EXAMPLE: $ find * -type f | scout # Pass an initial query to start filtering right away $ find * -type f | scout --search=foo # Use a custom config file $ find * -type f | scout --config="./config.toml" # Select a git branch and check it out with an inline menu $ git branch | cut -c 3- | scout -i | xargs git checkout
You can configure
scout's UI with a config file. By default the program will try to find this file in the path
$HOME/.config/scout.toml, but you can pass a custom path with the
This is how
scout looks like without any defined style:
This is an example of a configuration file with all the possible settings:
# General screen options [screen] # Display inline (under the current line) or in full screen mode = "inline" # or "full" # Max number of lines to display the whole UI. Only used in inline mode lines = 8 # The prompt is where you type your query [prompt] # Symbol displayed before the text you will type symbol = "❯ " # Style for the query (your text) style = "bold underline" # Style for the symbol style_symbol = "fg:green" # The gauge indicates the number of matches vs total number of lines [gauge] # Symbol used to separate both numbers symbol = " ⚡" # Text before the numbers prefix = "- " # Style for the numbers style = "fg:bright-yellow" # A candidate is an item in the list that is not selected [candidate] # Symbol displayed before the candidate's text symbol = "❔ " # Style for the candidate's text style = "bg:red fg:black" # Style for the symbol style_symbol = "bg:red" # A match is a character that is in both the query and the candidate style_match = "underline bg:black fg:red bold" # The selected candidate [selection] # Symbol displayed before the selection's text symbol = "✅ " # Style for the selection's text style = "bg:green fg:black" # Style for the symbol style_symbol = "bg:green" # A match is a character that is in both the query and the selection style_match = "underline fg:bright-green bg:black"
That configuration placed in the
$HOME/.config/scout.toml would generate this UI:
It is not the prettiest, but it is just an example of what you can do.
A style is defined with a
string of space separated values. I
copied based the syntax on starship.rs configuration system.
These are the possible values you can use to define a style:
underline: Put a line under the text
strikethrough: Cross the text with a line
reverse: Reverse the current terminal colors
bold: Use bold font
italic: Use italic font (if the terminal supports it)
dimmed: Fade the foreground color a bit
none: Reset any color, using terminal's defaults. This will ignore any other rule in the style definition
fg:<color-name>: Use the named color as foreground (text) color. Possible names are
white. You can also use their bright version with the
fg:<number>: Use the given ANSI Color number as the foreground color
fg:#<hex>: Use the given hexadecimal representation of an RGB color as the foreground color. For example
rgb(255, 187, 204)
bg:<color-name>: Same as with
fg:but for the background
bg:<number>: Same as with
fg:but for the background
bg:#<hex>: Same as with
fg:but for the background
For color setting it really depends on your terminal color capabilities. Most modern terminals allow you to set any color, though.
You can learn more about the fuzzy matching algorithm in the
README in the repository page of the
fuzzaldrin-plug package. The only missing part from that algorithm is the path scoring bonus.
From all the algorithms for fuzzy matching out there this is one of the most complete I found, so I decided to try to port it.
Check the contributing guidelines.
I don't know. Maybe? It really depends on your needs. I built this tool first to learn some Rust and second because I didn't like much other more heavy tools. That doesn't mean is better or worse. It is probably simpler. Give
scout a try, see if it works for you, and if not try any other tool, it's cool.
I don't know, I haven't run any benchmark, to be honest. It is fast enough for me and most probably for most of the people.