ClickUp

Interact with ClickUp tasks and documents via the API. Get task information, view comments, create tasks, manage assignments, post updates, and create/edit documents.

Setup

Install dependencies first — one time, per checkout:

cd .claude/skills/clickup && npm install

lib/markdown.mjs parses markdown with remark, and query.mjs reaches it through lib/format.mjs on startup. Every command — not just the comment ones — exits with ERRMODULENOT_FOUND until this runs.

Then create accounts.json in this skill directory with your API token:

{
  "defaultAccount": "bot",
  "accounts": {
    "bot": {
      "apiToken": "pk_your_token_here"
    }
  }
}

Generate token at: ClickUp Settings > Apps > API Token

Or use the CLI to add accounts:

node query.mjs add-account bot --token pk_your_token_here

Team ID, User ID, and other fields are auto-detected and cached on first use.

Migration from .env: If you have an existing .env file, credentials are auto-migrated to accounts.json on first run. The .env file is preserved; remove it when ready.

Default List (Optional)

Set defaultListId in your account to enable creating tasks without specifying a list:

{
  "defaultAccount": "bot",
  "accounts": {
    "bot": {
      "apiToken": "pk_...",
      "defaultListId": "901111220963"
    }
  }
}

Multi-Account

Support multiple named accounts (e.g., "bot" for automation, "justin" for personal use):

{
  "defaultAccount": "bot",
  "accounts": {
    "bot": {
      "apiToken": "pk_...",
      "teamId": "8459928",
      "userId": "75386805",
      "defaultListId": "901111220963"
    },
    "justin": {
      "apiToken": "pk_...",
      "teamId": "8459928",
      "userId": "10620972"
    }
  }
}

Only apiToken is required per account. Other fields are auto-detected and cached.

Use --account <name> with any command to target a specific account:

node query.mjs me --account justin
node query.mjs my-tasks --account bot

Account management commands:

node query.mjs accounts                          # List all accounts
node query.mjs switch-account justin             # Change default
node query.mjs add-account justin --token pk_... # Add account
node query.mjs remove-account old-account        # Remove account

Running Commands

node query.mjs <command> [options]

Task Commands

List Commands

Document Commands

Attachment Commands

Options

Examples

Get Task Details

# Using full URL
node query.mjs get "https://app.clickup.com/t/86a1b2c3d"

# Using task ID directly
node query.mjs get 86a1b2c3d

# Include subtasks
node query.mjs get 86a1b2c3d --subtasks

Create a Task

# With explicit list ID
node query.mjs create 901111220963 "New feature: dark mode"

# Using default list (if CLICKUP_DEFAULT_LIST_ID is set)
node query.mjs create "Quick task"

List My Tasks

# All tasks assigned to you across the workspace
node query.mjs my-tasks

Search Tasks

ClickUp's v2 API has no native text search across tasks, so search requires a scope so the workspace crawl stays bounded. Pick whichever scope fits:

# Scope to a specific list (fastest, recommended)
node query.mjs search "authentication" --list 901111220963

# All tasks assigned to you with a particular status
node query.mjs search --me --status "in progress"

# Scope to a folder ("project") — scans every list in that folder
node query.mjs search "oauth" --folder 90111122009

# Filter by assignee + text
node query.mjs search "migration" --assignee justin

# Multiple statuses (comma-separated)
node query.mjs search --me --status "in progress,review"

# Unscoped full-workspace scan — slow, fetches every task. Use sparingly.
node query.mjs search "dark mode" --all

Without a scope flag (and without --all), search will exit with a helpful error instead of silently hammering the API.

Find a List or Folder by Name

When you have a list name ("Red Launch", "Triage", "Sprint 12") but no ID, use find-list — it walks the workspace structure (spaces → folders → lists) using only metadata endpoints. Fast, no task fetches.

node query.mjs find-list "Red Launch"
node query.mjs find-list "triage" --json

