GitHub

License: MIT Tests MCP

Complete Tana integration: Query, write, search, and automate your Tana workspace from the command line.

What's New in v2.0.0

Tana has officially released their Local API and MCP server, and Supertag CLI now fully integrates with it. This means supertag-cli is no longer limited to read-only exports and basic node creation — you can now edit nodes, manage tags, set field values, check off tasks, and trash nodes directly from the command line or through any MCP-compatible AI tool. The new delta-sync feature uses the Local API to fetch only changed nodes since your last sync, making incremental updates fast without needing a full re-export. All you need is Tana Desktop running with the Local API enabled. Supertag CLI auto-detects the Local API and falls back to the Input API when Tana Desktop isn't available, so your existing workflows keep working unchanged.

Three-Tool Architecture

Tool Size Purpose
supertag ~57 MB Main CLI - query, write, sync, server
supertag-export ~59 MB Browser automation for exports
supertag-mcp ~60 MB MCP server for AI tool integration

Downloads: GitHub Releases (macOS ARM64/Intel, Linux x64, Windows x64)

New to Supertag? Check out the Visual Getting Started Guide with step-by-step screenshots.

Learn more: Video Course | Discord Community

Table of Contents

Quick Start

Homebrew (Recommended for macOS)

brew tap jcfischer/supertag
brew install supertag

Or in one command:

brew install jcfischer/supertag/supertag

This installs all binaries (supertag, supertag-mcp, supertag-export) and keeps them updated with brew upgrade supertag.

One-Line Install (Alternative)

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

This installs everything: Bun, Playwright, Chromium, supertag-cli, and configures MCP.

Need manual installation? See platform-specific guides: Windows | macOS | Linux

Migration (Upgrading from Older Versions)

If upgrading from an older version of supertag-cli, migrate your database to the new XDG-compliant location:

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

This moves your database from the legacy location to the standard XDG paths (~/.local/share/supertag/).

1. Configure API Token

Get your token from: https://app.tana.inc/?bundle=settings&panel=api

./supertag config --token "your_token_here"

2. Login and Export

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. Start Using

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

Capabilities

READ - Query Workspace

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 - Create Nodes

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 - Edit Existing Nodes

Requires Tana Desktop running with Local API enabled. Configure with:

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> <tagId1> <tagId2>
supertag tag remove <nodeId> <tagId>
supertag tag create "sprint" --description "Sprint supertag"
# Set field values
supertag set-field <nodeId> <attributeId> "value"
supertag set-field <nodeId> <attributeId> "additional value" --append
supertag set-field <nodeId> <attributeId> --option-id <optionId>
supertag set-field <nodeId> <attributeId> --option-id <optionId> --append
# Check/uncheck and trash
supertag done <nodeId>
supertag undone <nodeId>
supertag trash <nodeId> --confirm

Note: These commands require the Local API backend. If Tana Desktop isn't running, supertag falls back to the Input API (which only supports create operations).

FORMAT - JSON to Tana Paste

Convert JSON data to Tana Paste format for bulk import:

# 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

Useful for integrating external data sources and bulk imports into Tana.

QUERY - Unified Query Language

SQL-like queries for complex filtering in a single command.

# 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"

Operators:

Operator Meaning Example
= Exact match Status = Done
~ Contains Name ~ John
>, <, >=, <= Comparison Priority >= 2
exists Field has value Due exists
is empty Field is empty or missing Status is empty
not Negation not Status = Done
and, or Logical A and (B or C)

Relative Dates: today, yesterday, 7d, 30d, 1w, 1m, 1y

Select Clause (inline in query):

  • No select = Core fields only (id, name, created)
  • select * = All supertag fields including inherited
  • select "Email,Phone" = Specific fields by name

GQUERY - Graph Query DSL

Declarative graph queries for traversing typed relationships in a single statement.

# 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 Syntax:

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

Operators: =, !=, >, <, >=, <=, ~ (contains), LIKE, CONTAINS

How it differs from query: The query command runs SQL-like flat queries against the node index. The gquery command understands the graph structure — it traverses typed relationships between supertags using CONNECTED TO and can project fields from related nodes using dot notation.

