clickup

# ClickUp Skill **Enterprise-grade ClickUp integration for agency workflows.** Manage multiple clients, projects, and workspaces with advanced reporting, automatic subtask handling, and sophisticated folder organization. ## Key Benefits | Feature | Why It Matters | |---------|----------------| | **🔍 Always includes subtasks** | Never miss 70%+ of actual work — subtasks included automatically | | **📊 Advanced reporting** | Task counts, workload distribution, status breakdowns, standup reports | | **🏢 Multi-workspace** | Seamlessly switch between Client Work, Product Development, Personal Projects, and more | | **👥 Client organization** | Structured folders: 📋 Client Overview, 📁 Completed Work, active projects | | **📈 Sales pipeline** | Track proposals, negotiations, and project lifecycles | | **⏱️ Time tracking** | Built-in timers and manual entries with billing support | | **📄 Document management** | Create docs and pages via API v3 | | **🔗 Task relationships** | Dependencies, blocking/waiting, and arbitrary task linking | ## Quick Start ### Setup Set your ClickUp API token: ```bash export CLICKUP_API_TOKEN="pk_your_token_here" ``` Get your token from: ClickUp Settings → Apps → Generate API Token ### Basic Operations **List all workspaces:** ```bash python skills/clickup/scripts/clickup_client.py get_teams ``` **Create a task:** ```bash python skills/clickup/scripts/clickup_client.py create_task list_id="123" name="New Task" status="to do" ``` **Update a task:** ```bash python skills/clickup/scripts/clickup_client.py update_task task_id="abc" status="in progress" ``` ## Workspace Hierarchy ``` Team (Workspace) ├── Spaces │ ├── Folders │ │ └── Lists → Tasks │ └── Lists (Folderless) → Tasks └── Documents ``` All operations require explicit workspace identification via IDs. ## Multi-Workspace Support This skill supports operations across multiple ClickUp workspaces: 1. Use `get_teams` to list available workspaces 2. Reference workspace by `team_id` in operations 3. Each workspace maintains independent spaces, folders, lists 4. Custom task IDs require both `custom_task_ids=true` and `team_id` ## Common Workflows ### Workflow: Create Task in Specific Workspace 1. Get workspace ID: `get_teams` 2. Get target space: `get_spaces team_id="xxx"` 3. Get or create list: `get_folders space_id="yyy"` → `get_lists folder_id="zzz"` 4. Create task: `create_task list_id="aaa" name="Task" ...` ### Workflow: Configure Space Statuses 1. Get space: `get_space space_id="xxx"` 2. Update space with statuses: `update_space space_id="xxx" statuses=[...]` See [API Reference](references/api_reference.md) for status configuration format. ### Workflow: Track Time on Task **Option A - Manual Entry:** ```bash python skills/clickup_client.py create_time_entry \ team_id="xxx" \ task_id="yyy" \ duration=3600000 \ description="Worked on feature" ``` **Option B - Timer:** ```bash # Start timer python skills/clickup/scripts/clickup_client.py start_timer team_id="xxx" task_id="yyy" # Stop timer (stops current running timer for user) python skills/clickup/scripts/clickup_client.py stop_timer team_id="xxx" ``` ### Workflow: Create Document Structure 1. Create doc: `create_doc workspace_id="xxx" name="Project Docs"` 2. Add pages: Use ClickUp UI (pages API is in beta) Note: Documents use ClickUp API v3 (workspace_id instead of team_id). ### Workflow: Reporting & Analytics **Get task counts (with parent/subtask breakdown):** ```bash python skills/clickup/scripts/clickup_client.py task_counts team_id="xxx" # Returns: {"total": 50, "parents": 20, "subtasks": 30, "unassigned": 5} ``` **Get workload by assignee:** ```bash python skills/clickup/scripts/clickup_client.py assignee_breakdown team_id="xxx" # Returns: {"John Doe": 15, "Jane Smith": 12, "Unassigned": 8} ``` **Get tasks by status:** ```bash python skills/clickup/scripts/clickup_client.py status_breakdown team_id="xxx" # Returns: {"to do": 20, "in progress": 10, "complete": 15} ``` **Get tasks by priority:** ```bash python skills/clickup/scripts/clickup_client.py priority_breakdown team_id="xxx" # Returns: {"urgent": 2, "high": 5, "normal": 15, "low": 8, "none": 20} ``` **Daily standup report (grouped by status):** ```bash # All team members python skills/clickup/scripts/clickup_client.py standup_report team_id="xxx" # Specific person (use user ID) python skills/clickup/scripts/clickup_client.py standup_report team_id="xxx" assignee_id="12345" ``` **Get all tasks with pagination (auto-handled):** ```bash python skills/clickup/scripts/clickup_client.py get_all_tasks team_id="xxx" # Always includes subtasks automatically (critical!) ``` **Filter reports by space or assignee:** ```bash # Specific space python skills/clickup/scripts/clickup_client.py task_counts team_id="xxx" space_ids='["SPACE_ID_HERE"]' # Specific assignee python skills/clickup/scripts/clickup_client.py get_all_tasks team_id="xxx" assignees='["12345"]' # Include closed tasks python skills/clickup/scripts/clickup_client.py task_counts team_id="xxx" include_closed="true" ``` **Critical Rules for Reporting:** 1. **Always include subtasks** — Our methods do this automatically via `subtasks=true` 2. **Pagination handled** — `get_all_tasks` loops until all pages retrieved 3. **Parent vs Subtask** — Parents have `parent: null`, subtasks have `parent: "task_id"` 4. **Rate limit** — 100 requests/min; our pagination respects this ### Workflow: Link Doc to Task **Option A - Add as attachment:** ```bash python skills/clickup/scripts/clickup_client.py link_doc_to_task \ task_id="xxx" \ doc_id="yyy" ``` **Option B - Mention in description:** ```bash python skills/clickup/scripts/clickup_client.py mention_doc_in_task \ task_id="xxx" \ doc_id="yyy" ``` Both create clickable links to the document from the task. ### Workflow: Task Dependencies **Set up blocking relationship:** ```bash # Task B is blocked by/waiting on Task A python skills/clickup/scripts/clickup_client.py add_dependency \ task_id="TASK_B_ID" \ depends_on="TASK_A_ID" # Check dependencies python skills/clickup/scripts/clickup_client.py get_dependencies \ task_id="TASK_B_ID" # Remove dependency python skills/clickup/scripts/clickup_client.py remove_dependency \ task_id="TASK_B_ID" \ depends_on="TASK_A_ID" ``` **Set up reverse dependency (task is blocking another):** ```bash # Task A is blocking Task B python skills/clickup/scripts/clickup_client.py add_dependency \ task_id="TASK_A_ID" \ waiting_on="TASK_B_ID" ``` ### Workflow: Link Related Tasks (Non-Dependency) For related tasks that aren't blocking each other: ```bash # Link Task A to Task B (arbitrary relationship) python skills/clickup/scripts/clickup_client.py link_tasks \ task_id="TASK_A_ID" \ links_to="TASK_B_ID" # Remove link python skills/clickup/scripts/clickup_client.py unlink_tasks \ task_id="TASK_A_ID" \ links_to="TASK_B_ID" ``` Note: `link_tasks` creates a "linked task" relationship (appears in task's "Linked Tasks" section), while `add_dependency` creates blocking/waiting relationships. ### Workflow: Bulk Task Operations For bulk operations, loop through tasks: ```bash # Get tasks TASKS=$(python skills/clickup/scripts/clickup_client.py get_tasks list_id="xxx") # Process each (parse JSON and loop) ``` ## Script Reference ### scripts/clickup_client.py Main CLI interface for ClickUp operations. **Usage:** ```bash python scripts/clickup_client.py <command> [key=value ...] ``` **Commands:** #### Workspace Operations - `get_teams` - List all accessible workspaces #### Space Operations - `get_spaces team_id="xxx"` - List spaces - `create_space team_id="xxx" name="Name" [options...]` - Create space - `update_space space_id="xxx" [options...]` - Update space #### Folder Operations - `get_folders space_id="xxx"` - List folders - `create_folder space_id="xxx" name="Name"` - Create folder #### List Operations - `get_lists folder_id="xxx"` - Lists in folder - `get_space_lists space_id="xxx"` - Folderless lists - `create_list folder_id="xxx" name="Name" [options...]` - Create in folder - `create_space_list space_id="xxx" name="Name" [options...]` - Create folderless #### Task Operations - `get_task task_id="xxx"` - Get task details (includes dependencies, linked tasks) - `get_tasks list_id="xxx" [filters...]` - List tasks - `create_task list_id="xxx" name="Name" [options...]` - Create task - `update_task task_id="xxx" [options...]` - Update task #### Time Tracking - `get_time_entries team_id="xxx" [filters...]` - List entries - `create_time_entry team_id="xxx" task_id="yyy" duration=3600000 [...]` - Create entry - `start_timer team_id="xxx" task_id="yyy"` - Start timer - `stop_timer team_id="xxx"` - Stop timer #### Documents (API v3) - `get_docs workspace_id="xxx"` - List documents - `create_doc workspace_id="xxx" name="Name" [options...]` - Create document - `get_doc doc_id="xxx"` - Get document details **Note on Pages:** Doc pages API is in beta. Pages may need to be created via ClickUp UI. #### Doc-Task Linking - `link_doc_to_task task_id="xxx" doc_id="yyy"` - Attach doc URL to task - `mention_doc_in_task task_id="xxx" doc_id="yyy"` - Add doc link to task description #### Task Dependencies (Blocking/Waiting On) - `add_dependency task_id="xxx" depends_on="yyy"` - Task is blocked by/waiting on another task - `add_dependency task_id="xxx" waiting_on="yyy"` - Another task is blocked by/waiting on this task - `remove_dependency task_id="xxx" depends_on="yyy"` - Remove dependency - `get_dependencies task_id="xxx"` - List all dependencies for a task #### Task Linking (Arbitrary Relationships) - `link_tasks task_id="xxx" links_to="yyy"` - Create arbitrary link between tasks - `unlink_tasks task_id="xxx" links_to="yyy"` - Remove task link #### Reporting & Analytics - `get_all_tasks team_id="xxx" [include_closed="true"] [space_ids='["id1"]'] [assignees='["uid1"]']` - All tasks with auto-pagination (always includes subtasks) - `task_counts team_id="xxx" [filters...]` - Count breakdown: total, parents, subtasks, unassigned - `assignee_breakdown team_id="xxx" [filters...]` - Workload distribution by assignee - `status_breakdown team_id="xxx" [filters...]` - Tasks grouped by status - `priority_breakdown team_id="xxx" [filters...]` - Tasks grouped by priority - `standup_report team_id="xxx" [assignee_id="yyy"]` - Daily standup report grouped by status #### Documents - `get_docs team_id="xxx"` - List documents - `create_doc team_id="xxx" name="Name" [options...]` - Create document ## Advanced Configuration ### Custom Fields