fieldtheory-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

fieldtheory-cli

Skill by ara.so — Devtools Skills collection.

Field Theory CLI syncs and stores all your X/Twitter bookmarks locally. Search, classify, export to markdown, build knowledge bases, and make bookmarks available to AI agents with shell access.

由ara.so开发的Skill — 开发工具Skill合集。

Field Theory CLI可在本地同步并存储您所有的X/Twitter书签。您可以进行搜索、分类、导出为Markdown格式、构建知识库，还能让具备Shell访问权限的AI Agent调用这些书签。

What it does

核心功能

Syncs X bookmarks to
```
~/.fieldtheory/bookmarks/
```
(no API key needed by default)
Full-text search with BM25 ranking via SQLite FTS5
LLM classification by category (tool, security, technique, launch, research, opinion, commerce) and subject domain
Markdown export with enriched article text for knowledge bases
Agent integration via
```
/fieldtheory
```
skill for Claude Code, Codex
Possibility runs to generate ideas from bookmark-grounded seeds
OAuth support for cross-platform API sync

同步X书签至
```
~/.fieldtheory/bookmarks/
```
（默认无需API密钥）
全文搜索：通过SQLite FTS5实现BM25排序
LLM分类：按类别（工具、安全、技术、发布、研究、观点、商业）和主题领域进行分类
Markdown导出：附带丰富文章文本，用于构建知识库
Agent集成：通过
```
/fieldtheory
```
Skill支持Claude Code、Codex
创意生成：基于书签种子生成创意想法
OAuth支持：跨平台API同步

Installation

安装

bash

npm install -g fieldtheory

Requires Node.js 20+. Chrome-family browser or Firefox recommended for session sync.

Verify installation:

bash

ft --version
ft status

bash

npm install -g fieldtheory

需要Node.js 20+版本。推荐使用Chrome系浏览器或Firefox进行会话同步。

验证安装：

bash

ft --version
ft status

First-time setup

首次设置

bash

undefined

bash

undefined

Sync bookmarks (extracts session from browser)

同步书签（从浏览器提取会话信息）

ft sync

Search bookmarks

搜索书签

ft search "distributed systems"

View stats

查看统计信息

ft stats ft viz


For OAuth API sync (cross-platform):

```bash
ft auth
ft sync --api

ft stats ft viz


如需使用OAuth API同步（跨平台）：

```bash
ft auth
ft sync --api

Key commands

核心命令

Sync

同步

bash

undefined

bash

undefined

Basic sync (downloads bookmarks + media)

基础同步（下载书签+媒体）

ft sync

Sync without media

仅同步书签，不下载媒体

ft sync --no-media

Sync and classify with LLM

同步并通过LLM进行分类

ft sync --classify

Full re-crawl

完全重新爬取

ft sync --rebuild

Resume interrupted sync

恢复中断的同步

ft sync --continue

Backfill gaps (quoted tweets, truncated text, missing media)

补全缺失内容（引用推文、截断文本、缺失媒体）

ft sync --gaps

Sync X bookmark folders

同步X书签文件夹

ft sync --folders

Sync single folder

同步单个文件夹

ft sync --folder "AI Research"

OAuth API sync

OAuth API同步

ft sync --api

undefined

ft sync --api

undefined

Search and browse

搜索与浏览

bash

undefined

bash

undefined

Full-text search

全文搜索

ft search "machine learning papers" ft search "typescript debugging" --limit 20

List with filters

带筛选条件的列表展示

ft list --author elonmusk ft list --days 30 ft list --category research ft list --domain technology ft list --folder "Reading List"

Show single bookmark

查看单个书签

ft show 1234567890

Random sample

随机抽取样本

ft sample research

Stats

统计信息

ft stats ft categories ft domains ft folders ft viz

undefined

ft stats ft categories ft domains ft folders ft viz

undefined

Classification

分类

bash

undefined

bash

undefined

Classify all unclassified bookmarks

分类所有未分类的书签

ft classify

Classify with regex (fast, less accurate)