See Graph Query Documentation for full grammar and MCP usage.

BATCH - Multi-Node Operations

Fetch or create multiple nodes efficiently in a single request.

# 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

Input format for batch create:

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

Limits: 100 nodes for batch get, 50 nodes for batch create.

AGGREGATE - Group and Count

Aggregate nodes by field values or time periods. Useful for analytics, status breakdowns, and time-series analysis.

# 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

Time periods: day, week, month, quarter, year

Output:

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

See Aggregation Documentation for more examples.

TIMELINE - Time-Based Queries

View activity over time periods with configurable granularity.

# 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)

Granularity levels: hour, day, week, month, quarter, year

Period formats: Nh (hours), Nd (days), Nw (weeks), Nm (months), Ny (years)

Date formats:

  • ISO dates: 2025-01-01, 2025-06-15
  • Relative: 7d (7 days ago), 30d, 1m, 1w, 1y
  • Special: today, yesterday

RELATED - Graph Traversal

Find nodes related to a given node through references, children, and field links.

# 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

Relationship types: child, parent, reference, field

Output:

🔗 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

See Graph Traversal Documentation for more examples.

SYNC - Index and Delta-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

Delta-sync uses Tana Desktop's Local API to fetch only nodes changed since the last sync, making it much faster than a full reindex. Requires Tana Desktop running with Local API enabled and a bearer token configured (supertag config --bearer-token <token>).

The MCP server can run delta-sync automatically in the background at a configurable interval (default: every 5 minutes). Set localApi.deltaSyncInterval in config or use TANA_DELTA_SYNC_INTERVAL environment variable (0 disables polling).

⚠️ Field-Filtered Queries Require a Recent Full Sync

Delta-sync has a known correctness gap around supertag field values. When delta-sync detects a changed node it clears that node's entries in the field_values table but does not repopulate them — the tuple structure needed to re-extract field values isn't available via the Local API. A subsequent full sync (supertag sync index, without --delta) re-populates them from the export JSON.

Consequences:

  • Queries that filter on a supertag field (e.g., where: { "Time Sector": "🔴 This week" }) are only fully accurate against a recently full-synced database. Between full syncs, delta-sync will steadily degrade field-filter correctness.
  • If a node's field value changes in Tana but the node itself isn't otherwise edited, the Local API's edited.since filter may not surface it — delta-sync misses field-only changes entirely. The stale value remains in field_values until the next full sync.
  • tana_query and tana_stats now emit staleness warnings/flags (see below) so callers can detect this state before trusting results.

Recommended cadence: schedule a nightly supertag sync index (full reindex from the latest export) alongside any delta-sync-based workflows. Rely on delta-sync only for name/tag/creation changes and semantic search freshness.

Staleness Detection

Both tana_stats and tana_query now surface index freshness:

  • tana_stats returns lastFullSync, lastDeltaSync, lastDeltaNodesCount, secondsSinceLastSync, and isStale fields.
  • tana_query returns a warnings array when the index is older than the configured thresholds or when a field-filtered query runs against a database with no full sync.

Configurable thresholds (env vars):

Variable Default Purpose
SUPERTAG_STALE_DELTA_MINUTES 60 Warn when newest sync (full or delta) is older than this.
SUPERTAG_STALE_FULL_HOURS 168 (7 days) Warn when last full sync is older than this (field values drift).
SUPERTAG_LOCAL_API_TIMEOUT_MS 30000 Per-request timeout for Local API calls. Hung requests abort and retry.

WATCH - Continuous Monitoring

Monitor Tana for changes in real-time and trigger automation hooks.

# 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

Requirements: Tana Desktop running with Local API enabled. Uses delta-sync under the hood — each poll fetches only changed nodes.

Hooks receive change details via environment variables (SUPERTAG_EVENT_TYPE, SUPERTAG_NODE_ID, SUPERTAG_NODE_NAME, etc.). All events are logged to a JSONL file for audit and replay.

