title: CLI reference description: The two first-party CLIs that ship with fathomdx — fathom (delta CLI) and fathom-agent (local agent). Generated from each tool's own help output. audience: developer quadrant: reference last_verified: 2026-04-25 owners: [addons/cli/, addons/agent/]

CLI reference

Two command-line tools ship as npm packages inside the fathomdx repo and can be invoked via npx:

• fathom — the delta CLI. Search, write, recall, engage. What you reach for when you want the lake from a terminal without opening the dashboard.
• fathom-agent — the local agent. Pairs a machine to your Fathom, runs plugins, executes routines.

Each section below is the tool's own --help output, captured verbatim.

fathom — delta CLI

fathom — CLI for your Fathom memories

Commands:
  fathom remember <query> [--limit N] [--shallow]
  fathom write <content> [--tags a,b] [--source x] [--image path/to.png]
  fathom recall [--tags a,b] [--source x] [--since 24h] [--limit N]
  fathom deep_recall '<plan-json>'  (or pipe via stdin with -)
  fathom see_image <media_hash>
  fathom mind [tags]
  fathom refute <target_id> --reason "<why>"
  fathom affirm <target_id> --reason "<why>"
  fathom reply-to <target_id> --reason "<text>"
  fathom propose_contact <display_name> --rationale "<why>" [--slug bob] [--context '{"channel":"telegram"}']
  fathom instructions [--json]
  fathom rename-session "<name>" [--session <id>]

Pipe stdin:  echo 'notes' | fathom write - --tags meeting

API: http://localhost:8201
Key: (not set)

All commands honor FATHOM_API_URL (default http://localhost:8201) and FATHOM_API_KEY from the environment. See rotate an API key for how to mint the key.

fathom-agent — local agent

fathom-agent — local agent for the Fathom memory lake

Commands:
  fathom-agent run                   Start watching (uses config)
  fathom-agent run --vault ~/notes   Override plugin paths
  fathom-agent init                  Create default config
  fathom-agent install               Install as system service
  fathom-agent uninstall             Remove system service
  fathom-agent status                Show config and connection
  fathom-agent help                  Show this help

Config: ~/.fathom/agent.json
Env:    FATHOM_API_URL, FATHOM_API_KEY

Plugins:
  💓 Heartbeat (built-in)
  ⌂ HomeAssistant (built-in)
  🐈 Kitty (built-in)
  ⚙ LocalUI (built-in)
  💻 Sysinfo (built-in)
  📁 Vault (built-in)

Custom plugins: drop .js files in ~/.fathom/plugins/

Agent pairing is a one-time npx fathom-agent init --pair-code <code> — see pair another machine. After that, fathom-agent run keeps it alive in the foreground or fathom-agent install creates a persistent service.

Notes

• Both tools resolve localhost to IPv6 first on dual-stack systems. The api's compose binding includes [::1] for this reason; pairing over IPv4 still works thanks to the rootless-podman synthesis, but direct Docker installs may need a docker-compose.override.yml entry.
• Help output is cached from the source repo at generation time. Running npx fathom@latest --help always reflects the published version, which may be ahead of the copy in this repo.