Supertag Cli

Supertag CLI

完整的 Tana 集成：通过命令行查询、写入、搜索和自动化你的 Tana 工作区。

v2.0.0 新功能

Tana 已正式发布其本地 API 和 MCP 服务，Supertag CLI 现已全面集成。这意味着 supertag-cli 不再局限于只读导出和基本节点创建——你现在可以直接通过命令行或任何兼容 MCP 的 AI 工具编辑节点、管理标签、设置字段值、勾选任务，以及将节点移入废纸篓。新的增量同步功能使用本地 API 获取自上次同步以来发生变化的节点，无需完整重新导出即可快速增量更新。你只需运行启用了本地 API 的 Tana Desktop。Supertag CLI 会自动检测本地 API；当 Tana Desktop 不可用时，则回退到 Input API，因此你现有的工作流无需任何更改即可继续使用。

三工具架构

工具	大小	用途
supertag	~57 MB	主 CLI - 查询、写入、同步、服务
supertag-export	~59 MB	用于导出的浏览器自动化工具
supertag-mcp	~60 MB	用于集成 AI 工具的 MCP 服务

下载：GitHub Releases（macOS ARM64/Intel、Linux x64、Windows x64）

刚开始使用 Supertag？ 请查看可视化入门指南，其中包含逐步截图说明。

了解更多：视频课程 | Discord 社区

---

目录

• 快速开始
• 功能
  • READ - 查询工作区
  • WRITE - 创建节点
  • MUTATE - 编辑现有节点
  • QUERY - 统一查询语言
  • GQUERY - 图查询 DSL
  • BATCH - 多节点操作
  • AGGREGATE - 分组与计数
  • TIMELINE - 基于时间的查询
  • RELATED - 图遍历
  • WATCH - 持续监控
  • EXPORT - 自动备份
  • EMBED - 语义搜索
  • TABLE - 批量导出字段
  • CONTEXT - AI 上下文组装
  • RESOLVE - 实体解析
  • FIELDS - 查询字段值
  • TRANSCRIPTS - 会议录音
  • ATTACHMENTS - 提取附件
  • SERVER - Webhook API
  • VISUALIZE - 可视化继承关系图
  • CODEGEN - 生成 Effect Schema 类
  • MCP - AI 工具集成
  • WORKSPACES - 多工作区
  • SCHEMA - Supertag 注册表
  • OUTPUT - 显示格式设置
• 示例
• 安装
• 文档
• 故障排除
• 性能
• 参与贡献

---

快速开始

Homebrew（推荐用于 macOS）

brew tap jcfischer/supertag
brew install supertag

或者使用一条命令：

brew install jcfischer/supertag/supertag

此命令会安装所有二进制文件（supertag、supertag-mcp、supertag-export），并通过 brew upgrade supertag 保持它们为最新版本。

单行安装（替代方案）

macOS / Linux：

curl -fsSL https://raw.githubusercontent.com/jcfischer/supertag-cli/main/install.sh | bash

Windows（PowerShell）：

irm https://raw.githubusercontent.com/jcfischer/supertag-cli/main/install.ps1 | iex

此命令会安装所有内容：Bun、Playwright、Chromium、supertag-cli，并配置 MCP。

需要手动安装？ 查看特定平台的指南：Windows | macOS | Linux

迁移（从旧版本升级）

如果要从旧版 supertag-cli 升级，请将数据库迁移到新的 XDG 兼容位置：

supertag migrate           # Migrate database to new location
supertag migrate --dry-run # Preview migration without making changes

此命令会将数据库从旧位置移至标准 XDG 路径（~/.local/share/supertag/）。

1. 配置 API 令牌

从此处获取令牌：https://app.tana.inc/?bundle=settings&panel=api

./supertag config --token "your_token_here"

2. 登录并导出

supertag-export login      # Opens browser for Tana login
supertag-export discover   # Find your workspaces
supertag-export run        # Export your data
supertag sync index        # Index the export

3. 开始使用

./supertag search "meeting"                    # Full-text search
./supertag search "project ideas" --semantic   # Semantic search
./supertag create todo "Buy groceries"         # Create nodes
./supertag stats                               # Database stats

---

功能

READ - 查询工作区

supertag search "project"                    # Full-text search
supertag search "project" --semantic         # Semantic search
supertag search "ideas" --semantic --min-score 0.5  # Filter by similarity
supertag search --tag todo                   # All nodes with #todo tag
supertag search "groceries" --tag todo       # #todo nodes containing "groceries"
supertag search --tag meeting --field "Location=Zurich"  # Filter by field
supertag nodes show <id>                     # Node contents (day pages auto-expand)
supertag nodes show <id> --depth 3           # Explicit depth traversal
supertag related <id>                        # Find related nodes
supertag related <id> --depth 2              # Multi-hop traversal
supertag tags top                            # Most used tags
supertag tags inheritance manager            # Show tag hierarchy
supertag tags fields meeting --all           # Show tag fields with types
supertag tags show task                      # Show fields with option values
supertag tags visualize                      # Inheritance graph (mermaid)
supertag tags visualize --format dot         # Graphviz DOT format
supertag stats                               # Statistics

WRITE - 创建节点

supertag create todo "Task name" --status active
supertag create meeting "Team Standup" --date 2025-12-06
supertag create video,towatch "Tutorial" --url https://example.com

