fieldtheory-cli-bookmarks

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Field Theory CLI — X/Twitter Bookmark Manager

Field Theory CLI — X/Twitter 书签管理器

Skill by 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.

由 ara.so 开发的Skill — 2026年度每日技能合集。

Field Theory CLI (

ft

) 可将你所有的X/Twitter书签同步到本地，为其建立全文搜索索引，按类别和领域分类，还可通过Shell命令向AI Agent开放数据。默认同步模式无需使用官方API。

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

bash

npm install -g fieldtheory

依赖要求：

Node.js 20+
默认同步模式需要已登录X/Twitter的Google Chrome浏览器
Chrome会话同步仅支持macOS；Linux/Windows请使用OAuth模式

验证安装：

bash

ft --version
ft status

Quick Start

快速开始

bash

undefined

bash

undefined

Sync bookmarks (reads Chrome session automatically)

同步书签（自动读取Chrome会话）

ft sync

Search immediately

立即搜索

ft search "machine learning"

Explore with terminal dashboard

用终端仪表盘探索书签

ft viz


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

ft viz


数据默认存储在 `~/.ft-bookmarks/` 路径下。

Core Commands

核心命令

Syncing

同步

bash

undefined

bash

undefined

Incremental sync (new bookmarks only)

增量同步（仅同步新书签）

ft sync

Sync then auto-classify with LLM

同步后用LLM自动分类

ft sync --classify

Full history crawl from the beginning

从最开始完整爬取所有历史书签

ft sync --full

Sync via OAuth API (cross-platform, no Chrome needed)

通过OAuth API同步（跨平台，无需Chrome）

ft sync --api

Show sync status

查看同步状态

ft status

undefined

ft status

undefined

Searching

搜索

bash

undefined

bash

undefined

Full-text BM25 search

BM25全文搜索

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

按ID查看单条书签

ft show 1234567890

undefined

ft show 1234567890

undefined

Classification

分类

bash

undefined

bash

undefined

LLM-powered classification (requires LLM access)

基于LLM的分类（需要LLM访问权限）

ft classify

Regex-based classification (no LLM needed, faster)

基于正则的分类（无需LLM，速度更快）

ft classify --regex

Rebuild search index (preserves existing classifications)

重建搜索索引（保留现有分类结果）

ft index

undefined

ft index

undefined

Exploration & Stats

探索与统计

bash

undefined

bash

undefined

Terminal dashboard with sparklines and charts

带迷你折线图和图表的终端仪表盘

ft viz

Category distribution

类别分布

ft categories

Subject domain distribution

主题领域分布

ft domains

Top authors, languages, date range

Print data directory path

打印数据目录路径

ft path

undefined

ft path

undefined

Media

媒体资源

bash

undefined

bash

undefined

Download static images from bookmarks

下载书签中的静态图片

ft fetch-media

undefined

ft fetch-media

undefined

OAuth Setup (Cross-Platform / API Mode)

OAuth配置（跨平台/API模式）

bash

undefined

bash

undefined

Interactive OAuth setup

交互式OAuth设置

ft auth

Then sync via API

之后通过API同步

ft sync --api


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

ft sync --api


OAuth令牌存储在 `~/.ft-bookmarks/oauth-token.json`，权限为`chmod 600`。

Configuration

配置

Custom Data Directory

自定义数据目录

bash

undefined

bash

undefined

Set in shell profile (~/.zshrc or ~/.bashrc)

在Shell配置文件中设置（~/.zshrc 或 ~/.bashrc）

export FT_DATA_DIR=/path/to/custom/dir

Or per-command

或单条命令临时指定

FT_DATA_DIR=/Volumes/external/bookmarks ft sync

undefined

FT_DATA_DIR=/Volumes/external/bookmarks ft sync

undefined

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)

~/.ft-bookmarks/
  bookmarks.jsonl       # 原始书签，每行一个JSON对象
  bookmarks.db          # SQLite FTS5搜索索引
  bookmarks-meta.json   # 同步游标和元数据
  oauth-token.json      # OAuth凭证（仅API模式有）

Scheduling Sync

定时同步设置