Matches rank: exact > starts-with > contains, case-insensitive. Returns both list matches and folder matches (with the folder's nested lists inlined), so if the thing you named is a folder you still see the lists you probably want.

Update Task Status

# List available statuses for a task
node query.mjs status 86a1b2c3d

# Update status (case-insensitive, partial match)
node query.mjs status 86a1b2c3d "in progress"
node query.mjs status 86a1b2c3d "complete"

Assign Tasks

# Assign by username
node query.mjs assign 86a1b2c3d justin

# Assign by email
node query.mjs assign 86a1b2c3d [email protected]

Set Due Dates

node query.mjs due 86a1b2c3d "tomorrow"
node query.mjs due 86a1b2c3d "next friday"
node query.mjs due 86a1b2c3d "+3d"
node query.mjs due 86a1b2c3d "2024-01-15"

Set Priority

node query.mjs priority 86a1b2c3d urgent
node query.mjs priority 86a1b2c3d high
node query.mjs priority 86a1b2c3d none  # Clear priority

Create Subtasks

node query.mjs subtask 86a1b2c3d "Write unit tests"
node query.mjs subtask 86a1b2c3d "Update documentation"

Move Tasks

node query.mjs move 86a1b2c3d 901111220964

Add Links

# Add link with description
node query.mjs link 86a1b2c3d "https://github.com/..." "PR #123"

# Add link without description
node query.mjs link 86a1b2c3d "https://docs.example.com/guide"

Add Checklist Items

node query.mjs checklist 86a1b2c3d "Review code"
node query.mjs checklist 86a1b2c3d "Run tests"
node query.mjs checklist 86a1b2c3d "Deploy to staging"

List Tasks in a List

# All tasks in a list
node query.mjs tasks 901111220963

# Only tasks assigned to me
node query.mjs tasks 901111220963 --me

View Comments

node query.mjs comments "https://app.clickup.com/t/86a1b2c3d"

# Expand all threaded replies inline
node query.mjs comments 86a1b2c3d --threads

# View replies on a specific comment thread
node query.mjs thread 90110200841741

# Reply to a comment thread
node query.mjs reply 90110200841741 "Sounds good, I'll take care of it."

Post a Comment

node query.mjs comment 86a1b2c3d "Starting work on this task"

# Multi-line comment
node query.mjs comment 86a1b2c3d "Status update:
- Completed initial review
- Found 3 issues to address
- Will submit PR by EOD"

@Mention Users in Comments

The skill supports two mention syntaxes:

1. Explicit (preferred): @[identifier] — bracket syntax with fuzzy matching by name, email, or user ID
2. Bare (auto-detected): @Name or @First Last — automatically matched against workspace members

Bare mentions are a fallback so mentions work even if agents forget the bracket syntax. Both produce the same ClickUp mention attribute.

# Explicit bracket syntax (preferred)
node query.mjs comment 86a1b2c3d "Hey @[justin], can you review this?"

# Bare mention (auto-detected against workspace members)
node query.mjs comment 86a1b2c3d "Hey @Justin Maier, can you review this?"

# Both work the same — these are equivalent:
node query.mjs comment 86a1b2c3d "@[justin] please review"
node query.mjs comment 86a1b2c3d "@Justin please review"

# Mention by numeric user ID (bracket syntax only)
node query.mjs comment 86a1b2c3d "@[10620972] please take a look"

# Mention by email (bracket syntax only)
node query.mjs comment 86a1b2c3d "Assigned to @[[email protected]]"

# Multiple mentions in one comment
node query.mjs comment 86a1b2c3d "@[justin] and @[koen] - need your input on this"


**Bracket syntax**: Fuzzy matches partial names, emails, or numeric IDs. `@[justin]` matches "Justin Maier". Unknown users throw an error.

**Bare syntax**: Matches `@Name` against workspace member usernames (case-insensitive). Tries full name first (`@Justin Maier`), then first name (`@Justin`). Unmatched bare mentions are left as plain text (no error).

### Show Current User

node query.mjs me

### Delete a Comment

Get comment IDs from the comments command (shown in --json output)

node query.mjs delete-comment 90110200841741

### Add/Remove Watchers

Add user as watcher on a task

node query.mjs watch 86a1b2c3d koen

Remove watcher

node query.mjs unwatch 86a1b2c3d koen

### Add Tags

Add a tag to a task

node query.mjs tag 86a1b2c3d "DevOps" node query.mjs tag 86a1b2c3d "bug"

### Update Description

Update task description with markdown

node query.mjs description 86a1b2c3d "## Summary This is a bold statement.

• Item 1
• Item 2

See documentation for more info."

### Archive / Restore Tasks

Archive a task (removes from active views)

node query.mjs archive 86a1b2c3d

Restore an archived task

node query.mjs unarchive 86a1b2c3d

### Claim a Task (Session Linking)

When you start working on a ClickUp task, **claim it immediately** so your session can be resumed later. This writes your Claude Code session ID to the task's "Session ID" custom field, allowing work to be picked up where you left off.

Claim a task as soon as you begin working on it

node query.mjs claim 86a1b2c3d

Works with URLs too

node query.mjs claim "https://app.clickup.com/t/86a1b2c3d";

**Requirements:**
- The task's list must have a text custom field with "Session" in its name (e.g., "Session ID")
- Session ID resolution order: `$CLAUDE_SESSION_ID` → most-recently-modified `~/.claude/projects/*/*.jsonl` (within 60s). The fallback handles harnesses that don't expose the env var.

**When to claim:** As soon as you start working on a ClickUp task. This is how we pick up where you left off if we need to continue work on the same task later.

### Get List Details

Get list info including statuses

node query.mjs list 901111220963

### Create a List

Create a list in a space using space ID

node query.mjs create-list 20128955 "New List"

Create a list using space URL

node query.mjs create-list "https://app.clickup.com/8459928/v/s/20128955"; "Sprint Backlog"

Create a list with description

node query.mjs create-list 20128955 "Bug Tracker" --content "Track all bugs here"

### Delete a List

node query.mjs delete-list 901111220963

### List/Search Docs

List all docs in workspace

node query.mjs docs

Search docs by name

node query.mjs docs "API"

### Get Doc Details

Get doc info and page listing

node query.mjs doc abc123def

Using a doc URL

node query.mjs doc "https://app.clickup.com/12345/v/dc/abc123def";

### Create a Doc

Create an empty doc

node query.mjs create-doc "Project Notes"

Create a doc with initial content (populates the first page)

node query.mjs create-doc "API Documentation" --content "# API Documentation

This document covers the API endpoints and usage.

Overview

..."

### Get Page Content

Get a specific page's content

node query.mjs page abc123def page456

### Create a Page

Create a page with just a title

node query.mjs create-page abc123def "New Section"

Create a page with content

node query.mjs create-page abc123def "Getting Started" --content "# Welcome

This is the getting started guide.

Prerequisites

• Node.js 18+
• npm or yarn"

### Edit a Page

Update page content

node query.mjs edit-page abc123def page456 --content "Updated content here"

Rename a page

node query.mjs edit-page abc123def page456 --name "New Page Name"

Update both content and name

node query.mjs edit-page abc123def page456 --content "New content" --name "New Name"

### Upload Attachments

Upload a single file to a task

node query.mjs attach 86a1b2c3d --attach ./screenshot.png

Upload multiple files

node query.mjs attach 86a1b2c3d --attach ./screenshot1.png --attach ./report.pdf

Post a comment with file attachments (comment first, then files are attached)

node query.mjs comment 86a1b2c3d "Here are the screenshots" --attach ./screenshot.png

Comment with multiple attachments

node query.mjs comment 86a1b2c3d "Design review assets" --attach ./mockup.png --attach ./spec.pdf

**Supported file types**: Images (PNG, JPG, GIF, WebP, SVG), documents (PDF, DOCX, XLSX), archives (ZIP), and any other file type ClickUp accepts.

**Note**: The ClickUp API attaches files to the task itself (visible in the task's attachment list). When using `--attach` with the `comment` command, the comment is posted first and then the files are uploaded as task attachments. They appear in the task but are not embedded inline in the comment text.

### Viewing Attachments in Comments

Comments containing images or file attachments display them inline in plain-text output:

[Feb 11, 2026, 04:55 PM] Justin Maier (id: 90110209630450): Attachment: image.png If you look at the component, you'll see that...

To view the actual image, use `fetch-image` to download it locally:

Download attachment from URL shown in comment output

node query.mjs fetch-image "https://t8459928.p.clickup-attachments.com/t8459928/.../image.png";

→ Downloaded: /tmp/clickup-attachments/image.png

Save to a specific path

node query.mjs fetch-image "https://..."; --output ./screenshot.png

After downloading, use your file viewer or `Read` tool to view the image.

## File-based Content (Recommended)

For any content longer than a sentence, **write to a markdown file first** and use `--file` instead of `--content`. This avoids shell escaping issues and supports proper multi-line markdown.

### Workflow

1. Write your content to a temporary markdown file
2. Pass it with `--file path/to/file.md`
3. Optionally add `--cleanup` to auto-delete the file after success

### Examples

Create a doc from a prepared markdown file

node query.mjs create-doc "Architecture Spec" --file ./docs/spec.md --space 90114072520

Update a page from a file, then auto-delete the temp file

node query.mjs edit-page abc123 page456 --file /tmp/updated-content.md --cleanup

Post a detailed comment from a file

node query.mjs comment 86a1b2c3d --file ./review-notes.md

Set task description from a file

node query.mjs description 86a1b2c3d --file ./task-brief.md

### When to use which

| Approach | When to use |
|----------|-------------|
| `--content "short text"` | One-liners, simple status updates |
| `--file path.md` | Multi-line content, markdown with formatting, specs, documentation |
| `--file path.md --cleanup` | Temporary content (agent writes file, pushes to ClickUp, removes file) |

`--file` works with: `create-doc`, `create-page`, `edit-page`, `comment`, `description`, `create-list`, `update-list`

## Task/List/Space/Doc URL Formats

The skill recognizes these ClickUp URL formats:

**Tasks:**
- `https://app.clickup.com/t/{task_id}`
- `https://app.clickup.com/{team_id}/v/li/{list_id}?p={task_id}`
- Custom task ID: `#DEV-123` or `DEV-123`
- Direct task ID: `86a1b2c3d`

**Lists:**
- `https://app.clickup.com/{team_id}/v/li/{list_id}`
- Direct list ID: `901111220963`

**Spaces:**
- `https://app.clickup.com/{team_id}/v/s/{space_id}`
- Direct space ID: `20128955`

**Docs:**
- `https://app.clickup.com/{team_id}/v/dc/{doc_id}`
- `https://app.clickup.com/{team_id}/docs/{doc_id}`
- Direct doc ID: `abc123def`
## When to Use

**Tasks:**
- **Understanding context**: Get task details before starting work
- **Quick task creation**: Create tasks without leaving your terminal
- **Daily standups**: Use `my-tasks` to see your assignments
- **Status updates**: Post progress comments as you work
- **Task management**: Assign, prioritize, and set due dates
- **Collaboration**: View recent comments for context, add watchers
- **Task organization**: Add tags to categorize tasks
- **Task linking**: Reference task IDs in commit messages
- **Session tracking**: Claim tasks with `claim` so work can be resumed later

**Documents:**
- **Documentation**: Create and maintain project documentation
- **Knowledge base**: Build reference guides and wikis
- **Meeting notes**: Store meeting notes and decisions
- **Specifications**: Write and update technical specs
- **Quick edits**: Update doc content without leaving the terminal
- **Doc collaboration**: Read and reply to doc comments for inline reviews

## Comment Threading Best Practices

When responding to task discussions, **always check for thread context first**:

1. **Before posting a comment**, run `comments <task> --threads` to see existing conversations.
2. **If the user's message or context references a specific comment thread** (e.g., they replied in a thread, or you're continuing a prior conversation), use `reply <comment_id> "text"` to post within that thread — NOT `comment <task> "text"`.
3. **Only use `comment`** (top-level) for genuinely new topics that don't belong in an existing thread.
4. **Rule of thumb**: If you previously posted a comment and someone replied to it in a thread, your next response belongs in that same thread via `reply`.

## Tips

- Team ID, User ID, and other fields are auto-cached in `accounts.json`
- Set `defaultListId` in your account to skip list_id when creating tasks
- Use `my-tasks` for a quick overview of your assignments
- Use natural language dates: "tomorrow", "next friday", "+3d"
- Post comments to keep stakeholders updated on progress
- Include task IDs in commit messages for traceability
- Use `--json` for scripting or piping to other tools
- Doc content uses markdown format for both input and output
- The Docs API uses v3 endpoints (workspace-based instead of team-based)
- Custom task IDs supported: `#DEV-123` or `DEV-123`
- All task/comment queries auto-paginate (no manual page handling needed)
- Rate limiting handled automatically with retry and backoff


## Reference

Less-common material lives in [reference.md](reference.md) — read it when you need it:

- **Output Format** — sample output shapes for tasks, lists, comments, docs, pages
- **Technical Notes** — markdown handling per feature, @mention resolution, doc page structure, pagination
- **Testing** — smoke-test suite
- **Webhook Watchers** — real-time event monitoring via webhook.site + `listen.mjs`
- **Task Watcher (polling)** — dependency-free single-task/list watcher via `watch.mjs`
- **Batch Task Creation** — `batch-create` JSON plan schema and dependency wiring
- **Team Workflow Patterns** — lead/worker/QA/doc-keeper and phase-gate patterns