CLI Reference
One binary, every runtime: headless runs, interactive TUI, HTTP server, MCP endpoint and maintenance tools. All commands and flags of fathom.
Command overview
fathom
run Run a research task (headless)
tui Interactive TUI
serve HTTP API server + dashboard
mcp-serve Expose the agent tools over MCP (stdio)
memory Semantic memory: search / list / stats / distill / gc
sessions Browse past sessions
resume Resume an interrupted session
config Show or set configuration values
profiles List / show / create personas
contacts Contact database: list / export / dedup / push-crm
jobs Durable background jobs
bench Benchmark the tool-execution layer
stats Tool-call statistics for a recorded session run
Headless autonomous work. A coordinator decomposes the task into sub-agents, synthesizes their results and writes a structured output. The task can be passed as a positional argument [QUERY] or read from a file with –task-file. With –repeat it becomes watch mode: each run is diffed against the previous one and configured notifications can report changes.
| Flag | Description |
|---|---|
| -o, –output <DIR> | Output directory for results (default: from config) |
| –repeat <SECS> | Watch mode — re-run every N seconds, diff runs, alert on new contacts |
| –profile <NAME> | Persona: hunter | analyst | validator | a file in ~/.fathom/profiles/ | path to a .toml |
| –task-file <FILE> | Read task from a file instead of the positional argument |
fathom run "Compare Rust and Go for backend services" --output ./research/
# watch mode: re-collect every 6 hours, alert on new contacts
fathom run "Acme leadership team" --repeat 21600
# with a persona
fathom run --profile hunter "Find the CTO of Acme"tui
Interactive terminal interface (ratatui): live agent tree, streaming output, event log, jobs and memory panels, approval flow. See TUI interface for keys and panels.
| Flag | Description |
|---|---|
| [QUERY] | Optional initial query |
| –profile <NAME> | Persona applied to sessions started from the TUI |
| –replay <SESSION-ID> | Replay a stored session instead of a live run (prefix match accepted) |
fathom tui
fathom tui "Find VPs of Engineering at fintech startups" --profile analyst
fathom tui --replay 3f9c2a # browse a saved sessionserve
Axum HTTP server: session and job management, SSE event streams, memory API, Prometheus metrics and the web dashboard at /dashboard. Listens on loopback by default.
| Flag | Description |
|---|---|
| –port <PORT> | Listen port (default: 8080) |
| –host <HOST> | Bind address (default: 127.0.0.1) |
–host 0.0.0.0) requires FATHOM_API_KEYS to be set — otherwise startup is refused. Keys are passed via Authorization: Bearer or X-Api-Key. The per-client request limit is configured with FATHOM_RATE_LIMIT.fathom serve --port 8080
fathom serve --host 0.0.0.0 # requires FATHOM_API_KEYSmcp-serve
Exposes all agent tools to external MCP clients (Claude, ZCode, …) over stdio. Tool calls are executed through the same registry the agents use. Logging goes to stderr so stdout stays clean JSON-RPC.
fathom mcp-serveAdd it to your MCP client config:
{ "command": "fathom", "args": ["mcp-serve"] }memory
Maintain the long-term semantic knowledge base without running an agent: hybrid search (vectors + BM25), append-only version chains, distillation and GC. Nothing is ever silently deleted.
| Subcommand | Flags | Description |
|---|---|---|
| search <query> | –top-k (default 10), –scope agent|user|run|all | Hybrid semantic + keyword search |
| list | –scope, –status active|superseded|archived|all, -n | List stored facts, newest first |
| get <id> | –follow active|latest|full_history | One record plus its version chain |
| stats | — | Counts by scope/status, entity graph, DB size |
| rebuild | — | Re-embed all facts with the current embedding model |
| distill | –session <key>, –dry-run | Distill run-scoped session facts into durable knowledge |
| gc | –ttl-days <N>, –dry-run | Archive stale run facts, compact oversized scope groups |
| nuke | –scope, –yes | Hard-delete a scope’s records; requires explicit –yes |
fathom memory search "email of the director of Acme" --top-k 10
fathom memory list --scope agent --status active -n 20
fathom memory get 7f31 --follow full_history
fathom memory stats
fathom memory distill --dry-run
fathom memory gc --ttl-days 30 --dry-runsessions
Browse session history stored in the database.
| Subcommand | Flags | Description |
|---|---|---|
| list | -n <LIMIT> (default 20), -s, –search <SUBSTR> | Recent sessions, newest first; optional query substring filter |
| show <id> | — | One session in detail: agents + findings (unique prefix accepted) |
fathom sessions list -n 10 --search "fintech"
fathom sessions show 3f9c2aresume
Resume an interrupted session: re-runs its unfinished sub-tasks from the persisted state in .research.db.
| Flag | Description |
|---|---|
| -o, –output <DIR> | Session output directory (contains .research.db); default: configured output dir |
| -s, –session-id <ID> | Session to resume; default: the most recent interrupted one |
fathom resume --output ./results/config
Show or edit ~/.fathom/config.toml from the command line. Keys use dot notation: section.field.
fathom config show
fathom config set agent.max_depth 3
fathom config set agent.max_agents 30profiles
Personas for run –profile and tui –profile: a ready system prompt plus optional overrides for model, temperature, depth, agent count and denied tools. Built-ins: hunter, analyst, validator; your own TOML files live in ~/.fathom/profiles/.
fathom profiles list
fathom profiles show hunter
fathom profiles new my-persona # creates a template filecontacts
The OSINT contact database collected by save_contacts: list, export, deduplicate and push to the configured CRM (amoCRM, Bitrix24, HubSpot).
| Subcommand | Flags | Description |
|---|---|---|
| list | –limit (default 50) | List stored contacts |
| export | –format csv|vcf|json|xlsx (default csv), -o, –output <DIR> | Export contacts to a file |
| dedup | –merge | Find duplicates (normalized email/phone); –merge folds each group into its most complete row |
| push-crm | — | Push all stored contacts to the configured CRM |
fathom contacts list
fathom contacts export --format csv
fathom contacts dedup # dry run: list groups
fathom contacts dedup --merge # actually merge them
fathom contacts push-crmjobs
Durable background jobs in SQLite: attempts with self-healing retry (the task is re-submitted augmented with the previous error), survive restarts.
| Subcommand | Flags | Description |
|---|---|---|
| submit <task> | –attempts (default 3) | Run a task detached in the background |
| list | — | List all jobs |
| status <id> | –watch <SECS> | Detailed status; –watch refreshes until a terminal state |
| logs <id> | -n <LINES> (default 50) | stdout + stderr of all attempts |
| cancel <id> | — | Cancel a queued or running job |
| rerun <id> | — | Re-run a finished/cancelled/stale job from scratch |
fathom jobs submit "Analyze the market of AI agents" --attempts 3
fathom jobs list
fathom jobs status 9b2e --watch 5
fathom jobs logs 9b2e
fathom jobs cancel 9b2e
fathom jobs rerun 9b2ebench
Benchmark the tool-execution layer — no network, no LLM; fixtures are generated automatically. Nine scenarios cover dispatch overhead, parallel batches, parser scaling and semantic memory.
| Flag | Description |
|---|---|
| -s, –scenario <NAME> | Scenario to run (default: all) |
| -n <N> | parallel-safe calls / data files in batch scenarios (default: 16) |
| –save <FILE> | Also write the markdown report to a file |
fathom bench # all scenarios
fathom bench -s feed-parse # feed parsing (quick-xml)
fathom bench -s code-map # code_symbols / repo_map
fathom bench -s memory # absorb / search / digeststats
Per-tool call statistics — p50/p95 latencies — computed from a real recorded session (.research.db).
| Flag | Description |
|---|---|
| -o, –output <DIR> | Session output directory; default: configured output dir |
fathom stats -o ./results/worker
Internal worker mode — spawned automatically by the coordinator when use_multiprocess = true. Not intended for direct invocation.
| Flag | Description |
|---|---|
| –session-id <ID> | Session id (required) |
| –agent-id <ID> | Agent id (required) |
| –task <TEXT> | Task description (required) |
| –socket <PATH> | Unix socket path for IPC with coordinator (required) |
| –role <ROLE> | Agent role: coordinator, researcher, analyst, verifier, writer (default: researcher) |
TUI interface
The header shows the session id, elapsed time and a sparkline of token spend over the session. In replay mode the header is marked [REPLAY] and the saved agent tree loads with final statuses.
Keys
| Key | Action |
|---|---|
| q | Quit (also Ctrl+C) |
| i | Insert mode — type a query |
| Enter | Submit the query (insert mode) |
| Shift+Enter | Newline in the input |
| Esc | Leave insert mode / back to the input panel |
| Tab / BackTab | Cycle panels |
| Up / Down | Scroll — or move the agent cursor in the Agents panel; input history in the input |
| Left / Right | Collapse / expand an agent subtree (Agents panel) |
| t | Toggle the thinking panel |
| c | Clear output |
| y / n | Approve / deny a pending side-effect tool call |
| ? | Keymap help overlay |
| Ctrl+V | Paste mode (bracketed paste) |
Panels
Live agent tree: coordinator, sub-agents, statuses. Cursor navigation, subtrees collapse with Left/Right.
The final assembled output, streamed token-by-token as the writer produces it.
Event log: agent spawns, tool calls with timings, warnings and findings.
Durable background jobs submitted via jobs submit — state and attempts at a glance.
Recent records from the semantic memory store, refreshed live.
Query input with history navigation (Up/Down) and a dedicated paste mode.
Output structure
Every run writes the same layout into its output directory — plus optional PDF/HTML/JSON/DOCX exports when configured.
output/
├── index.md # table of contents + metadata
├── summary.md # final synthesis
├── findings/ # findings per subtask
│ ├── finding-1.md
│ ├── finding-2.md
│ └── finding-3.md
├── sources.md # source list
└── .research.db # session SQLite databaseCommon Workflows
These multi-step workflows show how to combine CLI commands for real-world use cases.
Workflow 1 — Research → Export → Push to CRM
The standard end-to-end pipeline: run a research task, export contacts, deduplicate, and push to your CRM.
# 1. Run the research with the hunter profile
fathom run --profile hunter "Find VPs of Engineering at Series B startups" -o ./fintech-vps/
# 2. Review the results
fathom sessions show --output ./fintech-vps/
# 3. Export contacts to CSV
fathom contacts export --format csv -o ./fintech-vps/
# 4. Deduplicate (dry run first, then merge)
fathom contacts dedup
fathom contacts dedup --merge
# 5. Push to your configured CRM
fathom contacts push-crmWorkflow 2 — Resume crashed session
If a long-running session was interrupted (network drop, system restart), you can resume from
where it left off using the persisted state in .research.db.
# 1. Find the interrupted session
fathom sessions list -n 5
# 2. Resume it (defaults to most recent interrupted session)
fathom resume --output ./fintech-vps/
# 3. Check the completed results
fathom sessions show --output ./fintech-vps/
fathom stats -o ./fintech-vps/Workflow 3 — Memory management
Keep the long-term memory store clean and useful: search, review, boost important facts, distill session-scoped knowledge into durable records, and garbage-collect stale entries.
# 1. Check what's in memory
fathom memory stats
# 2. Search for specific knowledge
fathom memory search "CTO of Acme Corp" --top-k 5
# 3. View a record and its version history
fathom memory get 7f31 --follow full_history
# 4. Distill session facts into durable knowledge
fathom memory distill --session a3f2 --dry-run
fathom memory distill --session a3f2
# 5. Garbage-collect stale run-scoped facts (older than 30 days)
fathom memory gc --ttl-days 30 --dry-run
fathom memory gc --ttl-days 30
# 6. Rebuild embeddings after upgrading the embedding model
fathom memory rebuildWorkflow 4 — Job management
Submit long-running tasks as durable background jobs that survive restarts and self-heal on failure.
# 1. Submit a job (detached, runs in background)
fathom jobs submit "Analyze the AI agent market landscape" --attempts 3
# 2. List all jobs and their states
fathom jobs list
# 3. Watch a job until it completes (refreshes every 5 seconds)
fathom jobs status 9b2e --watch 5
# 4. View the job's stdout/stderr logs
fathom jobs logs 9b2e -n 100
# 5. If it failed, re-run it
fathom jobs rerun 9b2e
# 6. Cancel a stuck job
fathom jobs cancel 9b2eWorkflow 5 — Profile-based campaigns
Create a custom profile for a specific campaign type, then reuse it across multiple runs.
# 1. Create a new profile from template
fathom profiles new series-b-outreach
# 2. Edit the profile (set prompt, model, temperature)
# vim ~/.fathom/profiles/series-b-outreach.toml
# 3. Verify the profile
fathom profiles show series-b-outreach
# 4. Run with the profile
fathom run --profile series-b-outreach "Find CTOs at Series B companies in fintech"
# 5. Reuse for a different vertical
fathom run --profile series-b-outreach "Find CTOs at Series B companies in healthtech"TUI Deep Dive
The TUI (Terminal User Interface) is built with ratatui and provides a real-time view
into the agent swarm. Here’s a detailed look at each panel and feature.
Panel details
Live agent tree showing the coordinator at the root and sub-agents as children. Each agent displays its status (running, complete, failed), current tool call, and elapsed time. Use Up/Down to move the cursor, Left/Right to collapse/expand subtrees. The selected agent’s details appear in the Output panel.
The final assembled output, streamed token-by-token as the writer produces it. In replay mode, this shows the complete saved output. When multiple writers run in parallel, their outputs are interleaved with agent-id markers.
Event log showing: agent spawns with task descriptions, tool calls with argument summaries and execution time in milliseconds, warnings (compaction events, truncation), and findings as they’re discovered. Each entry is timestamped relative to session start.
Active and recent tool calls with their arguments, execution status, and timing. Shows which tools are running in parallel and which are serialized. Pending approval calls are highlighted — press y or n to act.
Durable background jobs submitted via jobs submit. Shows job state (queued, running, complete, failed), attempt count, and last error if any. Refreshes automatically.
Recent records from the semantic memory store. Shows new facts as they’re absorbed during the run. Useful for verifying that the agent is remembering the right things.
Header sparkline
The header bar shows three things: the session ID (first 8 chars), elapsed time (MM:SS format), and a sparkline chart of token spend. The sparkline is a rolling 60-second window showing how many tokens were consumed per second. A flat sparkline means the agent is waiting (blocked on a tool or idle); a rising sparkline means active generation; a spike indicates a large tool output being processed.
Session browser (key ‘b’)
Press b to open the session browser — a list of all past sessions stored in the
database. Navigate with Up/Down, press Enter to load a session in replay mode. This is equivalent
to tui –replay <id> but accessible from inside the TUI. Sessions are sorted
newest-first and show: ID, query (truncated), status, and timestamp.
File reference mode (key ‘@’)
In insert mode, type @ followed by a path to reference a local file. The file content
is read and included as context for the agent. This is useful for:
@./contacts.csv validate these contacts@./task.txt reads the file as the query@./notes.md summarize and expand on thisTypical TUI session flow
fathom tui — the TUI opens with the Input panel focused. Type your query and press Enter.
Switch to the Agents panel (Tab) to watch sub-agents spawn and work. The Log panel shows tool calls in real-time.
When an approval prompt appears, press y to approve or n to deny. Switch to the Tools panel to see pending approvals.
Switch to the Output panel to read the synthesized report as it streams in. Use Up/Down to scroll through history.
Type a follow-up query in the Input panel to continue the research. The agent retains context from the previous run.
Output Structure Guide
Every research run produces a consistent output directory. Here’s what each file contains and how to use it.
File-by-file breakdown
| File | Contents | How to use it |
|---|---|---|
index.md | Table of contents with links to all findings, run metadata (query, profile, timestamps, agent count) | Start here — it’s the entry point to the report |
summary.md | Executive summary produced by the coordinator’s synthesis step. Key findings, recommendations, and contact highlights | Share this with stakeholders who don’t need the details |
findings/*.md | One file per sub-task. Contains the sub-agent’s full research output with inline source citations | Dive deeper into specific topics or verify claims |
sources.md | Deduplicated list of all source URLs referenced across all findings, with titles and last-seen dates | Fact-check the report or build a reading list |
.research.db | SQLite database with full session state: agents, messages, tool calls, findings, contacts, jobs | Resume interrupted sessions, run stats, or export contacts |
Export formats
When configured, the run produces additional files in the output directory:
| Format | File | Triggered by |
|---|---|---|
| HTML | report.html | export.html = true in config |
report.pdf | export.pdf = true in config | |
| JSON | report.json | export.json = true in config |
| DOCX | report.docx | export.docx = true in config |
All exports are generated from the same in-memory report structure, so they’re always consistent with the Markdown output. The JSON format includes the full source metadata and is ideal for programmatic consumption.
CLI Tips & Tricks
Use –task-file for complex queries
For long or structured queries, write them to a file instead of passing as a positional argument. This avoids shell escaping issues and lets you version-control your research prompts.
# task.txt
Research the competitive landscape of AI coding assistants.
Include:
1. GitHub Copilot, Cursor, Codeium, Tabnine, Cody
2. Pricing models and enterprise features
3. Technical architecture (local vs cloud, model choices)
4. Market share estimates and growth trajectories
5. Key differentiators and weaknesses
Format as a comparison table with a recommendation section.
# Run with the task file
fathom run --task-file task.txt -o ./ai-coding-tools/Use –repeat for monitoring loops
The –repeat flag turns run into a watch mode. Each cycle re-runs the
query, diffs results against the previous run, and alerts on new contacts or changed findings.
# Check for new Acme Corp signals every 6 hours
fathom run "Acme Corp latest news and hiring" --repeat 21600
# Monitor a job board every hour
fathom run "New postings on careers.acme.com" --repeat 3600Use –profile for campaign-specific behavior
Combine profiles with the same query to get different perspectives. Run once with hunter
for contacts, then with analyst for deep research on the same companies.
# Pass 1: harvest contacts
fathom run --profile hunter "Series B fintech companies" -o ./fintech/
# Pass 2: deep analysis on the same topic
fathom run --profile analyst "Series B fintech companies" -o ./fintech-analysis/Pipe output to other tools
The CLI writes structured Markdown and JSON that can be piped to other tools for further processing.
# Export contacts and pipe to jq for filtering
fathom contacts export --format json | jq '.[] | select(.title | contains("CTO"))'
# Search memory and format as markdown links
fathom memory search "fintech" --top-k 5 | grep -oP 'https?://\\S+' | sort -u
# Run stats and save to file
fathom stats -o ./results/ > stats-report.mdFind past research with sessions
The sessions command is your research history. Use substring search to find past runs
by topic, company, or date.
# Find all sessions about fintech
fathom sessions list --search "fintech"
# Show the last 5 sessions
fathom sessions list -n 5
# View details of a specific session (prefix match)
fathom sessions show 3f9c2aAnalyze tool performance with stats
The stats command shows per-tool call statistics from a recorded session: call counts,
p50/p95 latencies, and error rates. Use this to identify slow tools or optimize your research pipeline.
# Show stats for the most recent session
fathom stats
# Show stats for a specific output directory
fathom stats -o ./fintech-vps/
# Example output:
# Tool Calls p50(ms) p95(ms) Errors
# web_search 47 312 1840 2
# web_fetch 89 245 3200 5
# extract_contacts 23 180 420 0
# verify_email 15 890 4500 1
# memory_search 12 45 120 0Benchmark before deploying
Run the bench suite to verify your environment’s performance before starting large campaigns.
This catches issues like slow DNS, memory constraints, or misconfigured embedding models.
# Run all benchmark scenarios
fathom bench
# Run a specific scenario and save the report
fathom bench -s memory --save bench-report.md
# Quick check on tool dispatch overhead
fathom bench -s dispatch -n 32