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 ERR_MODULE_NOT_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

Command	Description
get <url|id>	Get task details (name, description, status, assignees, etc.)
comments <url|id>	List comments on a task (use --threads to expand replies inline)
thread <comment_id>	View threaded replies on a specific comment
reply <comment_id> "message"	Post a threaded reply to a comment
comment <url|id> "message"	Post a comment to a task (supports markdown)
status <url|id> [status]	Update task status (or list available statuses)
tasks <list_id>	List tasks in a list
me	Show current user info
create [list_id] "title"	Create a new task (list_id optional if default set)
my-tasks	List all tasks assigned to you across workspace
search [query]	Search tasks — requires a scope: --list, --folder, --me, --assignee, --status, or --all
find-list "name"	Find a list or folder by name (fast structural walk, no task fetch)
assign <task> <user>	Assign task to a user (by name, email, or ID)
due <task> "date"	Set due date (e.g., "tomorrow", "friday", "+3d")
priority <task> <level>	Set priority (urgent, high, normal, low, none)
subtask <task> "title"	Create a subtask
move <task> <list_id>	Move task to a different list
link <task> <url> ["desc"]	Add external link reference (as comment)
checklist <task> "item"	Add checklist item to task
delete-comment <comment_id>	Delete a comment
watch <task> <user>	Add a user as watcher/follower on a task
tag <task> "tag_name"	Add a tag to task
description <task> "text"	Update task description (markdown supported)
start <task> "date"	Set start date (same date formats as due)
schedule <task> "start" "due"	Set both start and due dates
rename <task> "new name"	Rename a task
depends <task> <other>	Set task as waiting on another task
blocks <task> <other>	Set task as blocking another task
task-link <task> <other>	Create bidirectional link between tasks
update-comment <id> "text"	Update a comment's text
resolve-comment <id>	Resolve/close a comment
remove-tag <task> "tag"	Remove a tag from task
unwatch <task> <user>	Remove a watcher from task
archive <task>	Archive a task (remove from active views)
unarchive <task>	Restore an archived task
claim <task>	Link your session to this task (sets Session ID custom field for resumability)

List Commands

Command	Description
list <list_id>	Get list details (name, statuses, task count)
create-list <space> "name"	Create a new list in a space
update-list <list_id>	Update list properties (--name, --content)
delete-list <list_id>	Delete a list
lists <folder_id>	List all lists in a folder
space-lists <space_id>	List folderless lists in a space

Document Commands

Command	Description
docs ["query"]	Search/list docs in workspace (optional search query)
doc <doc_id>	Get doc details and page listing
create-doc "title"	Create a new doc (use --content for initial content)
page <doc_id> <page_id>	Get page content (markdown format)
create-page <doc_id> "title"	Add a new page to a doc (use --parent for subpages)
edit-page <doc_id> <page_id>	Edit a page's content or name

Attachment Commands

Command	Description
attach <url|id>	Upload file attachment(s) to a task (--attach path, repeatable)
fetch-image <url>	Download a ClickUp attachment to a local temp file (--output path for custom location)

Options

Flag	Description
--json	Output raw JSON response
--threads, -t	Expand threaded replies inline when listing comments
--subtasks	Include subtasks when getting task details
--me	Filter to tasks assigned to me (for tasks command)
--content, -c	Inline content string (markdown). Use for short text only.
--file, -f	Read content from a file path. Preferred for anything longer than a sentence.
--cleanup	Delete the --file after successful execution
--name, -n	New page name for edit-page
--parent, -p	Parent page ID for create-page (creates as subpage)
--space, -s	Space ID for create-doc (places doc in that space)
--assignee, -a	Assignee for task creation
--due, -d	Due date for task creation
--description, --desc	Description for task creation (markdown)
--attach	File path to upload as attachment (repeatable; for attach and comment commands)
--output	Custom output path for fetch-image (default: temp directory)
--account	Use a specific named account (from accounts.json)

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 jane@example.com

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 @[jane@example.com]"

# 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

```bash
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](https://example.com) 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](https://t8459928.p.clickup-attachments.com/...)
  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 — 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