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 にフォールバックするため、既存のワークフローは変更せずに引き続き動作します。

3 つのツールで構成されるアーキテクチャ

ツール	サイズ	用途
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

または、次のコマンドを 1 つ実行します。

brew install jcfischer/supertag/supertag

すべてのバイナリ（supertag、supertag-mcp、supertag-export）がインストールされ、brew upgrade supertag で最新の状態に保たれます。

1 行インストール（別の方法）

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 - 既存のノードを編集する

Local API を有効にした状態で Tana Desktop を起動しておく必要があります。次のように設定してください。

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 - 統合クエリ言語

複雑なフィルタリングを 1 つのコマンドで行える、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

型付きの関係をたどる宣言型グラフクエリを、1 つの文で実行できます。

# 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 - 複数ノードの操作

1 回のリクエストで複数のノードを効率よく取得または作成できます。

# 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 を使用して前回の同期以降に変更されたノードのみを取得するため、全件のインデックス再作成よりも大幅に高速です。Local API を有効にした状態で Tana Desktop を実行し、ベアラートークン（supertag config --bearer-token <token>）を設定する必要があります。

MCP サーバーは、設定可能な間隔（デフォルト：5 分ごと）でバックグラウンドの差分同期を自動実行できます。設定で localApi.deltaSyncInterval を指定するか、環境変数 TANA_DELTA_SYNC_INTERVAL を使用してください（0 にするとポーリングが無効になります）。

⚠️ フィールドで絞り込んだクエリには、最近の全件同期が必要です

差分同期には、スーパータグのフィールド値に関する既知の正確性の問題があります。差分同期で変更されたノードが検出されると、そのノードの field_values テーブル内のエントリーはクリアされますが、再登録されません。フィールド値の再抽出に必要なタプル構造は Local API から取得できないためです。その後、全件同期（--delta を付けずに supertag sync index を実行）すると、エクスポート JSON からフィールド値が再登録されます。

影響：

• スーパータグのフィールドで絞り込むクエリ（例：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

要件： Local API を有効にした状態で Tana Desktop を実行する必要があります。内部では差分同期を使用し、各ポーリングで変更されたノードのみを取得します。

フックは環境変数（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 - フィールドの一括エクスポート

スーパータグのすべてのインスタンスを、解決済みのフィールド値を含むテーブルとしてエクスポートします。効率的な抽出のためにバッチクエリを使用するため、インスタンス数にかかわらず、フィールド値と参照の解決を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

機能：

• すべてのスーパータグフィールドを、型と値を含めて抽出します
• 参照フィールドを、人が読み取れる名前に自動的に解決します
• 複数値フィールドをカンマ区切りのリストで表示します
• --fieldsと--whereでは、大文字と小文字を区別せずにフィールド名を照合します
• --limitと--offsetによるページネーションに対応します

出力形式： table（デフォルト）、json（生の値と解決済みの値を含む）、csv、markdown

CONTEXT - AIコンテキストの組み立て

AIでの利用に向けて、ノードに関する豊富なコンテキストをトークン予算に合わせて組み立てます。ノードの内容、フィールド、関連ノードを組み合わせ、LLMのコンテキストウィンドウに最適化された構造化形式にします。

# 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

照合戦略： 名前の完全一致（最速）、レーベンシュタイン距離によるあいまい一致、エンベディングによるセマンティック類似度。結果は信頼度スコア順に並べられます。

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	親スーパータグごとに整理	./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...>	スーパータグで絞り込み
-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 - 継承グラフ

スーパータグの継承階層を視覚的に表現します。

# 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 - SVG／PNG／PDFにレンダリングするためのGraphviz DOT
• 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" }
  }
}

ツールモード： 登録するツールは、次の3つのモードで制御します。

