Skill: flexoid/ticktick-full (version 1.0.3)

--- name: ticktick-cli description: Operate TickTick through the `ticktick` command-line interface, including authentication, read/query flows, and safe mutations for tasks, projects, folders, columns, tags, habits, user info, focus analytics, and sync payloads. Use when users ask to run TickTick terminal commands, parse TickTick CLI JSON output, resolve IDs, or fix TickTick CLI configuration/auth failures. version: 1.0.3 metadata: openclaw: requires: env: - TICKTICK_CLIENT_ID - TICKTICK_CLIENT_SECRET - TICKTICK_ACCESS_TOKEN - TICKTICK_USERNAME - TICKTICK_PASSWORD --- # TickTick CLI Use this skill to execute TickTick workflows directly from terminal commands with deterministic output handling. ## Execution Policy 1. Execute the requested `ticktick ...` command first. Do not run version or tool-presence pre-checks. 2. If execution fails because CLI is missing, load `references/setup-and-auth.md` and follow install recovery flow. 3. If execution fails due auth/config issues, load `references/setup-and-auth.md` and run guided auth before retrying the original command. 4. Keep auth recovery CLI-only. Do not improvise custom SDK/Python token exchange scripts. 5. Use `--help` only as recovery when a command fails due unknown flags/arguments or missing required params. ## Defaults - Prefer `--json` on all data commands and parse structured output. - Resolve names to IDs before mutations; never guess identifiers. - Apply read -> mutate -> verify for every write operation. - Prefer explicit `--project PROJECT_ID` for task mutations when deterministic behavior matters. - Use explicit date formats (`YYYY-MM-DD` for date-only fields, ISO datetime for timed fields). ## Safety - Require explicit user confirmation before install/environment changes. - Never use risky system-install flags unless the user explicitly asks for that path. - Never print secrets or tokens in user-visible output. - Require explicit user confirmation before destructive operations: - `tasks delete` - `projects delete` - `folders delete` - `columns delete` - `tags delete` - `tags merge` - `habits delete` ## Reference Map Load only the file needed for the active area. - [Setup and auth](references/setup-and-auth.md) - [Tasks](references/tasks.md) - [Projects](references/projects.md) - [Folders](references/folders.md) - [Columns](references/columns.md) - [Tags](references/tags.md) - [Habits](references/habits.md) - [User, focus, sync](references/user-focus-sync.md) - [Troubleshooting](references/troubleshooting.md)

path: references/columns.md
content: # Columns Commands

## Contents

- Scope
- Commands
- Parameter rules

## Scope

Use this file for `ticktick columns ...` operations.

## Commands

```bash
ticktick columns list --project PROJECT_ID [--json]
ticktick columns create --project PROJECT_ID NAME [--sort N] [--json]
ticktick columns update COLUMN_ID --project PROJECT_ID [--name NAME] [--sort N] [--json]
ticktick columns delete COLUMN_ID --project PROJECT_ID [--json]
```

## Parameter rules

- `--project PROJECT_ID` is required for all column commands.
- `COLUMN_ID` is required for `update` and `delete`.
- `--sort` is integer sort order.
- `update` requires at least one update field (`--name` or `--sort`).

Use confirmation before delete.

Use `ticktick columns <action> --help` only as recovery for parameter errors.


path: references/setup-and-auth.md
content: # TickTick CLI Setup and Auth

## Use this file when

- First-time setup
- `Configuration error` / missing `TICKTICK_*` vars
- Token refresh

## Rules (keep it simple)

- TickTick CLI requires both auth layers:
  - OAuth: `TICKTICK_CLIENT_ID`, `TICKTICK_CLIENT_SECRET`, `TICKTICK_REDIRECT_URI`, `TICKTICK_ACCESS_TOKEN`
  - Session: `TICKTICK_USERNAME`, `TICKTICK_PASSWORD`
- Collect all required values before running task/project reads.
- Do not use ad-hoc SDK/Python token-exchange scripts.