# Reference existing nodes by name with @ prefix
supertag create task "My Task" --state "@Open"
supertag create meeting "Standup" --owner "@John Doe"
supertag create task "Project" --assignees "@Alice,@Bob"

MUTATE - 编辑现有节点

需要运行 Tana Desktop 并启用 Local API。使用以下命令进行配置：

supertag config --bearer-token <token>   # From Tana Desktop > Settings > Local API

# Update node name or description
supertag edit <nodeId> --name "New name"
supertag edit <nodeId> --description "Updated description"

# Tag operations
supertag tag add <nodeId> <tagName>        # name resolved via the index; exits 1 if not applied
supertag tag add <nodeId> <tagId> --tag-id # skip name resolution
supertag tag remove <nodeId> <tagNameOrId>
supertag tag create "sprint" --description "Sprint supertag"

# Set field values (field name is resolved via the index; or pass the attribute ID)
supertag set-field <nodeId> "Status" "value"
supertag set-field --field-id <attributeId> -- <nodeId> "Status" "value"   # skip name resolution
supertag set-field <nodeId> <fieldNameOrId> "additional value" --append
supertag set-field <nodeId> <fieldNameOrId> --option-id <optionId>       # no value with --option-id
supertag set-field <nodeId> <fieldNameOrId> --option-id <optionId> --append
# IDs starting with "-": use --option-id=-MG-xxx and put positionals after --
supertag set-field --option-id=-MG-UldK1Pn2 -- -P11YGvsvmBb "Status"

# Check/uncheck and trash
supertag done <nodeId>
supertag undone <nodeId>
supertag trash <nodeId> --confirm

注意： 这些命令需要 Local API 后端。如果 Tana Desktop 未运行，supertag 会回退到 Input API（仅支持创建操作）。

FORMAT - JSON 转 Tana Paste

将 JSON 数据转换为 Tana Paste 格式以便批量导入：

# From stdin
echo '{"name": "Test Node"}' | supertag format

# From file
cat data.json | supertag format

# From API response
curl https://api.example.com/data | supertag format

适用于集成外部数据源并将数据批量导入 Tana。

QUERY - 统一查询语言

使用类似 SQL 的查询，通过单条命令进行复杂筛选。

# Find todos with specific status
supertag query "find todo where Status = Done"

# Filter by date with relative dates
supertag query "find meeting where created > 7d"
supertag query "find task where Due < today"

# Combine conditions with AND/OR
supertag query "find project where Status = Active and Priority >= 2"
supertag query "find task where (Status = Open or Status = InProgress)"

# Contains search
supertag query "find contact where Name ~ John"

# Parent path queries
supertag query "find task where parent.tags ~ project"

# Sort and limit results
supertag query "find meeting order by -created limit 10"

# Include all supertag fields in output
supertag query "find contact select *"

# Include specific supertag fields
supertag query "find contact select 'Email,Phone,Company'"

# Find nodes with empty/missing field values
supertag query "find task where Status is empty"

运算符：

运算符	含义	示例
=	精确匹配	Status = Done
~	包含	Name ~ John
>, <, >=, <=	比较	Priority >= 2
exists	字段有值	Due exists
is empty	字段为空或缺失	Status is empty
not	否定	not Status = Done
and, or	逻辑运算	A and (B or C)

相对日期： today、yesterday、7d、30d、1w、1m、1y

Select 子句（在查询中内联使用）：

• 不指定 select = 仅核心字段（id、name、created）
• select * = 所有 supertag 字段，包括继承字段
• select "Email,Phone" = 按名称指定字段

GQUERY - 图查询 DSL

使用声明式图查询，在单条语句中遍历类型化关系。

# Find all persons
supertag gquery "FIND person RETURN name"

# Filter with WHERE clause
supertag gquery 'FIND person WHERE name ~ Simon RETURN name'

# Graph traversal: find meetings connected to persons
supertag gquery 'FIND person CONNECTED TO meeting RETURN name'

# Traverse via specific field
supertag gquery 'FIND meeting CONNECTED TO person VIA Attendees RETURN name, Date, person.name'

# Multi-hop traversal
supertag gquery 'FIND project CONNECTED TO person VIA "Team Members" CONNECTED TO meeting RETURN meeting.name'

# Show execution plan without running
supertag gquery 'FIND meeting CONNECTED TO person RETURN name' --explain

# Output formats and limits
supertag gquery "FIND person RETURN name" --format json
supertag gquery "FIND todo RETURN name" --limit 10

DSL 语法：

FIND <supertag>
  [WHERE <field> <op> <value>]*
  [CONNECTED TO <supertag> [VIA <field>]]*
  [DEPTH <n>]
  RETURN <projection>

运算符： =、!=、>、<、>=、<=、~（包含）、LIKE、CONTAINS

与 query 的区别： query 命令针对节点索引运行类似 SQL 的扁平查询。gquery 命令则能理解图结构——它使用 CONNECTED TO 遍历 supertag 之间的类型化关系，并可使用点表示法投影相关节点的字段。

完整语法和 MCP 用法请参阅图查询文档。

BATCH - 多节点操作

在单个请求中高效获取或创建多个节点。

# Fetch multiple nodes by ID
supertag batch get id1 id2 id3

# Pipe from search (get IDs, then fetch full details)
supertag search "meeting" --format ids | supertag batch get --stdin

# With children (depth 1-3)
supertag batch get id1 id2 --depth 2

