Terminal GuideTerminal Guide

percol

Fuzzy Finders•
macOSLinux
•Python

Interactive grep/filter tool for UNIX pipes.

Official Website

Features

Interactive FilteringRegex SupportCustomizable

Installation

pip
pip install percol

Why use percol?

percol is a powerful interactive grep/filter tool that enhances your command-line workflow. It allows you to filter any text stream interactively with regex support, making it perfect for processing command outputs efficiently.

Interactive Filtering

Filter any text stream interactively in real-time. See results update as you type, making it easy to find exactly what you need.

Regex Support

Full regular expression support for powerful pattern matching. Use Python regex syntax for complex filtering scenarios.

Pipe-friendly

Works seamlessly with Unix pipes. Chain any command output through percol for interactive filtering.

Customizable

Customize keybindings and behavior to match your preferences. Configuration via Python scripts.

Installation

Installation
# Using pip (recommended)
pip install percol

# Using Homebrew (macOS)
brew install percol

# Using apt (Ubuntu/Debian)
sudo apt install percol

# Using Pacman (Arch Linux)
sudo pacman -S percol

percol requires Python 3.x. Install via pip for the latest version.

Basic Usage

Filter Command Output

Basic Filtering
# Filter lines from any command
ls -la | percol

# Search through files with grep
grep -r "pattern" . | percol

# Filter process list
ps aux | percol

# Filter network connections
netstat -tulpn | percol

# Select from environment variables
env | percol

Practical Examples

Practical Examples
# Kill a process interactively
ps aux | percol | awk '{print $2}' | xargs kill -9

# Edit a file from find results
find . -type f | percol | xargs vim

# Switch git branches
git branch | percol | awk '{print $1}' | xargs git checkout

# SSH into a server
grep "^Host " ~/.ssh/config | awk '{print $2}' | percol | xargs ssh

# Browse command history
history | percol | awk '{print $2-}'

# Select docker container
docker ps | percol | awk '{print $1}'

Regular Expression Filtering

Regex Filtering
# Filter with regex (search for pattern)
cat /var/log/syslog | percol --query "error|warning"

# Case-insensitive search
cat file.txt | percol -i

# Match lines starting with specific pattern
ps aux | percol --query "^root"

# Match lines ending with specific pattern
ls -l | percol --query ".txt$"

# Exclude pattern (using percol's filtering)
cat log.txt | percol

Integration with Shell

Add percol functions to your shell configuration for convenient access to common filtering tasks.

Shell Functions
# ~/.bashrc or ~/.zshrc

# Kill process interactively
pkill() {
  local pid
  pid=$(ps aux | percol | awk '{print $2}')
  if [ ! -z "$pid" ]; then
    kill -9 "$pid"
  fi
}

# Switch git branch with percol
gb() {
  git branch | percol | awk '{print $1}' | xargs git checkout
}

# Edit file from find with percol
ef() {
  find . -type f | percol | xargs ${EDITOR:-vim}
}

# SSH into host from config
ssh-percol() {
  grep "^Host " ~/.ssh/config | awk '{print $2}' | percol | xargs ssh
}

# Browse docker containers
docker-percol() {
  docker ps | percol | awk '{print $1}' | xargs docker exec -it
}

# Select from command history
hist() {
  history | percol | awk '{print $2-}' | xargs
}

# Change directory from find
cdf() {
  cd "$(find . -type d | percol)"
}

Default Keybindings

KeyAction
Ctrl+J / DownMove to next item
Ctrl+K / UpMove to previous item
EnterSelect and output current item
Ctrl+C / EscCancel and exit
Ctrl+UClear query string
Ctrl+WDelete word from query
TabToggle selection (with -m flag)

Common Options

Command Options
# Case-insensitive matching
cat file.txt | percol -i

# Multi-selection mode
ls | percol -m

# Use initial query
ps aux | percol -q "python"

# Suppress output of unselected items
echo "test" | percol --no-unselected

# Configure with Python script
percol --rcfile ~/.percol.d/percol.conf

# Show prompt
cat file.txt | percol --prompt "Filter: "

# Don't sort results
ps aux | percol --no-sort

# Invert match (select items NOT matching)
cat log.txt | percol --invert-match

Configuration

Create a configuration file for percol at ~/.percol.d/percol.conf

percol.conf
# ~/.percol.d/percol.conf
# percol configuration file in Python

# Keybindings
percol.view.PROMPT = 'Filter: '

# Change key bindings
import percol.actions as acts
from percol.key_binding import add_keybinding, remove_keybinding

# Use 'j' to move down and 'k' to move up
add_keybinding(acts.move_down, 'j')
add_keybinding(acts.move_up, 'k')

# Use 'l' for select and Enter for cancel
add_keybinding(acts.finish, 'l')
remove_keybinding(acts.finish, 'C-m')

# Emacs-like keybindings
add_keybinding(acts.move_down, 'C-n')
add_keybinding(acts.move_up, 'C-p')
add_keybinding(acts.move_beginning_of_line, 'C-a')
add_keybinding(acts.move_end_of_line, 'C-e')

# Coloring
percol.view.StyleDict = {
    'default': ('white', 'default'),
    'highlighted': ('red', 'default'),
    'matched': ('yellow', 'default'),
}

Advanced Patterns

Advanced Patterns
# Multi-select mode for batch operations
ps aux | percol -m | awk '{print $2}' | xargs kill -9

# Combining with other tools
find . -name "*.log" | percol | xargs tail -f

# Using with git log
git log --oneline | percol | awk '{print $1}' | xargs git show

# Filter and count
cat access.log | percol | wc -l

# Extract specific field after filtering
df -h | percol | awk '{print $1}' | xargs mount

# Complex regex filtering
journalctl | percol -q 'ERROR|WARN|CRITICAL'

# Pipe to another tool
ls -la | percol | awk '{print $NF}' | xargs file

Tips

  • •percol is lighter and simpler than fzf, making it great for systems where you want minimal dependencies
  • •Use Python regex patterns in your queries for powerful filtering - full Python re module support
  • •Combine multiple filters by piping: command | percol | percol
  • •The -m flag enables multi-selection, useful for batch operations with xargs
  • •Create aliases for your most common percol commands to speed up your workflow
  • •Percol's Python-based configuration allows for complex customization compared to shell-based tools
  • •Works well in scripts and automation - output goes directly to stdout for piping
Written by Dai AokiPublished: 2026-01-20

Related Articles

fzf - Command-line Fuzzy Finder

General-purpose command-line fuzzy finder

tools10 min read

peco - Interactive Filtering

Interactive filtering tool for command line

tools6 min read

skim - Rust fzf Alternative

Fuzzy finder in Rust with fzf-compatible interface

tools6 min read

Explore More

Browse Fuzzy Finders

See all tools in this category

All CLI Tools

Explore all tool categories