Supertag CLI

What is Supertag CLI about?

Supertag CLI provides a comprehensive command‑line interface for interacting with Tana workspaces. It lets users read, write, search (both keyword and semantic), batch‑process nodes, visualize tag hierarchies, generate code schemas, and expose a webhook API via an MCP server for AI‑driven automation.

How to use Supertag CLI?

1. Download the appropriate binary from the GitHub Releases page and unzip it.
2. Configure the API token:

   ./supertag config --token "YOUR_TANA_API_TOKEN"
   

3. Export and index your workspace (requires Playwright for browser automation):

   ./supertag-export login           # opens browser for Tana login
   ./supertag-export discover        # finds workspaces
   ./supertag-export run            # creates a JSON export
   ./supertag sync index            # builds a local SQLite index
   

4. Run commands such as:

   ./supertag search "project"               # keyword search
   ./supertag search "project" --semantic    # semantic search
   ./supertag create todo "Buy groceries"   # create a node
   ./supertag aggregate --tag todo --group-by Status
   ./supertag server start --port 3100      # start MCP webhook server
   

5. Integrate with AI tools by configuring the supertag-mcp entry in the tool's MCP settings (e.g., Claude Desktop, Cursor, VS Code).

Key Features

• Unified query language (SQL‑like) for complex filters.
• Full‑text and semantic search using embeddings.
• Batch operations for fetching or creating many nodes in a single request.
• Aggregation to group and count nodes by fields or time periods.
• Graph traversal (related) for multi‑hop relationship discovery.
• Export automation via Playwright‑driven browser login.
• Tag inheritance visualization in Mermaid, Graphviz DOT, or JSON.
• Effect Schema code generation for type‑safe development.
• MCP server exposing a webhook API for AI‑driven workflows.
• Flexible output formats (table, json, csv, ids, minimal, jsonl).

Use Cases

• Personal productivity: Manage todos, meetings, and projects directly from the terminal.
• Team knowledge base: Search meeting transcripts and field values quickly.
• AI‑enhanced assistants: Connect Claude, ChatGPT, or other MCP‑compatible tools to create or retrieve Tana nodes on demand.
• Data analytics: Generate aggregated reports on tasks, statuses, or time‑based metrics.
• Automation scripts: Use batch commands in CI pipelines to sync or back up workspaces.
• Custom tooling: Generate TypeScript schemas and build bespoke UIs (e.g., the provided TUI todo example).

FAQ

Q: Do I need Node.js to run Supertag CLI? A: No. The CLI is a compiled binary. Only the supertag-export component requires Playwright, which can be installed via Bun or Node.js.

Q: How do I enable semantic search? A: Configure an embedding model with supertag embed config --model <model-name> and generate embeddings via supertag embed generate. Afterwards, use --semantic on the search command.

Q: Can I run the MCP server on a remote machine? A: Yes. Start it with ./supertag-mcp start --port <port> (or ./supertag server start). Point your AI tool’s MCP configuration to the host and port.

Q: What limits exist for batch commands? A: batch get supports up to 100 node IDs per request; batch create supports up to 50 nodes per request.

Q: How do I change the default output format? A: Set output.format in ~/.config/supertag/config.json or export the SUPERTAG_FORMAT environment variable.

Supertag CLI

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

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.

---

Table of Contents

• Quick Start
• Capabilities
  • READ - Query Workspace
  • WRITE - Create Nodes
  • QUERY - Unified Query Language
  • BATCH - Multi-Node Operations
  • AGGREGATE - Group and Count
  • RELATED - Graph Traversal
  • EXPORT - Automated Backup
  • EMBED - Semantic Search
  • FIELDS - Query Field Values
  • TRANSCRIPTS - Meeting Recordings
  • SERVER - Webhook API
  • VISUALIZE - Inheritance Graphs
  • CODEGEN - Generate Effect Schema Classes
  • MCP - AI Tool Integration
  • WORKSPACES - Multi-Workspace
  • OUTPUT - Display Formatting
• Examples
• Installation
• Documentation
• Troubleshooting
• Performance
• Contributing

---

Quick Start

Need detailed instructions? See platform-specific guides: Windows | macOS | Linux

1. Download and Extract

unzip supertag-cli-vX.Y.Z-macos-arm64.zip
cd supertag-cli-macos-arm64

# macOS: Remove quarantine
xattr -d com.apple.quarantine ./supertag ./supertag-mcp ./supertag-export

2. Configure API Token

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

./supertag config --token "your_token_here"

3. 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

4. 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 --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> --depth 3           # Node contents
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
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

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"

# Field projection
supertag query "find todo" --select id,name,fields.Status

Operators:

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

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

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.

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.

EXPORT - Automated Backup

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

See Export Documentation for details.

EMBED - Semantic Search

supertag embed config --model bge-m3    # Configure
supertag embed generate                  # Generate embeddings
supertag embed generate --include-fields # Include field values in context
supertag search "ideas" --semantic       # Search by meaning

See Embeddings Documentation for details.

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.

SERVER - Webhook API

supertag server start --port 3100 --daemon
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" }
  }
}

See MCP Documentation for setup guides.

WORKSPACES - Multi-Workspace

supertag workspace list
supertag workspace add <rootFileId> --alias work
supertag search "meeting" -w work

See Workspaces Documentation for details.

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

---

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

Detailed installation guides:

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

Quick Install (macOS/Linux)

# Download and extract from GitHub Releases
unzip supertag-cli-vX.Y.Z-*.zip
cd supertag-cli-*

# macOS: Remove quarantine
xattr -d com.apple.quarantine ./supertag ./supertag-mcp ./supertag-export

# Symlink to PATH
sudo ln -s $(pwd)/supertag /usr/local/bin/supertag
sudo ln -s $(pwd)/supertag-export /usr/local/bin/supertag-export
sudo ln -s $(pwd)/supertag-mcp /usr/local/bin/supertag-mcp

# Install Playwright for browser automation
curl -fsSL https://bun.sh/install | bash
bunx playwright install chromium

Playwright (Required for Export)

The supertag-export tool requires Playwright for browser automation. See the platform-specific guides above for detailed instructions.

---

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

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.