使用正则表达式分类（速度快，精度较低）

ft classify --regex

Classify domains only

仅对域名进行分类

ft classify-domains

Override LLM engine

覆盖默认LLM引擎

ft classify --engine claude-opus-4-20250514 ft sync --classify --engine claude-sonnet-4-20250514

Change default model

修改默认模型

ft model ft model claude-opus-4-20250514

undefined

ft model ft model claude-opus-4-20250514

undefined

Knowledge base

知识库

bash

undefined

bash

undefined

Export to markdown

导出为Markdown格式

ft md

Re-export only changed bookmarks

仅重新导出已修改的书签

ft md --changed

Build interlinked wiki

构建带内部链接的维基

ft wiki

Ask questions

提问

ft ask "What are the best resources on RAG?" ft ask "Summarize distributed systems bookmarks" --save

Health check wiki

维基健康检查

ft lint ft lint --fix

undefined

ft lint ft lint --fix

undefined

Possibility runs

创意生成

bash

undefined

bash

undefined

Create seed from search

通过搜索创建种子

ft seeds search "ai agents" --days 90 --limit 8 --create

Add repos

添加代码仓库

ft repos add ~/dev/my-project

Interactive wizard

交互式向导

ft possible

Run with defaults

使用默认配置运行

ft possible run --defaults

Background run

后台运行

ft possible run --background

View node prompt

查看节点提示词

ft possible prompt <node-id>

Install nightly schedule (macOS)

安装夜间调度（macOS）

ft possible nightly install --time 02:00 --defaults --model opus --effort medium --nodes 5 ft possible nightly show

undefined

ft possible nightly install --time 02:00 --defaults --model opus --effort medium --nodes 5 ft possible nightly show

undefined

Agent integration

Agent集成

bash

undefined

bash

undefined

Install skill for Claude Code/Codex

为Claude Code/Codex安装Skill

ft skill install

Show skill content

查看Skill内容

ft skill show

Uninstall

卸载Skill

ft skill uninstall

undefined

ft skill uninstall

undefined

Field Theory app companion

Field Theory应用配套功能

bash

undefined

bash

undefined

Show paths

查看路径

ft paths --json ft status --json

Library management

库管理

ft library search "distributed systems" ft library show notes/example.md ft library create notes/new.md --stdin ft library update notes/new.md --stdin --expected-sha256 <hash> ft library delete notes/old.md ft library open notes/example.md

Commands

命令管理

ft commands list ft commands new "daily-review" ft commands validate

Install Mac app

安装Mac应用

ft install app

undefined

ft install app

undefined

Utilities

实用工具

bash

undefined

bash

undefined

Rebuild search index

重建搜索索引

ft index

Backfill media

补全媒体资源

ft fetch-media ft fetch-media --skip-profile-images

Show status

查看状态

ft status ft path

undefined

ft status ft path

undefined

Configuration

配置

Environment variables

环境变量

bash

undefined

bash

undefined

Override data directory

覆盖数据目录

export FT_DATA_DIR=/path/to/custom/dir

Override library directory

覆盖库目录

export FT_LIBRARY_DIR=/path/to/custom/library

Override commands directory

覆盖命令目录

export FT_COMMANDS_DIR=/path/to/custom/commands

Point to dev app (macOS)

指定开发版应用路径（macOS）

export FT_APP_DEV_DIR=/Users/you/dev/fieldtheory/mac-app

Override app bundle ID

覆盖应用Bundle ID

export FT_APP_BUNDLE_ID=com.fieldtheory.app.dev

Custom app launcher

自定义应用启动器

export FT_APP_OPEN_COMMAND=/path/to/launcher

Proxy settings (standard)

代理设置（标准格式）

export HTTPS_PROXY=http://proxy:8080 export HTTP_PROXY=http://proxy:8080 export ALL_PROXY=socks5://proxy:1080 export NO_PROXY=localhost,127.0.0.1

undefined

export HTTPS_PROXY=http://proxy:8080 export HTTP_PROXY=http://proxy:8080 export ALL_PROXY=socks5://proxy:1080 export NO_PROXY=localhost,127.0.0.1

