Usage

On this page

Common workflows

# First-run (index + always-on global daemon service)
greplm setup

# Set up manually
greplm init             # scaffold .greplm/config.toml (no indexing yet)

# Indexing
greplm index            # incremental build/refresh
greplm index --force    # full rebuild
greplm watch            # re-index automatically on file changes
greplm clean            # remove .greplm/

# Search file contents
greplm search "tokio" --lang rust
greplm search -e 'fn .*candidates' --path crates/ --limit 20 --json
greplm search "get" --word --limit 20 --offset 20   # whole-identifier + pagination

# Symbols / definitions
greplm symbols Searcher --kind struct --exact
greplm symbols lc       # acronym match: loadConfig / load_config

# References, outlines, snippets
greplm refs SegmentWriter
greplm outline crates/greplm-core/src/trigram.rs
greplm snippet crates/greplm-core/src/trigram.rs 15 25 --context 3

# Repo info
greplm summary
greplm status

# Health check
greplm doctor           # diagnose index freshness, daemon, and version
greplm doctor --fix     # refresh a stale index and install the daemon service
greplm update --check   # see if a newer release is available

Most query commands accept --json for agent consumption and -C/--root <dir> to point at a different project. --json is compact (single-line) by default — add --pretty if you want indented output to read by eye. Set GREPLM_LOG=debug for verbose logging. See configuration for GREPLM_* environment overrides.

Warm daemon

Run a daemon to keep the index hot in memory with the watcher running; queries then drop to sub-millisecond:

greplm serve

While it’s running, query commands automatically route to it (so does the MCP server). Pass --no-daemon to force an in-process query.

The daemon is what makes greplm fast for agents. Once the index is warm the query itself costs well under a millisecond; what the daemon removes is having to open and integrity-check the index on every call, which scales with repository size — a millisecond or two on a small project, tens of milliseconds on a very large one. Keep it running so that cost is paid once, not per query.

One daemon for every project

For running many agents across many repos, use the global daemon — a single background process that serves every project on the machine over one per-user socket:

greplm serve --global

It loads each project lazily on first query (its own warm index + watcher) and evicts projects that go idle, so memory tracks only what you’re actively working on. Queries and the MCP server auto-discover the project root and route to it — no per-project setup. A per-project greplm serve still works and is tried as a fallback.

Keep it always-on

Run it as a background service that starts at login and restarts if it dies.

macOS (launchd):

contrib/launchd/install-launchd.sh --global              # one daemon for all projects (recommended)
contrib/launchd/install-launchd.sh /abs/path/to/project  # or just one project

Linux (systemd user service): contrib/systemd/greplm-global.service (all projects, recommended) or the per-project template contrib/systemd/[email protected]; each file documents its one-time systemctl --user enable --now command.

Semantic search (optional)

An optional, fully offline meaning-based search layer behind the semantic feature:

cargo build --release -p greplm-cli --features semantic
greplm semantic-index
greplm semantic-search "parse a regex into a trigram query" --limit 10