## Required `.env`

```dotenv
TICKTICK_CLIENT_ID=
TICKTICK_CLIENT_SECRET=
TICKTICK_REDIRECT_URI=http://127.0.0.1:8080/callback
TICKTICK_ACCESS_TOKEN=
TICKTICK_USERNAME=
TICKTICK_PASSWORD=
```

## Happy Path

1. Ensure CLI is available.
2. Fill `.env` with all required values except `TICKTICK_ACCESS_TOKEN`.
3. Run OAuth:
   - Desktop: `ticktick auth`
   - Headless/SSH: `ticktick auth --manual`
4. Save returned token to `TICKTICK_ACCESS_TOKEN`.
5. Verify:
   - `ticktick projects list --json`
   - `ticktick tasks today --json`

## Install Recovery (if CLI missing)

- Ask for explicit user permission before install/environment changes.
- Prefer isolated install:
  - Existing virtualenv if active
  - Otherwise local `.venv`:
    - `python3 -m venv .venv`
    - `.venv/bin/python -m pip install --upgrade pip`
    - `.venv/bin/python -m pip install --upgrade ticktick-cli`

## Manual OAuth Reliability

- Start manual auth only when user is ready to approve immediately.
- Paste the auth `code` right away; codes can expire quickly.
- If interactive prompt cannot be kept stable, have user run `ticktick auth --manual` themselves and provide the resulting access token.


path: references/troubleshooting.md
content: # TickTick CLI Troubleshooting

## 1) Missing CLI

Symptoms:

- `ticktick: command not found`
- `No module named ticktick_cli`

Fix:

1. Ask user permission before install.
2. Install in isolated env (prefer local `.venv`).
3. Retry the same command.

If pip shows `error: externally-managed-environment`:

- Stop system install attempts.
- Use local `.venv` install flow from `references/setup-and-auth.md`.

## 2) Missing credentials (most common)

Symptoms:

- `Configuration incomplete`
- Missing one or more `TICKTICK_*` vars
- `V2 session credentials incomplete`

Fix:

1. Set all required vars, not only OAuth vars:
   - `TICKTICK_CLIENT_ID`
   - `TICKTICK_CLIENT_SECRET`
   - `TICKTICK_REDIRECT_URI`
   - `TICKTICK_ACCESS_TOKEN`
   - `TICKTICK_USERNAME`
   - `TICKTICK_PASSWORD`
2. Re-run:
   - `ticktick projects list --json`
   - then original command

## 3) Manual OAuth expires

Symptoms:

- Auth code fails or prompt times out

Fix:

1. Re-run `ticktick auth --manual`.
2. Approve immediately and paste a fresh `code`.
3. If interactive session is unstable, user runs auth locally and provides token.

## 4) Redirect mismatch

Symptoms:

- Callback fails
- Redirect mismatch error

Fix:

1. Ensure app redirect URI exactly equals `TICKTICK_REDIRECT_URI`.
2. Re-run auth.

## 5) Arg/flag errors

Symptoms:

- `unrecognized arguments`
- required argument errors

Fix:

- Use `ticktick <group> <action> --help` and retry.


path: references/folders.md
content: # Folders Commands

## Contents

- Scope
- Commands
- Parameter notes

## Scope

Use this file for `ticktick folders ...` operations.

## Commands

```bash
ticktick folders list [--json]
ticktick folders create NAME [--json]
ticktick folders rename FOLDER_ID NAME [--json]
ticktick folders delete FOLDER_ID [--json]
```

## Parameter notes

- `FOLDER_ID`: folder identifier.
- `NAME`: folder display name.

Use confirmation before delete.

Use `ticktick folders <action> --help` only as recovery for parameter errors.


path: references/projects.md
content: # Projects Commands

## Contents

- Scope
- Read commands
- Create command
- Update command
- Delete command

## Scope

