agrep

agrep is grep for Arabic-script text. It matches across spelling variants, diacritics (tashkil), letter forms, consonant skeletons (rasm), and transliterated queries, and prints the original line with the byte offsets of each match.

# Matches across diacritics, alef forms, and ta-marbuta:
agrep 'مدرسه' book.txt                         # matches مَدْرَسَة and مدرسة
agrep -r -n --include '*.txt' 'كتاب' books/    # recursive search with line numbers
agrep --translit=buckwalter 'ktAb' corpus.txt  # Latin keyboard query → كتاب
agrep --json 'احمد' people.txt                 # JSON Lines with exact byte spans

With no path, agrep reads standard input. Pass - as a path argument to mix standard input with files. Exit status follows standard grep conventions: 0 for match, 1 for no match, and 2 for an error.

Install

Quick Install (macOS, Linux, BSD)

The install script downloads the latest release binary:

curl -fsSL https://raw.githubusercontent.com/MohamedElashri/agrep/main/scripts/install.sh | bash

To install somewhere else, such as ~/.local/bin:

curl -fsSL https://raw.githubusercontent.com/MohamedElashri/agrep/main/scripts/install.sh | BINDIR=~/.local/bin bash

To install a specific release:

curl -fsSL https://raw.githubusercontent.com/MohamedElashri/agrep/main/scripts/install.sh | VERSION=v0.1.1 bash

Pre-compiled Binaries

Download archives for Linux, macOS, Windows, FreeBSD, OpenBSD, and NetBSD (amd64, arm64) from GitHub Releases, and verify hashes against checksums.txt.

Windows archives (zip) are built but untested: CI runs only on Linux, and the install script does not support Windows. Download the zip and put agrep.exe on your PATH. Reports of what works and what doesn't are welcome.

Using GitHub CLI:

gh release download -R MohamedElashri/agrep --pattern '*_linux_amd64.tar.gz' --pattern checksums.txt

Direct download (Linux amd64 example):

TAG=$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/MohamedElashri/agrep/releases/latest | sed 's#.*/##')
curl -fsSL "https://github.com/MohamedElashri/agrep/releases/download/$TAG/agrep_${TAG#v}_linux_amd64.tar.gz" | tar -xz
sudo mv agrep /usr/local/bin/

Go Toolchain

go install github.com/MohamedElashri/agrep/cmd/agrep@latest

Build from Source

git clone https://github.com/MohamedElashri/agrep.git
cd agrep && go build -ldflags="-s -w" ./cmd/agrep

Add -tags formats to include HTML and EPUB extraction. See INPUT.md.

Updating

Check for a new release or update in place:

agrep --check-update    # check if a newer release is available
agrep --update          # download, verify, and update in place
agrep --update=v0.2.0   # update or switch to a specific version

Search modes

Need	Option	Detail
Exact spelling distinctions	--profile=strict	Keeps hamza, ta-marbuta, and alef-maksura distinct
High recall / skeleton	--profile=loose or --rasm	Folds consonants to dotless skeletons
Typographical / OCR errors	--fuzzy[=N]	Levenshtein edit distance over normalized codepoints
Regular expressions	--regex	Pattern syntax evaluated over normalized text
Non-Arabic orthographies	--lang=fa, --lang=ur, etc.	Language-specific equivalences (Persian, Urdu, Kurdish)
Legacy encodings	--encoding=auto	Automatic CP1256, ISO-8859-6, and UTF-16 decoding

The matching line is always printed with its original source spelling. Emitted JSON spans and -o refer to decoded UTF-8 byte offsets in that original line.

Documentation

Topic	Document	Description
Overview & Quickstart	index.md	Introduction, architecture, and getting started guide
CLI Reference	CLI.md	Full list of flags, options, and JSON Lines format
Normalization	NORMALIZATION.md	Unicode rules and profiles (search, strict, loose, lucene, camel)
Matching Engines	MATCHING.md	Dotless rasm, Myers fuzzy Levenshtein distance, regex
Languages & Encodings	LANGUAGES.md, INPUT.md	Persian, Urdu, Kurdish orthographies and transliteration
Web Playground	PLAYGROUND.md	Live interactive demo running in WebAssembly
Benchmarks	BENCHMARKS.md	Performance metrics and comparison suites
Agent Integration	Agent Skill	Search skill for Codex and Claude Code

Go packages

The CLI is built on three Go packages: arabic for normalization, match for literal, regex, and fuzzy matchers, and scan for streaming line search. See the Go package guide.

import "github.com/MohamedElashri/agrep/arabic"

// Normalized comparison treats diacritics and letter variants as equivalent:
same := arabic.Normalize("مَدْرَسَةٌ") == arabic.Normalize("مدرسه") // true

Documentation: arabic · match · scan.

License

MIT License. See LICENSE.