CLI-справка

Обзор команд

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

Автономный консольный режим. Координатор декомпозирует запрос на субагентов, синтезирует их результаты и формирует структурированный отчёт. С флагом --repeat переходит в режим мониторинга: каждый прогон сравнивается с предыдущим и отправляет алерты по новым контактам.

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

Интерактивный терминальный интерфейс (ratatui): живое дерево агентов, стриминговый вывод, журнал событий, панели jobs и memory, флоу одобрения. Клавиши и панели — в разделе TUI-интерфейс.

fathom tui
fathom tui "Find VPs of Engineering at fintech startups" --profile analyst
fathom tui --replay 3f9c2a   # browse a saved session

serve

HTTP-сервер Axum: управление сессиями и задачами, потоки событий SSE, memory API, метрики Prometheus и веб-дашборд на /dashboard. По умолчанию слушает loopback.

fathom serve --port 8080
fathom serve --host 0.0.0.0   # requires FATHOM_API_KEYS

mcp-serve

Предоставляет все инструменты агентов внешним MCP-клиентам (Claude, ZCode и др.) через stdio. Вызовы инструментов выполняются через тот же реестр, что используют агенты. Логи идут в stderr, поэтому stdout остаётся чистым JSON-RPC.

fathom mcp-serve

Добавьте его в конфиг вашего MCP-клиента:

{ "command": "fathom", "args": ["mcp-serve"] }

memory

Поддерживайте долгосрочную семантическую базу знаний без запуска агента: гибридный поиск (вектора + BM25), цепочек версий с возможностью только добавления (append-only), дистилляция и GC. Ничто никогда не удаляется молча.

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-run

sessions

Просматривайте историю сессий, хранящуюся в базе данных.

fathom sessions list -n 10 --search "fintech"
fathom sessions show 3f9c2a

resume

Возобновите прерванную сессию: повторно запускает незавершённые подзадачи из сохранённого состояния в .research.db.

fathom resume --output ./results/

config

Показать или отредактировать ~/.fathom/config.toml из командной строки. Ключи используют точечную нотацию: section.field.

fathom config show
fathom config set agent.max_depth 3
fathom config set agent.max_agents 30

profiles

Персоны для run --profile и tui --profile: готовый системный промпт плюс опциональные переопределения модели, температуры, глубины, числа агентов и запрещённых инструментов. Встроенные: hunter, analyst, validator; ваши TOML-файлы лежат в ~/.fathom/profiles/.

fathom profiles list
fathom profiles show hunter
fathom profiles new my-persona   # creates a template file

contacts

База OSINT-контактов, собранная save_contacts: список, экспорт, дедупликация и отправка в настроенную CRM (amoCRM, Bitrix24, HubSpot — дедупликация по crm_id, без дубликатов при повторных пушах).

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-crm

jobs

Устойчивые фоновые задачи в SQLite: попытки с самовосстанавливающимся ретраем (задача повторно отправляется с добавлением предыдущей ошибки), переживают рестарты.

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 9b2e

bench

Бенчмарк слоя выполнения инструментов — без сети и LLM; фикстуры генерируются автоматически. Девять сценариев охватывают overhead диспетчеризации, параллельные батчи, масштабирование парсеров и семантическую память.

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 / digest

stats

Статистика вызовов по каждому инструменту — задержки p50/p95 — вычисленные из реальной записанной сессии (.research.db).

fathom stats -o ./results/

worker

Внутренний режим воркера — запускается автоматически координатором при use_multiprocess = true. Не предназначен для прямого вызова.

TUI-интерфейс

Шапка показывает id сессии, прошедшее время и спарклайн расхода токенов за сессию. В replay-режиме шапка помечена [REPLAY], и сохранённое дерево агентов загружается с финальными статусами.

Клавиши

Панели

Структура вывода

Каждый запуск пишет одинаковую структуру в свой каталог вывода — плюс опциональные PDF/HTML/JSON/DOCX экспорты, если настроены.

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 database

Common 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-crm

Workflow 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 rebuild

Workflow 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 9b2e

Workflow 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

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:

Typical TUI session flow

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

Export formats

When configured, the run produces additional files in the output directory:

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 3600

Use –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.md

Find 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 3f9c2a

Analyze 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        0

Benchmark 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