luk/TICKTICK_SETUP.md

TickTick CLI Integration Setup

This guide helps you set up the TickTick CLI integration for task management.

Prerequisites

1. TickTick Account: You need a TickTick account
2. TickTick Developer App: Register an app at https://developer.ticktick.com/docs#/openapi

Setup Steps

1. Register TickTick Developer App

1. Go to https://developer.ticktick.com/docs#/openapi
2. Click "Manage Apps" in the top right
3. Click "+App Name" to create a new app
4. Fill in the app name (required field only)
5. Note down your Client ID and Client Secret
6. Set the OAuth Redirect URL to: http://localhost:8080

2. Set Environment Variables

Add these to your shell profile (.bashrc, .zshrc, etc.):

# OAuth2 Credentials (Required)
export TICKTICK_CLIENT_ID="your_client_id_here"
export TICKTICK_CLIENT_SECRET="your_client_secret_here"
export TICKTICK_REDIRECT_URI="http://localhost:8080"

# TickTick Login Credentials (Optional - you'll be prompted if not set)
export TICKTICK_USERNAME="your_email@example.com"
export TICKTICK_PASSWORD="your_password"

# SSL Configuration (Optional - for corporate networks with MITM proxies)
# export TICKTICK_DISABLE_SSL_VERIFY="true"

Important Note: The TickTick library requires both OAuth2 credentials AND your regular TickTick login credentials. This is how the library is designed:

• OAuth2: Used for API authentication and authorization
• Username/Password: Required for initial session establishment

Your login credentials are only used for authentication and are not stored permanently.

Authentication

Token Storage

OAuth tokens are automatically cached in:

~/.local/share/gtd-terminal-tools/ticktick_tokens.json

This file is created and managed automatically by the TickTick library. The tokens are used to avoid repeated OAuth flows and will be refreshed automatically when needed.

Authentication Status

Check your authentication setup and token status:

ticktick auth-status

This command shows:

• OAuth credentials status (environment variables)
• Login credentials status
• Token cache status and expiration
• Token file location and last modified time

If you need to clear the token cache and re-authenticate:

ticktick clear-cache

3. Install Dependencies

uv sync

Usage

Basic Commands

# List all tasks
ticktick list
ticktick ls          # Short alias

# Filter by project
ticktick ls -p "Work"

# Filter by due date  
ticktick ls -d today
ticktick ls -d tomorrow
ticktick ls -d "2024-01-15"

# Add a new task
ticktick add "Buy groceries"
ticktick a "Buy groceries" -d tomorrow -p "Personal"  # With options

# Edit a task
ticktick edit TASK_ID --title "New title"
ticktick e TASK_ID -d tomorrow -pr high

# Complete a task
ticktick complete TASK_ID
ticktick done TASK_ID
ticktick c TASK_ID    # Short alias

# Delete a task
ticktick delete TASK_ID
ticktick rm TASK_ID -f  # Force delete without confirmation

# Open task in browser/app
ticktick open TASK_ID
ticktick o TASK_ID    # Short alias

# Show detailed task info
ticktick show TASK_ID
ticktick s TASK_ID    # Short alias

# List projects and tags
ticktick projects
ticktick tags

# Sync with TickTick servers
ticktick sync

Command Aliases Reference

Full Command	Short Alias	Description
list	ls	List tasks
add	a	Add new task
edit	e	Edit existing task
complete	c, done	Mark task complete
delete	rm, del	Delete task
open	o	Open in browser/app
show	s, view	Show task details
projects	proj	List projects

Option Aliases

Full Option	Short	Description
--project	-p	Filter/set project
--due-date	-d	Filter/set due date
--priority	-pr	Filter/set priority
--tag	-t	Filter by tag
--all	-a	Show all tasks
--force	-f	Skip confirmations
--browser	-b	Force browser opening
--content	-c	Task description
--limit	-l	Limit results

Priority Levels

You can set priorities using numbers (0-5) or names:

• 0 or none: No priority
• 1 or low: Low priority
• 2 or medium: Medium priority
• 3 or high: High priority
• 4 or urgent: Very high priority
• 5 or critical: Critical priority

Date Formats

Supported date formats:

• today, tomorrow, yesterday
• YYYY-MM-DD (e.g., 2024-01-15)
• Most common date formats via dateutil parsing

Authentication

The TickTick integration uses a dual authentication approach:

1. OAuth2 Setup: On first use, the CLI will:

   • Open a web browser for OAuth authorization
   • Prompt you to copy the redirect URL
   • Cache the OAuth token in ~/.local/share/gtd-terminal-tools/ticktick_tokens.json

2. Login Credentials: The library also requires your TickTick username/password for session establishment. You can either:

   • Set TICKTICK_USERNAME and TICKTICK_PASSWORD environment variables
   • Enter them when prompted (they won't be stored)

The OAuth token cache lasts about 6 months, after which you'll need to re-authenticate.

Why Both?: The ticktick-py library uses OAuth2 for API calls but requires login credentials for initial session setup. This is the library's design, not a limitation of our CLI.

macOS App Integration

On macOS, the ticktick open command will try to open tasks in the TickTick desktop app first, falling back to the browser if the app isn't available.

Troubleshooting

"Please set TICKTICK_CLIENT_ID" Error

Make sure you've set the environment variables and restarted your terminal.

Authentication Issues

Try clearing the token cache:

rm ~/.local/share/gtd-terminal-tools/ticktick_tokens.json

SSL Certificate Errors

If you get SSL certificate verification errors (common on corporate networks with MITM proxies):

export TICKTICK_DISABLE_SSL_VERIFY="true"

Warning: This disables SSL verification. Only use this on trusted corporate networks.

Network/API Errors

Check your internet connection and verify your TickTick credentials.

Example Workflow

# Morning routine: check today's tasks
ticktick ls -d today

# Add a quick task
ticktick a "Review reports" -p "Work" -d today -pr high

# Complete a task when done
ticktick c TASK_ID

# Check what's due tomorrow
ticktick ls -d tomorrow

# Open an important task for details
ticktick o TASK_ID