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

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

@@ -1,5 +1,14 @@
 # Changelog
 
+## Unreleased
+
+## 1.8.0 (2026-04-26)
+
+- **Task output shaping and tagging workflows expanded.** `tasks get` now accepts `--fields` and `--full` alongside comment hydration flags, and `tasks create` supports repeatable `--tag` values applied after creation.
+- **Migration and safety workflows are broader.** New `tasks bulk move` and `tasks bulk tags` commands provide dry-run-friendly bulk operations with resume-oriented failure output, while `lists backup`, `folders backup`, enriched delete dry-runs, and `folders purge-empty` add safer hierarchy cleanup paths.
+- **Space tag management is now first-class.** `tags create`, `tags delete`, and `tags usage` cover Space-level tag lifecycle and usage auditing, including archived-list coverage fixes.
+- **API resilience and destructive safety were tightened.** Safe GET requests retry transient 502/503/504 responses without changing 429 behavior, and bulk/tag/destructive validation now rejects unsafe or empty plans earlier.
+
 ## 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.

{clickup_cli-1.7.0 → clickup_cli-1.8.0}/FEATURE-GAP-ANALYSIS.md

@@ -22,11 +22,11 @@ This document identifies the largest feature gaps between the current `clickup-c
 
 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
+- Tasks: `list`, `get`, `create`, `update`, `search`, `delete`, `move`, `merge`, `bulk`, `depend`, linked-task management, multi-list operations, output shaping, create-time tags
 - 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
+- Hierarchy: spaces/folders/lists CRUD, statuses, privacy toggles, local backups, guarded empty-folder purge
+- Metadata/admin-lite: fields, task types, Space tag lifecycle and usage audit, task tag add/remove, `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.
 

{clickup_cli-1.7.0 → clickup_cli-1.8.0}/INTEGRATION.md

@@ -12,8 +12,8 @@
 ## Output Modes
 
 - Default task list and search output is compact
-- `--fields` returns only the requested fields
-- `--full` returns full task objects with normalized status metadata
+- `--fields` returns only the requested fields on task list/search/get flows
+- `--full` returns full task objects with normalized status metadata where applicable
 
 ## Bounded Defaults
 
@@ -32,4 +32,9 @@
 
 - Validate response metadata instead of assuming a default scan is exhaustive
 - Use `--dry-run` before automating mutations in a new environment
+- Use `tasks bulk ...` and backup commands for migration workflows that need resumable failure output or local JSON snapshots
 - Treat doc IDs and page IDs as different values
+
+## Reliability
+
+- Safe GET requests retry transient 502/503/504 responses; 429 rate-limit handling remains explicit and separate

