Field Theory CLI

Website: https://fieldtheory.dev/cli Repository: https://github.com/afar1/fieldtheory-cli CLI Tool: fieldtheory (ft) Authentication: X/Twitter session via Chrome or OAuth

Description

Field Theory CLI syncs and stores all of your X/Twitter bookmarks locally. Search, classify, and make them available to Claude Code, Codex, or any agent with shell access. Free and open source. Designed for Mac.

Installation

npm install -g fieldtheory

Requires Node.js 20+ and Google Chrome.

Commands

Sync

Basic Sync

ft sync

Download and sync all bookmarks (no API required). Uses Chrome session.

Sync with Classification

ft sync --classify

Sync then classify new bookmarks with LLM.

Full Sync

ft sync --full

Full history crawl (not just incremental).

API Sync

ft sync --api

Sync via OAuth API (cross-platform).

Search

Full-Text Search

ft search "distributed systems"
ft search "machine learning"
ft search <query>

Full-text search with BM25 ranking.

Visualization

Dashboard

ft viz

Terminal dashboard with sparklines, categories, and domains.

Categories

ft categories

Show category distribution.

Domains

ft domains

Subject domain distribution.

Stats

ft stats

Top authors, languages, date range.

Classification

LLM Classification

ft classify

Classify by category and domain using LLM.

Regex Classification

ft classify --regex

Classify by category using simple regex.

List and View

List Bookmarks

ft list
ft list --author @username
ft list --date 2024-01-01
ft list --category tool
ft list --domain engineering

Filter by author, date, category, domain.

Show Bookmark

ft show <id>

Show one bookmark in detail.

Index

Merge Index

ft index

Merge new bookmarks into search index (preserves classifications).

Authentication

OAuth Setup

ft auth

Set up OAuth for API-based sync (optional).

Media

Fetch Media

ft fetch-media

Download media assets (static images only).

Status

Check Status

ft status

Show sync status and data location.

Get Path

ft path

Print data directory path.

Examples

Quick Start

# 1. Sync your bookmarks (needs Chrome logged into X)
ft sync

# 2. Search them
ft search "distributed systems"

# 3. Explore
ft viz
ft categories
ft stats

Daily Sync Schedule

# Sync every morning at 7am (crontab)
0 7 * * * ft sync

# Sync and classify every morning
0 7 * * * ft sync --classify

Agent Integration

# Search bookmarks for a topic
ft search "cancer research"

# List bookmarks by category
ft list --category research

# List bookmarks by author
ft list --author @elonmusk

# Get detailed bookmark
ft show <bookmark-id>

Classification Workflow

# First sync
ft sync

# Classify with LLM
ft classify

# View results
ft categories
ft domains

Cross-Platform Usage

# On non-Mac systems, use OAuth
ft auth
ft sync --api

Data Storage

All data is stored locally at ~/.ft-bookmarks/:

~/.ft-bookmarks/
  bookmarks.jsonl         # raw bookmark cache (one per line)
  bookmarks.db            # SQLite FTS5 search index
  bookmarks-meta.json     # sync metadata
  oauth-token.json        # OAuth token (if using API mode)

Override the location:

export FT_DATA_DIR=/path/to/custom/dir

Remove all data:

rm -rf ~/.ft-bookmarks

Categories

Notes

• Privacy: All data stays local. No telemetry, no analytics
• Chrome Session: Reads cookies from Chrome for sync, discards after use
• OAuth Tokens: Stored with chmod 600 (owner-only)
• Platform: Full support on macOS; Linux/Windows use OAuth mode
• API: Uses X's internal GraphQL API (same as x.com browser)
• Official API: Use ft auth + ft sync --api for v2 API
• Search: Uses BM25 ranking algorithm
• Index: SQLite FTS5 for fast full-text search
• Output: JSONL format for easy scripting
• Agent-friendly: Designed for Claude Code, Codex, or any shell agent
• License: MIT