undefined

LLM configuration

LLM配置

bash

undefined

bash

undefined

View current model

查看当前模型

ft model

Change default model

修改默认模型

ft model claude-opus-4-20250514

Available engines (via env):

可用引擎（需配置环境变量）：

- Anthropic: ANTHROPIC_API_KEY

- OpenAI: OPENAI_API_KEY

- OpenRouter: OPENROUTER_API_KEY

undefined

undefined

Browser selection

浏览器选择

bash

undefined

bash

undefined

Auto-detect (default)

自动检测（默认）

ft sync

Specify browser

指定浏览器

ft sync --browser chrome ft sync --browser firefox ft sync --browser brave ft sync --browser edge

Windows: specify profile

Windows系统：指定配置文件

ft sync --browser chrome --chrome-profile-directory "Default"

Firefox: specify profile directory

Firefox：指定配置文件目录

ft sync --firefox-profile-dir /path/to/profile

Manual cookies (last resort)

手动传入Cookie（备选方案）

ft sync --cookies <ct0> <auth_token>

undefined

ft sync --cookies <ct0> <auth_token>

undefined

Data structure

数据结构

~/.fieldtheory/
├── bookmarks/
│   ├── bookmarks.jsonl         # Raw cache (one JSON per line)
│   ├── bookmarks.db            # SQLite FTS5 search index
│   ├── bookmarks-meta.json     # Sync metadata
│   └── oauth-token.json        # OAuth token (chmod 600)
├── library/
│   └── index.md                # Knowledge base
├── commands/
│   └── *.md                    # Portable commands
└── ideas/
    ├── seeds/                  # Possibility seeds
    ├── runs/                   # Possibility runs
    ├── nodes/                  # Node prompts
    ├── batches/                # Multi-repo batches
    ├── jobs/                   # Background jobs
    └── nightly/                # Nightly schedules

~/.fieldtheory/
├── bookmarks/
│   ├── bookmarks.jsonl         # 原始缓存（每行一个JSON）
│   ├── bookmarks.db            # SQLite FTS5搜索索引
│   ├── bookmarks-meta.json     # 同步元数据
│   └── oauth-token.json        # OAuth令牌（权限chmod 600）
├── library/
│   └── index.md                # 知识库
├── commands/
│   └── *.md                    # 可移植命令
└── ideas/
    ├── seeds/                  # 创意种子
    ├── runs/                   # 创意生成任务
    ├── nodes/                  # 节点提示词
    ├── batches/                # 多仓库批量任务
    ├── jobs/                   # 后台任务
    └── nightly/                # 夜间调度任务

Common patterns

常见使用场景

Daily sync with classification

每日同步并分类

bash

undefined

bash

undefined

Crontab: sync every morning at 7am

Crontab配置：每天早上7点同步

0 7 * * * ft sync --classify

undefined

0 7 * * * ft sync --classify

undefined

Search and show workflow

搜索与查看工作流

typescript

// Get search results as JSON
const { execSync } = require('child_process');

function searchBookmarks(query: string): any[] {
  const output = execSync(`ft search "${query}" --json`, { encoding: 'utf8' });
  return JSON.parse(output);
}

function showBookmark(id: string): any {
  const output = execSync(`ft show ${id} --json`, { encoding: 'utf8' });
  return JSON.parse(output);
}

const results = searchBookmarks('typescript patterns');
const first = showBookmark(results[0].id);
console.log(first.text);

typescript

// 以JSON格式获取搜索结果
const { execSync } = require('child_process');

function searchBookmarks(query: string): any[] {
  const output = execSync(`ft search "${query}" --json`, { encoding: 'utf8' });
  return JSON.parse(output);
}

function showBookmark(id: string): any {
  const output = execSync(`ft show ${id} --json`, { encoding: 'utf8' });
  return JSON.parse(output);
}

const results = searchBookmarks('typescript patterns');
const first = showBookmark(results[0].id);
console.log(first.text);

Export to custom format