Failure handling: Exponential backoff on poll failures (5s → 10s → 20s → ... → 60s cap). Exits after 10 consecutive failures by default (--max-failures).

EXPORT - Automated Backup

Setup

Before running exports for the first time, install the required browser:

supertag-export setup        # Install Playwright browser

This installs the Chromium browser needed for automated Tana exports.

Workspace Discovery

Automatically discover Tana workspace IDs via network capture:

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

Captures network traffic to find workspace IDs and rootFileIds, simplifying initial setup. First discovered workspace is auto-added as "main" if no workspaces are configured.

Export Commands

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

See Export Documentation for details.

Export Cleanup

Remove old export files to free disk space:

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 - Semantic Search

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

See Embeddings Documentation for details.

TABLE - Bulk Field Export

Export all instances of a supertag as a table with resolved field values. Uses batched queries for efficient extraction — O(1) for field values and reference resolution regardless of instance count.

# 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

Features:

  • All supertag fields extracted with types and values
  • Reference fields automatically resolved to human-readable names
  • Multi-value fields shown as comma-separated lists
  • Case-insensitive field name matching in --fields and --where
  • Pagination with --limit and --offset

Output formats: table (default), json (includes raw + resolved values), csv, markdown

CONTEXT - AI Context Assembly

Assemble rich, token-budgeted context about nodes for AI consumption. Combines node content, fields, and related nodes into a structured format optimized for LLM context windows.

# 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

Lenses: general (default), writing, project-management, research, meeting — each lens prioritizes different aspects of the workspace data.

RESOLVE - Entity Resolution

Resolve ambiguous names to specific Tana nodes using multi-strategy matching (exact, fuzzy, semantic).

# 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

Matching strategies: Exact name match (fastest), fuzzy Levenshtein distance, semantic similarity via embeddings. Results ranked by confidence score.

FIELDS - Query Field Values

Query structured field data from Tana nodes. Fields like "Summary", "Action Items", or custom fields store values in tuple children.

# 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

See Field Values Documentation for details.

TRANSCRIPTS - Meeting Recordings

Query and search meeting transcripts. By default, transcripts are excluded from general search to keep results clean.

# 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

Include in embeddings:

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

See Transcript Documentation for details.

ATTACHMENTS - Extract Attachments

Discover and download attachments (images, PDFs, audio, video) from your Tana exports.

# 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

Organization Strategies:

Strategy Description Example Path
flat All files in output directory (default) ./attachments/image.png
date By year/month ./attachments/2025/04/image.png
tag By parent supertag ./attachments/meeting/image.png
node By parent node ID ./attachments/abc123/image.png

Options:

Flag Description
-o, --output <dir> Output directory (default: ~/Downloads/tana-attachments)
--organize-by <strategy> Organization: flat, date, tag, node
-c, --concurrency <n> Parallel downloads 1-10 (default: 3)
--skip-existing Skip files that already exist
-t, --tag <tags...> Filter by supertag
-e, --extension <exts...> Filter by extension (png, pdf, etc.)
--dry-run List files without downloading

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"}'

See Webhook Server Documentation for API reference.

VISUALIZE - Inheritance Graphs

Generate visual representations of your supertag inheritance hierarchy.

# 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

Output formats:

  • mermaid - Mermaid flowchart syntax (default)
  • dot - Graphviz DOT for rendering to SVG/PNG/PDF
  • json - Raw data for custom visualization

See Visualization Documentation for rendering instructions.

CODEGEN - Generate Effect Schema Classes

Generate type-safe Effect Schema class definitions from your Tana supertags.

# 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

Output Example:

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" }),
}) {}

Options:

Flag Description
-o, --output <path> Output file path (required)
-t, --tags <tags...> Filter to specific supertags
--split Generate separate file per supertag
--optional <strategy> option (default), undefined, or nullable
--no-metadata Exclude supertag metadata comments
-d, --dry-run Preview without writing files

Type Mapping:

Tana Type 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 Tool Integration

Integrate with Claude Desktop, ChatGPT, Cursor, VS Code, and other MCP-compatible AI tools.

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