# Create multiple nodes from JSON file
supertag batch create --file nodes.json

# Create from stdin
echo '[{"supertag":"todo","name":"Task 1"},{"supertag":"todo","name":"Task 2"}]' | \
  supertag batch create --stdin

# Dry-run mode (validate without creating)
supertag batch create --file nodes.json --dry-run

批量创建的输入格式：

[
  {"supertag": "todo", "name": "Task 1", "fields": {"Status": "Open"}},
  {"supertag": "meeting", "name": "Standup", "children": [{"name": "Agenda item"}]}
]

限制： batch get 最多 100 个节点，batch create 最多 50 个节点。

AGGREGATE - 分组与计数

按字段值或时间段汇总节点。适用于分析、状态分布和时间序列分析。

# Count tasks by status
supertag aggregate --tag task --group-by Status

# Time-based aggregation
supertag aggregate --tag meeting --group-by month
supertag aggregate --tag todo --group-by week

# Two-dimensional grouping
supertag aggregate --tag task --group-by Status,Priority

# Show percentages and top N
supertag aggregate --tag task --group-by Status --show-percent
supertag aggregate --tag meeting --group-by month --top 5

# Output formats
supertag aggregate --tag task --group-by Status --json
supertag aggregate --tag task --group-by Status --format csv

时间段： day、week、month、quarter、year

输出：

Status    Count   Percent
Done      50      50%
Active    30      30%
Open      20      20%
Total: 100 nodes in 3 groups

更多示例请参阅聚合文档。

TIMELINE - 基于时间的查询

以可配置的粒度查看各时间段内的活动。

# Last 30 days, daily buckets (default)
supertag timeline

# Weekly view of last 3 months
supertag timeline --from 3m --granularity week

# Monthly view for a specific year
supertag timeline --from 2025-01-01 --to 2025-12-31 --granularity month

# Filter by supertag
supertag timeline --tag meeting --granularity week

# Recently created/updated items
supertag recent                    # Last 24 hours
supertag recent --period 7d        # Last 7 days
supertag recent --period 1w --types meeting,task

# Only created or only updated
supertag recent --created          # Only newly created
supertag recent --updated          # Only updated (not created)

粒度级别： hour、day、week、month、quarter、year

时间段格式： Nh（小时）、Nd（天）、Nw（周）、Nm（月）、Ny（年）

日期格式：

• ISO 日期：2025-01-01、2025-06-15
• 相对日期：7d（7 天前）、30d、1m、1w、1y
• 特殊日期：today、yesterday

RELATED - 图遍历

通过引用、子节点和字段链接查找与给定节点相关的节点。

# Find all nodes connected to a topic
supertag related <id> --pretty

# Direction filtering
supertag related <id> --direction out    # What this node references
supertag related <id> --direction in     # What references this node

# Filter by relationship type
supertag related <id> --types reference  # Only inline references
supertag related <id> --types field      # Only field connections
supertag related <id> --types child,parent  # Structural relationships

# Multi-hop traversal (depth 1-5)
supertag related <id> --depth 2          # Find nodes within 2 hops

# Output formats
supertag related <id> --json             # JSON for scripting
supertag related <id> --format csv       # CSV for spreadsheets
supertag related <id> --format ids       # IDs for piping to other commands

关系类型： child、parent、reference、field

输出：

🔗 Related to: Project Alpha:

📤 Outgoing (3):
  → John Smith [person]
     Type: field
  → Product Roadmap
     Type: reference

📥 Incoming (5):
  ← Meeting notes from Q4 planning [meeting]
     Type: reference
  ← Task: Review project scope [todo]
     Type: field

Total: 8

更多示例请参阅图遍历文档。

SYNC - 索引与增量同步

# Full reindex from export files
supertag sync index

# Delta-sync: fetch only changes since last sync (requires Tana Desktop + Local API)
supertag sync index --delta

# Check sync status (includes delta-sync info)
supertag sync status

# Cleanup old exports
supertag sync cleanup --keep 5

增量同步使用 Tana Desktop 的 Local API，仅获取自上次同步以来发生更改的节点，速度远快于完整重新索引。需要运行 Tana Desktop 并启用 Local API，同时配置 bearer token（supertag config --bearer-token <token>）。

MCP 服务可按可配置的间隔在后台自动执行增量同步（默认：每 5 分钟）。在配置中设置 localApi.deltaSyncInterval，或使用 TANA_DELTA_SYNC_INTERVAL 环境变量（0 表示禁用轮询）。

⚠️ 字段筛选查询需要近期进行过完整同步

增量同步在 supertag 字段值方面存在已知的正确性缺陷。增量同步检测到节点更改时，会清除该节点在 field_values 表中的条目，但不会重新填充这些条目——通过 Local API 无法获取重新提取字段值所需的元组结构。之后进行完整同步（supertag sync index，不带 --delta）时，会从导出 JSON 中重新填充这些条目。

影响：

• 对 supertag 字段进行筛选的查询（例如，where: { "Time Sector": "🔴 This week" }）只有在近期执行过完整同步的数据库中才完全准确。两次完整同步之间，增量同步会逐渐降低字段筛选的准确性。
• 如果 Tana 中的节点字段值发生变化，但节点本身没有其他编辑，Local API 的 edited.since 筛选器可能不会返回该节点——增量同步会完全漏掉仅字段值的更改。过时的值会保留在 field_values 中，直到下次完整同步。
• tana_query 和 tana_stats 现在会发出过时警告/标记（见下文），以便调用方在信任结果前检测这种状态。

