Cheat Sheet

Copy-paste ready. Every command runs headless (no prompts, no TTY needed) unless marked Interactive. Agents: this page is the canonical scrape target. Section anchors match tool names.

fs ftree fls fsearch fcontent fmap fread fedit fwrite fbash fcase freplay fprobe fmetrics

How to read this page

Each tool block has three parts: drone profile (one-line role · classification · chain position), commands table (every canonical invocation), and terminal sample (Monokai-print of real output as the agent sees it).

⚠ MCP CALLERS — READ THIS FIRST

If you call fsuite tools through the MCP server, every call is sequential — the MCP protocol does not pipe. You’ll get correct results, but you’ll lose the parallelism that makes Unix pipes fast.

For full performance, install fsuite as a native CLI (Debian package or shell scripts) and pipe directly: fsearch -o paths ‘*.py’ | fmap -o json. You can keep fbash as your MCP entry point and have the agent call other fsuite tools through it via shell — that’s how you unlock combination calls instead of being trapped in sequential MCP.

fs

fsUnified search orchestrator · the front door

RoleRECON

Chain position1 (entry)

Auto-routes tofsearch · fcontent · fmap

MCPstructured output

Call	What it does
`fs "authenticate"`	Unified search — scouts, finds, maps, returns ranked results in one call
`fs "error handler" --scope '*/.py'`	Narrow the search surface to a glob
`fs "class AuthHandler" --intent symbol`	Force symbol-name intent over auto-detection
`fs "TODO" --intent content`	Force in-file text content intent
`fs "*.log" --intent file`	Force file-name pattern intent
`fs "def authenticate" -o json`	JSON with ranked hits, tool breakdown, confidence

fs(teleport) · symbol intent · 328ms · ~80 tokens

● Now let me find the teleport code and the Telegram agent:
·
fs(teleport | path: “/home/user/Projects/nightfox/src” | intent: “symbol” | scope: “*.ts”)
└─ symbol (high) via fsearch → fcontent → fmap
explicit intent=symbol
50 candidates, 1 enriched, 328ms
·
nightfox/src/claude/command-parser.ts (1 matches)
50  · ‘/teleport’  // Move session to terminal (forked)
·
next → fread(path: “/home/user/…/command-parser.ts”, around: teleport)
·

ftree

ftreeTerritory scout · directory recon

RoleRECON

Chain position2 (scout)

Pipenot chainable (arg-based)

Outputpretty · paths · json

Command	What it does
`ftree /project`	Tree view, depth 3, default excludes, 200-line cap
`ftree --recon /project`	Recon: per-dir item counts and sizes
`ftree -L5 /project/src`	Deeper tree (depth 5) of a subdir
`ftree -o json /project`	Structured JSON tree with metadata envelope
`ftree -o paths /project`	Flat file list, one per line
`ftree --recon -o json /project`	Recon JSON: per-dir inventory
`ftree --snapshot /project`	Recon inventory + tree excerpt in one output
`ftree --snapshot -o json /project`	Snapshot JSON: recon + tree, agent-ready
`ftree --recon --hide-excluded /project`	Clean recon, no excluded summaries
`ftree --include .git /project`	Show `.git` even though normally ignored
`ftree -I 'docs\|*.md' /project`	Exclude additional patterns
`ftree --no-default-ignore /project`	Disable built-in ignore list
`ftree --self-check`	Verify tree availability

fls

flsStructured directory listing · ls replacement with recon mode

RoleRECON

Chain positionspecialist

Pipenot chainable

Outputpretty · json

Command	What it does
`fls /project`	Structured listing with type, size, language hints
`fls /project --recon`	Adds per-entry recon data — sizes + counts
`fls /project -o json`	JSON for programmatic decisions
`fls /project --depth 1`	Limit recursion depth

fls(/project/src/telegram) · recon mode

fls(“/home/user/Projects/nightfox/src/telegram” | mode: “recon”)
└─ Recon(/home/user/Projects/nightfox/src/telegram, depth=1)
7 entries (7 visible, 0 default-excluded)
·
message-sender.ts          —    17.9K
telegraph.ts               —    12K
terminal-renderer.ts       —    10.3K
markdown.ts                —    6.7K
terminal-settings.ts       —    2.8K
session-lane.ts            —    1.2K
deduplication.ts           —    1005
·

fsearch

fsearchFilename / path search · fd-aware

RoleNARROW

Chain position3 (narrow files)

Pipeproducer (-o paths)

Outputpretty · paths · json

