# ClickUp CLI Feature Gap Analysis

> Historical backlog inventory for public repo readers. This file tracks candidate future work and gap sizing; it is not the active implementation spec for the current selected milestone slice.

> Authority note: use this file for backlog-level gap context. For the currently chosen design slice, see `docs/superpowers/README.md` and the linked spec there.

## Contents

- [Purpose](#purpose)
- [Current repo coverage snapshot](#current-repo-coverage-snapshot)
- [Method / sources](#method--sources)
- [Gaps by area](#gaps-by-area)
- [Final priority summary](#final-priority-summary)
- [Recommended sequencing principles](#recommended-sequencing-principles)
- [Appendix: concise source list](#appendix-concise-source-list)

## Purpose

This document identifies the largest feature gaps between the current `clickup-cli` repository and ClickUp's public API and broader product surface. It is intended to answer one question clearly: what should this repo add next, and which missing areas are confirmed, uncertain, or lower-value right now.

## Current repo coverage snapshot

The repo already covers a solid core developer workflow surface:

- Tasks: `list`, `get`, `create`, `update`, `search`, `delete`, `move`, `merge`, `depend`, linked-task management, multi-list operations
- Comments: task comments only via `list`, `add`, `update`, `delete`, `thread`, `reply`
- Docs/pages: doc list/get/create, page list/get/create/edit
- Hierarchy: spaces/folders/lists CRUD, statuses, privacy toggles
- Metadata/admin-lite: fields, task types, tags, `whoami`, workspace members, bootstrap/init

Depth is strongest in tasks and docs/pages. The CLI already mixes v2 and v3 pragmatically, which is a good foundation for further expansion.

## Method / sources

This assessment combines:

- Local repo command inventory and manifest review
- ClickUp v2 public API coverage review
- ClickUp v3 public API coverage review
- Broader ClickUp product-surface review for areas where user expectations may exceed public API coverage

Priority in this document is a blended judgment based on four factors:

1. User value for a terminal workflow
2. Public API certainty
3. Fit with the current CLI shape
4. Likely implementation complexity and risk

Priority labels should be read this way:

- `High`: high value, high API confidence, strong fit with existing commands
- `Medium`: valuable and likely worth doing, but broader in scope or a bit less certain
- `Low`: niche, admin-heavy, experimental, enterprise-oriented, or not clearly public yet

## Gaps by area

### Task workflows and task-adjacent operations

#### [High] Checklists (`v2`)

Missing today: no checklist or checklist-item commands exist.

Why it matters: this is one of the most CLI-natural task-adjacent features. It adds lightweight decomposition without forcing full subtask workflows.

Suggested surface: `tasks checklist list/create/rename/delete` and `tasks checklist item add/toggle/update/delete`.

Why this is high priority: it is a clean public API surface, highly compatible with existing task commands, and useful immediately.

#### [Medium] Remaining task-create follow-through (`v2`)

Missing today: the main `v1.2` create-parity work shipped, including dates, estimates, points, inline custom fields, and task-type selection. The remaining gap is adjacent create-time setup such as checklist bootstrapping and attachment upload, which still requires follow-up commands or is unsupported.

Why it matters: task creation is one of the CLI's most visible workflows, so the remaining rough edges still show up quickly in real use.

Suggested surface: keep `tasks create` focused, but consider bounded follow-through helpers for checklist setup and attachments where the API shape is clean.

Why this is medium priority: the core parity gap is closed, but there is still room to smooth the create flow around nearby task setup.

#### [Medium] Task attachment upload (`v2`, bounded)

Missing today: no attachment upload support exists.

Why it matters: file upload is a practical workflow for bug reports, exports, screenshots, and logs.

Suggested surface: a narrow first slice such as `tasks attachments upload <task> --file <path>`.

Why this is medium priority: confirmed task upload support appears real and valuable, but broader attachment semantics should not be assumed yet.

#### [Low] Attachment listing and broader attachment coverage (`v3`, validate first)

Missing today: no attachment listing or broader cross-entity attachment support exists.

Why it matters: these could become useful later, especially if docs or other entities are brought deeper into the CLI.

Suggested surface: validate task-level listing first, then only expand if the v3 entity semantics are clean enough to justify it.

Why this is low priority: public support exists in a less settled shape, and this should not be mistaken for a clean v2 parity task.

### Collaboration and discussion

#### [Medium] Comments beyond tasks (`v2`)

Missing today: current comment support is task-only, while v2 also exposes list comments and view/chat-view comments.

Why it matters: this is another asymmetry inside an already-supported domain. It matters for shared list workflows and operational views.

Suggested surface: extend `comments list/add` with entity-explicit options such as `--task`, `--list`, and `--view`, while preserving edit/reply/thread behavior where supported.

Why this is medium priority: it expands an existing command group without introducing a new top-level product area.

#### [Low] Chat (`v3`, experimental)

Missing today: no chat-channel, DM, or chat-message support exists.

Why it matters: the v3 surface is broader than expected and could matter if the CLI evolves into a wider ClickUp power-user tool.

Suggested surface: only consider after the core task/reporting/admin gaps are better covered.

Why this is low priority: the official API is experimental, which makes it a risky foundation for near-term roadmap work.

### Time tracking and execution

#### [High] Time tracking and timers (`v2`, with selective `v3` estimate helpers later)

Missing today: no time-entry, timer, or time-report commands exist.

Why it matters: time tracking is one of ClickUp's most substantial CLI-compatible workflows. It fits developer usage especially well: start/stop timers, add retroactive work, inspect running timers, and export recent entries.

Suggested surface: a top-level `time` command group with `current`, `start`, `stop`, `list`, `add`, `edit`, `delete`, and tag helpers. Later, selectively add v3 task time-estimate helpers if they improve the UX.

Why this is high priority: it is a large but very high-value public API surface with strong CLI ergonomics.

### Hierarchy, planning, and reporting

#### [Medium] Views and saved-query workflows (`v2`)

Missing today: no command group exists for views, despite public list/board/calendar/gantt view support and view-task retrieval.

Why it matters: views are probably the public API's strongest reporting/query surface and the best CLI substitute for some dashboard-like needs.

Suggested surface: `views list/get/create/update/delete` and `views tasks <view>`.

Why this is medium priority: valuable and public, but broad enough that it deserves a deliberate command design rather than a quick parity patch.

#### [Medium] Goals and key results (`v2`)

Missing today: no goals or key-result support exists.

Why it matters: goals are a real ClickUp planning surface and appear in event/webhook concepts as well.

Suggested surface: `goals list/get/create/update/delete`, key-result commands, and compact progress summaries.

Why this is medium priority: useful, but slightly less foundational than task, time, and view workflows.

#### [Medium] Template discovery and application (`v2`)

Missing today: no first-class template workflows exist.

Why it matters: templates are a natural planning and bootstrap surface, especially once the CLI supports richer task, list, or workflow setup.

Suggested surface: start with read-only discovery and application flows before attempting broader template lifecycle management.

Why this is medium priority: important, but likely easier to justify after the primary task workflow gaps are closed.

### Automation and integrations

#### [Medium] Webhooks (`v2`)

Missing today: no webhook management support exists.

Why it matters: webhooks are the clearest public automation surface in ClickUp and unlock event-driven integrations even if full automation-rule CRUD remains unavailable.

Suggested surface: `webhooks list/create/update/delete`, with scope and event-selection helpers.

Why this is medium priority: high leverage for automation users, but slightly more specialized than core task and time parity work.

#### [Low] Full automation-rule management (`non-public/unclear`)

Missing today: no automation management support exists.

Why it matters: users may expect it because ClickUp markets automations heavily.

Suggested surface: do not plan this as a confirmed feature yet. Treat webhooks as the public-API automation proxy unless official automation CRUD becomes clearly available.

Why this is low priority: public API coverage was not clearly confirmed.

### Admin, identity, and governance

#### [Low] Broader identity/admin surface (`v2`)

Missing today: current support stops at `whoami` and workspace members. There is no groups, guests, roles, shared hierarchy, plan, or seats coverage.

Why it matters: these are real public API capabilities for admin-heavy environments.

Suggested surface: `team plan`, `team seats`, `groups ...`, `guests ...`, and related sharing inspection commands.

Why this is low priority: real surface area, but not the highest day-to-day value for the repo's current direction.

#### [Low] Granular ACL/share management (`v3`, partially understood)

Missing today: the CLI exposes boolean privacy toggles only.

Why it matters: the v3 ACL endpoint appears much broader and may eventually enable richer sharing workflows.

Suggested surface: validate semantics and billing/plan behavior before planning user/group grant commands.

Why this is low priority: the surface is promising but still not well understood enough for early roadmap commitment.

#### [Low] Audit logs (`v3`, enterprise/admin)

Missing today: no audit-log support exists.

Why it matters: useful for enterprise/admin inspection workflows.

Suggested surface: treat as a later admin-oriented reporting feature.

Why this is low priority: it is narrow, enterprise-facing, and not central to general CLI adoption.

## Product areas that are real, but not strong roadmap bets yet

### [Low] Dashboards (`non-public/unclear`)

Dashboards are clearly important in the product, but public dashboard object management was not confirmed in the API materials reviewed. Do not plan dashboard CRUD until public coverage is verified.

### [Low] Forms (`non-public/unclear`)

Forms matter in real ClickUp workflows, but public forms CRUD was not confirmed. Downstream support through tasks, views, and automation-style workflows is a better near-term bet.

### [Low] Whiteboards (`non-public/likely unsupported publicly`)

Whiteboards exist as a product area, but the docs reviewed indicate page views such as whiteboards are not part of the public API surface. This should stay out of active planning unless the API changes.

### [Low] Docs/page parity limitations (`v3`, public but incomplete)

The repo already covers most of the public docs/page surface. Remaining gaps such as doc rename/delete and page delete appear to be public API limitations rather than repo omissions.

## Final priority summary

### High priority

1. Checklists
2. Time tracking and timers

### Medium priority

1. Remaining task-create follow-through
2. Task attachment upload
3. Comments beyond tasks
4. Views and saved-query workflows
5. Goals and key results
6. Template discovery and application
7. Webhooks

### Low priority or validate-first

1. Attachment listing and broader attachment coverage
2. Chat
3. Full automation-rule management
4. Broader identity/admin surface
5. Granular ACL/share management
6. Audit logs
7. Dashboards
8. Forms
9. Whiteboards
10. Docs/page delete or rename parity that appears limited by the public API itself

## Recommended sequencing principles

1. Finish the biggest task-surface asymmetries before expanding into unrelated top-level domains.
2. Prefer public-API certainty over product-surface temptation.
3. Bias toward features that improve daily CLI workflows first: task creation, task decomposition, search/filtering, time, and saved-query/reporting.
4. Keep early expansions bounded. A narrow upload command or read-only template discovery is better than an oversized first cut.
5. Treat experimental or enterprise-heavy surfaces as explicit later-phase work, not hidden scope creep.
6. Where v2 and v3 overlap, prefer the narrower and better-documented path unless v3 clearly unlocks better behavior.

## Appendix: concise source list

- Local repo inventory: `README.md`, `CLAUDE.md`, `src/clickup_cli/commands/*.py`, `src/clickup_cli/commands/__init__.py`
- ClickUp developer docs: `developer.clickup.com/docs/tasks`, `docs/comments`, `docs/customfields`, `docs/views`, `docs/webhooks`, `docs/chat`, `docs/general-v2-v3-api`, `docs/move-a-task-to-a-new-list`, `docs/docsimportexportlimitations`
- ClickUp OpenAPI specs: `developer.clickup.com/openapi/clickup-api-v2-reference.json`, `developer.clickup.com/openapi/ClickUp_PUBLIC_API_V3.yaml`
- ClickUp product pages reviewed for expectation-setting: automations, dashboards, goals, forms, project time tracking, chat, whiteboards