建议的频率： 除基于增量同步的工作流外，还应安排每晚执行一次 supertag sync index（从最新导出文件完整重新索引）。增量同步仅用于保持名称/标签/创建时间更改和语义搜索的新鲜度。

过时检测

tana_stats 和 tana_query 现在都会显示索引的新鲜度：

• tana_stats 返回 lastFullSync、lastDeltaSync、lastDeltaNodesCount、secondsSinceLastSync 和 isStale 字段。
• 当索引超过配置的阈值，或字段筛选查询针对从未进行过完整同步的数据库运行时，tana_query 会返回 warnings 数组。

可配置阈值（环境变量）：

变量	默认值	用途
SUPERTAG_STALE_DELTA_MINUTES	60	最近一次同步（完整或增量）超过此时长时发出警告。
SUPERTAG_STALE_FULL_HOURS	168（7 天）	上次完整同步超过此时长时发出警告（字段值可能漂移）。
SUPERTAG_LOCAL_API_TIMEOUT_MS	30000	Local API 调用的单次请求超时时间。挂起的请求会中止并重试。

WATCH - 持续监控

实时监控 Tana 的更改并触发自动化钩子。

# Watch for changes with default 30s interval
supertag sync watch

# Custom interval (minimum 5s)
supertag sync watch -i 10

# Execute shell commands on specific events
supertag sync watch --on-change "echo 'Something changed'"
supertag sync watch --on-create "notify-send 'New node created'"
supertag sync watch --on-modify "curl -X POST http://localhost/webhook"
supertag sync watch --on-delete "echo 'Node deleted'"

# Watch only specific supertags
supertag sync watch --filter-tag todo --on-create "say 'New todo'"

# Dry run — detect changes without executing hooks
supertag sync watch --dry-run

# Custom event log path (default: ~/.local/share/supertag/watch-events.jsonl)
supertag sync watch --event-log ./events.jsonl

要求： 运行 Tana Desktop 并启用 Local API。底层使用增量同步——每次轮询只获取已更改的节点。

钩子通过环境变量（SUPERTAG_EVENT_TYPE、SUPERTAG_NODE_ID、SUPERTAG_NODE_NAME 等）接收更改详情。所有事件都会记录到 JSONL 文件中，以供审计和重放。

故障处理： 轮询失败时采用指数退避（5 秒 → 10 秒 → 20 秒 → ... → 最多 60 秒）。默认连续失败 10 次后退出（--max-failures）。

EXPORT - 自动备份

设置

首次运行导出前，请安装所需的浏览器：

supertag-export setup        # Install Playwright browser

这会安装自动执行 Tana 导出所需的 Chromium 浏览器。

工作区发现

通过网络流量捕获自动发现 Tana 工作区 ID：

supertag-export discover              # Discover all workspaces
supertag-export discover --add        # Auto-add discovered workspaces to config
supertag-export discover --update     # Update existing workspaces with rootFileIds

捕获网络流量以查找工作区 ID 和 rootFileIds，简化初始设置。如果尚未配置工作区，则自动将发现的第一个工作区添加为“main”。

导出命令

supertag-export login        # First-time login
supertag-export run          # Export workspace
supertag-export run --all    # Export all workspaces

详情请参阅导出文档。

清理导出文件

删除旧的导出文件以释放磁盘空间：

supertag sync cleanup             # Remove old exports, keep most recent
supertag sync cleanup --keep 3    # Keep 3 most recent files
supertag sync cleanup --all       # Clean up all workspaces
supertag sync cleanup --dry-run   # Preview what would be deleted

EMBED - 语义搜索

supertag embed config --model bge-m3    # Configure
supertag embed generate                  # Generate embeddings (graph-aware by default)
supertag embed generate --no-graph-aware # Legacy ancestor-based contextualization
supertag embed generate --enrichment-preview <nodeId>  # Preview enriched text
supertag search "ideas" --semantic       # Search by meaning
supertag search "meetings" --semantic --type-hint meeting  # Type-aware search

# Maintenance and diagnostics
supertag embed stats                     # Embedding health: count, staleness, fragmentation
supertag embed maintain compact          # Merge fragmented LanceDB storage
supertag embed maintain stale            # Remove orphaned embeddings for deleted nodes
supertag embed maintain rebuild          # Full reindex from scratch
supertag embed filter-stats              # Show content filter breakdown

详情请参阅嵌入文档。

TABLE - 批量字段导出

将某个 supertag 的所有实例导出为表格，并解析字段值。使用批量查询进行高效提取，无论实例数量多少，字段值和引用解析的复杂度均为 O(1)。

# Export all books as a table
supertag table book

# Select specific columns
supertag table person --fields "Name,Email,Company"

# Filter rows by field value
supertag table task --where "Status=Done"

# Sort and paginate
supertag table project --sort Name --direction asc --limit 50

# Export formats
supertag table book --format csv > books.csv
supertag table book --format json
supertag table book --format markdown

# Show raw IDs instead of resolved names
supertag table contact --no-resolve

功能：

• 提取所有 supertag 字段及其类型和值
• 自动将引用字段解析为易读的名称
• 多值字段以逗号分隔的列表显示
• --fields 和 --where 中的字段名称不区分大小写
• 支持分页，可使用 --limit 和 --offset