Use this file for `ticktick projects ...` operations.

## Read commands

```bash
ticktick projects list [--json]
ticktick projects get PROJECT_ID [--json]
ticktick projects data PROJECT_ID [--json]
```

Parameter notes:

- `PROJECT_ID`: project identifier.
- `data`: returns project details plus project tasks and columns.

## Create command

```bash
ticktick projects create NAME \
  [--color HEX] \
  [--kind TASK|NOTE] \
  [--view list|kanban|timeline] \
  [--folder FOLDER_ID] \
  [--json]
```

Parameter notes:

- `NAME`: required project name.
- `--color`: hex color string (example `#F18181`).
- `--kind`: defaults to `TASK`.
- `--view`: defaults to `list`.
- `--folder`: folder/project-group ID.

## Update command

```bash
ticktick projects update PROJECT_ID \
  [--name NEW_NAME] \
  [--color HEX] \
  [--folder FOLDER_ID | --remove-folder] \
  [--json]
```

Validation rules:

- At least one update field is required.
- Do not combine `--folder` with `--remove-folder`.

## Delete command

```bash
ticktick projects delete PROJECT_ID [--json]
```

Use confirmation before running delete operations.

Use `ticktick projects <action> --help` only as recovery for parameter errors.


path: references/habits.md
content: # Habits Commands

## Contents

- Scope
- Read commands
- Create command
- Update command
- Check-in and lifecycle commands
- Parameter notes

## Scope

Use this file for `ticktick habits ...` operations.

Batch check-in is intentionally omitted from this reference.

## Read commands

```bash
ticktick habits list [--json]
ticktick habits get HABIT_ID [--json]
ticktick habits sections [--json]
ticktick habits preferences [--json]
ticktick habits checkins HABIT_ID [HABIT_ID ...] [--after-stamp YYYYMMDD] [--json]
```

## Create command

```bash
ticktick habits create NAME \
  [--type Boolean|Real] \
  [--goal FLOAT] \
  [--step FLOAT] \
  [--unit TEXT] \
  [--icon ICON_KEY] \
  [--color HEX] \
  [--section SECTION_ID] \
  [--repeat RRULE] \
  [--reminders HH:MM,HH:MM] \
  [--target-days N] \
  [--encouragement TEXT] \
  [--json]
```

Defaults:

- `--type Boolean`
- `--goal 1.0`
- `--step 0.0`
- `--unit Count`
- `--icon habit_daily_check_in`
- `--color #97E38B`
- `--repeat RRULE:FREQ=WEEKLY;BYDAY=SU,MO,TU,WE,TH,FR,SA`
- `--target-days 0`
- `--encouragement ""`

## Update command

```bash
ticktick habits update HABIT_ID \
  [--name TEXT] \
  [--goal FLOAT] \
  [--step FLOAT] \
  [--unit TEXT] \
  [--icon ICON_KEY] \
  [--color HEX] \
  [--section SECTION_ID] \
  [--repeat RRULE] \
  [--reminders HH:MM,HH:MM] \
  [--target-days N] \
  [--encouragement TEXT] \
  [--json]
```

Validation rule:

- At least one update field is required.

## Check-in and lifecycle commands

```bash
ticktick habits checkin HABIT_ID [--value FLOAT] [--date YYYY-MM-DD] [--json]
ticktick habits archive HABIT_ID [--json]
ticktick habits unarchive HABIT_ID [--json]
ticktick habits delete HABIT_ID [--json]
```

## Parameter notes

- `HABIT_ID`: habit identifier.
- `--value` default is `1.0`.
- `--date` uses `YYYY-MM-DD`.
- `--after-stamp` uses integer `YYYYMMDD` format.
- `--reminders` is comma-separated `HH:MM` values.

Use confirmation before delete.

Use `ticktick habits <action> --help` only as recovery for parameter errors.


path: references/tasks.md
content: # Tasks Commands

## Contents