Command	What it does
`fsearch '*.log' /var/log`	Find all `.log` files (pretty output)
`fsearch log /var/log`	Bare word `log` auto-expands to `*.log`
`fsearch 'upscale*' /home/user`	Files starting with `upscale`
`fsearch 'progress' /home/user`	Files containing `progress`
`fsearch --output paths '*.py' /project`	One path per line — pipe currency
`fsearch --output json '*.conf' /etc`	JSON with `total_found`, `results[]`, `backend`
`fsearch --include 'src' --exclude 'test' '*.py' /project`	Scope to source, skip tests
`fsearch --max 10 '*.py' /project`	Limit to first 10 results
`fsearch --backend fd '*.rs' /src`	Force `fd` backend (faster)
`fsearch --self-check`	Show available backends

fcontent

fcontentBounded content search · token-capped ripgrep

RoleNARROW

Chain position3 (narrow content)

Pipeproducer + consumer

Outputpretty · paths · json

Command	What it does
`fcontent "ERROR" /var/log`	Search for `ERROR` inside files
`fcontent "TODO" /project`	Find every `TODO` in a project tree
`fcontent --output paths "ERROR" /var/log`	Only file paths that matched
`fcontent --output json "ERROR" /var/log`	JSON with `matches[]`, counts
`fcontent -m 20 "debug" /project`	Cap output to 20 match lines
`fcontent -n 50 "debug" /project`	Cap to 50 files searched
`fcontent --rg-args "-i" "error" /var/log`	Case-insensitive
`fcontent --rg-args "-w" "main" /project`	Whole-word match

fmap

fmapSymbol cartography · the keystone — the gap native CLI doesn’t fill

RoleKEYSTONE

Chain position4 (bridge to read)

Pipeconsumer (stdin paths)

Languages50+

Command	What it does
`fmap /project`	Map all source files (pretty output)
`fmap /project/src/auth.py`	Map a single file
`fmap -o json /project`	JSON output with symbol metadata
`fmap --name authenticate -o json /project`	Filter by symbol-name match
`fmap -o paths /project`	File paths that contain symbols
`fmap -t function /project`	Functions only
`fmap -t class /project`	Classes only
`fmap --no-imports /project`	Skip import lines
`fmap -L bash /project/scripts`	Force language
`fmap -m 50 /project`	Cap shown symbols
`fsearch -o paths '*.py' /project \| fmap -o json`	Pipeline: find then map

fmap(reconciler.ts) · 27 symbols · typescript ~98K tokens saved vs cat