导出为自定义格式

typescript

import { readFileSync } from 'fs';
import { join } from 'path';
import { homedir } from 'os';

const dataDir = process.env.FT_DATA_DIR || join(homedir(), '.fieldtheory');
const bookmarksPath = join(dataDir, 'bookmarks', 'bookmarks.jsonl');

// Read raw JSONL
const bookmarks = readFileSync(bookmarksPath, 'utf8')
  .split('\n')
  .filter(line => line.trim())
  .map(line => JSON.parse(line));

// Filter and transform
const aiBookmarks = bookmarks
  .filter(b => b.classification?.category === 'research')
  .filter(b => b.classification?.domain === 'AI/ML')
  .map(b => ({
    text: b.text,
    author: b.author.screen_name,
    url: b.url,
    created: b.created_at
  }));

console.log(JSON.stringify(aiBookmarks, null, 2));

typescript

import { readFileSync } from 'fs';
import { join } from 'path';
import { homedir } from 'os';

const dataDir = process.env.FT_DATA_DIR || join(homedir(), '.fieldtheory');
const bookmarksPath = join(dataDir, 'bookmarks', 'bookmarks.jsonl');

// 读取原始JSONL文件
const bookmarks = readFileSync(bookmarksPath, 'utf8')
  .split('\n')
  .filter(line => line.trim())
  .map(line => JSON.parse(line));

// 筛选并转换数据
const aiBookmarks = bookmarks
  .filter(b => b.classification?.category === 'research')
  .filter(b => b.classification?.domain === 'AI/ML')
  .map(b => ({
    text: b.text,
    author: b.author.screen_name,
    url: b.url,
    created: b.created_at
  }));

console.log(JSON.stringify(aiBookmarks, null, 2));

Programmatic classification

程序化分类

typescript

import { execSync } from 'child_process';

function classifyBookmarks(engine?: string): void {
  const cmd = engine 
    ? `ft classify --engine ${engine}`
    : 'ft classify';
  
  try {
    execSync(cmd, { stdio: 'inherit' });
  } catch (error) {
    console.error('Classification failed:', error);
    throw error;
  }
}

// Use default model
classifyBookmarks();

// Override model
classifyBookmarks('claude-opus-4-20250514');

typescript

import { execSync } from 'child_process';

function classifyBookmarks(engine?: string): void {
  const cmd = engine 
    ? `ft classify --engine ${engine}`
    : 'ft classify';
  
  try {
    execSync(cmd, { stdio: 'inherit' });
  } catch (error) {
    console.error('Classification failed:', error);
    throw error;
  }
}

// 使用默认模型
classifyBookmarks();

// 指定模型
classifyBookmarks('claude-opus-4-20250514');

Build custom knowledge base

构建自定义知识库

bash

undefined

bash

undefined

Export all bookmarks to markdown

将所有书签导出为Markdown格式

ft md

Build wiki with interlinks

构建带内部链接的维基

ft wiki

Ask questions

提问

ft ask "What are the key themes in my AI bookmarks from 2026?"

Save answer as concept page

将答案保存为概念页面

ft ask "Summarize RAG techniques" --save

undefined

ft ask "Summarize RAG techniques" --save

undefined

Possibility automation

创意生成自动化

typescript

import { execSync } from 'child_process';

// Create seed from recent bookmarks
execSync('ft seeds search "ai agents" --days 90 --limit 8 --frame leverage-specificity --create', {
  stdio: 'inherit'
});

// Add repositories
execSync('ft repos add ~/dev/my-agent', { stdio: 'inherit' });
execSync('ft repos add ~/dev/my-framework', { stdio: 'inherit' });

// Run in background
const output = execSync('ft possible run --background --defaults --model opus --effort high --nodes 8', {
  encoding: 'utf8'
});

const jobId = output.match(/Job ID: (\S+)/)?.[1];
console.log(`Started job: ${jobId}`);

typescript

import { execSync } from 'child_process';

// 从近期书签创建种子
execSync('ft seeds search "ai agents" --days 90 --limit 8 --frame leverage-specificity --create', {
  stdio: 'inherit'
});