Add to crontab (

crontab -e

bash

undefined

添加到crontab（执行

crontab -e

编辑）：

bash

undefined

Sync every morning at 7am

每天早上7点同步

0 7 * * * ft sync

Sync and classify every morning at 7am

每天早上7点同步并分类

0 7 * * * ft sync --classify

Full sync every Sunday at midnight

每周日零点全量同步

0 0 * * 0 ft sync --full

undefined

0 0 * * 0 ft sync --full

undefined

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

分类	描述
`tool`	GitHub仓库、CLI工具、npm包、开源项目
`security`	CVE、漏洞、利用手段、供应链安全
`technique`	教程、演示、代码模式、实操指南线程
`launch`	产品发布、公告、"刚刚上线"类内容
`research`	ArXiv论文、研究、学术发现
`opinion`	观点、分析、评论、讨论线程
`commerce`	产品、购物、实体商品

Working with Bookmark Data (TypeScript/Node.js)

处理书签数据（TypeScript/Node.js）

The

bookmarks.jsonl

file can be consumed directly in scripts:

typescript

import { createReadStream } from "fs";
import { createInterface } from "readline";
import { homedir } from "os";
import { join } from "path";

interface Bookmark {
  id: string;
  text: string;
  author: string;
  created_at: string;
  url: string;
  category?: string;
  domain?: string;
  media?: string[];
}

async function loadBookmarks(): Promise<Bookmark[]> {
  const dataDir = process.env.FT_DATA_DIR ?? join(homedir(), ".ft-bookmarks");
  const filePath = join(dataDir, "bookmarks.jsonl");

  const bookmarks: Bookmark[] = [];
  const rl = createInterface({
    input: createReadStream(filePath),
    crlfDelay: Infinity,
  });

  for await (const line of rl) {
    if (line.trim()) {
      bookmarks.push(JSON.parse(line));
    }
  }

  return bookmarks;
}

// Usage
const bookmarks = await loadBookmarks();
const tools = bookmarks.filter((b) => b.category === "tool");
console.log(`Found ${tools.length} tool bookmarks`);

bookmarks.jsonl

文件可直接在脚本中读取使用：

typescript

import { createReadStream } from "fs";
import { createInterface } from "readline";
import { homedir } from "os";
import { join } from "path";

interface Bookmark {
  id: string;
  text: string;
  author: string;
  created_at: string;
  url: string;
  category?: string;
  domain?: string;
  media?: string[];
}

async function loadBookmarks(): Promise<Bookmark[]> {
  const dataDir = process.env.FT_DATA_DIR ?? join(homedir(), ".ft-bookmarks");
  const filePath = join(dataDir, "bookmarks.jsonl");

  const bookmarks: Bookmark[] = [];
  const rl = createInterface({
    input: createReadStream(filePath),
    crlfDelay: Infinity,
  });

  for await (const line of rl) {
    if (line.trim()) {
      bookmarks.push(JSON.parse(line));
    }
  }

  return bookmarks;
}

// 使用示例
const bookmarks = await loadBookmarks();
const tools = bookmarks.filter((b) => b.category === "tool");
console.log(`Found ${tools.length} tool bookmarks`);

Query SQLite Index Directly

直接查询SQLite索引

typescript

import Database from "better-sqlite3";
import { join } from "path";
import { homedir } from "os";

const dataDir = process.env.FT_DATA_DIR ?? join(homedir(), ".ft-bookmarks");
const db = new Database(join(dataDir, "bookmarks.db"), { readonly: true });

// Full-text search using SQLite FTS5
function searchBookmarks(query: string, limit = 20) {
  const stmt = db.prepare(`
    SELECT id, text, author, created_at, category, domain
    FROM bookmarks
    WHERE bookmarks MATCH ?
    ORDER BY rank
    LIMIT ?
  `);
  return stmt.all(query, limit);
}

// Filter by category
function getByCategory(category: string) {
  const stmt = db.prepare(`
    SELECT * FROM bookmarks WHERE category = ? ORDER BY created_at DESC
  `);
  return stmt.all(category);
}

const results = searchBookmarks("transformer architecture");
console.log(results);

typescript

import Database from "better-sqlite3";
import { join } from "path";
import { homedir } from "os";

const dataDir = process.env.FT_DATA_DIR ?? join(homedir(), ".ft-bookmarks");
const db = new Database(join(dataDir, "bookmarks.db"), { readonly: true });

// 使用SQLite FTS5进行全文搜索
function searchBookmarks(query: string, limit = 20) {
  const stmt = db.prepare(`
    SELECT id, text, author, created_at, category, domain
    FROM bookmarks
    WHERE bookmarks MATCH ?
    ORDER BY rank
    LIMIT ?
  `);
  return stmt.all(query, limit);
}

// 按类别筛选
function getByCategory(category: string) {
  const stmt = db.prepare(`
    SELECT * FROM bookmarks WHERE category = ? ORDER BY created_at DESC
  `);
  return stmt.all(category);
}

const results = searchBookmarks("transformer architecture");
console.log(results);

Shell Integration in Agent Scripts

Agent脚本中的Shell集成

typescript

import { execSync } from "child_process";

// Run ft commands from Node.js
function ftSearch(query: string): string {
  return execSync(`ft search "${query}"`, { encoding: "utf8" });
}

function ftList(options: { category?: string; since?: string; author?: string }) {
  const flags = [
    options.category ? `--category ${options.category}` : "",
    options.since ? `--since ${options.since}` : "",
    options.author ? `--author ${options.author}` : "",
  ]
    .filter(Boolean)
    .join(" ");

  return execSync(`ft list ${flags}`, { encoding: "utf8" });
}

// Example: find AI memory tools bookmarked this year
const memoryTools = ftSearch("AI memory");
const recentTools = ftList({ category: "tool", since: "2025-01-01" });

typescript

import { execSync } from "child_process";

// 从Node.js运行ft命令
function ftSearch(query: string): string {
  return execSync(`ft search "${query}"`, { encoding: "utf8" });
}

function ftList(options: { category?: string; since?: string; author?: string }) {
  const flags = [
    options.category ? `--category ${options.category}` : "",
    options.since ? `--since ${options.since}` : "",
    options.author ? `--author ${options.author}` : "",
  ]
    .filter(Boolean)
    .join(" ");

  return execSync(`ft list ${flags}`, { encoding: "utf8" });
}

// 示例：查找今年收藏的AI记忆工具
const memoryTools = ftSearch("AI memory");
const recentTools = ftList({ category: "tool", since: "2025-01-01" });

Agent Integration Patterns

Agent集成方案

Tell your AI agent to use

ft

directly in natural language:

"Search my bookmarks for distributed tracing tools and summarize the top 5."

"Sync any new X bookmarks, then list all research papers from 2025."

"Find everything I've bookmarked about Rust and categorize it by subtopic."

"Every morning, run ft sync --classify to keep my bookmarks up to date."

Claude Code example prompt:

Use the `ft` CLI to search my bookmarks for "vector database" 
and pick the best open-source option to add to this project.
Run: ft search "vector database" --category tool

你可以用自然语言告诉AI Agent直接使用

ft

：

"搜索我的书签中关于分布式追踪工具的内容，总结前5条。"

"同步所有新的X书签，然后列出2025年的所有研究论文。"

"查找我收藏的所有关于Rust的内容，按子主题分类。"

"每天早上运行ft sync --classify，保持我的书签更新。"

Claude Code示例提示词：

使用`ft` CLI搜索我的书签中关于"vector database"的内容，选出最好的开源选项加入这个项目。
运行: ft search "vector database" --category tool

Troubleshooting

问题排查

Chrome session not found

找不到Chrome会话

bash

undefined

bash

undefined

Ensure Chrome is open and logged into X

确保Chrome已打开且登录了X

Then retry

然后重试

ft sync

If Chrome session still fails, use OAuth mode

如果Chrome会话仍然失败，使用OAuth模式

ft auth ft sync --api

undefined

ft auth ft sync --api

undefined

Sync stalls or returns 0 bookmarks

同步卡住或返回0条书签

bash

undefined

bash

undefined

Check sync status and metadata

查看同步状态和元数据

ft status

Force full re-crawl

强制全量重爬

ft sync --full

Check data directory permissions

检查数据目录权限

ls -la ~/.ft-bookmarks/

undefined

ls -la ~/.ft-bookmarks/

undefined

Search returns no results

搜索无结果

bash

undefined

bash

undefined

Rebuild the search index

重建搜索索引

ft index

Verify bookmarks exist

确认书签存在

ft stats wc -l ~/.ft-bookmarks/bookmarks.jsonl

undefined

ft stats wc -l ~/.ft-bookmarks/bookmarks.jsonl

undefined

Classification not running

分类未执行

bash

undefined

bash

undefined

LLM classify requires an LLM — use regex fallback

LLM分类需要LLM访问权限，可使用正则降级方案

ft classify --regex

Or sync with regex classify

或同步时使用正则分类

ft sync --classify --regex

undefined

ft sync --classify --regex

undefined

Reset all data

重置所有数据

bash

rm -rf ~/.ft-bookmarks
ft sync

bash

rm -rf ~/.ft-bookmarks
ft sync

Custom data directory issues

自定义数据目录问题

bash

undefined

bash

undefined

Confirm the env var is set

确认环境变量已设置

echo $FT_DATA_DIR ft path

Ensure directory is writable

确保目录可写

mkdir -p "$FT_DATA_DIR" chmod 755 "$FT_DATA_DIR"

undefined

mkdir -p "$FT_DATA_DIR" chmod 755 "$FT_DATA_DIR"

undefined

Security Notes

安全说明

All data is local only — no telemetry or external calls except to X during sync
Chrome cookies are read temporarily for sync and never stored separately
OAuth token is stored
```
chmod 600
```
— treat it like a password
Default sync uses X's internal GraphQL API (same as browser);
```
--api
```
uses official v2 API

所有数据仅存储在本地——除同步时访问X之外，无任何遥测或外部请求
Chrome Cookie仅临时用于同步，不会单独存储
OAuth令牌存储权限为
```
chmod 600
```
——请像密码一样保管它
默认同步使用X的内部GraphQL API（和浏览器一致）；
```
--api
```
模式使用官方v2 API

Platform Support

平台支持

Feature	macOS	Linux	Windows
`ft sync` (Chrome session)	✅	❌	❌
`ft sync --api` (OAuth)	✅	✅	✅
Search, classify, viz	✅	✅	✅

Linux/Windows users must run

ft auth

first, then use

ft sync --api

功能	macOS	Linux	Windows
`ft sync` (Chrome会话)	✅	❌	❌
`ft sync --api` (OAuth)	✅	✅	✅
搜索、分类、仪表盘	✅	✅	✅

Linux/Windows用户必须先运行

ft auth

，再使用

ft sync --api

。

Resources

资源

Homepage: fieldtheory.dev/cli
Repository: github.com/afar1/fieldtheory-cli
License: MIT

主页: fieldtheory.dev/cli
仓库: github.com/afar1/fieldtheory-cli
许可证: MIT

fieldtheory-cli-bookmarks

Original

Translation

Field Theory CLI — X/Twitter Bookmark Manager

Field Theory CLI — X/Twitter 书签管理器

Installation

安装

Quick Start

快速开始

Sync bookmarks (reads Chrome session automatically)

同步书签（自动读取Chrome会话）

Search immediately

立即搜索

Explore with terminal dashboard

用终端仪表盘探索书签

Core Commands

核心命令

Syncing

同步

Incremental sync (new bookmarks only)

增量同步（仅同步新书签）

Sync then auto-classify with LLM

同步后用LLM自动分类

Full history crawl from the beginning

从最开始完整爬取所有历史书签

Sync via OAuth API (cross-platform, no Chrome needed)

通过OAuth API同步（跨平台，无需Chrome）

Show sync status

查看同步状态

Searching

搜索

Full-text BM25 search

BM25全文搜索

Filter results

筛选结果

Show a single bookmark by ID

按ID查看单条书签

Classification

分类

LLM-powered classification (requires LLM access)

基于LLM的分类（需要LLM访问权限）

Regex-based classification (no LLM needed, faster)

基于正则的分类（无需LLM，速度更快）

Rebuild search index (preserves existing classifications)

重建搜索索引（保留现有分类结果）

Exploration & Stats

探索与统计

Terminal dashboard with sparklines and charts

带迷你折线图和图表的终端仪表盘

Category distribution

类别分布

Subject domain distribution

主题领域分布

Top authors, languages, date range

热门作者、语言、日期范围

Print data directory path

打印数据目录路径

Media

媒体资源

Download static images from bookmarks

下载书签中的静态图片

OAuth Setup (Cross-Platform / API Mode)

OAuth配置（跨平台/API模式）

Interactive OAuth setup

交互式OAuth设置

Then sync via API

之后通过API同步

Configuration

配置

Custom Data Directory

自定义数据目录

Set in shell profile (~/.zshrc or ~/.bashrc)

在Shell配置文件中设置（~/.zshrc 或 ~/.bashrc）

Or per-command

或单条命令临时指定

Data File Layout

数据文件结构

Scheduling Sync

定时同步设置

Sync every morning at 7am