GETTING-STARTED.md•5.19 kB
# Getting Started with TickTick API Client
A simple guide to get up and running in 5 minutes.
## Prerequisites
- Python 3.7 or higher
- A TickTick account
- 5 minutes of setup time
## Step 1: Clone and Install
```bash
# Clone the repository (or download the files)
cd your-project-directory
# Install dependencies
pip install -r requirements.txt
```
## Step 2: Get TickTick API Credentials
1. Go to **https://developer.ticktick.com/manage**
2. Log in with your TickTick account
3. Click **"+ App Name"** to create a new app
4. Give it any name (e.g., "My Task Automation")
5. Set **Redirect URI** to: `http://127.0.0.1:8080`
6. Click **Save**
7. Copy your **Client ID** and **Client Secret**
## Step 3: Configure Environment Variables
1. Copy the example environment file:
```bash
cp .env.example .env
```
2. Edit `.env` and add your credentials:
```bash
# From TickTick Developer Console (step 2)
TICKTICK_CLIENT_ID=your-client-id-here
TICKTICK_CLIENT_SECRET=your-client-secret-here
TICKTICK_REDIRECT_URI=http://127.0.0.1:8080
# Your TickTick account credentials
TICKTICK_USERNAME=your-email@example.com
TICKTICK_PASSWORD=your-password
```
3. Save the file
## Step 4: Authenticate (One-Time Setup)
Run this once to authenticate:
```bash
python ticktick_rest_api.py --auth
```
This will:
1. Open your browser for authorization
2. Ask you to approve the app
3. Save a token to `.ticktick-token.json`
4. **You won't need to do this again** (token lasts ~165 days)
You should see: `✓ Authentication successful!`
## Step 5: Start Using It!
### Add a Simple Task
```bash
python add_task.py "Buy groceries"
```
### Add a Task with Details
```bash
python add_task.py "Morning workout" --project Health --priority 5 --due today
```
### Add a Task with Long Description
```bash
python add_task.py "Weekly check-in" --project Marriage --priority 5 --content "$(cat <<'EOF'
Review questions:
1. What went well this week?
2. What needs improvement?
3. Goals for next week?
Notes:
- Schedule 30 minutes
- Be honest and kind
EOF
)"
```
## Common Use Cases
### Daily Tasks
```bash
# Add to inbox (no project)
python add_task.py "Call dentist"
# Add to specific project
python add_task.py "30 min walk" --project Health --priority 3
# Add with due date
python add_task.py "Submit report" --due "2025-11-20" --priority 5
```
### Weekly Planning
```bash
# Tasks due today
python add_task.py "Team meeting prep" --due today --priority 5
# Tasks due tomorrow
python add_task.py "Review pull requests" --due tomorrow --priority 3
```
### Projects
First, create projects in TickTick (or use the setup script):
```bash
# Optional: Create full Health & Marriage system
python ticktick_rest_api.py --setup
```
Then add tasks to those projects:
```bash
python add_task.py "Exercise" --project Health
python add_task.py "Date night" --project Marriage
```
## Parameters Reference
| Parameter | Values | Example |
|-----------|--------|---------|
| `--content` | Any text | `--content "Task notes"` |
| `--project` | Project name | `--project Health` |
| `--priority` | 0, 1, 3, 5 | `--priority 5` (High) |
| `--due` | YYYY-MM-DD, today, tomorrow | `--due today` |
**Priority Levels:**
- `5` = High (red)
- `3` = Medium (yellow)
- `1` = Low (blue)
- `0` = None (default)
## Troubleshooting
### "No token found" or browser keeps opening
**Fix:** Run authentication once:
```bash
python ticktick_rest_api.py --auth
```
### "TICKTICK_CLIENT_ID must be set"
**Fix:** Check your `.env` file exists and has the correct credentials.
### "Project not found"
**Fix:** Check the exact project name in TickTick. Project names are case-insensitive but must match exactly.
### Token expired
Tokens last ~165 days. If expired, delete and re-authenticate:
```bash
rm .ticktick-token.json
python ticktick_rest_api.py --auth
```
## Advanced Usage
### View All Tasks
```bash
python ticktick_rest_api.py --status
```
### Create Test Task
```bash
python ticktick_rest_api.py --test
```
### Programmatic Usage
```python
from ticktick_rest_api import TickTickClient
import os
client = TickTickClient(
client_id=os.getenv('TICKTICK_CLIENT_ID'),
client_secret=os.getenv('TICKTICK_CLIENT_SECRET')
)
# Create task
task = client.create_task(
title="My Task",
content="Description here",
priority=5
)
```
## Security Notes
- Never commit `.env` to version control (it contains your password!)
- Never commit `.ticktick-token.json` (it contains your access token!)
- Both files are already in `.gitignore`
## Need Help?
- Check the [README.md](README.md) for detailed documentation
- Check the [CLAUDE.md](CLAUDE.md) for technical architecture details
- Review the code in `add_task.py` (it's simple and well-commented)
## What's Next?
Now that you're set up:
1. **Create your projects** in TickTick (Health, Work, Personal, etc.)
2. **Add tasks** using the command line: `python add_task.py "Task name"`
3. **Check TickTick app** on your phone/web to see tasks appear
4. **Automate** - integrate into your scripts, cron jobs, or workflows!
---
**You're all set!** Start adding tasks and building your productivity system.