fff-cli

CLI file search tools using @ff-labs/fff-node library part of the amazing fff - file search library. The tools can be used in Daemon Mode, or (much less efficient, but compatible) Standalone (Non-Daemon) Mode.

Tools

Command	Purpose
ffgrep	Content search: regex and literal grep with frecency ranking
fffind	Fuzzy file finder: search by path with frecency ranking
fff-multi-grep	SIMD multi-pattern OR search (Aho-Corasick)
fff-daemon	Long-running indexer + IPC server for instant queries

Installation

Global install (recommended)

npm install -g @ff-labs/fff-node
# Clone or copy this fff-cli directory anywhere
node fff-cli/bin/ffgrep --help

Or put bin/ on your PATH

export PATH="$PATH:/path/to/fff-cli/bin"
ffgrep "console.log" --base ~/my-project

Or symlink individual tools

The scripts resolve their internal modules relative to their real source directory, so symlinking works at any depth:

ln -s /projects/fff-cli/bin/ffgrep ~/.local/bin/ffgrep
ln -s /projects/fff-cli/bin/fffind ~/.local/bin/fffind
ln -s /projects/fff-cli/bin/fff-multi-grep ~/.local/bin/fff-multi-grep
ln -s /projects/fff-cli/bin/fff-daemon ~/.local/bin/fff-daemon

@ff-labs/fff-node resolution

The tools auto-discover @ff-labs/fff-node via:

1. FFF_NODE_PATH env var (highest priority)
2. Direct dependency in node_modules
3. Through @ff-labs/pi-fff dependency
4. npm config get prefix global path
5. Common global npm paths (/usr/local/lib/node_modules, ~/.npm-global, etc.)

Set it explicitly if FFF is installed somewhere unusual:

export FFF_NODE_PATH=/custom/path/@ff-labs/fff-node/dist/src/index.js

Quick Reference

fff-daemon

Usage: fff-daemon [directory|command] [options]

Server mode:
  fff-daemon               Start daemon for current directory
  fff-daemon ~/my-project  Start daemon for specific directory

Client control commands:
  fff-daemon scan          Trigger a rescan in the running daemon
  fff-daemon health        Show daemon status
  fff-daemon watch-on      Start watching for file changes
  fff-daemon watch-off     Stop watching for file changes
  fff-daemon shutdown      Stop the running daemon

Options:
  --sock <path>                     Socket (default: $FFF_DAEMON_SOCK or /tmp/fff.sock)
  --disable-watch                   Disable file watching
  --ai-mode                         Enable AI-agent optimizations

Advanced Options (see documentation for details):
  --frecency-db <path>              Frecency DB
  --history-db <path>               History DB
  --log-file-path <path>            Tracing log file path
  --log-level <level>               trace | debug | info | warn | error
  --cache-budget-max-files <n>      Cache file-count cap (0 = auto)
  --cache-budget-max-bytes <n>      Cache byte cap (0 = auto)
  --cache-budget-max-file-size <n>  Cache per-file byte cap (0 = auto)
  --disable-content-indexing        Reduces memory but cripples ffgrep
  --disable-mmap-cache              Very slow ffgrep; and disables content indexing

  --help                            Show this message

ffgrep

Usage: ffgrep <pattern> [options]
Options:
  -c, --constraints <...>   Path filter constraints
  -i, --ignore-case         Case-insensitive (default: smartCase)
  -e, --regex               Force regex
      --literal             Force literal
      --context <N>         Context lines before and after each match
  -b, --before-context <N>  Lines before each match
  -a, --after-context <N>   Lines after each match
  -l, --limit <N>           Max matches per file (default: 50, max 100)
  -p, --page-size <N>       Number of matched lines per page (default: 50)
  -n, --cursor <id>         Page number (default: 1)
  -s, --sock <path>         Daemon socket (default: $FFF_DAEMON_SOCK or /tmp/fff.sock)

Standalone Options (Non-Daemon mode):
      --base <path>         Base directory (forces standalone mode)
      --frecency-db <path>  Frecency DB
      --history-db <path>   History DB

      --help                Show this message

fffind

Usage: fffind <pattern> [options]
Options:
  -c, --constraints <...>   Path filter constraints
  -l, --limit <N>           Max results per page (default: 30)
  -p, --page-size <N>       Alias for --limit (default: 30)
  -n, --cursor <id>         Page number (default: 1)
  -s, --sock <path>         Daemon socket (default: $FFF_DAEMON_SOCK or /tmp/fff.sock)

Standalone Options (Non-Daemon mode):
      --base <path>         Base directory (forces standalone mode)
      --frecency-db <path>  Frecency DB
      --history-db <path>   History DB

      --help                Show this message

fff-multi-grep

Usage: fff-multi-grep <p1,p2,...> [options]
Options:
  -c, --constraints <...>   Path filter constraints
  -i, --ignore-case         Case-insensitive (default: smartCase)
      --context <N>         Lines before and after each match
  -b, --before-context <N>  Lines before each match
  -a, --after-context <N>   Lines after each match
  -l, --limit <N>           Max matches per file (default: 50, max 100)
  -p, --page-size <N>       Number of matched lines per page (default: 50)
  -n, --cursor <id>         Page number (default: 1)
  -s, --sock <path>         Daemon socket (default: $FFF_DAEMON_SOCK or /tmp/fff.sock)

Standalone Options (Non-Daemon mode):
      --base <path>         Base directory (forces standalone mode)
      --frecency-db <path>  Frecency DB
      --history-db <path>   History DB

      --help                Show this message

Full docs

• docs/fff-daemon.md
• docs/ffgrep.md
• docs/fffind.md
• docs/fff-multi-grep.md

Environment variables

Variable	Effect
FFF_FRECENCY_DB	Frecency database directory
FFF_HISTORY_DB	Query history database directory
FFF_CURSORS_DIR	Cursor JSON storage directory (default: ~/.local/cache/fff/cursors)
FFF_DAEMON_SOCK	Unix socket path for fff-daemon (default: /tmp/fff.sock)
FFF_NODE_PATH	Override @ff-labs/fff-node module path

Acknowledgements

Thanks fff