Clear Tangle CLI

Command-line interface for tasks, thoughts, pages, and projects

Clear Tangle CLI brings your second brain to the terminal. Create tasks, capture thoughts, manage pages, and search everything without leaving your shell. It is built for speed, automation, and AI-friendly workflows.

Quick Facts

Command: ct
Authentication: API keys via ct auth set-key or CLEARTANGLE_API_KEY
Outputs: table, compact, json, csv, tsv

Features

Task Management

Create, update, complete, and organize tasks with priorities and due dates.

Thought Capture

Quickly capture ideas and notes from anywhere.

Page Management

Create and manage documentation pages with tags.

Project Organization

Group tasks and captures into projects.

Smart Search

Semantic search across all your content.

AI Planning

Generate prioritized action plans with context.

Multiple Formats

JSON, table, compact, CSV, and TSV outputs.

Beautiful Output

Color-coded tables, status badges, and relative timestamps.

Shell Completions

Tab completion for bash, zsh, and fish.

Installation

Install globally from npm:

Global install (recommended)bash

npm install -g clear-tangle-cli

# Verify install
ct --help

After install, verify the CLI is on your path by running ct --help.

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 Settings > API Keys. Learn more on the API Keys page.

Auth commandsbash

# 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

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 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, priorities, and recommendations.

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

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: apiKey, timeoutMs, output, defaultProjectId

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 tables with short IDs, status badges, priority indicators, and relative timestamps.

Compact

Single-line format for quick scanning in long lists.

JSON

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

CSV / TSV

ct tasks list --csv > tasks.csv
ct tasks list --tsv | pbcopy

Environment Variables

Variable	Description
`CLEARTANGLE_API_KEY`	API key
`CLEARTANGLE_OUTPUT`	Output format (json or table)
`CLEARTANGLE_PLAIN`	Disable colors and 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

Automation Guidance

Use --json when parsing output.
Check auth first with ct auth status --json.
Use --dry-run to preview destructive operations.
Limit columns with --fields for smaller payloads.
Prefer quick filters like ct tasks list today for speed.

Example workflowbash

# 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

Next Steps

Explore the API Keys guide for secure automation, or connect your AI assistant with the MCP Server.