- Scope
- Project resolution
- Read/query commands
- Create commands
- Update/lifecycle commands
- Move, hierarchy, pin, column
- Parameter rules

## Scope

Use this file for `ticktick tasks ...` workflows.

## Project resolution

When `--project` is omitted:

- Existing-task mutation commands (`update`, `done`, `abandon`, `delete`, `pin`, `unpin`, `column`, `subtask`, `unparent`) resolve project from task ID.
- Create commands (`add`, `quick-add`) resolve in this order:
  1. `--project`
  2. `TICKTICK_CURRENT_PROJECT_ID`
  3. inbox project ID
- Query commands default to all projects unless `--project` is set.

Prefer explicit `--project` for deterministic writes.

## Read/query commands

```bash
ticktick tasks list [--project PROJECT_ID] [--due YYYY-MM-DD] [--json]
ticktick tasks get TASK_ID [--project PROJECT_ID] [--json]
ticktick tasks search QUERY [--project PROJECT_ID] [--json]
ticktick tasks by-tag TAG_NAME [--project PROJECT_ID] [--json]
ticktick tasks by-priority PRIORITY [--project PROJECT_ID] [--json]
ticktick tasks today [--project PROJECT_ID] [--json]
ticktick tasks overdue [--project PROJECT_ID] [--json]
ticktick tasks completed [--days N] [--limit N] [--project PROJECT_ID] [--json]
ticktick tasks abandoned [--days N] [--limit N] [--project PROJECT_ID] [--json]
ticktick tasks deleted [--limit N] [--project PROJECT_ID] [--json]
```

Key parameters:

- `TASK_ID`: task identifier.
- `QUERY`: text search query.
- `TAG_NAME`: tag name (not tag ID).
- `PRIORITY`: `none|low|medium|high|0|1|3|5`.
- `--due` on `list`: local-date filter in `YYYY-MM-DD`.
- `--days`: lookback days (default `7` for completed/abandoned).
- `--limit`: result cap (default `100` where supported).

## Create commands

```bash
ticktick tasks add TITLE \
  [--project PROJECT_ID] \
  [--content TEXT] \
  [--description TEXT] \
  [--kind TEXT|NOTE|CHECKLIST] \
  [--start YYYY-MM-DD|ISO_DATETIME] \
  [--due YYYY-MM-DD|ISO_DATETIME] \
  [--priority none|low|medium|high] \
  [--tags tag1,tag2] \
  [--recurrence RRULE] \
  [--time-zone IANA_TZ] \
  [--all-day|--timed] \
  [--parent PARENT_TASK_ID] \
  [--reminders TRIGGER_1,TRIGGER_2] \
  [--json]

ticktick tasks quick-add TEXT [--project PROJECT_ID] [--json]
```

Parameter notes:

- `TITLE`: required task title.
- `--content`: note/body text.
- `--description`: checklist description field.
- `--kind`: task kind (`TEXT`, `NOTE`, `CHECKLIST`; case-insensitive in CLI input).
- `--start`, `--due`: accept date-only or ISO datetime.
- `--tags`: comma-separated names.
- `--recurrence`: RRULE string.
- `--time-zone`: IANA timezone stored on task.
- `--all-day` / `--timed`: mutually exclusive.
- `--parent`: create task as subtask.
- `--reminders`: comma-separated trigger strings (example `TRIGGER:-PT30M`).

## Update/lifecycle commands

```bash
ticktick tasks update TASK_ID \
  [--project PROJECT_ID] \
  [--title TEXT] \
  [--content TEXT] \
  [--description TEXT] \
  [--kind TEXT|NOTE|CHECKLIST] \
  [--priority none|low|medium|high] \
  [--start YYYY-MM-DD|ISO_DATETIME|--clear-start] \
  [--due YYYY-MM-DD|ISO_DATETIME|--clear-due] \
  [--tags tag1,tag2|--clear-tags] \
  [--recurrence RRULE|--clear-recurrence] \
  [--time-zone IANA_TZ] \
  [--all-day|--timed] \
  [--json]

ticktick tasks done TASK_ID [--project PROJECT_ID] [--json]
ticktick tasks abandon TASK_ID [--project PROJECT_ID] [--json]
ticktick tasks delete TASK_ID [--project PROJECT_ID] [--json]
```

