clickup-cli 1.6.0__tar.gz → 1.7.0__tar.gz

clickup_cli-1.7.0/.claude/agents/test-writer.md

@@ -0,0 +1,44 @@
+---
+name: test-writer
+description: Generate tests for clickup-cli commands following the repo's current split test layout and command-fake patterns
+---
+
+# Test Writer Agent
+
+You generate tests for the clickup-cli project.
+
+## Before Writing Tests
+
+1. Read `tests/conftest.py` for the test config setup pattern
+2. Read the relevant split test files in `tests/` for the command family you are changing
+3. Read `tests/command_fakes.py` for shared fake client helpers
+4. Read the source file you're writing tests for
+
+## Conventions
+
+- Use `unittest.TestCase` classes (matching existing style)
+- Use the fake client helpers from `tests/command_fakes.py` (for example `FlexClient`) — do NOT make real HTTP calls
+- Use `unittest.mock.patch` and `MagicMock` for things FakeClient doesn't cover
+- Use `argparse.Namespace` to construct fake args
+- Test these for every command:
+  - Argument parsing (parser accepts the expected args)
+  - `--dry-run` behavior (mutating commands return preview, don't call API)
+  - Normal execution with mocked responses
+  - Error cases (missing required args, API errors)
+- All output assertions should check JSON structure
+- Put tests in the appropriate existing split test file when possible:
+- `tests/test_cli.py` for parser/dispatch behavior
+- `tests/test_command_manifest.py` for manifest wiring
+- `tests/test_tasks_facade.py` for tasks facade/tasks_internal regressions
+- `tests/test_commands_tasks.py`, `tests/test_commands_docs_comments.py`, `tests/test_commands_spaces_lists_folders.py`, or `tests/test_commands_misc.py` for handler coverage
+
+## Example Pattern
+
+```python
+class TestTasksSearch(unittest.TestCase):
+    def test_search_dry_run(self):
+        client = FlexClient(dry_run=True)
+        args = Namespace(query="test", space="testspace", ...)
+        result = cmd_tasks_search(client, args)
+        self.assertIn("dry_run", result)
+```

{clickup_cli-1.6.0 → clickup_cli-1.7.0}/.claude/skills/add-command.md

@@ -11,6 +11,7 @@ Follow these steps in order when adding a new command or subcommand.
 
 - If this is a new command group, create `src/clickup_cli/commands/<group>.py`
 - If extending an existing group, add the handler function to the existing file
+- For `tasks`, keep `src/clickup_cli/commands/tasks.py` as the public facade and put new parser/read/write internals under `src/clickup_cli/commands/tasks_internal/` when appropriate
 - Handler signature: `def cmd_<group>_<command>(client, args):`
 - Return a dict (will be output as JSON)
 - Mutating commands must check `client.dry_run` and return a dry-run preview instead of calling the API
@@ -19,7 +20,7 @@ Follow these steps in order when adding a new command or subcommand.
 
 - Each command module owns its parser via `register_parser(subparsers, F)`
 - If extending an existing group, add the new subparser inside the existing `register_parser()`
-- If creating a new group, add a `register_parser(subparsers, F)` function that creates the group parser and all its subparsers
+- If creating a new group, expose a `COMMAND_MANIFEST` with `group`, `register_parser`, and `handlers`
 - Add the subparser with:
   - `description=` — what this command does
   - `epilog=` — usage examples (at least 2)
@@ -30,14 +31,14 @@ Follow these steps in order when adding a new command or subcommand.
 ## 3. Register the handler
 
 - Open `src/clickup_cli/commands/__init__.py`
-- Import the new handler function
-- Add it to the `HANDLERS` dict with key `"<group>_<command>"`
+- Update the owning module's `COMMAND_MANIFEST["handlers"]`
+- For new command groups, import the group's `COMMAND_MANIFEST` and add it to `COMMAND_MANIFESTS`
+- Do not hand-edit `HANDLERS`; it is derived from the manifests
 
-## 3b. Wire up new command groups in cli.py (new groups only)
+## 3b. Root parser wiring
 
-- If this is a new command group, open `src/clickup_cli/cli.py`
-- Import `register_parser` from the new module
-- Call it in `build_parser()` alongside the other `register_parser()` calls
+- `cli.py` already iterates `COMMAND_MANIFESTS`
+- New groups become available once their manifest is added to `src/clickup_cli/commands/__init__.py`
 
 ## 4. Write help text
 
@@ -47,7 +48,11 @@ Follow these steps in order when adding a new command or subcommand.
 
 ## 5. Add tests
 
-- Open `tests/test_cli.py` (or create a new test file if the group is large)
+- Update the relevant split test module in `tests/`:
+- `tests/test_cli.py` for parser/dispatch behavior
+- `tests/test_command_manifest.py` for manifest wiring changes
+- `tests/test_tasks_facade.py` when changing the tasks facade/tasks_internal split
+- `tests/test_commands_<group>.py` or the nearest shared command-family test file for handler coverage
 - Test argument parsing (parser accepts the new args)
 - Test dry-run behavior (mutating commands return dry-run preview)
 - Test core logic with `FakeClient`
@@ -73,3 +78,4 @@ scripts/validate-cli-output.sh
 ## 7. Update the skill (if needed)
 
 If the new command adds a new workflow pattern, update `.claude/skills/clickup-cli.md` with a usage example.
+Prefer pointing contributors to `README.md` or `CONTRIBUTING.md` instead of duplicating general repo guidance here.

{clickup_cli-1.6.0 → clickup_cli-1.7.0}/.claude/skills/clickup-cli.md

@@ -32,7 +32,7 @@ Global flags (`--pretty`, `--dry-run`, `--debug`) can appear before or after the
 - Successful output is always JSON on stdout
 - Errors go to stderr with non-zero exit code
 - Use `--pretty` for indented JSON when reading output
-- Use `--full` on task list/search for raw API response
+- On `tasks list` and `tasks search`, default output is compact; `--full` returns full task objects, while `--fields` lets you request a smaller custom shape
 
 ## Common Workflows
 
@@ -46,6 +46,7 @@ clickup tasks get <task_id>
 ```bash
 clickup --dry-run tasks create --space <space_name> --name "Fix auth" --desc "Details"
 clickup tasks create --space <space_name> --name "Fix auth" --desc "Details"
+clickup tasks create --list <list_id> --name "Fix auth" --desc "Details"
 ```
 
 ### Update a task (including tags, assignees, custom fields)
@@ -107,21 +108,12 @@ the ClickUp UI. Hits the v3 ACLs endpoint.
 
 ## Configuration
 
-The CLI loads config from (in order):
-1. `CLICKUP_CONFIG_PATH` env var
-2. `~/.config/clickup-cli/config.json`
-3. `clickup-config.json` in current directory
-
-Or use environment variables only:
-- `CLICKUP_API_TOKEN` (required)
-- `CLICKUP_WORKSPACE_ID` (auto-detected for single-workspace accounts)
-
-Run `clickup init` for interactive setup.
+Use `clickup init` for interactive setup. For config file shape, resolution order, and contributor-facing setup notes, prefer `README.md` and `CONTRIBUTING.md` over this repo-local skill.
 
 ## Key Behaviors
 
 - `tasks get` auto-fetches comments (use `--no-comments` to skip)
 - `tasks search` auto-detects task ID patterns (e.g. "PROJ-39") and applies prefix filtering
-- `tasks create` checks for duplicates before creating (use `--skip-dedup` to bypass)
+- `tasks create` accepts `--space` or `--list`; when only `--list` is provided, the CLI auto-infers the matching configured space alias before resolving the target list
 - Tag names are auto-lowercased (ClickUp API requirement)
 - Doc ID ≠ page ID — always use `docs pages` to find page IDs first

{clickup_cli-1.6.0 → clickup_cli-1.7.0}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.7.0 (2026-04-20)
+
+- **Metadata discovery and custom-field lookup are easier to drive from the CLI.** New discovery flows cover field and task-type metadata, and task search can now target custom fields directly instead of forcing clients to pre-resolve everything out of band.
+- **Task creation and task membership operations now match more of ClickUp's native surface area.** `tasks create` gained richer payload parity, task link operations are exposed directly, and multi-list task flows support adding and removing list memberships without leaving the CLI.
+- **Space management reached CRUD parity.** Spaces now support the same create, read, update, and delete coverage already available on other container types, keeping workspace-level automation inside one tool.
+- **Docs and help text were refreshed for agent-first discoverability.** Command help and supporting documentation were tightened so `--help` remains enough to discover the newer workflows without external context.
+
 ## 1.6.0 (2026-04-18)
 
 - **Space-scoped task search and docs filtering now match the requested scope.** `tasks search --space <alias-or-id>` expands to every list in the resolved space, preserves explicit `--list` / `--folder` overrides, handles archived-only and empty-space edge cases without widening scope, and keeps the existing dry-run envelope intact. `docs list` and `docs create` now resolve `--space` through the shared alias-or-raw-ID path and fail fast on bad non-numeric space names.

{clickup_cli-1.6.0 → clickup_cli-1.7.0}/CLAUDE.md

@@ -11,10 +11,15 @@ src/clickup_cli/
 ├── cli.py           # root parser, dispatch, main() — delegates to command modules
 ├── client.py        # ClickUpClient API wrapper (rate limiting, dry-run, debug)
 ├── config.py        # Config loader (lazy, fallback chain, workspace auto-detect)
-├── helpers.py       # output(), error(), compact_task(), etc.
+├── helpers.py       # output(), error(), compact_task(), add_id_argument(), etc.
 └── commands/
-    ├── __init__.py  # HANDLERS dict
-    ├── tasks.py     # tasks parser + handlers (list/get/create/update/search/delete/move/merge/depend)
+    ├── __init__.py  # COMMAND_MANIFESTS registry + derived HANDLERS map
+    ├── tasks.py     # compatibility facade for tasks entrypoints
+    ├── tasks_internal/
+    │   ├── parser.py   # tasks parser registration
+    │   ├── read.py     # list/get/search handlers
+    │   ├── write.py    # create/update/delete/move/merge/depend handlers
+    │   └── shared.py   # task-scoped resolution helpers
     ├── comments.py  # comments parser + handlers (list/add/update/delete/thread/reply)
     ├── docs.py      # docs parser + handlers (list/get/create/pages/get-page/edit-page/create-page)
     ├── folders.py   # folders parser + handlers (list/get/create/update/delete/privacy)
@@ -25,7 +30,7 @@ src/clickup_cli/
     └── init.py      # clickup init setup command
 ```
 
-Each command module owns both its argparse parser definition (`register_parser()`) and its handler functions. `cli.py` builds the root parser and delegates to each module's `register_parser(subparsers, F)`.
+Each command group exposes a `COMMAND_MANIFEST` with `group`, `register_parser`, and `handlers`. `cli.py` builds the root parser by iterating `COMMAND_MANIFESTS`, and `commands/__init__.py` derives the dispatch map from those manifests.
 
 ## Argument Pattern: Positional + Flag Aliases
 
@@ -46,7 +51,7 @@ When adding new commands with ID arguments, always use `add_id_argument()` inste
 
 ## Space Inference
 
-`tasks create` auto-infers `--space` from `--list` via a lazy API lookup (`GET /v2/list/{id}`). The `_infer_space_from_list()` function in tasks.py reverse-maps the space ID to a config name. This eliminates the most common agent error.
+`tasks create` accepts either `--space` or `--list`. If only `--list` is provided, it lazily infers the matching configured space alias from `GET /v2/list/{id}` before resolving the target list.
 
 ## Development Setup
 
@@ -61,15 +66,21 @@ scripts/validate-cli-output.sh   # verify JSON stdout contract
 
 ```
 tests/
-├── conftest.py       # test config setup (runs at import time, before clickup_cli loads)
-├── test_cli.py       # argument parsing, dispatch, global flags, resolve_id_args
-├── test_client.py    # ClickUpClient: rate limiting, dry-run, debug mode, HTTP methods
-├── test_commands.py  # all command handlers: tasks, comments, docs, folders, lists, spaces, tags, team
-├── test_config.py    # config loading: file, env vars, fallback chain, workspace auto-detect
-└── test_helpers.py   # output/error helpers, compact_task, add_id_argument, fetch_all_comments pagination
+├── conftest.py                             # test config setup before clickup_cli loads
+├── command_fakes.py                       # shared fake client helpers for command tests
+├── test_cli.py                            # parser, dispatch, global flags, resolve_id_args
+├── test_client.py                         # ClickUpClient behavior
+├── test_command_manifest.py               # manifest registry + derived handlers
+├── test_commands_tasks.py                 # task command handlers
+├── test_commands_docs_comments.py         # docs/comments handlers
+├── test_commands_spaces_lists_folders.py  # spaces/lists/folders handlers
+├── test_commands_misc.py                  # tags/team/init coverage
+├── test_tasks_facade.py                   # tasks facade -> tasks_internal regression coverage
+├── test_config.py                         # config loading
+└── test_helpers.py                        # helpers and pagination utilities
 ```
 
-305 tests, all using `unittest.TestCase` + `FakeClient` pattern (no real HTTP calls).
+See `README.md` and `CONTRIBUTING.md` for contributor-facing usage and workflow details; keep this file focused on repo-local development conventions.
 
 ## CI
 
@@ -78,13 +89,13 @@ GitHub Actions (`ci.yml`): lint + test on Python 3.9, 3.11, 3.13. Runs on push t
 ## Adding a New Command
 
 1. Create or extend a file in `src/clickup_cli/commands/`
-2. Add the handler function and `register_parser()` in the same module
-3. Register the handler in `commands/__init__.py` HANDLERS dict
-4. If it's a new command group, call `register_parser()` from `cli.py`'s `build_parser()`
+2. Add or update that group's `COMMAND_MANIFEST` (`group`, `register_parser`, `handlers`)
+3. If it's a new command group, import its manifest in `commands/__init__.py` and add it to `COMMAND_MANIFESTS`
+4. For `tasks`, keep the public facade in `commands/tasks.py` and put parser/read/write internals in `commands/tasks_internal/` when extending the split structure
 5. Add detailed `--help` text (description + epilog with examples)
 6. Mutating commands must support `--dry-run`
 7. All output goes to stdout as JSON, errors to stderr
-8. Add tests in `tests/`
+8. Add tests in the relevant split test module under `tests/`
 
 ## Rules
 

clickup_cli-1.7.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,27 @@
+# Code of Conduct
+
+## Our Standard
+
+Participation in this project should stay respectful, constructive, and focused on improving the software.
+
+Examples of expected behavior:
+
+- Be respectful in issues, pull requests, and reviews
+- Assume good intent and discuss technical disagreements directly
+- Share actionable feedback instead of personal attacks
+- Respect privacy and avoid posting secrets or private workspace data
+
+Examples of unacceptable behavior:
+
+- Harassment, discrimination, or intimidation
+- Personal insults or bad-faith escalation
+- Publishing someone else's private information without permission
+- Spamming, trolling, or deliberately derailing project discussions
+
+## Enforcement
+
+Project maintainers may remove, edit, or reject contributions and discussions that do not meet these standards.
+
+## Reporting
+
+If you experience or observe unacceptable behavior, contact the maintainers through the repository's available contact channels.

clickup_cli-1.7.0/CONTRIBUTING.md

@@ -0,0 +1,74 @@
+# Contributing
+
+Thanks for your interest in clickup-cli.
+
+## Getting Started
+
+```bash
+git clone https://github.com/efetoker/clickup-cli.git
+cd clickup-cli
+pip install -e ".[dev]"
+```
+
+## Running Tests
+
+```bash
+pytest -v
+scripts/validate-cli-output.sh
+```
+
+Current suite shape:
+
+- `tests/test_cli.py` — parser, dispatch, global flags, ID alias resolution
+- `tests/test_client.py` — API wrapper behavior, dry-run, debug, retries
+- `tests/test_command_manifest.py` — manifest-derived registration and handlers
+- `tests/test_commands_tasks.py` — task commands and task-specific behavior
+- `tests/test_commands_docs_comments.py` — docs and comments commands
+- `tests/test_commands_spaces_lists_folders.py` — spaces, lists, folders, privacy
+- `tests/test_commands_misc.py` — tags, team, init, misc dispatch coverage
+- `tests/test_config.py` — config loading and fallback rules
+- `tests/test_helpers.py` — stdout/stderr helpers, task formatting, pagination helpers
+- `tests/test_tasks_facade.py` — task facade exports
+
+At the time of writing, `pytest --collect-only -q` collects 397 tests.
+
+## Linting
+
+```bash
+ruff check src/ tests/
+ruff format src/ tests/
+```
+
+## Guidelines
+
+- **JSON stdout, errors to stderr** — all commands follow this convention
+- **Dry-run on mutations** — every mutating command must support `--dry-run`
+- **Help text is documentation** — `--help` should be self-sufficient for discovering usage
+- **No workspace-specific values** — help text and source must not contain hardcoded workspace IDs, space names, or user data
+- **Tests required** — new commands need test coverage in `tests/`
+
+## Adding a New Command
+
+1. Create or extend a file in `src/clickup_cli/commands/`
+2. Keep parser registration and handlers in the same command module, or behind the existing task facade/internal split when working on tasks
+3. Expose a `COMMAND_MANIFEST` from that module and add it to `COMMAND_MANIFESTS` in `src/clickup_cli/commands/__init__.py`
+4. Let the derived `HANDLERS` map pick up handlers from the manifest instead of maintaining a separate manual registry
+5. Use `add_id_argument()` from `helpers.py` for positional ID arguments so both positional and `--flag` forms work
+6. Add self-sufficient `--help` text with examples, return-shape notes, and `--dry-run` guidance for mutating commands
+7. Add or update focused tests in the relevant `tests/test_*.py` file
+
+## Submitting Changes
+
+1. Fork the repo and create a feature branch
+2. Make your changes with tests
+3. Run `pytest -v`, `ruff check src/ tests/`, and `scripts/validate-cli-output.sh`
+4. Open a PR with a clear description of what changed and why
+
+## Maintainer Workflows
+
+- Maintainer release steps live in [RELEASE.md](RELEASE.md)
+- Public support and disclosure docs live in `README.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`, `INTEGRATION.md`, and `TROUBLESHOOTING.md`
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

clickup_cli-1.7.0/FEATURE-GAP-ANALYSIS.md

@@ -0,0 +1,281 @@
+# 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