{clickup_cli-1.7.0 → clickup_cli-1.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clickup-cli
-Version: 1.7.0
+Version: 1.8.0
 Summary: The missing ClickUp CLI. Built for developers and AI agents.
 Project-URL: Homepage, https://github.com/efetoker/clickup-cli
 Project-URL: Repository, https://github.com/efetoker/clickup-cli
@@ -111,15 +111,15 @@ Output is JSON on stdout; errors go to stderr.
 | Group | Subcommands | Description |
 |-------|-------------|-------------|
 | `init` | — | Interactive workspace setup |
-| `tasks` | list, get, create, update, search, delete, move, merge, lists, add-to-list, remove-from-list, depend, link | Full task CRUD + memberships, links, and dependencies |
+| `tasks` | list, get, create, update, search, delete, move, merge, bulk, lists, add-to-list, remove-from-list, depend, link | Full task CRUD + memberships, links, dependencies, and migration-safe bulk operations |
 | `comments` | list, add, update, delete, thread, reply | Full comment CRUD with threading |
 | `docs` | list, get, create, pages, get-page, edit-page, create-page | Docs and page management |
 | `fields` | list | Custom field discovery for list or space scope |
-| `folders` | list, get, create, update, delete, privacy | Folder CRUD + privacy toggle |
-| `lists` | list, get, create, update, delete, privacy | List CRUD + privacy toggle |
+| `folders` | list, get, create, update, delete, backup, purge-empty, privacy | Folder CRUD + backups, guarded empty-folder purge, and privacy toggle |
+| `lists` | list, get, create, update, delete, backup, privacy | List CRUD + backups and privacy toggle |
 | `spaces` | list, get, create, update, delete, statuses, privacy | Full space CRUD + statuses + privacy toggle |
 | `team` | whoami, members | Workspace and member info |
-| `tags` | list, add, remove | Tag management |
+| `tags` | list, create, delete, usage, add, remove | Space tag lifecycle, usage audit, and task tag management |
 | `task-types` | list | Workspace custom task type discovery |
 
 Use `clickup <group> <command> --help` for detailed usage, examples, and return format.
@@ -144,7 +144,7 @@ clickup tasks list --space <name> --pretty
 
 - **Flag aliases** — every positional argument also accepts a `--flag` form. `tasks get abc123` and `tasks get --task-id abc123` are equivalent. Same for `--query`, `--doc-id`, `--page-id`, `--folder-id`, `--list-id`, `--comment-id`, `--space`.
 - **Raw numeric IDs** on `--space` and `--folder` flags are accepted transparently alongside config aliases. On tasks commands, list-bound commands may resolve a raw space ID to its first folderless list via one API call.
-- **`tasks create`** auto-infers `--space` from `--list` via API lookup. You can omit `--space` if `--list` is provided, and create also supports start/due dates, time estimates, points, repeatable `--custom-field` values, and `--task-type`.
+- **`tasks create`** auto-infers `--space` from `--list` via API lookup. You can omit `--space` if `--list` is provided, and create also supports start/due dates, time estimates, points, repeatable `--custom-field` values, repeatable `--tag` values, and `--task-type`.
 - **`tasks update`** handles core fields, assignee diffs (`--add-assignee` / `--remove-assignee`), tag diffs (`--add-tag` / `--remove-tag`), and custom fields (`--custom-field FIELD_ID=VALUE`) in one call. All flags are repeatable; `--dry-run` returns a structured plan.
 - **`tasks lists` / `tasks add-to-list` / `tasks remove-from-list`** let you inspect and manage multi-list task membership separately from home-list moves.
 - **`tasks link`** manages non-blocking linked-task relationships; use `tasks depend` for blocking dependencies.
@@ -153,8 +153,12 @@ clickup tasks list --space <name> --pretty
 - **`tasks list` / `tasks search --include-archived`** — second paginated call with `archived=true`, merged into the default results. Since ClickUp's `archived` param is a filter, this is the only way to see both in one command.
 - **`tasks list` / `tasks search` bounded defaults** — by default, these commands fetch a bounded aggregate scan and return `pages_fetched`, `results_complete`, and `results_truncated`. Use `--all-pages` for an exhaustive scan.
 - **`tasks list --full` / `tasks search --full`** return full task objects with a normalized `status` dict shape (`{status, color, type, orderindex}`), not just the compact projection.
-- **`tasks get`** auto-fetches comments and appends them to the output. By default this is a bounded slice and the response includes `comment_count_returned`, `comments_complete`, and `comments_truncated`. Use `--all-comments` for exhaustive comment hydration or `--no-comments` to skip it.
+- **`tasks get`** auto-fetches comments and appends them to the output. By default this is a bounded slice and the response includes `comment_count_returned`, `comments_complete`, and `comments_truncated`. Use `--fields` to select specific task fields, `--full` to request the full task payload explicitly, `--all-comments` for exhaustive comment hydration, or `--no-comments` to skip it.
 - **`tasks search`** auto-detects task ID patterns like `PROJ-39` and applies prefix filtering.
+- **`tasks bulk move` / `tasks bulk tags`** provide dry-run-friendly batch migration flows with resume-oriented failure details.
+- **`lists backup` / `folders backup`** write local JSON backups with safety-first defaults before migration or deletion; `folders purge-empty` only deletes after exhaustive empty-folder proof.
+- **Space tag lifecycle** — `tags create`, `tags delete`, and `tags usage` manage and audit Space-level tags; task-level `tags add` / `tags remove` remain available.
+- **GET retries** — transient ClickUp 502/503/504 responses are retried only for safe GET requests; 429 rate-limit handling remains separate.
 - **`docs edit-page --append`** reads the current page content, appends your new content, and sends one update.
 - **Tag names** are auto-lowercased (ClickUp API stores them lowercase regardless of UI display).
 - **Doc ID ≠ page ID.** Always use `docs pages <doc_id>` to discover page IDs before using `get-page` or `edit-page`.

{clickup_cli-1.7.0 → clickup_cli-1.8.0}/README.md

@@ -79,15 +79,15 @@ Output is JSON on stdout; errors go to stderr.
 | Group | Subcommands | Description |
 |-------|-------------|-------------|
 | `init` | — | Interactive workspace setup |
-| `tasks` | list, get, create, update, search, delete, move, merge, lists, add-to-list, remove-from-list, depend, link | Full task CRUD + memberships, links, and dependencies |
+| `tasks` | list, get, create, update, search, delete, move, merge, bulk, lists, add-to-list, remove-from-list, depend, link | Full task CRUD + memberships, links, dependencies, and migration-safe bulk operations |
 | `comments` | list, add, update, delete, thread, reply | Full comment CRUD with threading |
 | `docs` | list, get, create, pages, get-page, edit-page, create-page | Docs and page management |
 | `fields` | list | Custom field discovery for list or space scope |
-| `folders` | list, get, create, update, delete, privacy | Folder CRUD + privacy toggle |
-| `lists` | list, get, create, update, delete, privacy | List CRUD + privacy toggle |
+| `folders` | list, get, create, update, delete, backup, purge-empty, privacy | Folder CRUD + backups, guarded empty-folder purge, and privacy toggle |
+| `lists` | list, get, create, update, delete, backup, privacy | List CRUD + backups and privacy toggle |
 | `spaces` | list, get, create, update, delete, statuses, privacy | Full space CRUD + statuses + privacy toggle |
 | `team` | whoami, members | Workspace and member info |
-| `tags` | list, add, remove | Tag management |
+| `tags` | list, create, delete, usage, add, remove | Space tag lifecycle, usage audit, and task tag management |
 | `task-types` | list | Workspace custom task type discovery |
 
 Use `clickup <group> <command> --help` for detailed usage, examples, and return format.
@@ -112,7 +112,7 @@ clickup tasks list --space <name> --pretty
 
 - **Flag aliases** — every positional argument also accepts a `--flag` form. `tasks get abc123` and `tasks get --task-id abc123` are equivalent. Same for `--query`, `--doc-id`, `--page-id`, `--folder-id`, `--list-id`, `--comment-id`, `--space`.
 - **Raw numeric IDs** on `--space` and `--folder` flags are accepted transparently alongside config aliases. On tasks commands, list-bound commands may resolve a raw space ID to its first folderless list via one API call.
-- **`tasks create`** auto-infers `--space` from `--list` via API lookup. You can omit `--space` if `--list` is provided, and create also supports start/due dates, time estimates, points, repeatable `--custom-field` values, and `--task-type`.
+- **`tasks create`** auto-infers `--space` from `--list` via API lookup. You can omit `--space` if `--list` is provided, and create also supports start/due dates, time estimates, points, repeatable `--custom-field` values, repeatable `--tag` values, and `--task-type`.
 - **`tasks update`** handles core fields, assignee diffs (`--add-assignee` / `--remove-assignee`), tag diffs (`--add-tag` / `--remove-tag`), and custom fields (`--custom-field FIELD_ID=VALUE`) in one call. All flags are repeatable; `--dry-run` returns a structured plan.
 - **`tasks lists` / `tasks add-to-list` / `tasks remove-from-list`** let you inspect and manage multi-list task membership separately from home-list moves.
 - **`tasks link`** manages non-blocking linked-task relationships; use `tasks depend` for blocking dependencies.
@@ -121,8 +121,12 @@ clickup tasks list --space <name> --pretty
 - **`tasks list` / `tasks search --include-archived`** — second paginated call with `archived=true`, merged into the default results. Since ClickUp's `archived` param is a filter, this is the only way to see both in one command.
 - **`tasks list` / `tasks search` bounded defaults** — by default, these commands fetch a bounded aggregate scan and return `pages_fetched`, `results_complete`, and `results_truncated`. Use `--all-pages` for an exhaustive scan.
 - **`tasks list --full` / `tasks search --full`** return full task objects with a normalized `status` dict shape (`{status, color, type, orderindex}`), not just the compact projection.
-- **`tasks get`** auto-fetches comments and appends them to the output. By default this is a bounded slice and the response includes `comment_count_returned`, `comments_complete`, and `comments_truncated`. Use `--all-comments` for exhaustive comment hydration or `--no-comments` to skip it.
+- **`tasks get`** auto-fetches comments and appends them to the output. By default this is a bounded slice and the response includes `comment_count_returned`, `comments_complete`, and `comments_truncated`. Use `--fields` to select specific task fields, `--full` to request the full task payload explicitly, `--all-comments` for exhaustive comment hydration, or `--no-comments` to skip it.
 - **`tasks search`** auto-detects task ID patterns like `PROJ-39` and applies prefix filtering.
+- **`tasks bulk move` / `tasks bulk tags`** provide dry-run-friendly batch migration flows with resume-oriented failure details.
+- **`lists backup` / `folders backup`** write local JSON backups with safety-first defaults before migration or deletion; `folders purge-empty` only deletes after exhaustive empty-folder proof.
+- **Space tag lifecycle** — `tags create`, `tags delete`, and `tags usage` manage and audit Space-level tags; task-level `tags add` / `tags remove` remain available.
+- **GET retries** — transient ClickUp 502/503/504 responses are retried only for safe GET requests; 429 rate-limit handling remains separate.
 - **`docs edit-page --append`** reads the current page content, appends your new content, and sends one update.
 - **Tag names** are auto-lowercased (ClickUp API stores them lowercase regardless of UI display).
 - **Doc ID ≠ page ID.** Always use `docs pages <doc_id>` to discover page IDs before using `get-page` or `edit-page`.

{clickup_cli-1.7.0 → clickup_cli-1.8.0}/src/clickup_cli/__init__.py

@@ -1,3 +1,3 @@
 """ClickUp CLI — the missing ClickUp CLI for developers and AI agents."""
 
-__version__ = "1.7.0"
+__version__ = "1.8.0"

{clickup_cli-1.7.0 → clickup_cli-1.8.0}/src/clickup_cli/client.py

@@ -13,6 +13,10 @@ from .runtime import RuntimeContext
 class ClickUpClient:
     BASE_V2 = "https://api.clickup.com/api/v2"
     BASE_V3 = "https://api.clickup.com/api/v3"
+    TRANSIENT_RETRY_STATUSES = {502, 503, 504}
+    TRANSIENT_RETRY_METHODS = {"GET"}
+    TRANSIENT_RETRY_ATTEMPTS = 3
+    TRANSIENT_RETRY_BACKOFF_SECONDS = 0.25
 
     def __init__(self, token, dry_run=False, debug=False, runtime=None):
         self.token = token
@@ -72,6 +76,21 @@ class ClickUpClient:
                 time.sleep(wait)
                 response = _do_request()
 
+        attempt = 1
+        while (
+            method in self.TRANSIENT_RETRY_METHODS
+            and response.status_code in self.TRANSIENT_RETRY_STATUSES
+            and attempt < self.TRANSIENT_RETRY_ATTEMPTS
+        ):
+            attempt += 1
+            self._log(
+                f"  retrying transient {response.status_code} "
+                f"(attempt {attempt}/{self.TRANSIENT_RETRY_ATTEMPTS})"
+            )
+            time.sleep(self.TRANSIENT_RETRY_BACKOFF_SECONDS)
+            response = _do_request()
+            self._log(f"  → {response.status_code} ({len(response.text)} bytes)")
+
         if response.status_code == 401:
             error(
                 "Authentication failed — check your API token"

clickup_cli-1.8.0/src/clickup_cli/commands/backup.py

@@ -0,0 +1,162 @@
+"""Shared backup and destructive-safety helpers for list/folder commands."""
+
+import json
+from pathlib import Path
+
+from ..helpers import fetch_all_comments
+
+
+def backup_options(args):
+    """Return safety-first backup options from argparse flags."""
+    return {
+        "include_closed": not getattr(args, "no_closed", False),
+        "include_archived": not getattr(args, "no_archived", False),
+        "subtasks": not getattr(args, "no_subtasks", False),
+        "all_pages": not getattr(args, "first_page", False),
+        "comments": not getattr(args, "no_comments", False),
+    }
+
+
+def scan_list_tasks(client, list_id, options):
+    """Scan task summaries for a list using explicit completeness metadata."""
+    tasks = []
+    pages_fetched = 0
+    complete = True
+    passes = [{"archived": "false"}]
+    if options["include_archived"]:
+        passes.append({"archived": "true"})
+
+    for pass_params in passes:
+        page = 0
+        while True:
+            params = dict(pass_params)
+            params["page"] = str(page)
+            if options["include_closed"]:
+                params["include_closed"] = "true"
+            if options["subtasks"]:
+                params["subtasks"] = "true"
+
+            response = client.get_v2(
+                f"/list/{list_id}/task", params=params, allow_dry_run=True
+            )
+            pages_fetched += 1
+            tasks.extend(response.get("tasks", []))
+
+            if response.get("last_page", False):
+                break
+            if not options["all_pages"]:
+                complete = False
+                break
+            page += 1
+
+    deduped = list({task.get("id"): task for task in tasks if task.get("id")}.values())
+    return {
+        "tasks": deduped,
+        "task_ids": [task["id"] for task in deduped],
+        "count": len(deduped),
+        "pages_fetched": pages_fetched,
+        "complete": complete,
+    }
+
+
+def count_list_tasks(client, list_id):
+    """Count all active, closed, archived, and subtask items for safety checks."""
+    options = {
+        "include_closed": True,
+        "include_archived": True,
+        "subtasks": True,
+        "all_pages": True,
+        "comments": False,
+    }
+    scan = scan_list_tasks(client, list_id, options)
+    return {
+        "total": scan["count"],
+        "task_ids": scan["task_ids"],
+        "pages_fetched": scan["pages_fetched"],
+        "complete": scan["complete"],
+    }
+
+
+def write_json(path, payload):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n")
+
+
+def backup_list(client, list_id, output_dir, options, *, prefix=""):
+    """Write a deterministic backup for one list and return manifest details."""
+    root = Path(output_dir)
+    list_meta = client.get_v2(f"/list/{list_id}", allow_dry_run=True)
+    scan = scan_list_tasks(client, list_id, options)
+
+    files = []
+    list_file = root / "list.json"
+    tasks_file = root / "tasks.json"
+    write_json(list_file, list_meta)
+    write_json(tasks_file, scan["tasks"])
+    files.extend([f"{prefix}list.json", f"{prefix}tasks.json"])
+
+    comments_complete = True
+    for task_id in scan["task_ids"]:
+        task = client.get_v2(f"/task/{task_id}", allow_dry_run=True)
+        if options["comments"]:
+            comment_result = fetch_all_comments(client, task_id, all_pages=True)
+            task["comments"] = comment_result["comments"]
+            task["comments_complete"] = comment_result["complete"]
+            comments_complete = comments_complete and comment_result["complete"]
+        task_file = root / "tasks" / f"{task_id}.json"
+        write_json(task_file, task)
+        files.append(f"{prefix}tasks/{task_id}.json")
+
+    manifest = {
+        "type": "list_backup",
+        "list_id": list_id,
+        "task_ids": scan["task_ids"],
+        "task_count": scan["count"],
+        "options": options,
+        "complete": scan["complete"] and comments_complete,
+        "tasks_complete": scan["complete"],
+        "comments_complete": comments_complete,
+        "pages_fetched": scan["pages_fetched"],
+        "files": files,
+    }
+    write_json(root / "manifest.json", manifest)
+    return manifest
+
+
+def count_folder_tasks(client, folder):
+    """Count all tasks in every child list included by folder metadata."""
+    list_counts = []
+    total = 0
+    task_ids = []
+    complete = True
+    pages_fetched = 0
+    for child_list in folder_child_lists(client, folder, include_archived=True):
+        count = count_list_tasks(client, child_list["id"])
+        list_counts.append({"list_id": child_list["id"], **count})
+        total += count["total"]
+        task_ids.extend(count["task_ids"])
+        complete = complete and count["complete"]
+        pages_fetched += count["pages_fetched"]
+    return {
+        "total": total,
+        "task_ids": task_ids,
+        "lists": list_counts,
+        "pages_fetched": pages_fetched,
+        "complete": complete,
+    }
+
+
+def folder_child_lists(client, folder, include_archived=False):
+    """Return folder child lists, optionally adding archived lists not in metadata."""
+    child_lists = list(folder.get("lists", []))
+    if include_archived and folder.get("id"):
+        archived_response = client.get_v2(
+            f"/folder/{folder['id']}/list",
+            params={"archived": "true"},
+            allow_dry_run=True,
+        )
+        child_lists.extend(archived_response.get("lists", []))
+    deduped = {}
+    for child_list in child_lists:
+        deduped.setdefault(child_list["id"], child_list)
+    return list(deduped.values())

{clickup_cli-1.7.0 → clickup_cli-1.8.0}/src/clickup_cli/commands/folders.py

@@ -1,6 +1,7 @@
 """Folder command handlers — list, get, create, update, delete, privacy."""
 
 from ..helpers import error, resolve_space_id, add_id_argument
+from .backup import backup_list, backup_options, count_folder_tasks, folder_child_lists, write_json
 from .privacy import handle_privacy_request, register_privacy_subcommand
 
 
@@ -22,6 +23,8 @@ Subcommands:
   create   — create a new folder in a space (mutating)
   update   — update a folder's name (mutating)
   delete   — delete a folder (destructive)
+  backup   — export folder/list metadata and tasks to local JSON files
+  purge-empty — delete only if exhaustive scans prove the folder is empty
   privacy  — make a folder private or public (mutating)
 
 Does not cover: reordering folders or setting folder-level statuses
@@ -158,6 +161,54 @@ examples:
     )
     add_id_argument(fd, "folder_id", "ClickUp folder ID to delete")
 
+    fb = folders_sub.add_parser(
+        "backup",
+        formatter_class=F,
+        help="Back up a folder and child lists to local JSON files",
+        description="""\
+Back up a folder before migration or deletion. Writes folder metadata,
+per-list backups, per-task full JSON, and a deterministic manifest.json to
+--output-dir.
+
+Defaults are safety-first: include closed tasks, archived tasks, subtasks,
+all task pages, and all comments unless explicitly disabled.""",
+        epilog="""\
+returns:
+  {"status": "ok", "action": "backup_folder", "folder_id": "...", ...}
+
+examples:
+  clickup folders backup 12345 --output-dir ./backup/folder-12345
+  clickup folders backup --folder-id 12345 --output-dir ./backup --no-comments
+
+notes:
+  This command writes local files and does not mutate ClickUp.""",
+    )
+    add_id_argument(fb, "folder_id", "ClickUp folder ID to back up")
+    fb.add_argument("--output-dir", required=True, help="Directory for backup JSON files")
+    fb.add_argument("--no-closed", action="store_true", help="Do not include closed tasks")
+    fb.add_argument("--no-archived", action="store_true", help="Do not include archived tasks")
+    fb.add_argument("--no-subtasks", action="store_true", help="Do not include subtasks")
+    fb.add_argument("--first-page", action="store_true", help="Only fetch the first task page")
+    fb.add_argument("--no-comments", action="store_true", help="Do not hydrate task comments")
+
+    fpe = folders_sub.add_parser(
+        "purge-empty",
+        formatter_class=F,
+        help="Delete a folder only after proving every child list is empty",
+        description="""\
+Exhaustively scans every child list for active, closed, archived, and subtask
+items. The folder is deleted only when all scans are complete and zero tasks
+are found. Use --dry-run to preview the proof without deleting.""",
+        epilog="""\
+returns:
+  {"status": "ok", "action": "purged_empty_folder", "folder_id": "..."}
+
+examples:
+  clickup --dry-run folders purge-empty 12345
+  clickup folders purge-empty 12345""",
+    )
+    add_id_argument(fpe, "folder_id", "ClickUp folder ID to purge if empty")
+
     register_privacy_subcommand(
         folders_sub,
         F,
@@ -230,12 +281,98 @@ def cmd_folders_update(client, args):
 def cmd_folders_delete(client, args):
     """Delete a folder by ID."""
     if client.dry_run:
-        return {"dry_run": True, "action": "delete_folder", "folder_id": args.folder_id}
+        folder = client.get_v2(f"/folder/{args.folder_id}", allow_dry_run=True)
+        task_counts = count_folder_tasks(client, folder)
+        return {
+            "dry_run": True,
+            "action": "delete_folder",
+            "folder_id": args.folder_id,
+            "folder": folder,
+            "lists": folder.get("lists", []),
+            "task_counts": task_counts,
+        }
 
     client.delete_v2(f"/folder/{args.folder_id}")
     return {"status": "ok", "action": "deleted", "folder_id": args.folder_id}
 
 
+def cmd_folders_backup(client, args):
+    """Back up a folder and its child lists to local JSON files."""
+    from pathlib import Path
+
+    root = Path(args.output_dir)
+    options = backup_options(args)
+    folder = client.get_v2(f"/folder/{args.folder_id}", allow_dry_run=True)
+    write_json(root / "folder.json", folder)
+
+    files = ["folder.json"]
+    list_ids = []
+    task_ids = []
+    task_count = 0
+    complete = True
+    list_manifests = []
+    for child_list in folder_child_lists(client, folder, include_archived=options["include_archived"]):
+        list_id = child_list["id"]
+        list_ids.append(list_id)
+        list_manifest = backup_list(
+            client,
+            list_id,
+            root / "lists" / list_id,
+            options,
+            prefix=f"lists/{list_id}/",
+        )
+        list_manifests.append(list_manifest)
+        task_ids.extend(list_manifest["task_ids"])
+        task_count += list_manifest["task_count"]
+        complete = complete and list_manifest["complete"]
+        files.extend(list_manifest["files"])
+
+    manifest = {
+        "type": "folder_backup",
+        "folder_id": args.folder_id,
+        "list_ids": list_ids,
+        "task_ids": task_ids,
+        "task_count": task_count,
+        "options": options,
+        "complete": complete,
+        "lists": list_manifests,
+        "files": files,
+    }
+    write_json(root / "manifest.json", manifest)
+    return {
+        "status": "ok",
+        "action": "backup_folder",
+        "folder_id": args.folder_id,
+        "output_dir": args.output_dir,
+        "manifest": "manifest.json",
+        "task_count": task_count,
+        "complete": complete,
+    }
+
+
+def cmd_folders_purge_empty(client, args):
+    """Delete a folder only after exhaustive scans prove it is empty."""
+    folder = client.get_v2(f"/folder/{args.folder_id}", allow_dry_run=True)
+    task_counts = count_folder_tasks(client, folder)
+    if not task_counts["complete"]:
+        error("Cannot purge folder: exhaustive task scan did not complete")
+    if task_counts["total"] > 0:
+        error("Cannot purge folder: child lists contain tasks")
+
+    if client.dry_run:
+        return {
+            "dry_run": True,
+            "action": "purge_empty_folder",
+            "folder_id": args.folder_id,
+            "deletable": True,
+            "folder": folder,
+            "task_counts": task_counts,
+        }
+
+    client.delete_v2(f"/folder/{args.folder_id}")
+    return {"status": "ok", "action": "purged_empty_folder", "folder_id": args.folder_id}
+
+
 def cmd_folders_privacy(client, args):
     """Set a folder private or public via the v3 ACLs endpoint."""
     return handle_privacy_request(
@@ -255,6 +392,8 @@ COMMAND_MANIFEST = {
         "create": cmd_folders_create,
         "update": cmd_folders_update,
         "delete": cmd_folders_delete,
+        "backup": cmd_folders_backup,
+        "purge-empty": cmd_folders_purge_empty,
         "privacy": cmd_folders_privacy,
     },
 }

{clickup_cli-1.7.0 → clickup_cli-1.8.0}/src/clickup_cli/commands/lists.py

@@ -1,6 +1,7 @@
 """List command handlers — list, get, create, update, delete, privacy."""
 
 from ..helpers import read_content, error, resolve_space_id, add_id_argument
+from .backup import backup_list, backup_options, count_list_tasks
 from .privacy import handle_privacy_request, register_privacy_subcommand
 
 
@@ -22,6 +23,7 @@ Subcommands:
   create   — create a new list in a folder or space (mutating)
   update   — update a list's name, content, or status (mutating)
   delete   — delete a list (destructive)
+  backup   — export list metadata, tasks, and comments to local JSON files
   privacy  — make a list private or public (mutating)""",
         epilog="""\
 examples:
@@ -199,6 +201,35 @@ examples:
     )
     add_id_argument(ld, "list_id", "ClickUp list ID to delete")
 
+    lb = lists_sub.add_parser(
+        "backup",
+        formatter_class=F,
+        help="Back up a list to local JSON files",
+        description="""\
+Back up a list before migration or deletion. Writes list metadata, task-list
+JSON, per-task full JSON, and a deterministic manifest.json to --output-dir.
+
+Defaults are safety-first: include closed tasks, archived tasks, subtasks,
+all task pages, and all comments unless explicitly disabled.""",
+        epilog="""\
+returns:
+  {"status": "ok", "action": "backup_list", "list_id": "...", ...}
+
+examples:
+  clickup lists backup 12345 --output-dir ./backup/list-12345
+  clickup lists backup --list-id 12345 --output-dir ./backup --no-comments
+
+notes:
+  This command writes local files and does not mutate ClickUp.""",
+    )
+    add_id_argument(lb, "list_id", "ClickUp list ID to back up")
+    lb.add_argument("--output-dir", required=True, help="Directory for backup JSON files")
+    lb.add_argument("--no-closed", action="store_true", help="Do not include closed tasks")
+    lb.add_argument("--no-archived", action="store_true", help="Do not include archived tasks")
+    lb.add_argument("--no-subtasks", action="store_true", help="Do not include subtasks")
+    lb.add_argument("--first-page", action="store_true", help="Only fetch the first task page")
+    lb.add_argument("--no-comments", action="store_true", help="Do not hydrate task comments")
+
     register_privacy_subcommand(
         lists_sub,
         F,
@@ -292,12 +323,39 @@ def cmd_lists_update(client, args):
 def cmd_lists_delete(client, args):
     """Delete a list by ID."""
     if client.dry_run:
-        return {"dry_run": True, "action": "delete_list", "list_id": args.list_id}
+        list_meta = client.get_v2(f"/list/{args.list_id}", allow_dry_run=True)
+        task_counts = count_list_tasks(client, args.list_id)
+        return {
+            "dry_run": True,
+            "action": "delete_list",
+            "list_id": args.list_id,
+            "list": list_meta,
+            "task_counts": task_counts,
+        }
 
     client.delete_v2(f"/list/{args.list_id}")
     return {"status": "ok", "action": "deleted", "list_id": args.list_id}
 
 
+def cmd_lists_backup(client, args):
+    """Back up a list to local JSON files."""
+    manifest = backup_list(
+        client,
+        args.list_id,
+        args.output_dir,
+        backup_options(args),
+    )
+    return {
+        "status": "ok",
+        "action": "backup_list",
+        "list_id": args.list_id,
+        "output_dir": args.output_dir,
+        "manifest": "manifest.json",
+        "task_count": manifest["task_count"],
+        "complete": manifest["complete"],
+    }
+
+
 def cmd_lists_privacy(client, args):
     """Set a list private or public via the v3 ACLs endpoint."""
     return handle_privacy_request(
@@ -317,6 +375,7 @@ COMMAND_MANIFEST = {
         "create": cmd_lists_create,
         "update": cmd_lists_update,
         "delete": cmd_lists_delete,
+        "backup": cmd_lists_backup,
         "privacy": cmd_lists_privacy,
     },
 }