Tool Modes: Three modes control which tools are registered:

Mode Tools Flag Use Case
full 37 (default) Standalone — all tools available
slim 17 --slim Context-optimized — fewer tools for AI agents
lite 21 --lite Complement tana-local MCP — analytics & search only 
# 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 mode is designed for two-layer MCP setups where Tana's official tana-local MCP handles live workspace CRUD (read, create, edit, tag, trash) and supertag-mcp provides the complementary analytics layer: semantic search, aggregation, timeline, field queries, transcripts, graph traversal, context assembly, entity resolution, and schema analysis. Excluded tools return a message pointing to the equivalent tana-local tool.

Slim mode keeps semantic search, all mutation tools, sync, cache clear, capabilities, and tool schema. Removes read-only query tools that overlap with semantic search.

Background Delta-Sync: The MCP server automatically runs incremental syncs in the background (default: every 5 minutes) when Tana Desktop is reachable. Configure with localApi.deltaSyncInterval or TANA_DELTA_SYNC_INTERVAL (0 disables).

See MCP Documentation for setup guides.

WORKSPACES - Multi-Workspace

Manage multiple Tana workspaces with separate databases and configurations.

# 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

See Workspaces Documentation for details.

SCHEMA - Supertag Registry

Manage the supertag schema registry. The registry stores your workspace's supertag definitions including fields and inheritance relationships.

# 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

Audit detectors: orphan-tags, low-usage, duplicate-fields, type-mismatch, unused-fields, fill-rate, missing-inheritance. Each produces findings with severity levels: critical, warning, info.

Output formats: --format table (default), --format json, --format names (list command only)

OUTPUT - Display Formatting

All commands support --format <type> with these options:

Format Description Use Case
table Human-readable with emojis Interactive terminal use
json Pretty-printed JSON array API integration, jq processing
csv RFC 4180 compliant CSV Excel, spreadsheets
ids One ID per line xargs piping, scripting
minimal Compact JSON (id, name, tags) Quick lookups
jsonl JSON Lines (streaming) Log processing, large datasets 
# 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

Format Resolution Priority:

  1. --format <type> flag (explicit)
  2. --json or --pretty flags (shortcuts)
  3. SUPERTAG_FORMAT environment variable
  4. Config file (output.format)
  5. TTY detection: table for interactive, json for pipes/scripts

Output Flags:

Flag Description
--format <type> Output format (table, json, csv, ids, minimal, jsonl)
--pretty Shortcut for --format table
--json Shortcut for --format json
--select <fields> Select specific fields in JSON output (comma-separated)
--verbose Include technical details (timing, IDs)
--human-dates Localized date format (Dec 23, 2025)
--no-header Omit header row in CSV output

Configuration:

Set defaults in ~/.config/supertag/config.json:

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

Environment Variable:

export SUPERTAG_FORMAT=csv  # Default to CSV output

Additional Environment Variables:

Variable Description Default
TANA_DELTA_SYNC_INTERVAL Delta-sync polling interval in minutes (0 disables) 5
TANA_MCP_TOOL_MODE MCP tool mode: full (36 tools), slim (17 tools), or lite (20 tools) full
TANA_LOCAL_API_TOKEN Bearer token for Tana Desktop Local API
TANA_LOCAL_API_URL Local API endpoint URL http://localhost:8262

Examples

The examples/ directory contains sample applications demonstrating supertag-cli features:

TUI Todo (examples/tui-todo/)

A terminal-based todo manager built with Ink (React for CLIs). Demonstrates:

  • Codegen integration: Uses Effect Schema classes generated from Tana supertags
  • SQLite queries: Reads from the supertag-cli indexed database
  • Tana Input API: Creates new todos directly in Tana
  • Split-pane UI: Vim-style navigation with search/filter
cd examples/tui-todo
bun install
bun run start

See examples/tui-todo/README.md for full documentation.

Installation

One-Line Install (Recommended)

The installer handles everything: Bun runtime, Playwright, Chromium browser, supertag-cli binaries, PATH configuration, and MCP auto-setup.

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

