Serpl Commands

Comprehensive Serpl terminal UI commands for project-wide search and replace operations.

Installation

Command	Description
cargo install serpl	Install via Cargo (Rust)
brew install serpl	Install via Homebrew (macOS)
nix-env -i serpl	Install via Nix
pacman -S serpl	Install on Arch Linux
Download from GitHub Releases	Pre-built binaries available
serpl --version	Show Serpl version

Basic Usage

Command	Description
serpl	Launch Serpl in current directory
serpl --search-text "oldFunc"	Launch with pre-filled search term
serpl --replace-text "newFunc"	Launch with pre-filled replacement
serpl --search-path ./src	Search in specific directory
serpl --hidden	Include hidden files in search
serpl --ignore-case	Case-insensitive search

Navigation Keys

Shortcut	Description
j	Move down in results list
k	Move up in results list
g	Jump to first result
G	Jump to last result
/	Search within results list
Enter	Select/confirm action
Escape	Cancel/go back
q	Quit Serpl

Mode Switching

Shortcut	Description
Tab	Switch between search and replace fields
Ctrl + N	Toggle between search and replace modes
Ctrl + B	Open help dialog
Ctrl + C	Quit application

Search Operations

Shortcut	Description
Type in search field	Live search across all files
Ctrl + N	Toggle search mode
Case-sensitive mode	Match exact case
Case-insensitive mode	Ignore case differences
Regex mode	Use regular expressions
AST Grep mode	Structural code search

Replace Operations

Shortcut	Description
Ctrl + O	Process replace for ALL files
d	Delete selected file or line from results
Simple replace	Replace all occurrences directly
Preserve case replace	Maintain original casing pattern
AST Grep replace	Structural code replacement

Replace Modes

Mode	Description
Simple	Direct text replacement
Preserve Case	Matches case pattern of original text
AST Grep	Syntax-tree-aware replacement

Search Modes

Mode	Description
Fixed String	Literal text matching
Regex	Regular expression matching
AST Grep	Structural code pattern matching

File Operations

Shortcut	Description
d	Remove file/line from results (skip)
Ctrl + O	Apply replacements to all remaining files
Review changes per file	See preview before applying
Undo is not available	Changes are permanent—use Git

Configuration

Setting	Description
~/.config/serpl/config.json	Configuration file location
Custom key bindings	Override default shortcuts
Search mode default	Set preferred search mode
Replace mode default	Set preferred replace mode
File pattern filters	Configure which files to include
Ignore patterns	Configure which files to exclude

Example Configuration

{
  "key_bindings": {
    "quit": "q",
    "navigate_up": "k",
    "navigate_down": "j",
    "go_to_top": "g",
    "go_to_bottom": "G",
    "delete": "d",
    "process_replace": "Ctrl+o",
    "toggle_help": "Ctrl+b",
    "search_in_list": "/"
  },
  "search_mode": "fixed_string",
  "replace_mode": "simple"
}

Common Workflows

Workflow	Description
Rename variable	Search old name → Replace with new name
Update import paths	Search old path → Replace with new path
Migrate API calls	Search deprecated → Replace with new API
Fix typos across project	Search misspelling → Replace with correct
Update config values	Search old value → Replace with new value

Integration with Git

Workflow	Description
git diff after serpl	Review all changes made
git stash before serpl	Save current work first
git checkout -- . to undo	Revert all changes if needed
Work in a branch	Isolate search-replace changes
git add -p after serpl	Selectively stage changes

Comparison with Alternatives

Feature	Serpl	sed	VS Code
Interactive preview	Yes	No	Yes
TUI interface	Yes	No	GUI
Preserve case	Yes	Manual	Yes
AST Grep	Yes	No	Extension
Works over SSH	Yes	Yes	No
Regex support	Yes	Yes	Yes

Tips and Best Practices

Tip	Description
Always use Git	Commit before running replacements
Preview before applying	Review each change in the TUI
Use AST Grep for code	Structural matching avoids false positives
Use preserve case	Maintains camelCase, PascalCase, etc.
Remove false positives	Use d to skip unwanted matches
Search specific paths	Use --search-path to narrow scope
Check hidden files	Use --hidden flag when needed