输出格式： table（默认）、json（包含原始值和解析后的值）、csv、markdown

CONTEXT - AI 上下文组装

组装关于节点的丰富上下文，并控制令牌预算，供 AI 使用。将节点内容、字段和相关节点组合为结构化格式，以优化大模型上下文窗口的利用。

# Get context about a topic (default: general lens, 4000 tokens max)
supertag context "quarterly planning"

# Use a specific lens for focused context
supertag context "sprint review" --lens project-management
supertag context "research paper" --lens research
supertag context "team standup" --lens meeting

# Control depth and token budget
supertag context "architecture" --depth 3 --max-tokens 8000

# Include field values in context
supertag context "client project" --include-fields

# Output as JSON for programmatic use
supertag context "onboarding" --format json

视角： general（默认）、writing、project-management、research、meeting——每种视角会优先呈现工作区数据的不同方面。

RESOLVE - 实体解析

使用多种匹配策略（精确、模糊、语义）将含糊的名称解析为特定的 Tana 节点。

# Resolve a name to a node
supertag resolve "John Smith"

# Resolve within a specific tag
supertag resolve "Sprint 4" --tag project

# Exact match only (no fuzzy/semantic)
supertag resolve "Meeting Notes" --exact

# Adjust confidence threshold (default: 0.85)
supertag resolve "quarterly review" --threshold 0.7

# Create node if no match found
supertag resolve "New Client" --tag contact --create-if-missing

# Batch resolve multiple names
supertag resolve --batch "Alice,Bob,Charlie" --tag person

匹配策略： 精确名称匹配（最快）、模糊 Levenshtein 距离、通过嵌入实现语义相似度。结果按置信度评分排序。

FIELDS - 查询字段值

查询 Tana 节点中的结构化字段数据。“Summary”“Action Items”等字段或自定义字段会将值存储在元组子节点中。

# Discover what fields exist
supertag fields list                              # List all field names with counts

# Query specific fields
supertag fields values "Summary" --limit 10       # Get values for a field
supertag fields values "Action Items" --after 2025-01-01  # Filter by date

# Full-text search
supertag fields search "meeting notes"            # FTS search in all fields
supertag fields search "project" --field Summary  # Search within specific field

# Export for analysis
supertag fields values "Gratitude" --json > reflections.json

详情请参阅字段值文档。

TRANSCRIPTS - 会议录音

查询和搜索会议文字记录。默认情况下，文字记录不会纳入常规搜索，以保持结果整洁。

# List meetings with transcripts
supertag transcript list                      # Tab-separated output
supertag transcript list --pretty             # Formatted table
supertag transcript list --limit 10           # Recent 10 meetings

# View transcript content
supertag transcript show <meeting-id>         # Full transcript with speakers
supertag transcript show <id> --pretty        # Formatted with speaker sections
supertag transcript show <id> --json          # JSON with timing metadata

# Search within transcripts only
supertag transcript search "budget"           # Find spoken mentions
supertag transcript search "quarterly" --limit 5

纳入嵌入：

supertag embed generate --include-transcripts  # Opt-in for semantic search

详情请参阅文字记录文档。

ATTACHMENTS - 提取附件

发现并下载 Tana 导出文件中的附件（图像、PDF、音频、视频）。

# List all attachments
supertag attachments list                       # JSON output (default)
supertag attachments list --format table        # Human-readable table
supertag attachments list --extension png       # Filter by extension
supertag attachments list --tag meeting         # Filter by parent tag

# Show statistics
supertag attachments stats                      # Count by extension and tag

# Download attachments
supertag attachments extract                    # Download all to ~/Downloads/tana-attachments
supertag attachments extract -o ./my-files      # Custom output directory
supertag attachments extract --organize-by date # Organize by date (YYYY/MM/)
supertag attachments extract --organize-by tag  # Organize by supertag
supertag attachments extract --skip-existing    # Skip already downloaded files
supertag attachments extract --dry-run          # Preview without downloading

# Download single attachment (use --id since Tana IDs start with -)
supertag attachments get --id <nodeId>               # Download by node ID
supertag attachments get --id <nodeId> -o ./file.png # Custom output path

整理方式：

策略	说明	示例路径
flat	所有文件放在输出目录中（默认）	./attachments/image.png
date	按年/月整理	./attachments/2025/04/image.png
tag	按父级 supertag 整理	./attachments/meeting/image.png
node	按父级节点 ID 整理	./attachments/abc123/image.png

选项：

标志	说明
-o, --output <dir>	输出目录（默认：~/Downloads/tana-attachments）
--organize-by <strategy>	整理方式：flat、date、tag、node
-c, --concurrency <n>	并行下载数量，范围为 1-10（默认：3）
--skip-existing	跳过已存在的文件
-t, --tag <tags...>	按 supertag 筛选
-e, --extension <exts...>	按扩展名筛选（png、pdf 等）
--dry-run	列出文件但不下载

SERVER - Webhook API

# Start the server
supertag server start [--port <port>]    # Run in foreground
supertag server start --daemon           # Run as background daemon

# Stop the server (daemon mode)
supertag server stop

# Check server status
supertag server status

# Example API call
curl http://localhost:3100/search -d '{"query": "meeting"}'

API 参考请参阅Webhook 服务文档。

VISUALIZE - 继承关系图

生成 supertag 继承层级的可视化表示。

