Skip to content
fsuite

📖 fread

Budgeted reading with symbol + line-range resolution

Section titled “Budgeted reading with symbol + line-range resolution”

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

Help output

Section titled “Help output”

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

fread — budgeted file reading with line numbers, token estimates, and pipeline integration.


USAGE
  fread <file>                                   Read file (capped)
  fread <file> --symbol authenticate             Read one exact symbol block
  fread <dir> --symbol authenticate              Resolve one exact symbol within a directory scope
  fread <file> -r 120:220                        Line range
  fread <file> --head 50                         First N lines
  fread <file> --tail 30                         Last N lines
  fread <file> --around-line 150 -B 5 -A 10      Context around line
  fread <file> --around "pattern" -B 5 -A 10     Context around literal pattern
  fread --paths "~/.codex/auth.json,~/.config/codex/auth.json"   Try paths in order
  ... | fread --from-stdin --stdin-format=paths
  git diff | fread --from-stdin --stdin-format=unified-diff -B 3 -A 10


OPTIONS
  --paths P1,P2,...           Comma-separated file paths to try in order (first existing wins)
  -r, --lines START:END       Line range (1-based, inclusive)
  --head N                    Read first N lines
  --tail N                    Read last N lines
  --around-line N             Context around specific line number
  --around PATTERN            Context around first literal pattern match
  --all-matches               With --around: include all matches up to caps
  --symbol NAME               Read exactly one exact symbol match within file or directory scope
  -B, --before N              Lines before (default 5)
  -A, --after N               Lines after (default 10)
  --max-lines N               Cap total emitted lines (default 200)
  --max-bytes N               Cap total emitted bytes (default 50000)
  --token-budget N            Cap by estimated tokens (conservative bytes/3)
  --max-files N               Cap files from stdin paths mode (default 10)
  --from-stdin                Read input from stdin
  --stdin-format FMT          Required with --from-stdin: paths|unified-diff
  --force-text                Read even if binary is detected
  -o, --output FMT            pretty (default), json, paths
  -q, --quiet                 Suppress pretty headers
  --project-name NAME         Override telemetry project name
  --self-check                Verify dependencies
  --install-hints             Print install commands
  --version                   Print version
  -h, --help                  Show help


NOTES
  Budget precedence: token_budget > max_bytes > max_lines
  --symbol is strict: exactly one exact symbol match succeeds; ambiguous or missing matches fail
  --stdin-format=unified-diff reads NEW-side hunk ranges from +++ path and @@ +start,count

See also

Section titled “See also”