モード	ツール	フラグ	用途
full	37	（デフォルト）	単独で使用 — すべてのツールを利用可能
slim	17	--slim	コンテキストを最適化 — AI エージェント向けにツールを削減
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 モードは、Tana の公式 tana-local MCP でワークスペースのライブ CRUD（読み取り、作成、編集、タグ付け、ゴミ箱への移動）を処理し、supertag-mcp で補完的な分析レイヤー（セマンティック検索、集計、タイムライン、フィールドクエリ、トランスクリプト、グラフのトラバーサル、コンテキストの組み立て、エンティティ解決、スキーマ分析）を提供する、2層構成の 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 コマンドのみ）

出力 - 表示形式

すべてのコマンドは、次のオプションで --format <type> をサポートしています。

形式	説明	使用例
table	絵文字付きで読みやすく表示	対話型ターミナルでの使用
json	整形済み JSON 配列	API 連携、jq による処理
csv	RFC 4180 準拠の CSV	Excel、スプレッドシート
ids	1 行につき 1 つの 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 のベアラートークン
TANA_LOCAL_API_URL	ローカル API エンドポイント URL	http://localhost:8262

---

例

examples/ ディレクトリには、supertag-cli の機能を紹介するサンプルアプリケーションが含まれています。

TUI Todo（examples/tui-todo/）

Ink（CLI 向け React）で構築された、ターミナルベースの Todo 管理ツールです。次の機能を紹介します。

• コード生成との連携：Tana supertag から生成された Effect Schema クラスを使用
• SQLite クエリ：supertag-cli のインデックス付きデータベースから読み込み
• Tana Input API：Tana に直接新しい Todo を作成
• 分割ペイン 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、ローカル LLM
埋め込み	セマンティック検索の設定
フィールド値	ノードのフィールドデータのクエリと検索
集計	フィールドまたは期間ごとにノードをグループ化してカウント
トランスクリプト	会議のトランスクリプトのクエリと検索
可視化	継承グラフのレンダリング（Mermaid、DOT、PNG）
コード生成	supertag から Effect Schema クラスを生成
Webhook サーバー	HTTP API リファレンス
ワークスペース	複数のワークスペースの管理
エクスポート	自動バックアップとスケジュール設定
開発	ビルド、テスト、コントリビューション
Launchd のセットアップ	macOS の自動起動設定
フィールド構造	Tana のタプル／フィールドパターンに関する技術リファレンス
データベーススキーマ	SQLite のスキーマ、テーブル、JSON ストレージ

---

トラブルシューティング

パス

設定ファイルとデータのすべてのパスを表示します。

supertag paths

設定ファイル、データベース、キャッシュ、エクスポートディレクトリの場所が表示されます。トラブルシューティングや、supertag がデータを保存する場所の確認に役立ちます。

よくある問題

問題	解決方法
「API トークンが設定されていません」	export TANA_API_TOKEN="your_token"
「データベースが見つかりません」	supertag sync index
「Chromium が見つかりません」	supertag-export setup

tana-index.db-wal ファイルのサイズが大きい

SQLite は、古いスナップショットを保持するリーダーがいなくなった場合にのみ、インデックスの先行書き込みログ（WAL）を切り詰めます。supertag はフルインデックスの作成後、および変更を書き込んだ差分同期のたびに WAL を切り詰めます。また、MCP ポーラーはサイクル間で接続を開いたままにしなくなりました。複数の supertag-mcp プロセスが同時に実行されている場合、リーダーがチェックポイントを妨げることがあります。WAL のサイズは supertag sync status で確認でき、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 で 設定 → エクスポート に移動します。
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
データベース	100 万ノードで約 500 MB

---

コントリビューション

開発環境のセットアップとプルリクエストのガイドラインについては、CONTRIBUTING.md を参照してください。

セキュリティ

セキュリティポリシーと脆弱性の報告については、SECURITY.md を参照してください。

ライセンス

MIT License。詳細は LICENSE を参照してください。

---

Jens-Christian Fischer 作成、2025 年。