Clear Tangle CLI

A powerful command-line interface for Clear Tangle - manage tasks, thoughts, pages, and projects from your terminal.

Features

• Task Management - Create, update, complete, and organize tasks with priorities and due dates
• Thought Capture - Quickly capture ideas and notes
• Page Management - Create and manage documentation pages
• Project Organization - Group tasks and captures into projects
• Smart Search - Semantic search across all your content
• AI Planning - Generate prioritized action plans
• Beautiful Output - Color-coded tables, status badges, and relative timestamps
• Multiple Formats - JSON, table, compact, CSV/TSV export
• Shell Completions - Tab completion for bash, zsh, and fish

Installation

cd /path/to/clear-tangle-cli/cli
npm install
npm run build
npm link

Quick Start

# Set up authentication with your API key
ct auth set-key <YOUR_API_KEY>

# Verify authentication
ct auth status

# List your tasks
ct tasks list

# Create a new task
ct tasks create --title "Review PR" --priority high --due-date 2026-02-10

# Capture a thought
ct thoughts create --content "Remember to follow up on the API design"

# Search across everything
ct search "api design"

Authentication

Get your API key from: https://app.cleartangle.com/settings/api

# Set your API key
ct auth set-key <YOUR_API_KEY>

# Verify authentication
ct auth status

# Test API connectivity
ct auth test

# Clear stored API key
ct auth logout

You can also set the API key via environment variable:

export CLEARTANGLE_API_KEY=ctak_your_api_key_here

Global Options

These options work with any command:

| Option | Description | |--------|-------------| | --json | Output as formatted JSON | | --table | Output as formatted table (default) | | --compact | Single-line per item, great for quick scanning | | --fields <list> | Show only specific fields (comma-separated) | | --csv | Export as CSV | | --tsv | Export as TSV | | --plain | No colors or unicode (for scripts/pipes) | | -v, --verbose | Show debug information | | --dry-run | Preview changes without executing |

Examples

ct tasks list --compact                    # Quick overview
ct tasks list --fields id,title,status     # Select columns
ct tasks list --csv > tasks.csv            # Export to CSV
ct tasks list --json | jq '.[] | .title'   # Pipe to jq
ct tasks create --title "Test" --dry-run   # Preview without creating

Commands

Tasks

Manage your tasks with status tracking, priorities, and due dates.

# List tasks
ct tasks list                              # All tasks
ct tasks list today                        # Due today
ct tasks list overdue                      # Overdue tasks
ct tasks list upcoming                     # Next 7 days
ct tasks list pending                      # Pending status
ct tasks list in_progress                  # In progress
ct tasks list completed                    # Completed tasks
ct tasks list --status pending --priority high
ct tasks list --project proj_abc123 --limit 10

# Get task details
ct tasks get <id>

# Create task
ct tasks create --title "Review PR" --priority high
ct tasks create --title "Deploy" --due-date 2026-02-10 --due-time 17:00
ct tasks create                            # Interactive mode

# Update task
ct tasks update <id> --status in_progress
ct tasks update <id> --priority critical --due-date 2026-02-05

# Complete task
ct tasks complete <id>

# Delete task
ct tasks delete <id>                       # With confirmation
ct tasks delete <id> --force               # Skip confirmation

# Dashboard view
ct tasks dashboard                         # Grouped by overdue/today/upcoming

Output Fields: id, title, status, priority, due_date, category

Status Values: pending, in_progress, completed

Priority Values: critical, high, medium, low

Plan

AI-powered task planning and prioritization.

# View current plan
ct plan get

# Generate new plan
ct plan generate
ct plan generate --context "Focus on Q1 goals and high priority items"

The plan includes:

• Alerts - Urgent items requiring attention
• Priorities - Ordered list of what to focus on
• Recommendations - Suggestions for productivity

Thoughts (Captures)

Quickly capture ideas, notes, and observations.

# List thoughts
ct thoughts list
ct thoughts list --limit 10
ct thoughts list --project proj_abc123

# Get thought details
ct thoughts get <id>
ct thoughts get <id> --full                # Full view with metadata

# Create thought
ct thoughts create --content "Remember to review the API design"
ct thoughts create --content "Meeting notes: discussed roadmap" --project proj_abc123

# Update thought
ct thoughts update <id> --content "Updated content"

# Delete thought
ct thoughts delete <id>
ct thoughts delete <id> --force

Output Fields: id, content, type, created_at

Pages

Create and manage documentation pages.

# List pages
ct pages list
ct pages list --search "api design"
ct pages list --project proj_abc123

# Get page details
ct pages get <id>

# Create page
ct pages create --title "API Design Document"
ct pages create --title "Meeting Notes" --content "# Overview\n..." --tags design,api

# Update page
ct pages update <id> --title "New Title"
ct pages update <id> --tags design,updated

# Delete page
ct pages delete <id>
ct pages delete <id> --force

Output Fields: id, title, tags, created_at

Projects

Organize tasks and captures into projects.

# List projects
ct projects list
ct projects list --tree                    # Show with nested tasks

# Get project details
ct projects get <id>

# Create project
ct projects create --name "Q1 Goals"
ct projects create --name "Backend" --description "Backend services" --color blue

# Update project
ct projects update <id> --name "New Name"
ct projects update <id> --description "Updated description"

# Delete project
ct projects delete <id>
ct projects delete <id> --force

# Assign items to project
ct projects assign <id> --tasks task_1,task_2,task_3
ct projects assign <id> --captures cap_1,cap_2