Library integration

添加代码仓库

typescript

import { execSync } from 'child_process';
import { readFileSync } from 'fs';

// Search library
function searchLibrary(query: string): any[] {
  const output = execSync(`ft library search "${query}" --json`, { encoding: 'utf8' });
  return JSON.parse(output);
}

// Show page with metadata
function showPage(path: string): any {
  const output = execSync(`ft library show "${path}" --json`, { encoding: 'utf8' });
  return JSON.parse(output);
}

// Create page
function createPage(path: string, content: string): void {
  execSync(`ft library create "${path}" --stdin`, {
    input: content,
    stdio: ['pipe', 'inherit', 'inherit']
  });
}

// Update page with conflict protection
function updatePage(path: string, content: string, expectedSha: string): void {
  execSync(`ft library update "${path}" --stdin --expected-sha256 ${expectedSha}`, {
    input: content,
    stdio: ['pipe', 'inherit', 'inherit']
  });
}

const results = searchLibrary('distributed systems');
const page = showPage(results[0].path);
console.log(page.content);

execSync('ft repos add ~/dev/my-agent', { stdio: 'inherit' }); execSync('ft repos add ~/dev/my-framework', { stdio: 'inherit' });

Troubleshooting

后台运行

Sync fails with browser session

—

bash

undefined

const output = execSync('ft possible run --background --defaults --model opus --effort high --nodes 8', { encoding: 'utf8' });

const jobId = output.match(/Job ID: (\S+)/)?.[1]; console.log(

Started job: ${jobId}

);

undefined

Close browser completely and retry

库集成

ft sync

typescript

import { execSync } from 'child_process';
import { readFileSync } from 'fs';

// 搜索库内容
function searchLibrary(query: string): any[] {
  const output = execSync(`ft library search "${query}" --json`, { encoding: 'utf8' });
  return JSON.parse(output);
}

// 查看页面及元数据
function showPage(path: string): any {
  const output = execSync(`ft library show "${path}" --json`, { encoding: 'utf8' });
  return JSON.parse(output);
}

Specify browser explicitly

创建页面

ft sync --browser chrome

function createPage(path: string, content: string): void { execSync(

ft library create "${path}" --stdin

, { input: content, stdio: ['pipe', 'inherit', 'inherit'] }); }

Windows: specify profile

更新页面（带冲突保护）

ft sync --browser chrome --chrome-profile-directory "Default"

function updatePage(path: string, content: string, expectedSha: string): void { execSync(

ft library update "${path}" --stdin --expected-sha256 ${expectedSha}

, { input: content, stdio: ['pipe', 'inherit', 'inherit'] }); }

const results = searchLibrary('distributed systems'); const page = showPage(results[0].path); console.log(page.content);

undefined

Try OAuth instead

故障排查

—

浏览器会话同步失败

ft auth ft sync --api

undefined

bash

undefined

Cookie extraction fails

完全关闭浏览器后重试

bash

undefined

ft sync

Firefox on Windows needs Node 22.5+ or sqlite3 on PATH

明确指定浏览器

node --version

ft sync --browser chrome

Manual cookie fallback (treat as passwords)

Windows系统：指定配置文件

ft sync --cookies <ct0> <auth_token>

undefined

ft sync --browser chrome --chrome-profile-directory "Default"

Windows PowerShell alias conflict

尝试使用OAuth同步

powershell

undefined

ft auth ft sync --api

undefined

Use full command name

Cookie提取失败

fieldtheory sync

bash

undefined

Or ft.cmd

Windows系统下的Firefox需要Node 22.5+或sqlite3在PATH中

ft.cmd sync

undefined

node --version

Classification not working

手动传入Cookie作为备选（需像密码一样妥善保管）

bash

undefined

ft sync --cookies <ct0> <auth_token>

undefined

Ensure API key is set

Windows PowerShell别名冲突

echo $ANTHROPIC_API_KEY

powershell

undefined

Try different engine

使用完整命令名称

