Super Productivity CLI

A command-line interface for Super Productivity with full read-write support via Local REST API.

Note: This is an unofficial CLI and is not affiliated with the Super Productivity project.

Overview

This CLI supports two backend modes:

| Mode | Access | Requirements | |------|--------|--------------| | Local REST API | Read-Write | Super Productivity desktop app must be open | | Dropbox Sync | Read-Only | Dropbox sync enabled in app (no app required) |

Which Mode Should I Use?

| Feature | Local REST API | Dropbox Sync | |---------|:--------------:|:------------:| | View tasks | ✅ | ✅ | | Search tasks | ✅ | ✅ | | View projects | ✅ | ✅ | | View tags | ✅ | ✅ | | View status | ✅ | ✅ | | Create tasks | ✅ | ❌ | | Update tasks | ✅ | ❌ | | Delete tasks | ✅ | ❌ | | Start/stop task | ✅ | ❌ | | Archive/restore | ✅ | ❌ | | Assign tags | ✅ | ❌ | | Move to project | ✅ | ❌ | | Set time estimate | ✅ | ❌ | | View counters | ❌ | ✅ | | View notes | ❌ | ✅ | | App must be open | ✅ Yes | ❌ No | | Works offline | ❌ No | ✅ Yes |

Recommendation: Use Local REST API for full functionality. Use Dropbox Sync when the app is closed or for read-only access.

Auto-detection: The CLI automatically detects if the Local REST API is available. If the API is unreachable, it falls back to Dropbox mode.

Features

• Dual Backend - API (read-write) and Dropbox (read-only)
• Auto-detection - Falls back to Dropbox if API unavailable
• Native Dropbox API - Direct OAuth authentication, no rclone needed
• Encryption Support - Decrypt sync files with AES-256-GCM + Argon2id
• JSON Output - All commands support --json, --ndjson, and --full

Requirements

• Node.js 18+
• Super Productivity desktop app (for Local REST API)
• OR Dropbox sync enabled (for read-only mode)

Installation

# Run directly with npx (no installation required)
npx super-productivity-cli --help

# Or install globally
npm install -g super-productivity-cli
sp --help

Quick Start

Option 1: Local REST API (Recommended - Full Features)

Requirements: Super Productivity desktop app must be running with Local REST API enabled.

1. Open Super Productivity desktop app
2. Enable API: Settings → Misc → Enable local REST API
3. The API runs at http://127.0.0.1:3876

# List tasks (auto-detects API)
sp task list

# Create a new task
sp task create "Buy groceries"

# Start tracking time
sp task start <task-id>

# Stop tracking
sp task stop

# Update task
sp task update <task-id> --title "New title" --tag TODAY

# Move to project
sp task update <task-id> -p <project-id>

# Archive task
sp task archive <task-id>

Option 2: Dropbox Sync (Read-Only)

Requirements: Dropbox sync enabled in Super Productivity. Works without the app open.

# Login to Dropbox (one-time setup)
sp login

# Set encryption password if your sync is encrypted
sp encrypt-key "your-password"

# Force Dropbox mode
sp --dropbox task list

# View counters/habits (only available in Dropbox mode)
sp --dropbox counter list

# View notes (only available in Dropbox mode)
sp --dropbox note list

Backend Selection

# Auto-detect (API if available, else Dropbox)
sp task list

# Force API mode
sp --api task list

# Force API with custom URL
sp --api http://localhost:8080 task list

# Force Dropbox mode
sp --dropbox task list

# Set custom API URL via environment variable
export SP_API_URL=http://localhost:8080
sp task list

Commands

Authentication (Dropbox)

| Command | Description | |---------|-------------| | sp login | Authenticate with Dropbox via OAuth | | sp logout | Clear stored tokens | | sp encrypt-key <password> | Set encryption password | | sp encrypt-key --clear | Remove encryption password |

Tasks (Read - Both Modes)

| Command | Description | |---------|-------------| | sp task list | List all incomplete tasks | | sp task list --today | Tasks due today or tagged TODAY | | sp task list --past-due | Overdue incomplete tasks | | sp task list --done | Show completed tasks | | sp task list --archived | Show archived tasks | | sp task list -p <id> | Filter by project ID | | sp task list -t <id> | Filter by tag ID | | sp task search <query> | Search tasks by title | | sp task show <id> | Show task details |

Tasks (Write - API Mode Only)

| Command | Description | |---------|-------------| | sp task create <title> | Create a new task | | sp task update <id> | Update task fields | | sp task delete <id> | Delete a task | | sp task start <id> | Start task (set as current) | | sp task stop | Stop current task | | sp task archive <id> | Archive a task | | sp task restore <id> | Restore archived task |

Task Update Options

sp task update <id> -t "New title"           # Change title
sp task update <id> -p <project-id>          # Move to project
sp task update <id> -e 2h                    # Set estimate (2 hours)
sp task update <id> --tag TODAY,Urgent       # Set tags (replaces existing)
sp task update <id> --add-tag TODAY          # Add tag (keeps existing)
sp task update <id> --remove-tag Urgent      # Remove tag
sp task update <id> --done                   # Mark as done
sp task update <id> --undone                 # Mark as not done

Projects & Tags

| Command | Description | |---------|-------------| | sp project list | List all projects | | sp project list -q "Work" | Search projects | | sp tag list | List all tags | | sp tag show <id> | Show tag details |

Status & State

| Command | Description | |---------|-------------| | sp status | Today's summary with time spent | | sp state summary | Entity counts overview |

Counters & Notes (Dropbox Only)

| Command | Description | |---------|-------------| | sp counter list | List all counters with today's values | | sp note list | List all notes with preview |

Output Formats

All list commands support multiple output formats:

# Pretty JSON
sp task list --json

# Newline-delimited JSON (for streaming/processing)
sp task list --ndjson

# Full entity data (all fields)
sp task list --json --full

Examples

# Create task with project and estimate
sp task create "Review PR" -p Work -e 30m --tag Urgent

# Start working on a task
sp task start abc123

# Move task to another project and add tag
sp task update abc123 -p "Side Project" --add-tag TODAY

# Get tasks as JSON for scripting
sp task list --today --json | jq '.[] | .title'

# Check current status
sp status

Configuration

Config stored at ~/.config/super-productivity-cli/config.json:

{
  "dropbox": {
    "accessToken": "...",
    "refreshToken": "...",
    "encryptKey": "optional-password"
  }
}

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | SP_API_URL | Local REST API URL | http://127.0.0.1:3876 |

Development

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm run start -- --help

# Link for global use
npm link

Related Projects

• Super Productivity - The main application

License

MIT