# Mermaid flowchart (default) - paste into Obsidian, GitHub, etc.
supertag tags visualize

# Graphviz DOT format - render with `dot -Tpng`
supertag tags visualize --format dot

# JSON data structure for custom tooling
supertag tags visualize --format json

# Filter options
supertag tags visualize --root entity              # Subtree from a tag
supertag tags visualize --direction LR             # Left-to-right layout
supertag tags visualize --show-fields              # Show field counts
supertag tags visualize --colors                   # Use tag colors (DOT)

# Write to file
supertag tags visualize --output graph.md
supertag tags visualize --format dot --output graph.dot

输出格式：

• mermaid - Mermaid 流程图语法（默认）
• dot - Graphviz DOT，可渲染为 SVG/PNG/PDF
• json - 用于自定义可视化的原始数据

渲染说明请参阅可视化文档。

CODEGEN - 生成 Effect Schema 类

根据你的 Tana 超级标签生成类型安全的 Effect Schema 类定义。

# Generate single file with all supertags
supertag codegen generate -o ./generated/schemas.ts

# Filter to specific supertags
supertag codegen generate -o ./generated/todo.ts --tags TodoItem Meeting

# Generate separate files per supertag
supertag codegen generate -o ./generated/schemas.ts --split

# Preview without writing
supertag codegen generate -o ./generated/schemas.ts --dry-run

输出示例：

import { Schema } from "effect";

export class TodoItem extends Schema.Class<TodoItem>("TodoItem")({
  id: Schema.String,
  title: Schema.optionalWith(Schema.String, { as: "Option" }),
  dueDate: Schema.optionalWith(Schema.DateFromString, { as: "Option" }),
  completed: Schema.optionalWith(Schema.Boolean, { as: "Option" }),
}) {}

// Child class extends parent
export class WorkTask extends TodoItem.extend<WorkTask>("WorkTask")({
  project: Schema.optionalWith(Schema.String, { as: "Option" }),
}) {}

选项：

标志	描述
-o, --output <path>	输出文件路径（必需）
-t, --tags <tags...>	筛选指定的超级标签
--split	为每个超级标签生成单独的文件
--optional <strategy>	option（默认）、undefined 或 nullable
--no-metadata	排除超级标签元数据注释
-d, --dry-run	预览但不写入文件

类型映射：

