GROK is a powerful command-line tool like UNIX grep on steroids. It uses grok patterns (named regular expression macros) to simplify complex pattern matching tasks.

Often, regular expressions become huge and hard to maintain. To resolve this, grok patterns (macros) can be applied. The term "grok" is borrowed from the Logstash project. Grok patterns are named references to regular expressions that can be rather complex. These regular expressions can contain references to other groks, allowing you to build complex patterns from simple, reusable components.

Instead of writing complex regular expressions, you can use a macro name defined in pattern files, making your pattern matching more readable and maintainable.

• 🚀 Fast pattern matching using PCRE2
• 📝 Named pattern macros for reusable regular expressions
• 🔗 Pattern composition - groks can reference other groks
• 📁 Multiple input modes: files, strings, and stdin
• 🎯 Info mode for detailed match information
• 🌍 Cross-platform support (Linux, macOS, Windows)
• 📦 Pre-built binaries for easy installation
• 🔍 Built-in pattern libraries for common use cases

• Installation
• Quick Start
• Usage
• Examples
• Building from Source
• Pattern Files
• License

Add the tap (one-time setup):

brew tap aegoroff/tap

Install grok:

brew install aegoroff/tap/grok

Update grok:

brew upgrade aegoroff/tap/grok

scoop bucket add aegoroff https://github.com/aegoroff/scoop-bucket.git
scoop install grok

Install the binary package:

yay -S grok-tool-bin

If the package is not found, update repository information:

yay -Syyu grok-tool-bin

1. Download pre-compiled binaries from the releases page
2. Extract and copy the executable to your desired location
3. Linux: Copy *.patterns files to /usr/share/grok/patterns (create the directory if it doesn't exist)
4. Other platforms: Place *.patterns files in the same directory as the executable

List all available pattern macros:

grok macro

View the regular expression for a specific macro:

grok macro UNIXPATH

Match a string:

grok string -m EMAILADDRESS "user@example.com"

Search in a file:

grok file -m SYSLOGBASE /var/log/system.log

Pipe from stdin:

cat /var/log/system.log | grok stdin -m SYSLOGBASE

grok <COMMAND> [OPTIONS]

Run grok <command> -h or grok <command> --help for detailed help on any command.

• -p, --patterns=<patterns>... - One or more pattern files. If not set, current directory is used to search for all *.patterns files
• -m, --macro=<STRING> - Pattern macro to build regexp (required for string, file, and stdin commands)
• -i, --info - Output matched string with additional information (captured groups, etc.)
• -j, --jsonl - Output matched strings in JSONL (Newline delimited JSON) format
• -v, --invert-match - Select non-matching lines (invert match)
• -h, --help - Print help and exit

Match a single string against a grok pattern.

grok string [OPTIONS] <STRING>

Arguments:

• STRING - String to match

Example:

grok string -m EMAILADDRESS "user@example.com"

Search for patterns in a file.

grok file [OPTIONS] <PATH>

Arguments:

• PATH - Full path to file to read data from

Options:

• -c, --count - Print only the number of matched lines
• -n, --line-number - Print line numbers with matching lines
• -v, --invert-match - Select non-matching lines (invert match)

Example:

grok file -m SYSLOGBASE /var/log/system.log

Process input from standard input (pipes, redirects, etc.).

grok stdin [OPTIONS]

Example:

cat /var/log/system.log | grok stdin -m SYSLOGBASE

Options:

• -c, --count - Print only the number of matched lines
• -n, --line-number - Print line numbers with matching lines
• -v, --invert-match - Select non-matching lines (invert match)

Display macro information or list all available macros.

grok macro [OPTIONS] [MACRO]

Arguments:

• MACRO - (Optional) Macro name to expand to its real regular expression

Examples:

# List all available macros
grok macro

# Show the regexp for a specific macro
grok macro UNIXPATH

Output all possible macro names (to pass as -m parameter):

grok macro

Output the regular expression that a macro will be expanded to:

grok macro UNIXPATH

Output:

(?>/(?>[\w_%!$@:.,-]+|\\.)*)+

Match an email address:

grok string -m EMAILADDRESS "user@example.com"

With info mode to see captured groups:

grok string -m EMAILADDRESS -i "user@example.com"

Search for syslog entries in a log file:

grok file -m SYSLOGBASE /var/log/system.log

With info mode to see line numbers and captured groups:

grok file -m SYSLOGBASE -i /var/log/system.log

Same as above but reading from stdin:

cat /var/log/system.log | grok stdin -m SYSLOGBASE

Or with a pipe:

tail -f /var/log/system.log | grok stdin -m SYSLOGBASE

Specify custom pattern files:

grok file -p /path/to/custom.patterns -m MYCUSTOMPATTERN /path/to/file.log

Multiple pattern files:

grok file -p patterns/custom.patterns -p patterns/webservers.patterns -m APACHELOG access.log

Select non-matching lines (like grep -v):

# Show lines that do NOT match the pattern
grok file -m SYSLOGBASE -v /var/log/system.log

Combine with other options:

# Show line numbers for non-matching lines
grok stdin -m SYSLOGBASE -n -v < logfile.txt

Output matched strings in JSONL (Newline delimited JSON) format:

grok stdin -m SYSLOGBASE -j < /var/log/system.log

This format is useful for further processing with tools like jq:

grok stdin -m SYSLOGBASE -j < /var/log/system.log | jq .

• Zig compiler (version 0.16.0 or compatible)
• flex (or win_flex on Windows)
• bison (or win_bison on Windows)
• PCRE2 library (automatically handled by Zig package manager)
• Optional: mise for managing Zig version and build tasks
• Optional: just for running build commands

1. Clone the repository:

git clone https://github.com/aegoroff/grok.git
cd grok

2. (Optional) Install the correct Zig version using mise:

mise install

3. Build the project:

mise exec zig@0.16.0 -- zig build

Or using just:

just build ReleaseFast

The executable will be in zig-out/bin/.

4. Run tests:

mise exec zig@0.16.0 -- zig build test

Or using just:

just test

5. Create a release archive:

mise exec zig@0.16.0 -- zig build archive -Dversion=1.0.0

The project supports cross-compilation. Use just to build for all platforms:

just build_all 0.4.0-dev

Or build manually for specific targets:

mise exec zig@0.16.0 -- zig build archive -Dtarget=x86_64-linux-musl -Dversion=1.0.0
mise exec zig@0.16.0 -- zig build archive -Dtarget=aarch64-linux-musl -Dversion=1.0.0
mise exec zig@0.16.0 -- zig build archive -Dtarget=x86_64-macos-none -Dversion=1.0.0
mise exec zig@0.16.0 -- zig build archive -Dtarget=aarch64-macos-none -Dversion=1.0.0
mise exec zig@0.16.0 -- zig build archive -Dtarget=x86_64-windows-gnu -Dversion=1.0.0
mise exec zig@0.16.0 -- zig build archive -Dtarget=aarch64-windows-gnu -Dversion=1.0.0

Grok uses pattern files (.patterns) that define named macros. The project includes several built-in pattern files:

• grok.patterns - Common patterns (numbers, strings, paths, etc.)
• linuxsyslog.patterns - Linux syslog patterns
• webservers.patterns - Web server log patterns
• custom.patterns - Custom patterns

Pattern files use a simple syntax:

MACRONAME regexp

Macros can reference other macros using %{MACRONAME:fieldname} syntax.

You can also create your own pattern files and specify them with the -p option.

Copyright (c) 2018-2026 Alexander Egorov

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.