Update validation rules:

- At least one update field is required.
- Invalid combinations:
  - `--start` with `--clear-start`
  - `--due` with `--clear-due`
  - `--tags` with `--clear-tags`
  - `--recurrence` with `--clear-recurrence`

## Move, hierarchy, pin, column

```bash
ticktick tasks move TASK_ID --to-project PROJECT_ID [--from-project PROJECT_ID] [--json]
ticktick tasks subtask TASK_ID --parent PARENT_TASK_ID [--project PROJECT_ID] [--json]
ticktick tasks unparent TASK_ID [--project PROJECT_ID] [--json]
ticktick tasks pin TASK_ID [--project PROJECT_ID] [--json]
ticktick tasks unpin TASK_ID [--project PROJECT_ID] [--json]
ticktick tasks column TASK_ID [--project PROJECT_ID] (--column COLUMN_ID | --clear-column) [--json]
```

Parameter notes:

- `move`: `--to-project` required; `--from-project` optional (auto-resolved from task when omitted).
- `subtask`: `--parent` required.
- `column`: must set one of `--column` or `--clear-column`.

## Parameter rules

- Priority mapping: `none=0`, `low=1`, `medium=3`, `high=5`.
- `TZ` controls local-date interpretation for listing/filtering.
- Date-only values are interpreted as all-day task values.
- Use `--json` for deterministic parsing.

Use `ticktick tasks <action> --help` only when a command fails due parameter mismatch.


path: references/tags.md
content: # Tags Commands

## Contents

- Scope
- Commands
- Parameter and safety notes

## Scope

Use this file for `ticktick tags ...` operations.

## Commands

```bash
ticktick tags list [--json]
ticktick tags create NAME [--color HEX] [--parent PARENT_TAG] [--json]
ticktick tags update NAME [--color HEX] [--parent PARENT_TAG | --clear-parent] [--json]
ticktick tags rename OLD_NAME NEW_NAME [--json]
ticktick tags merge SOURCE TARGET [--json]
ticktick tags delete NAME [--json]
```

## Parameter and safety notes

- `NAME`, `OLD_NAME`, `NEW_NAME`, `SOURCE`, `TARGET` are tag names.
- `--color` expects hex string (example `#57A8FF`).
- `update` requires at least one of:
  - `--color`
  - `--parent`
  - `--clear-parent`
- Do not combine `--parent` and `--clear-parent`.
- `merge` and `delete` are destructive; confirm intent first.

Use `ticktick tags <action> --help` only as recovery for parameter errors.


path: references/user-focus-sync.md
content: # User, Focus, and Sync Commands

## Contents

- Scope
- User commands
- Focus commands
- Sync command
- Parameter notes

## Scope

Use this file for read-only account/profile/analytics/sync operations.

## User commands

```bash
ticktick user profile [--json]
ticktick user status [--json]
ticktick user statistics [--json]
ticktick user preferences [--json]
```

## Focus commands

```bash
ticktick focus heatmap [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--days N] [--json]
ticktick focus by-tag [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--days N] [--json]
```

## Sync command

```bash
ticktick sync [--json]
```

## Parameter notes

- `--from`, `--to`: ISO date (`YYYY-MM-DD`).
- `--days`: lookback when explicit range is not supplied; default is `30`.
- `sync --json`: emits raw full-account sync payload for diagnostics/export-style inspection.

Use `ticktick <group> <action> --help` only as recovery for parameter errors.


Security scan verdicts — ClawScan: clean | static analysis:  | VirusTotal: clean | SkillSpector: clean (LOW)