clickup

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

---

*Content truncated.*