wip
This commit is contained in:
Tim Bendt
237
TICKTICK_SETUP.md
Normal file
237
TICKTICK_SETUP.md
Normal file
@@ -0,0 +1,237 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user