📦

Supertag CLI

CLI for Tana integration - query, create, sync, and manage Tana workspaces with semantic search and MCP Server

0 installs

34 stars

5 forks

Trust: 64 — Good

Devtools

Installation

npx supertag-cli

Ask AI about Supertag CLI

I know everything about Supertag CLI. Ask me about installation, configuration, usage, or troubleshooting.

0/500

Loading tools...

Reviews

Documentation

Supertag CLI

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

Quick Start
Capabilities
Examples
Installation
Documentation
Troubleshooting
Performance
Contributing

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> --option-id <optionId>

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

--format <type> flag (explicit)
--json or --pretty flags (shortcuts)
SUPERTAG_FORMAT environment variable
Config file (output.format)
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)

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

Option 2: Using Bun

Install Bun from https://bun.sh
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:

In Tana, go to Settings → Export
Select JSON format and export
Save the file to %USERPROFILE%\Documents\Tana-Export\main\
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.

Supertag CLI

Installation

Reviews

Documentation

Supertag CLI

What's New in v2.0.0

Three-Tool Architecture

Table of Contents

Quick Start

Homebrew (Recommended for macOS)

One-Line Install (Alternative)

Migration (Upgrading from Older Versions)

1. Configure API Token

2. Login and Export

3. Start Using

Capabilities

READ - Query Workspace

WRITE - Create Nodes

MUTATE - Edit Existing Nodes

FORMAT - JSON to Tana Paste

QUERY - Unified Query Language

GQUERY - Graph Query DSL

BATCH - Multi-Node Operations

AGGREGATE - Group and Count

TIMELINE - Time-Based Queries

RELATED - Graph Traversal

SYNC - Index and Delta-Sync

⚠️ Field-Filtered Queries Require a Recent Full Sync

Staleness Detection

WATCH - Continuous Monitoring

EXPORT - Automated Backup

Setup

Workspace Discovery

Export Commands

Export Cleanup

EMBED - Semantic Search

TABLE - Bulk Field Export

CONTEXT - AI Context Assembly

RESOLVE - Entity Resolution

FIELDS - Query Field Values

TRANSCRIPTS - Meeting Recordings

ATTACHMENTS - Extract Attachments

SERVER - Webhook API

VISUALIZE - Inheritance Graphs

CODEGEN - Generate Effect Schema Classes

MCP - AI Tool Integration

WORKSPACES - Multi-Workspace

SCHEMA - Supertag Registry

OUTPUT - Display Formatting

Examples

TUI Todo (examples/tui-todo/)

Installation

One-Line Install (Recommended)

Uninstall

Manual Installation

Documentation

Troubleshooting

Paths

Common Issues

Debug Mode

Error Logging

Error Codes

Windows-Specific Issues

"Cannot find package 'playwright'" Error

Alternative: Manual Export (No Playwright Required)

Windows Path Configuration

Windows API Token Configuration

Performance

Contributing

Security

License

TUI Todo (`examples/tui-todo/`)