Tana 类型	Effect Schema
text	Schema.String
number	Schema.Number
date	Schema.DateFromString
checkbox	Schema.Boolean
url	Schema.String.pipe(Schema.pattern(/^https?:\/\//))
email	Schema.String
reference	Schema.String
options	Schema.String

MCP - AI 工具集成

与 Claude Desktop、ChatGPT、Cursor、VS Code 及其他兼容 MCP 的 AI 工具集成。

{
  "mcpServers": {
    "tana": { "command": "/path/to/supertag-mcp" }
  }
}

工具模式： 三种模式用于控制注册哪些工具：

模式	工具数	标志	使用场景
full	37	（默认）	独立使用 — 可用所有工具
slim	17	--slim	针对上下文优化 — 为 AI Agent 提供更少的工具
lite	21	--lite	配合 tana-local MCP — 仅提供分析和搜索

# Lite mode: complement tana-local with analytics/search tools
supertag-mcp --lite

# Slim mode: reduced tool set for simpler AI agents
supertag-mcp --slim

# Or via environment variable / config
TANA_MCP_TOOL_MODE=lite supertag-mcp
# { "mcp": { "toolMode": "lite" } }

Lite 模式专为双层 MCP 设置而设计：Tana 官方的 tana-local MCP 负责实时工作区 CRUD（读取、创建、编辑、标记、移至废纸篓），supertag-mcp 则提供互补的分析层，包括语义搜索、聚合、时间线、字段查询、转录文本、图遍历、上下文组装、实体解析和架构分析。被排除的工具会返回一条消息，指向对应的 tana-local 工具。

Slim 模式保留语义搜索、所有变更工具、同步、清除缓存、功能集和工具架构。移除与语义搜索功能重叠的只读查询工具。

后台增量同步： 当 Tana Desktop 可连接时，MCP 服务会自动在后台运行增量同步（默认每 5 分钟一次）。可通过 localApi.deltaSyncInterval 或 TANA_DELTA_SYNC_INTERVAL 配置（设为 0 可禁用）。

请参阅 MCP 文档了解设置指南。

WORKSPACES - 多工作区

使用独立的数据库和配置管理多个 Tana 工作区。

# List all workspaces
supertag workspace list

# Add a new workspace
supertag workspace add <alias> --workspace-id <id> --token <token>

# Remove a workspace
supertag workspace remove <alias>

# Set default workspace
supertag workspace set-default <alias>

# Show workspace details
supertag workspace show <alias>

# Enable/disable a workspace
supertag workspace enable <alias>
supertag workspace disable <alias>

# Update workspace configuration
supertag workspace update <alias> [options]

# Use a specific workspace in commands
supertag search "meeting" -w work

详情请参阅工作区文档。

SCHEMA - 超级标签注册表

管理超级标签架构注册表。该注册表存储工作区中的超级标签定义，包括字段和继承关系。

# Sync schemas from Tana export (updates field definitions)
supertag schema sync

# List all registered supertags
supertag schema list

# Show details for a specific supertag (fields, options, inheritance)
supertag schema show meeting

# Search supertags by name
supertag schema search "task"

# Audit schema quality — detect issues across all supertags
supertag schema audit
supertag schema audit --severity warning     # Only warnings and above
supertag schema audit --detector orphan-tags # Run specific detector
supertag schema audit --tag project          # Audit a specific supertag
supertag schema audit --format json          # Machine-readable output

# Auto-fix safe issues (interactive confirmation)
supertag schema audit --fix
supertag schema audit --fix --yes            # Apply all safe fixes without prompting

# Use specific workspace
supertag schema list -w work

审计检测器： orphan-tags、low-usage、duplicate-fields、type-mismatch、unused-fields、fill-rate、missing-inheritance。每个检测器都会生成带有严重级别的发现结果：critical、warning、info。

输出格式： --format table（默认）、--format json、--format names（仅限 list 命令）

OUTPUT - 显示格式

所有命令均支持 --format <type>，可使用以下选项：

格式	描述	使用场景
table	带表情符号，便于阅读	交互式终端使用
json	格式化的 JSON 数组	API 集成、jq 处理
csv	符合 RFC 4180 的 CSV	Excel、电子表格
ids	每行一个 ID	xargs 管道、脚本
minimal	精简 JSON（id、name、tags）	快速查找
jsonl	JSON Lines（流式）	日志处理、大型数据集

# Explicit format selection
supertag search "meeting" --format csv > meetings.csv
supertag tags list --format ids | xargs -I{} supertag tags show {}
supertag search "project" --format jsonl >> results.jsonl

# TTY auto-detection (interactive terminal gets table output)
supertag search "meeting"                  # Rich table in terminal
supertag search "meeting" | jq '.[0]'      # JSON when piped

# Shortcuts (legacy support)
supertag search "meeting" --pretty         # Same as --format table
supertag search "meeting" --json           # Same as --format json

# Select specific fields (reduces output)
supertag search "meeting" --json --select id,name,tags
supertag nodes show <id> --json --select id,name,fields
supertag fields values Status --json --select valueText,parentId

# Verbose mode: Additional details
supertag search "meeting" --verbose    # Adds timing info
supertag tags top --verbose            # Adds tag IDs

格式解析优先级：

1. --format <type> 标志（显式指定）
2. --json 或 --pretty 标志（快捷方式）
3. SUPERTAG_FORMAT 环境变量
4. 配置文件（output.format）
5. TTY 检测：交互式使用时采用 table，管道/脚本中采用 json

输出标志：

标志	描述
--format <type>	输出格式（table、json、csv、ids、minimal、jsonl）
--pretty	--format table 的快捷方式
--json	--format json 的快捷方式
--select <fields>	选择 JSON 输出中的特定字段（以逗号分隔）
--verbose	包含技术详情（耗时、ID）
--human-dates	本地化日期格式（Dec 23, 2025）
--no-header	在 CSV 输出中省略表头

配置：

在 ~/.config/supertag/config.json 中设置默认值：

{
  "output": {
    "format": "table",
    "humanDates": false
  }
}

环境变量：

export SUPERTAG_FORMAT=csv  # Default to CSV output

其他环境变量：

变量	描述	默认值
TANA_DELTA_SYNC_INTERVAL	增量同步轮询间隔，单位为分钟（0 表示禁用）	5
TANA_MCP_TOOL_MODE	MCP 工具模式：full（36 个工具）、slim（17 个工具）或 lite（20 个工具）	full
TANA_LOCAL_API_TOKEN	Tana Desktop Local API 的 Bearer 令牌
TANA_LOCAL_API_URL	本地 API 端点 URL	http://localhost:8262

---

示例

examples/ 目录包含演示 supertag-cli 功能的示例应用：

TUI Todo（examples/tui-todo/）

一个基于终端的待办事项管理器，使用 Ink（适用于 CLI 的 React）构建。演示了：

• 代码生成集成：使用从 Tana 超级标签生成的 Effect Schema 类
• SQLite 查询：读取 supertag-cli 索引数据库中的数据
• Tana Input API：直接在 Tana 中创建待办事项
• 分屏 UI：采用 Vim 风格的导航，并支持搜索/筛选

cd examples/tui-todo
bun install
bun run start

完整文档请参阅 examples/tui-todo/README.md。

---

安装

一键安装（推荐）

安装程序会处理所有事项：Bun 运行时、Playwright、Chromium 浏览器、supertag-cli 二进制文件、PATH 配置以及 MCP 自动设置。

macOS / Linux：

curl -fsSL https://raw.githubusercontent.com/jcfischer/supertag-cli/main/install.sh | bash

Windows（PowerShell）：

irm https://raw.githubusercontent.com/jcfischer/supertag-cli/main/install.ps1 | iex

选项：

./install.sh --version 1.9.0    # Install specific version
./install.sh --no-mcp           # Skip MCP auto-configuration

卸载

# macOS/Linux
curl -fsSL https://raw.githubusercontent.com/jcfischer/supertag-cli/main/uninstall.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/jcfischer/supertag-cli/main/uninstall.ps1 | iex

手动安装

如需手动安装或排查问题，请参阅对应平台的指南：

平台	指南
Windows	Windows 安装指南
macOS	macOS 安装指南
Linux	Linux 安装指南

---

文档

文档	说明
入门指南	配有分步截图的可视化指南
Windows 安装	使用 Bun/Playwright 的 Windows 详细安装指南
macOS 安装	使用 launchd 自动化的 macOS 安装指南
Linux 安装	使用 systemd 自动化的 Linux 安装指南
MCP 集成	AI 工具设置（Claude、ChatGPT、Cursor 等）
MCP 替代方案	更经济的选项：Ollama、BYOK、本地大模型
嵌入	语义搜索配置
字段值	查询和搜索节点中的字段数据
聚合	按字段或时间段对节点分组和计数
转录文本	查询和搜索会议转录文本
可视化	继承关系图渲染（Mermaid、DOT、PNG）
代码生成	从 supertag 生成 Effect Schema 类
Webhook 服务	HTTP API 参考
工作区	多工作区管理
导出	自动备份和计划任务
开发	构建、测试和贡献
Launchd 设置	macOS 自动启动配置
字段结构	Tana 元组/字段模式的技术参考
数据库架构	SQLite 架构、表和 JSON 存储

---

故障排除

路径

显示所有配置和数据路径：

supertag paths

显示配置文件、数据库、缓存和导出目录的位置。可用于排查问题，并了解 supertag 将数据存储在哪里。

常见问题

问题	解决方案
"API token not configured"	export TANA_API_TOKEN="your_token"
"Database not found"	supertag sync index
"Chromium not found"	supertag-export setup

tana-index.db-wal 文件过大

只有在没有读取器持有较旧快照时，SQLite 才会截断索引的预写日志（WAL）。supertag 会在每次完整索引以及每次写入更改的增量同步后截断该日志，并且 MCP 轮询器不再在轮询周期之间保持连接打开。如果同时运行多个 supertag-mcp 进程，读取器仍可能阻止该检查点操作。supertag sync status 会显示 WAL 大小，并在超过 1 GB 时发出警告。

若要释放磁盘空间（不会丢失数据；MCP 客户端会重启其服务）：

pkill -f supertag-mcp
sqlite3 ~/.local/share/supertag/workspaces/main/tana-index.db 'PRAGMA wal_checkpoint(TRUNCATE);'

调试模式

使用 --debug 标志输出包含堆栈跟踪的详细错误信息：

supertag search "test" --debug          # Show detailed errors
supertag create todo "Test" --debug     # Debug node creation

调试模式会显示：

• 完整错误代码（例如，WORKSPACE_NOT_FOUND、DATABASE_NOT_FOUND）
• 用于调试的堆栈跟踪
• 有关出错原因的详细上下文

错误日志

使用 errors 命令查看和管理错误日志：

supertag errors                   # Show recent errors
supertag errors --last 10         # Show last 10 errors
supertag errors --json            # Output as JSON
supertag errors --export          # Export all errors
supertag errors --clear           # Clear error log

错误日志存储在 ~/.cache/supertag/errors.log（最多 1000 条记录）。

错误代码

代码	含义	恢复方法
WORKSPACE_NOT_FOUND	未配置工作区别名	检查 supertag workspace list
DATABASE_NOT_FOUND	数据库尚未编入索引	运行 supertag sync index
TAG_NOT_FOUND	Supertag 不存在	检查 supertag tags list
NODE_NOT_FOUND	节点 ID 不存在	验证节点 ID
API_ERROR	Tana API 请求失败	检查令牌和网络
VALIDATION_ERROR	输入参数无效	检查命令选项

Windows 特有问题

“Cannot find package 'playwright'” 错误

在 Windows 上运行 supertag-export login 时，可能会看到：

error: Cannot find package 'playwright' from 'B:/~BUN/root/supertag-export.exe'

解决方案： 单独安装 Playwright。浏览器自动化二进制文件无法打包到可执行文件中。

选项 1：使用 Node.js（推荐）

1. 从 https://nodejs.org 安装 Node.js（LTS 版本）
2. 打开 PowerShell 并运行：

   npx playwright install chromium
   

选项 2：使用 Bun

1. 从 https://bun.sh 安装 Bun
2. 打开 PowerShell 并运行：

   bunx playwright install chromium
   

安装 Playwright 后，supertag-export login 应该可以正常运行。

替代方案：手动导出（无需 Playwright）

如果你不想安装 Node.js/Bun，可以手动导出：

1. 在 Tana 中，前往 Settings → Export
2. 选择 JSON 格式并导出
3. 将文件保存到 %USERPROFILE%\Documents\Tana-Export\main\
4. 运行 .\supertag sync index 为导出内容建立索引

这样就完全不需要使用 supertag-export。

Windows 路径配置

如需从任意目录运行 supertag，请将其添加到 PATH：

# Add to current session
$env:PATH += ";C:\path\to\supertag-cli-windows-x64"

# Add permanently (run as Administrator)
[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";C:\path\to\supertag-cli-windows-x64", "User")

Windows API 令牌配置

# Set for current session
$env:TANA_API_TOKEN = "your_token_here"

# Set permanently
[Environment]::SetEnvironmentVariable("TANA_API_TOKEN", "your_token_here", "User")

---

性能

操作	性能
索引	每秒 107k 个节点
FTS5 搜索	< 50ms
数据库	1M 个节点约占 500 MB

---

贡献

开发环境设置和拉取请求指南请参阅 CONTRIBUTING.md。

安全

安全策略和漏洞报告请参阅 SECURITY.md。

许可证

MIT 许可证——详情请参阅 LICENSE。

---

由 Jens-Christian Fischer 于 2025 年构建。