ft model ft classify --engine claude-sonnet-4-20250514

fieldtheory sync

Fall back to regex

或使用ft.cmd

ft classify --regex

undefined

ft.cmd sync

undefined

Search index out of sync

分类功能无法工作

bash

undefined

bash

undefined

Rebuild index

确保已设置API密钥

ft index

echo $ANTHROPIC_API_KEY

Or full rebuild

尝试使用不同引擎

ft sync --rebuild

undefined

ft model ft classify --engine claude-sonnet-4-20250514

Media download stalls

退而使用正则表达式分类

bash

undefined

ft classify --regex

undefined

Sync without media

搜索索引不同步

ft sync --no-media

bash

undefined

Skip profile images

重建索引

ft sync --skip-profile-images

ft index

Backfill media separately

或完全重新构建

ft fetch-media

undefined

ft sync --rebuild

undefined

Proxy issues

媒体下载停滞

bash

undefined

bash

undefined

Set proxy env vars

仅同步书签，不下载媒体

export HTTPS_PROXY=http://proxy:8080 export HTTP_PROXY=http://proxy:8080

ft sync --no-media

Retry sync

跳过头像图片

ft sync

undefined

ft sync --skip-profile-images

Data corruption

单独补全媒体资源

bash

undefined

ft fetch-media

undefined

Check status

代理问题

ft status

bash

undefined

Rebuild index

设置代理环境变量

ft index

export HTTPS_PROXY=http://proxy:8080 export HTTP_PROXY=http://proxy:8080

Last resort: full re-sync

重新尝试同步

rm ~/.fieldtheory/bookmarks/bookmarks.db ft sync --rebuild

undefined

ft sync

undefined

OAuth token expired

数据损坏

bash

undefined

bash

undefined

Re-authenticate

查看状态

ft auth

ft status

Sync with fresh token

重建索引

ft sync --api

undefined

ft index

Security notes

最后方案：完全重新同步

Local-first: No telemetry, no analytics, no phone-home
Session sync reads cookies from browser database, uses them once, discards

OAuth tokens stored with

chmod 600

~/.fieldtheory/bookmarks/oauth-token.json

Treat
```
ct0
```
,
```
auth_token
```
, and
```
oauth-token.json
```
like passwords
Default sync uses X's internal GraphQL API (same as browser)
OAuth sync uses official v2 API

rm ~/.fieldtheory/bookmarks/bookmarks.db ft sync --rebuild

undefined

Platform support

OAuth令牌过期

Feature	macOS	Linux	Windows
Session sync	✓	✓	✓
OAuth API	✓	✓	✓
Search/classify	✓	✓	✓
Supported browsers	Chrome, Chromium, Brave, Edge, Firefox, Helium, Comet, Dia	Chrome, Chromium, Brave, Edge, Firefox	Chrome, Chromium, Brave, Edge, Firefox

bash

undefined

Additional resources

重新认证

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

ft auth

—

使用新令牌同步

—

ft sync --api

undefined

—

安全说明

—

本地优先：无遥测、无分析、无后台上报
会话同步：读取浏览器数据库中的Cookie，仅使用一次后即丢弃

OAuth令牌：以

chmod 600

权限存储在

~/.fieldtheory/bookmarks/oauth-token.json

请将
```
ct0
```
、
```
auth_token
```
和
```
oauth-token.json
```
视为密码妥善保管
默认同步使用X的内部GraphQL API（与浏览器一致）
OAuth同步使用官方v2 API

—

平台支持

—

功能	macOS	Linux	Windows
会话同步	✓	✓	✓
OAuth API	✓	✓	✓
搜索/分类	✓	✓	✓
支持的浏览器	Chrome、Chromium、Brave、Edge、Firefox、Helium、Comet、Dia	Chrome、Chromium、Brave、Edge、Firefox	Chrome、Chromium、Brave、Edge、Firefox

—

额外资源

—

主页：https://fieldtheory.dev/cli
GitHub：https://github.com/afar1/fieldtheory-cli
许可证：MIT