/clickup:list - List ClickUp Tasks

Purpose

Fetch and display user stories/bugs from ClickUp filtered by status.

Usage

/clickup:list                         # Default: "To Do" tasks
/clickup:list --status "in progress"  # Tasks currently being worked on
/clickup:list --status "to review"    # Tasks ready for review
/clickup:list --all                   # All tasks (all statuses)

Common Status Filters

Behavioral Flow

When this command is invoked:

1. Load Environment: Read ClickUp credentials from the project's .env file:

- CLICKUPTOKEN - API authentication token - CLICKUPLIST_ID - The ClickUp list to fetch tasks from

1. Parse Status Filter:

- Default: To Do - If --status provided, use that status (URL encode spaces as %20)

1. Fetch Tasks: Call ClickUp API with the specified status and format with jq:

```bash # IMPORTANT: # - Always use jq to format output compactly to avoid truncation # - Use subtasks=true to ensure ALL tasks are returned (not just first page) # - The API may paginate results; subtasks=true bypasses this for most cases

# Default (To Do) - formatted output curl -s "https://api.clickup.com/api/v2/list/${CLICKUPLISTID}/task?statuses[]=To%20Do&includeclosed=false&subtasks=true" \ -H "Authorization: ${CLICKUPTOKEN}" | jq -r ' "📋 Tasks Ready for Development (To Do)\n", (.tasks[] | "• [\(.id)] \(if (.tags | map(.name) | contains(["bug"])) then "🐛" elif (.tags | map(.name) | contains(["story"])) then "📖" else " " end) \(.name)"), "", "Found \(.tasks | length) tasks ready for development.", "", "💡 Use: /clickup:process <id> to set up a worktree and start" '

# In Progress - with branch info curl -s "https://api.clickup.com/api/v2/list/${CLICKUPLISTID}/task?statuses[]=in%20progress&includeclosed=false&subtasks=true" \ -H "Authorization: ${CLICKUPTOKEN}" | jq -r ' "📋 Tasks In Progress\n", (.tasks[] | "• [\(.id)] \(if (.tags | map(.name) | contains(["bug"])) then "🐛" elif (.tags | map(.name) | contains(["story"])) then "📖" else " " end) \(.name)\n Branch: \((.custom_fields[] | select(.name == "branch") | .value) // "not set")"), "", "Found \(.tasks | length) tasks in progress.", "", "💡 Use: /clickup:work <id> to spawn a subagent to work on a task", "💡 Use: /clickup:work --all to work on all in-progress tasks", "💡 Use: /clickup:done to complete a task" '

# All statuses - comprehensive view curl -s "https://api.clickup.com/api/v2/list/${CLICKUPLISTID}/task?includeclosed=false&subtasks=true" \ -H "Authorization: ${CLICKUPTOKEN}" | jq -r ' "📋 All Tasks\n", (.tasks[] | "• [\(.id)] \(if (.tags | map(.name) | contains(["bug"])) then "🐛" elif (.tags | map(.name) | contains(["story"])) then "📖" else " " end) [\(.status.status)] \(.name)"), "", "Found \(.tasks | length) total tasks." ' ```

1. Format Output: Display tasks in a formatted table with:

- Task ID (for use with /clickup:process or /clickup:work) - Type (bug or story based on tags) - Priority (Urgent, High, Normal, Low) - Title - Branch (if available, for "In Progress" tasks)

1. Show Next Steps: Context-aware suggestions based on status

Expected Output Format

"To Do" Tasks (Default)

📋 Tasks Ready for Development (To Do)

• [86bqy2f6j] 🐛 Fix payment webhook race condition
• [86bqy3abc] 📖 Add user profile avatar upload
• [def456uvw] 📖 Update dashboard layout for better mobile responsiveness

Found 48 tasks ready for development.

💡 Use: /clickup:process <id> to set up a worktree and start

"In Progress" Tasks

📋 Tasks In Progress

• [86bqy2f6j] 🐛 Fix payment webhook race condition
  Branch: fix/86bqy2f6j-payment-webhook
• [abc123def] 📖 Add user profile feature with avatar upload support
  Branch: feature/abc123def-user-profile

Found 2 tasks in progress.

💡 Use: /clickup:work <id> to spawn a subagent to work on a task
💡 Use: /clickup:work --all to work on all in-progress tasks
💡 Use: /clickup:done to complete a task

All Tasks (--all)

📋 All Tasks

• [86bqy2f6j] 🐛 [in progress] Fix payment webhook race condition
• [86bqy3abc] 📖 [to do] Add user profile avatar upload
• [def456uvw] 📖 [to review] Update dashboard layout for better mobile responsiveness

Found 50 total tasks.

Error Handling

• If CLICKUP_TOKEN is not set: Show error with instructions to set it in .env
• If CLICKUPLISTID is not set: Show error with instructions
• If API call fails: Show error message from ClickUp
• If no tasks found: Show friendly message that no tasks match the filter

Tool Coordination

• Bash: Execute curl commands for ClickUp API calls
• Read: Load .env file to get credentials

ARGUMENTS: $ARGUMENTS