fmap(path: “/home/user/Projects/brane-code/src/ink/reconciler.ts”)
[ 27 symbols | typescript ]
3    import     import { appendFileSync } from ‘fs’
4    import     import createReconciler from ‘react-reconciler’
5    import     import { getYogaCounters } from ‘src/native-ts/yoga-layout/index’
24   import     import { Dispatcher } from ’./events/dispatcher.js’
28   import     import applyStyles, { type Styles, type TextStyles } from ’./styles’
60   type       type AnyObject = Record<string, unknown>
92   function   const diff = (before: AnyObject, after: AnyObject): AnyObject
95   function   const cleanupYogaNode = (node: DOMElement | TextNode): void
114  function   function setEventHandler(node: DOMElement, key: string, value: unknown)
158  function   export function getOwnerChain(fiber: unknown): string[] {
191  constant   const COMMIT_LOG = process.env.CLAUDE_CODE_COMMIT_LOG
205  export     export function recordYogaMs(ms: number): void
217  function   export function resetProfileCounters(): void
·

fread

freadBudgeted reading · symbol & line-range resolution · PDF + image media

RoleREAD

Chain position5 (read)

Pipeconsumer (—from-stdin)

MediaPDF · image · diff

Command	What it does
`fread /path/to/file.py`	Read a file with default caps
`fread /path/to/file.py -r 120:220`	Precise inclusive line range
`fread /path/to/file.py --head 50`	First 50 lines
`fread /path/to/file.py --tail 40`	Last 40 lines
`fread /path/to/file.py --around-line 150 -B 5 -A 15`	Context around line 150
`fread /path/to/file.py --around "def authenticate" -B 5 -A 20`	Context around literal pattern
`fread /path/to/file.py --symbol authenticate -o json`	One exact symbol block
`fread /project/src --symbol authenticate -o json`	Resolve & read symbol from a directory
`fread /path/to/file.py --max-lines 80 --max-bytes 12000`	Hard output budgets
`fread /path/to/file.py --token-budget 2000 -o json`	Cap by estimated tokens
`fsearch -o paths '*.py' /p \| fread --from-stdin --stdin-format=paths --max-files 5`	Read first 5 from a pipeline
`git diff \| fread --from-stdin --stdin-format=unified-diff -B 3 -A 10`	Read context around hunks
`fread screenshot.png`	Read image with auto-resize
`fread invoice.pdf`	Extract PDF text
`fread paper.pdf --render --pages 1:5`	Rasterize PDF pages
`fread big.pdf --meta-only`	PDF metadata only

fread(—around teleport) · 66 lines · -829 tokens vs full read

fread(/home/user/Projects/nightfox/src/discord/commands/teleport.ts | head: 80)
[ 66 lines | -829 tokens ]
1  import { ChatInputCommandInteraction } from ‘discord.js’;
2  import { discordChatId } from ’../id-mapper.js’;
3  import { sessionManager } from ’../../claude/session-manager.js’;
4  import { config } from ’../../config.js’;
5  import path from ‘path’;
6
7  export async function handleTeleport(interaction: ChatInputCommandInteraction): Promise<void> {
8     const chatId = discordChatId(interaction.user.id);
9
10 // Try active in-memory session first, then fall back to most recent from history
11 let session = sessionManager.getSession(chatId);
12 if (!session) {
13    session = sessionManager.resumeLastSession(chatId) ?? undefined;
14 }
·

fedit

feditSurgical patches · line-range · symbol-scoped · anchor-based

RolePATCH

Chain position7 (act)

Defaultdry-run (CLI)

Guard—expect · —expect-sha256

Command	What it does
`fedit /path/file.py --replace 'old' --with 'new'`	Preview exact replacement (dry-run)
`fedit /path/file.py --replace 'old' --with 'new' --apply`	Apply the replacement
`fedit /path/file.py --lines 71:73 --with " return deny()\n"`	Replace a specific line range
`fedit /path/file.py --after 'def authenticate(user):' --content-file patch.txt`	Insert after anchor
`fedit /path/file.py --before 'return True' --stdin --apply`	Insert from stdin before anchor
`fedit /path/file.py --symbol authenticate --replace 'X' --with 'Y'`	Symbol-scoped patch
`fedit /path/file.py --function authenticate --replace 'X' --with 'Y'`	Function-scoped (no —symbol-type needed)
`fedit /path/file.py --class AuthHandler --after '...' --with '...'`	Class-block scoped
`printf '/a.py\n/b.py\n' \| fedit --targets-file - --targets-format paths --replace 'x' --with 'y'`	Batch from stdin
`fedit --targets-file map.json --targets-format fmap-json --function auth --replace 'X' --with 'Y' --apply`	Symbol-scoped batch via fmap JSON
`fedit /path/file.py --expect 'def authenticate' --replace 'X' --with 'Y'`	Require expected text first
`fedit /path/file.py --expect-sha256 HASH --replace 'X' --with 'Y' --apply`	Guard with content hash
`fedit --create /path/new.py --content-file body.txt --apply`	Create new file from payload
`fedit --replace-file /path/file.py --content-file rewrite.txt --apply`	Replace entire file

fwrite

fwriteAtomic file creation · MCP-only

RolePATCH

AvailableMCP only (no CLI)

Use forcreate or full rewrite

Use fedit forsurgical changes

MCP-only tool. Not available as a CLI binary. Call via the fsuite MCP server. Writes or overwrites a file from a string payload. Use fedit for surgical patches; fwrite for complete file creation or full rewrites.

fbash

fbashToken-budgeted shell · classification · session state · MCP entry point

RoleEXEC

Chain positionspecialist

MCP advantageshells out to all CLI tools

Outputbudgeted · classified

The MCP escape hatch. When you’re calling fsuite through MCP and feel sequential limits biting, route through fbash and run real Unix pipes inside it: fbash "fsearch -o paths '*.py' src | fmap -o json". You get pipe-speed inside an MCP-friendly tool.

fcase

fcaseInvestigation continuity ledger · cross-session state machine

RoleSTATE

Chain positionwraps every chain

Lifecycleinit → note → handoff → resolve

Storage~/.fsuite/fcase.db

Command	What it does
`fcase init auth-seam --goal "Trace authenticate flow"`	Create a new investigation
`fcase list -o json`	List known cases
`fcase status auth-seam -o json`	Read current case state
`fcase note auth-seam --body "Focused on denial branch"`	Append a note
`fcase target add auth-seam --path /p/src/auth.py --symbol authenticate --symbol-type function --state active`	Mark a seam as active
`fcase evidence auth-seam --tool fread --path /p --lines 40:72 --summary "..."`	Store structured proof
`fcase hypothesis add auth-seam --body "Cleanup bug in cancellation"`	Track a hypothesis
`fcase reject auth-seam --hypothesis-id 1 --reason "..."`	Reject a hypothesis
`fmap -o json /p \| fcase target import auth-seam`	Import mapped symbols as targets
`fread -o json /p --around "def auth" -A 20 \| fcase evidence import auth-seam`	Import bounded reads
`fcase next auth-seam --body "Patch denial branch next"`	Update next best move
`fcase handoff auth-seam -o json`	Emit handoff packet
`fcase export auth-seam -o json`	Export full envelope

freplay

freplayDerivation chain replay · deterministic rerun

RoleREPLAY

Chain positionspecialist

Pairs withfcase

Use forpost-mortems · regression

Command	What it does
`freplay record auth-seam --purpose "Traced denial" -- fread /p --around 'def auth'`	Record a derivation step
`freplay record auth-seam -- fcontent -o paths "auth" src`	Record without purpose annotation
`freplay show auth-seam`	Show full replay chain
`freplay show auth-seam -o json`	Machine-readable chain w/ timestamps
`freplay list`	List cases with replay chains
`freplay list -o json`	JSON list with step counts

fprobe

fprobeBinary / bundle inspection + patching · text tools can’t reach

RoleBINARY

Chain positionspecialist branch

Use whentarget is compiled or obfuscated

Subcommandsstrings · scan · window · patch

Command	What it does
`fprobe strings /path/to/binary`	Extract printable strings
`fprobe strings /path --min-len 8`	Strings 8+ chars
`fprobe strings /path --filter "http"`	Strings containing literal substring
`fprobe scan /path --pattern "userFacingName"`	Find literal byte pattern (offset + context)
`fprobe scan /path --pattern "x" --context 200 -o json`	JSON with offset, hex, surrounding bytes
`fprobe window /path --offset 0x100 --after 256`	Read 256 bytes after offset
`fprobe window /path --offset 0x100 --before 64 --after 256`	Read bytes before + after
`fprobe window /path --offset 0x100 --after 256 --decode hex`	Hex dump

fmetrics

fmetricsTelemetry analytics · tool-chain prediction

RoleLEARN

Chain positionspecialist

StorageSQLite

Use forpredict best next step

Command	What it does
`fmetrics import`	Import `telemetry.jsonl` into SQLite
`fmetrics stats`	Aggregate runtime + reliability dashboard
`fmetrics stats -o json`	Machine-readable stats
`fmetrics history --tool ftree --limit 10`	Recent runs for one tool
`fmetrics history --project MyApp`	Filter by project
`fmetrics combos --project fsuite`	Evidence-backed combo patterns
`fmetrics combos --starts-with ftree,fsearch --contains fmap -o json`	Filter combo analytics
`fmetrics recommend --after ftree,fsearch --project fsuite`	Suggest the strongest next step
`fmetrics predict /project`	Estimate runtimes
`fmetrics profile`	Show machine profile
`fmetrics clean --days 30`	Prune old telemetry

Canonical pipelines

Workflow	Command chain
Full scout	`ftree --snapshot -o json /project`
Find + map	`fsearch -o paths '*.py' /p \| fmap -o json`
Find + grep	`fsearch -o paths '*.log' /var/log \| fcontent "ERROR"`
Find + read	`fsearch -o paths '*.py' /p \| fread --from-stdin --stdin-format=paths --max-files 5 -o json`
Map + read	`fmap --name auth -o json /p \| fread --symbol auth -o json`
Binary recon	`fprobe scan /bin && fprobe strings /bin --filter "http"`
Investigation	`fcase init seam --goal "..." && fmap -o json /p \| fcase target import seam && fcase handoff seam -o json`
Batch patch	`fsearch -o paths '*.py' /p \| fedit --targets-file - --targets-format paths --replace 'x' --with 'y' --apply`
Git diff read	`git diff \| fread --from-stdin --stdin-format=unified-diff -o json`

MCP vs CLI — pipe semantics

Mode	Pipe behavior	Performance
CLI (Debian / shell)	Real Unix pipes, parallel where possible	Fastest
CLI inside `fbash` (MCP)	Real pipes inside the budgeted shell	Fast — MCP escape hatch
Pure MCP tool calls	Sequential, agent constructs chain by hand	Correct, slower

The MCP adapter handles -o json automatically — agents always get structured JSON back regardless of mode.