# 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.):

```bash
# 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:

```bash
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:

```bash
ticktick clear-cache
```

### 3. Install Dependencies

```bash
uv sync
```

## Usage

### Basic Commands

```bash
# 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:
```bash
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):

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

```bash
# 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
```