rgx

A regex debugger for the terminal — step-through execution, 3 engines, code generation, and live stream filtering

Test and debug regular expressions without leaving your terminal. Written in Rust.

Press F1 in the app for a multi-page cheat sheet.

---

Who is this for?

rgx is useful if you:

• Work on remote servers where opening a browser isn't practical — SSH, containers, air-gapped environments.
• Want to pipe regex results into other commands (echo "log" | rgx -p '\d+' | sort) — regex101 can't do this.
• Need engine-specific behavior — check whether a pattern works in Rust's regex crate vs. PCRE2 without guessing.
• Prefer staying in the terminal and find the context switch to a browser disruptive.

If you write regex a few times a month and regex101.com works fine for you, it probably still will. rgx is strongest for developers doing regex-heavy work in terminal-centric workflows.

Install

cargo install rgx-cli                                         # crates.io
brew install brevity1swos/tap/rgx                             # Homebrew
yay -S rgx-cli                                                # AUR
curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/brevity1swos/rgx/releases/latest/download/rgx-installer.sh | sh

Prebuilt binaries are also on GitHub Releases.

Build from source / enable PCRE2

# From source
git clone https://github.com/brevity1swos/rgx.git
cd rgx && cargo install --path .

# With PCRE2 engine (requires libpcre2-dev)
cargo install rgx-cli --features pcre2-engine

See docs/advanced.md for the PCRE2 security note.

Quickstart

rgx                                   # interactive TUI
rgx '\d{3}-\d{3}-\d{4}'               # start with a pattern
echo "Call 555-123-4567" | rgx '\d+'  # stdin as test string
rgx -p -t "error 404" '\d+'           # batch mode (non-interactive)
cat app.jsonl | rgx filter --json '.msg' 'error'   # live stream filter on a JSON field

Full flag reference, piping recipes, and rgx filter + --json usage: docs/usage.md.

Features

• Step-through debugger (Ctrl+D, PCRE2) — backtracking visualization, heatmap mode, dual-cursor trace
• Real-time matching with AST-based syntax highlighting and capture-group colors
• 3 regex engines: Rust regex (default), fancy-regex (lookaround / backrefs), PCRE2 (+ recursion / conditionals)
• Auto engine selection — upgrades engines automatically when your pattern needs lookahead, backreferences, or recursion
• Plain-English explanations for any pattern, generated from the AST
• Code generation — Ctrl+G produces ready-to-paste code in 8 languages (Rust, Python, JS, Go, Java, C#, PHP, Ruby)
• Generate regex from examples — Ctrl+X opens a grex overlay
• Live filter mode — rgx filter streams stdin/file through a regex TUI, with --json JSONL-field extraction
• Test suite mode — rgx --test file.toml validates patterns against assertions in CI
• Non-interactive batch mode — -p with --count, --group, --json, --color, grep-like exit codes
• Benchmark mode — Ctrl+B compares compile and match time across all engines
• regex101.com export — Ctrl+U copies a shareable regex101 URL to clipboard
• Output pattern mode — -P prints the final pattern after an interactive session (eval $(rgx -P))
• Vim mode, mouse, pattern history + undo/redo, clipboard copy, whitespace visualization
• Workspaces — save/load regex state to a TOML file (-w) — track in git
• Editor integrations — VS Code, Neovim, Zed, tmux
• Shell completions — --completions bash|zsh|fish
• Cross-platform — Linux, macOS, Windows

Documentation

• Usage — interactive / batch / filter modes, all flags, piping recipes
• Keyboard shortcuts — main TUI, vim mode, filter mode
• Editor integrations — VS Code, Neovim, Zed, tmux
• Advanced — test suite mode, config file, engines deep-dive, comparison matrix

Engines at a glance

Engine	Features	Dependencies
Rust regex (default)	Fast, linear time, Unicode	Pure Rust
fancy-regex	+ lookaround, backreferences	Pure Rust
PCRE2	+ possessive quantifiers, recursion, conditionals	libpcre2

Full matrix and comparison against other tools: docs/advanced.md.

Contributing

See CONTRIBUTING.md.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

at your option.