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.

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.

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

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:

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

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)

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.

Name		Name	Last commit message	Last commit date
Latest commit History 195 Commits
.github		.github
.mcp		.mcp
.specify/specs		.specify/specs
docs		docs
examples/tui-todo		examples/tui-todo
export		export
launchd		launchd
scripts		scripts
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
SKILL.md		SKILL.md
SUPPORTERS.md		SUPPORTERS.md
bunfig.toml		bunfig.toml
package.json		package.json
pai-manifest.yaml		pai-manifest.yaml
release.sh		release.sh
tsconfig.json		tsconfig.json

Uh oh!

License

jcfischer/supertag-cli

Folders and files

Latest commit

History

Repository files navigation

Supertag CLI

Three-Tool Architecture

Table of Contents

Quick Start

1. Download and Extract

2. Configure API Token

3. Login and Export

4. Start Using

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

ATTACHMENTS - Extract Attachments

SERVER - Webhook API

VISUALIZE - Inheritance Graphs

CODEGEN - Generate Effect Schema Classes

MCP - AI Tool Integration

WORKSPACES - Multi-Workspace

OUTPUT - Display Formatting

Examples

TUI Todo (examples/tui-todo/)

Installation

Quick Install (macOS/Linux)

Playwright (Required for Export)

Documentation

Troubleshooting

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

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 33

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Contributors 2

Uh oh!

Languages

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

Packages