Fieldtheory Cli Bookmarks

# Field Theory CLI — X/Twitter Bookmark Manager

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

Field Theory CLI (`ft`) syncs all your X/Twitter bookmarks locally, indexes them for full-text search, classifies them by category and domain, and exposes them to AI agents via shell commands. No official API required for the default sync mode.

## Installation

```bash
npm install -g fieldtheory
```

**Requirements:**
- Node.js 20+
- Google Chrome (logged into X/Twitter) for default sync mode
- macOS for Chrome session sync; Linux/Windows use OAuth mode

Verify installation:

```bash
ft --version
ft status
```

## Quick Start

```bash
# Sync bookmarks (reads Chrome session automatically)
ft sync

# Search immediately
ft search "machine learning"

# Explore with terminal dashboard
ft viz
```

Data is stored at `~/.ft-bookmarks/` by default.

## Core Commands

### Syncing

```bash
# Incremental sync (new bookmarks only)
ft sync

# Sync then auto-classify with LLM
ft sync --classify

# Full history crawl from the beginning
ft sync --full

# Sync via OAuth API (cross-platform, no Chrome needed)
ft sync --api

# Show sync status
ft status
```

### Searching

```bash
# Full-text BM25 search
ft search "distributed systems"
ft search "rust async runtime"
ft search "cancer immunotherapy"

# Filter results
ft list --author elonmusk
ft list --category tool
ft list --domain ai
ft list --since 2024-01-01
ft list --category research --domain biology

# Show a single bookmark by ID
ft show 1234567890
```

### Classification

```bash
# LLM-powered classification (requires LLM access)
ft classify

# Regex-based classification (no LLM needed, faster)
ft classify --regex

# Rebuild search index (preserves existing classifications)
ft index
```

### Exploration & Stats

```bash
# Terminal dashboard with sparklines and charts
ft viz

# Category distribution
ft categories

# Subject domain distribution
ft domains

# Top authors, languages, date range
ft stats

# Print data directory path
ft path
```

### Media

```bash
# Download static images from bookmarks
ft fetch-media
```

## OAuth Setup (Cross-Platform / API Mode)

```bash
# Interactive OAuth setup
ft auth

# Then sync via API
ft sync --api
```

OAuth token stored at `~/.ft-bookmarks/oauth-token.json` with `chmod 600`.

## Configuration

### Custom Data Directory

```bash
# Set in shell profile (~/.zshrc or ~/.bashrc)
export FT_DATA_DIR=/path/to/custom/dir

# Or per-command
FT_DATA_DIR=/Volumes/external/bookmarks ft sync
```

### Data File Layout

```
~/.ft-bookmarks/
  bookmarks.jsonl       # raw bookmarks, one JSON object per line
  bookmarks.db          # SQLite FTS5 search index
  bookmarks-meta.json   # sync cursor and metadata
  oauth-token.json      # OAuth credentials (API mode only)
```

## Scheduling Sync

Add to crontab (`crontab -e`):

```bash
# Sync every morning at 7am
0 7 * * * ft sync

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

# Full sync every Sunday at midnight
0 0 * * 0 ft sync --full
```

## Categories Reference

| Category | Description |
|----------|-------------|
| `tool` | GitHub repos, CLI tools, npm packages, open-source |
| `security` | CVEs, vulnerabilities, exploits, supply chain |
| `technique` | Tutorials, demos, code patterns, how-to threads |
| `launch` | Product launches, announcements, "just shipped" |
| `research` | ArXiv papers, studies, academic findings |
| `opinion` | Takes, analysis, commentary, threads |
| `commerce` | Products, shopping, physical goods |

## Working with Bookmark Data (TypeScript/Node.js)

The `bookmarks