# Remove items from project
ct projects remove-items --tasks task_1,task_2
ct projects remove-items --captures cap_1,cap_2

Output Fields: id, name, description, color

Task Comments

Add and manage comments on tasks.

# List comments
ct tasks comments <task-id>
ct tasks comments list <task-id>

# Add a comment
ct tasks comments add <task-id> --content "Progress update"
ct tasks comments add <task-id> --content "Blocked by API" --type blocker
ct tasks comments add <task-id>                    # Interactive mode

# Delete a comment
ct tasks comments delete <task-id> <comment-id>
ct tasks comments delete <task-id> <comment-id> --force

Comment Types: | Type | Description | |------|-------------| | note | General note (default) | | progress | Progress update | | blocker | Blocking issue | | delegation | Delegated to someone | | deferral | Deferred to later |

Memories

Manage AI-extracted memories and personal context.

# List memories
ct memories list
ct memories list --active-only              # Only active memories
ct memories list --category work            # Filter by category
ct memories list --project proj_abc123

# Get memory details
ct memories get <id>

# Create memory manually
ct memories create --category work --content "Prefers dark mode in all apps"
ct memories create                          # Interactive mode

# Update memory
ct memories update <id> --content "Updated content"
ct memories update <id> --category preferences
ct memories update <id> --project proj_abc123

# Toggle active/inactive
ct memories toggle <id>
ct memories toggle <id> --active
ct memories toggle <id> --inactive

# Delete memory
ct memories delete <id>
ct memories delete <id> --force

# AI synthesis
ct memories synthesize                       # Extract from captures
ct memories extract <capture-id>             # Extract from specific capture
ct memories extract --batch                  # Batch extraction

# Analytics & management
ct memories analytics                        # View analytics
ct memories stale                            # Memories needing review
ct memories export                           # Export as JSON
ct memories import --file memories.json      # Import from file

# AI suggestions
ct memories suggestions                      # List pending suggestions
ct memories suggestions --accept <id>
ct memories suggestions --reject <id>

Memory Categories: | Category | Description | |----------|-------------| | identity | Core identity info | | work | Work-related preferences/context | | interests | Personal interests | | preferences | General preferences | | people | People and relationships | | projects | Project-specific context |

Search

Semantic search across all your content.

ct search "api design"
ct search "meeting notes" --limit 5
ct search "urgent tasks" --threshold 0.8   # Higher = more relevant
ct search "project ideas" --full           # Full result details

Output Fields: id, title/content, type, score

Config

Manage CLI configuration.

# View all config
ct config get

# View specific setting
ct config get output
ct config get timeoutMs

# Update settings
ct config set output json                  # Default output format
ct config set output table
ct config set timeoutMs 30000              # Request timeout
ct config set defaultProjectId proj_abc123

Available Keys: | Key | Description | |-----|-------------| | apiKey | API key (masked in output) | | timeoutMs | Request timeout in milliseconds | | output | Default output format (json or table) | | defaultProjectId | Default project for new items |

Shell Completions

Enable tab completion for your shell.

# Bash
ct completions bash >> ~/.bashrc
source ~/.bashrc

# Zsh
ct completions zsh >> ~/.zshrc
source ~/.zshrc

# Fish
ct completions fish > ~/.config/fish/completions/ct.fish

Output Formats

Table (Default)

Clean, readable tables with:

• Short IDs (last 8 characters)
• Color-coded status badges: ● pending, ◉ in progress, ✓ completed
• Priority indicators: 🔴 critical, 🟠 high, 🟡 medium, 🟢 low
• Relative timestamps: "Today", "Yesterday", "3 days ago", "In 2 days"

Compact

Single-line format for quick scanning:

#0c907b23 ● pending    Review API design docs           🟡 medium   Tomorrow
#d6b68def ◉ in progress Fix auth bug                    🟠 high     Today

JSON

Full structured data for scripting:

ct tasks list --json | jq '.[] | select(.priority == "high")'

CSV/TSV

Export for spreadsheets:

ct tasks list --csv > tasks.csv
ct tasks list --tsv | pbcopy  # Copy to clipboard (macOS)

Environment Variables

Override config settings with environment variables:

| Variable | Description | |----------|-------------| | CLEARTANGLE_API_KEY | API key | | CLEARTANGLE_OUTPUT | Output format (json, table) | | CLEARTANGLE_PLAIN | Set to disable colors/unicode | | NO_COLOR | Standard no-color flag |

Configuration File

Config is stored in OS-specific paths (via env-paths):

• macOS: ~/Library/Preferences/cleartangle-cli/config.json
• Linux: ~/.config/cleartangle-cli/config.json
• Windows: %APPDATA%\cleartangle-cli\config.json

Tips for AI Agents

When using this CLI programmatically:

1. Use --json for parsing: Always add --json when you need to process output
2. Check auth first: Run ct auth status --json to verify credentials
3. Use --dry-run: Preview destructive operations before executing
4. Filter with --fields: Request only needed fields to reduce output
5. Use quick filters: ct tasks list today is faster than filtering JSON
6. Handle errors: Non-zero exit codes indicate failures

Example workflow:

# Check auth
ct auth status --json

# Get high priority tasks due today
ct tasks list today --json | jq '.[] | select(.priority == "high" or .priority == "critical")'

# Create a task and capture the ID
TASK_ID=$(ct tasks create --title "New task" --json | jq -r '.id')

# Update the task
ct tasks update $TASK_ID --status in_progress

Development

# Build
npm run build

# Watch mode
npm run dev

# Type check
npm run typecheck

License

MIT