purr is a zsh CLI tool for viewing and searching through Android logcat output. It leverages fzf to provide a simple yet powerful user interface, fuzzy-finding capabilities, and much more.
While Android Studio’s logcat viewer is sufficient for most app development, it breaks down when exposed to situations such as terminal-only access or when multiple devices need to be accessed quickly. When performing development on the Android operating system itself, developers revert to using raw
adb logcat in shell.
This is sub-optimal and wastes a lot of time on writing
grep statements and rooting through uncolored, unfiltered text with poor user experience.
purr is meant as a solution to this; a powerful logcat viewer running entirely on the shell, capable of going through millions of logs quickly, while leveraging other shell-based solutions for common problems.
purr currently functions on Ubuntu Linux and Mac on zsh. It will attempt to source an
fzf version locally if possible, but requires version
0.40.0 or higher.
If you do not have
0.40.0 or higher locally,
purr will use bundled
fzf versions for
darwin_amd64 if applicable. If you have a different operating system, you need to download a
0.40.0 or higher
fzf binary manually.
Support for Windows may be provided in future, but is not a current priority.
- Clone the repo
- Add the scripts directory to your path
- Run using
purr comes with two bundled programs:
purr_osc52_copyis a fallback to copy to the system clipboard through SSH and TMUX sessions.
purr_fzfis a bundled version of fzf
0.40.0used if a higher version of
fzfcannot be found.
purr includes a simple tool to help select the device serial from
adb devices, or can read from the
$ANDROID_SERIAL environment variable if set. Otherwise,
purr has six command-line parameters:
- -a: Sets custom parameters for
adbthat will be used as well as the defaults whenever an input stream is selected.
- -f: Sets custom parameters for
fzf. Used on top of default parameters.
- -i: Disables the instruction preview on launch.
- -q: Set the default query string upon
- -v: Shows the
- -V: Shows a composite version of
Any other command-line parameters will print the help dialog.
Note that both
-f are read without validation; there is no guarantee that setting either parameter will not break
The following hotkeys can be used:
- Escape: Exits
purr. Ctrl-c and other methods also work, but may take longer, and may not gracefully exit.
- F1/F2/F3/F4: Sets the logcat stream between Error/Warning/Info/Verbose, respectively.
- F5: Opens the serial selection menu. Pressing Enter will select and load the highlighted device.
- F6: Opens ADB command mode. Pressing Enter will execute the current query as an ADB shell command on the current device, and print the output to the finder window.
- Ctrl-r: Opens the history menu. Pressing Enter will load the selected history item into the query and return you to the verbose stream.
- Ctrl-p: Toggles the preview window on/off. By default, the window is on, but you can use the -i flag to make it default to off.
- F7: Show the instruction preview (on by default).
- F9: Shows context around the selected line in the currently selected input stream.
- F10: Shows context around the selected line in the verbose input stream.
- Shift-up/down: Scrolls one item up or down the preview window, respectively.
- Home/End: Scrolls one page up or down the preview window, respectively.
- Ctrl-s: Enables scroll lock. While in scroll lock mode, your cursor will remain bound to the selected item as long as it remains in the search filter.
- Ctrl-f: Shorthand for enabling scroll lock and clearing the query. This allows you to go to the surrounding context of a selected item. Scroll lock will end once you move your cursor.
- Ctrl-j: Changes search modes between Chronological (default) and Relevance. This may be useful for fuzzy queries.
- Ctrl-t: Trims the logs to any logs after the currently selected items. Useful if attempting to isolate a specific issue after a certain point.
- Ctrl-alt-t: Untrims logs, reverting to showing all logs from the device.
- Ctrl-w: Wipes the logcat logs from the device.
- Tab: Select a line. Multiple lines can be selected simultaneously.
- Ctrl-y: Yanks selected lines into the system clipboard.
- Ctrl-v: Opens the text editor; see below.
purr saves a query string to history once it has not been changed for more than 3.5 seconds. You can use the following hotkeys to access history:
- Alt-shift-up: Move to the next entry in history.
- Alt-shift-down: Move to the previous entry in history.
When scrolling through history with alt-shift-up or alt-shift-down, your position in the history will reset once a string has been in the query for 3.5 seconds.
When you select a single line and press Ctrl-V,
purr will open the selected line and surrounding context in a text editor. You can specify the text editor through the
$EDITOR_PURR environment variables; if no text editor is specified,
purr will use
Note that logcat uses ANSI color codes to display color, so an editor that supports these codes is recommended; for example, AnsiEsc for
If multiple lines are selected, only those selected lines will be opened in the text editor.
- Clone the repo
- Open in your favorite IDE/editor
If you’ve found an error, please file an issue:
Patches are encouraged, and may be submitted by forking this project and submitting a pull request through GitHub.