Technical Reference

This is the precise reference for Grex’s UI commands, patterns, files, settings, outputs, and limits. See Usage for guided workflows and Architecture for implementation flow.

Keyboard and pointer commands

Path forms

The CLI validates Directory.Exists before invoking the search service. Use WSL UNC paths with the CLI; a raw /home/... path is not a Windows directory and fails CLI validation.

Match Files syntax

Match Files compares only the filename, case-insensitively.

Examples:

Use |, not semicolons.

Exclude Dirs syntax

Exclude Dirs supports:

1. comma-separated directory names, such as .git,node_modules,vendor;
2. a case-insensitive Regex matched against each path component and the relative directory path.

Use an anchored expression to make Regex intent explicit:

^(.git|node_modules|vendor)$

The UI rejects obviously invalid Regex-like input. The local engine falls back to comma-name handling if Regex construction fails.

.gitignore behavior

Local Windows and mirror searches use GitIgnoreService, which supports:

• comments and blank lines;
• negation;
• root-relative patterns;
• directory-only patterns;
• *, ?, **, and bracket patterns;
• nested .gitignore files.

The parser caches at most 100 entries and evicts half when over capacity. Ignore-rule Regex operations use a 5-second timeout.

Target differences:

• WSL at a Git root uses git grep, which searches files visible to Git. Otherwise WSL uses normal find/grep.
• Direct Docker reads only <search-root>/.gitignore, uses simplified wildcard matching, and ignores negation.
• Docker mirror fallback uses the local parser on the copied tree.

System path exclusions

When Include system files is off, local search excludes Windows System attributes and any path component or path pair below:

Hidden filtering is separate. With Include hidden items off, Grex skips the Windows Hidden attribute and dot-prefixed files or directory components.

Size filter tolerances

The local engine applies:

• Less Than: size < limit + tolerance
• Equal To: abs(size - limit) <= tolerance
• Greater Than: size > limit - tolerance

WSL maps size to find -size, whose boundary behavior can differ. Direct Docker search does not apply size.

The CLI passes the numeric size and selected unit directly to the search service. For example, --size-limit 2 --size-unit MB means 2 MB.

Text comparison

StringComparisonMode

Case sensitivity selects the matching sensitive/insensitive form.

UnicodeNormalizationMode

When diacritic sensitivity is off, Grex decomposes text and removes non-spacing marks before comparison.

These settings affect local plain-text matching. Regex, WSL grep, and direct Docker grep do not use the full comparison pipeline.

Regex behavior

User-supplied .NET patterns use RegexOptions.None plus optional IgnoreCase, never RegexOptions.Compiled.

An invalid search Regex reports an error. An invalid result-filter Regex displays all current results until valid.

Searchable documents and binary formats

The local extractor recognizes:

This is not OCR or full document parsing. Password-protected, scanned, heavily compressed, or unusual documents may not match.

Known binary extensions that remain excluded include legacy Office (.doc, .xls, .ppt), images, media, executables, libraries, and most archive types.

Replacement does not reconstruct these formats. Replace skips known binary, archive, and document extensions even when binary search is enabled.

Encoding detection

Encoding detection reads at most 65,536 bytes and uses:

1. BOM detection;
2. candidate decoding and statistical scoring;
3. Shift-JIS, Chinese, Korean, and Cyrillic-oriented heuristics;
4. UTF-8 fallback.

Built-in Unicode candidates are UTF-8, UTF-16 LE/BE, and UTF-32 LE. The service also attempts to load UTF-32 BE, ISO-8859 variants, Windows-125x, Shift-JIS, GB2312/GBK, Big5, EUC-KR, and KOI8-R/U. Availability depends on the encoding providers registered by the runtime.

WSL and direct Docker results report UTF-8-oriented content rather than running the full local detector.

Results

Content row

Match previews are capped at 400 characters. Extracted archive/PDF display lines are capped at 500 characters plus an ellipsis.

Files row

Result export

GUI export uses the currently displayed result mode and filter:

• Content CSV/JSON/clipboard: name, line, column, content, relative path, full path, and match count
• Files CSV/JSON/clipboard: name, size, match count, relative path, full path, extension, encoding, and modified time

Clipboard output is tab-separated.

User data and files

No search index or result database is persisted by Grex.

Settings schema

%LocalAppData%\Grex\settings.json is a JSON serialization of DefaultSettings. Enum values are numeric.

{
  "IsRegexSearch": false,
  "IsFilesSearch": false,
  "RespectGitignore": false,
  "SearchCaseSensitive": false,
  "IncludeSystemFiles": false,
  "IncludeSubfolders": true,
  "IncludeHiddenItems": false,
  "IncludeBinaryFiles": false,
  "IncludeSymbolicLinks": false,
  "UseWindowsSearchIndex": false,
  "EnableDockerSearch": false,
  "SizeUnit": 0,
  "ThemePreference": 3,
  "UILanguage": "en-US",
  "StringComparisonMode": 0,
  "UnicodeNormalizationMode": 0,
  "DiacriticSensitive": true,
  "Culture": "en-US",
  "DefaultMatchFiles": "",
  "DefaultExcludeDirs": "",
  "ContentLineColumnVisible": true,
  "ContentColumnColumnVisible": true,
  "ContentPathColumnVisible": true,
  "FilesSizeColumnVisible": true,
  "FilesMatchesColumnVisible": true,
  "FilesPathColumnVisible": true,
  "FilesExtColumnVisible": true,
  "FilesEncodingColumnVisible": true,
  "FilesDateModifiedColumnVisible": true,
  "WindowX": null,
  "WindowY": null,
  "WindowWidth": 1100,
  "WindowHeight": 700,
  "ContextPreviewLinesBefore": 5,
  "ContextPreviewLinesAfter": 5,
  "AiSearchEndpoint": "https://api.openai.com/v1",
  "AiSearchApiKey": "",
  "AiSearchModel": "gpt-4o-mini"
}