Options:

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

Uninstall

# 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

Manual Installation

For manual installation or troubleshooting, see the platform-specific guides:

Platform Guide
Windows Windows Installation Guide
macOS macOS Installation Guide
Linux Linux Installation Guide

Documentation

Document Description
Getting Started Visual guide with step-by-step screenshots
Windows Install Detailed Windows installation with Bun/Playwright
macOS Install macOS installation with launchd automation
Linux Install Linux installation with systemd automation
MCP Integration AI tool setup (Claude, ChatGPT, Cursor, etc.)
MCP Alternatives Cheaper options: Ollama, BYOK, local LLMs
Embeddings Semantic search configuration
Field Values Query and search field data from nodes
Aggregation Group and count nodes by field or time period
Transcripts Query and search meeting transcripts
Visualization Inheritance graph rendering (Mermaid, DOT, PNG)
Codegen Generate Effect Schema classes from supertags
Webhook Server HTTP API reference
Workspaces Multi-workspace management
Export Automated backup and scheduling
Development Building, testing, contributing
Launchd Setup macOS auto-start configuration
Field Structures Technical reference for Tana tuple/field patterns
Database Schema SQLite schema, tables, JSON storage

Troubleshooting

Paths

Display all configuration and data paths:

supertag paths

Shows locations for configuration files, databases, caches, and export directories. Useful for troubleshooting and understanding where supertag stores its data.

Common Issues

Problem Solution
"API token not configured" export TANA_API_TOKEN="your_token"
"Database not found" supertag sync index
"Chromium not found" supertag-export setup

Debug Mode

Use the --debug flag for verbose error output with stack traces:

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

Debug mode shows:

  • Full error codes (e.g., WORKSPACE_NOT_FOUND, DATABASE_NOT_FOUND)
  • Stack traces for debugging
  • Detailed context about what went wrong

Error Logging

View and manage error logs with the errors command:

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

Error logs are stored at ~/.cache/supertag/errors.log (up to 1000 entries).

Error Codes

Code Meaning Recovery
WORKSPACE_NOT_FOUND Workspace alias not configured Check supertag workspace list
DATABASE_NOT_FOUND Database not indexed Run supertag sync index
TAG_NOT_FOUND Supertag doesn't exist Check supertag tags list
NODE_NOT_FOUND Node ID doesn't exist Verify node ID
API_ERROR Tana API request failed Check token & network
VALIDATION_ERROR Invalid input parameters Check command options

Windows-Specific Issues

"Cannot find package 'playwright'" Error

When running supertag-export login on Windows, you may see:

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

Solution: Install Playwright separately. The browser automation binaries cannot be bundled into the executable.

Option 1: Using Node.js (Recommended)

  1. Install Node.js from https://nodejs.org (LTS version)
  2. Open PowerShell and run: 
    npx playwright install chromium

Option 2: Using Bun

  1. Install Bun from https://bun.sh
  2. Open PowerShell and run: 
    bunx playwright install chromium

After installing Playwright, supertag-export login should work.

Alternative: Manual Export (No Playwright Required)

If you prefer not to install Node.js/Bun, you can export manually:

  1. In Tana, go to Settings → Export
  2. Select JSON format and export
  3. Save the file to %USERPROFILE%\Documents\Tana-Export\main\
  4. Run .\supertag sync index to index the export

This bypasses the need for supertag-export entirely.

Windows Path Configuration

To run supertag from any directory, add it to your 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 Token Configuration

# Set for current session
$env:TANA_API_TOKEN = "your_token_here"
# Set permanently
[Environment]::SetEnvironmentVariable("TANA_API_TOKEN", "your_token_here", "User")

Performance

Operation Performance
Indexing 107k nodes/second
FTS5 Search < 50ms
Database ~500 MB for 1M nodes

Contributing

See CONTRIBUTING.md for development setup and pull request guidelines.

Security

See SECURITY.md for security policy and vulnerability reporting.

License

MIT License - see LICENSE for details.

Built by Jens-Christian Fischer, 2025.

Read the original on github.com ↗