237 lines
6.4 KiB
Markdown
237 lines
6.4 KiB
Markdown
# 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
|
|
``` |