Culture defaults to the current machine culture, so it may differ from this example. Preview line values are clamped to 1 through 20 when read or written.

SizeUnit

ThemePreference

Settings write behavior

• Settings are cached in process and saved immediately after most changes.
• Missing or unreadable JSON returns defaults.
• Save failures are ignored by the service.
• Restore Defaults deletes only settings.json.
• The AI API key is plain text.

Settings backup and import

Export serializes all DefaultSettings fields, including:

• window position and size;
• AI endpoint;
• AI API key;
• AI model.

Treat exported JSON as a secret when it contains a key.

Import validates JSON and merges only fields present in the imported object. It applies every exported non-window field, including Docker enablement, default Match Files/Exclude Dirs, context-preview counts, and AI settings. Unknown fields are ignored. Invalid enum values are rejected. Window position and size remain machine-local and are never imported.

Search history schema

Each entry in search_history.json contains:

• SearchTerm, SearchPath;
• MatchFileNames, ExcludeDirs;
• IsRegexSearch, IsFilesSearch;
• SearchCaseSensitive, RespectGitignore;
• IncludeSubfolders, IncludeHiddenItems, IncludeBinaryFiles;
• Timestamp, ResultCount.

The deduplication key uses term, path, search/result modes, case sensitivity, Match Files, and Exclude Dirs.

Search profile schema

Each profile contains:

• name, path, and term;
• search and result modes;
• .gitignore, case, system, recursion, hidden, binary, link, and Windows Search flags;
• Match Files and Exclude Dirs;
• size type, value, and unit;
• string comparison, normalization, diacritic, and culture values;
• created and updated timestamps.

Profiles do not contain result rows, replacement text, or a Docker container id.

AI protocol

Endpoint construction

Grex prepends https:// when the scheme is missing and trims trailing slashes. It also accepts an explicit http:// URL, but HTTPS is strongly recommended.

Request

The chat request contains:

{
  "model": "configured-or-resolved-id",
  "temperature": 0.2,
  "messages": [
    { "role": "system", "content": "Grex assistant instructions" },
    { "role": "system", "content": "Path, query, modes, and filter suggestions" },
    { "role": "user", "content": "Conversation..." }
  ]
}

An Authorization: Bearer <key> header is added only when the key is non-empty.

Model selection

1. Use a configured non-empty model exactly.
2. Otherwise request the first data[].id from Models.
3. Fall back to gpt-4o-mini.

The resolved model is cached until the normalized endpoint changes.

Response parsing

Grex accepts:

• choices[0].message.content as a string or content-part array;
• choices[0].text;
• top-level output_text.

Structured error.message is preferred for failures. HTTP requests use a shared client with a 90-second timeout.

CLI reference

Syntax

grex-cli <path> <term> [options]

The path comes first.

Options

The short -i flag is intentionally wired to case-sensitive behavior in the current CLI, unlike GNU grep’s conventional meaning.

Invalid size units fall back to KB. Invalid size types become No Limit.

Output-mode priority is Quiet, Count, Files Only, then Format.

Examples

grex-cli "C:\repo" "TODO"
grex-cli "C:\repo" "TODO|FIXME" --regex --case-sensitive
grex-cli "C:\repo" "deprecated" --gitignore --match-files "*.cs|*.xaml"
grex-cli "C:\repo" "error" --exclude-dirs ".git,node_modules" --format json
grex-cli "C:\repo" "warning" --count
grex-cli "C:\repo" "secret" --quiet

PowerShell exit-code use:

grex-cli "C:\repo" "TODO" --quiet
if ($LASTEXITCODE -eq 0) { "Found" }
elseif ($LASTEXITCODE -eq 1) { "No match" }
else { "Search error" }

Exit codes

Text output

One line per matching source line, using a relative path:

path\file.cs:42:10:// TODO: fix this

JSON output

[
  {
    "file": "path\\file.cs",
    "line": 42,
    "column": 10,
    "content": "// TODO: fix this",
    "matchCount": 1,
    "fullPath": "C:\\repo\\path\\file.cs"
  }
]

CSV output

File,Line,Column,Content,FullPath,MatchCount
path\file.cs,42,10,// TODO: fix this,C:\repo\path\file.cs,1

Fields containing commas, quotes, or newlines are CSV-escaped. --files-only prints unique full paths rather than formatted records.

CLI boundaries

The CLI does not expose:

• Docker targets;
• Replace;
• Windows Search;
• culture, normalization, or diacritic flags;
• GUI history, profiles, preview, or export.

Operational caps

Current limitations

• Windows-only GUI and CLI
• Published release only for win-x64
• No replace undo or rollback
• No empty-string replacement through the GUI
• No Docker replacement
• Direct Docker size filtering unavailable
• Docker direct .gitignore support is partial
• WSL/Docker Regex syntax differs from .NET Regex
• Best-effort document extraction, no OCR
• No automatic updater
• Non-English localization catalogs are incomplete
• AI keys and settings exports are plain text
• CLI MB/GB size conversion issue described above