📄 fcontent

Bounded content search (token-capped ripgrep)

fcontent is part of the fsuite toolkit — a set of fourteen CLI tools built for AI coding agents.

fcontent Bounded content search · token-capped ripgrep

RoleNARROW

Chain position3 (narrow content)

Pipeproducer + consumer

Outputpretty · paths · json

fcontent is ripgrep with a token budget. Same speed, same regex power, but capped output so a single grep doesn’t blow your context. Use it when you know what’s inside a file but not which file.

It’s both a producer (-o paths outputs file paths that matched) and a consumer (reads paths from stdin to narrow within a previously-filtered set). That makes it the bridge tool in 3-step chains.

Canonical chains

# Search for a literal in a project
fcontent "ERROR" /var/log

# Get only file paths that matched (pipe currency)
fcontent -o paths "TODO" /project

# Pipe to fmap — find files containing a keyword, map their symbols
fcontent -o paths "authenticate" /project | fmap -o json

# Progressive narrowing — chain two fcontents
fsearch -o paths '*.py' /project \
  | fcontent -o paths "import" \
  | fcontent "authenticate"

# Cap match output explicitly
fcontent -m 20 "debug" /project

# Case-insensitive (passthrough to ripgrep)
fcontent --rg-args "-i" "error" /var/log

Help output

The content below is the live --help output of fcontent, captured at build time from the tool binary itself. It cannot drift from the source — regenerating the docs regenerates this section.

fcontent — search inside files (uses ripgrep "rg"), agent-friendly

USAGE
  fcontent [OPTIONS] <query> [path]

MODES
  1) Directory mode:
     fcontent "needle" /some/dir
     - Searches recursively under /some/dir

  2) Piped file-list mode (best with fsearch):
     fsearch --output paths '*.log' /var/log | fcontent "ERROR"
     - Reads file paths from stdin and searches only those files

OPTIONS
  -p, --path PATH
      Directory to search (recursive). Default: current directory.
      Ignored if paths are provided via stdin.

  -o, --output pretty|paths|json
      pretty: human-readable summary + sample matches (default)
      paths:  print unique file paths that matched (one per line)
      json:   print compact JSON with match metadata (best for AI agents)

  -m, --max-matches N
      Limit number of printed matches in pretty/json output. Default: 200

  -n, --max-files N
      When reading from stdin, limit number of file paths consumed (safety). Default: 2000

  -q, --quiet
      Suppress header lines in pretty mode. Useful for scripting.

  --project-name <name>
      Override project name in telemetry.

  --rg-args "..."
      Extra arguments passed to rg (advanced).
      Example: --rg-args "-i --hidden"

  --no-default-ignore
      Disable built-in low-signal directory filtering in directory mode.
      By default, fcontent suppresses dependency/build trees such as:
        node_modules, dist, build, .next, coverage, .git, vendor, target

  --install-hints
      Print how to install rg and exit.

  --self-check
      Verify rg exists and show setup tips. Exit.

  -h, --help
      Show help and exit.

NOTES
  - This tool searches file CONTENTS, not filenames.
  - For filenames/paths, use fsearch.
  - Quote your query if it contains spaces:
      fcontent "fatal error" /path
  - If your literal query starts with '-', terminate options first:
      fcontent -o json -- '--test' /path

HEADLESS / AI AGENT USAGE
  Best outputs for agents:
    fcontent --output json "token" /path
    fcontent --output paths "ERROR" < <(fsearch --output paths '*.log' /path)

SECURITY / SUDO
  This tool does not store credentials.
  If you need to read protected files, run with sudo:
    sudo fcontent "needle" /var/log
  If installing packages, authenticate once first:
    sudo -v

📄 fcontent

Bounded content search (token-capped ripgrep)

Canonical chains

Help output

See also