clickup-cli 1.2.0__py3-none-any.whl

clickup_cli/__init__.py

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

clickup_cli/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for `python -m clickup_cli`."""
+
+from .cli import main
+
+main()

clickup_cli/cli.py

@@ -0,0 +1,176 @@
+"""CLI parser, dispatch, and main entry point."""
+
+import argparse
+import os
+import sys
+
+from . import __version__
+from .client import ClickUpClient
+from .helpers import output, error, resolve_id_args
+
+
+GLOBAL_FLAGS = {"--pretty", "--dry-run", "--debug"}
+
+
+def normalize_cli_argv(argv):
+    """Allow global flags before or after the command group."""
+    front = []
+    rest = []
+
+    for arg in argv:
+        if arg in GLOBAL_FLAGS:
+            if arg not in front:
+                front.append(arg)
+        else:
+            rest.append(arg)
+
+    return front + rest
+
+
+def build_parser():
+    F = argparse.RawDescriptionHelpFormatter
+
+    parser = argparse.ArgumentParser(
+        prog="clickup",
+        formatter_class=F,
+        description="""\
+ClickUp CLI — manage tasks, comments, docs, folders, lists, spaces, and teams from the command line.
+
+Covers eight command groups: tasks, comments, docs, folders, lists, spaces, team, and tags.
+All successful output is JSON printed to stdout.
+Errors are printed to stderr with a non-zero exit code.
+
+Global flags can appear before or after the command group:
+  clickup --pretty tasks list --space <name>
+  clickup tasks list --space <name> --pretty
+  clickup --dry-run tasks create --space <name> --name "My task"
+  clickup --debug tasks list --space <name>""",
+        epilog="""\
+examples:
+  clickup init                              # set up config
+  clickup tasks list --space <name>
+  clickup tasks list --list 12345
+  clickup --dry-run tasks create --space <name> --name "Fix login"
+  clickup folders list --space <name>
+  clickup lists list --folder 12345
+  clickup comments list abc123
+  clickup docs pages doc_abc123
+
+current coverage:
+  tasks     — list, get, create, update, search, delete, move, merge
+  comments  — list, add, update, delete, thread, reply
+  docs      — list, get, create, pages, get-page, edit-page, create-page
+  folders   — list, get, create, update, delete
+  lists     — list, get, create, update, delete
+  spaces    — list, get, statuses
+  team      — whoami, members
+  tags      — list, add, remove
+
+Use <group> --help for details on each group.""",
+    )
+    parser.add_argument(
+        "--pretty",
+        action="store_true",
+        help="Pretty-print JSON output with indentation",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Preview the API request without executing it (safe for mutations)",
+    )
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="Log API requests and responses to stderr for troubleshooting",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+
+    subparsers = parser.add_subparsers(dest="group", required=True)
+
+    # init (standalone — no register_parser, handled specially in main())
+    init_parser = subparsers.add_parser(
+        "init",
+        formatter_class=F,
+        help="Set up ClickUp CLI configuration",
+        description="""\
+Set up the ClickUp CLI by connecting to your workspace.
+
+Fetches your workspaces and spaces, then writes a config file to
+~/.config/clickup-cli/config.json.
+
+Run interactively (prompts for token) or pass --token for automation.""",
+        epilog="""\
+examples:
+  clickup init
+  clickup init --token pk_YOUR_API_TOKEN""",
+    )
+    init_parser.add_argument(
+        "--token",
+        type=str,
+        help="ClickUp API token (skips interactive prompt)",
+    )
+
+    # Register all command group parsers from their modules
+    from .commands.tasks import register_parser as tasks_register
+    from .commands.comments import register_parser as comments_register
+    from .commands.docs import register_parser as docs_register
+    from .commands.spaces import register_parser as spaces_register
+    from .commands.folders import register_parser as folders_register
+    from .commands.lists import register_parser as lists_register
+    from .commands.team import register_parser as team_register
+    from .commands.tags import register_parser as tags_register
+
+    tasks_register(subparsers, F)
+    comments_register(subparsers, F)
+    docs_register(subparsers, F)
+    spaces_register(subparsers, F)
+    folders_register(subparsers, F)
+    lists_register(subparsers, F)
+    team_register(subparsers, F)
+    tags_register(subparsers, F)
+
+    return parser
+
+
+def dispatch(client, args):
+    """Route parsed args to the correct command handler."""
+    from .commands import HANDLERS
+
+    key = f"{args.group}_{args.command}"
+    handler = HANDLERS.get(key)
+    if not handler:
+        error(f"Unknown command: {args.group} {args.command}")
+    assert handler is not None
+    return handler(client, args)
+
+
+def main():
+    parser = build_parser()
+    args = parser.parse_args(normalize_cli_argv(sys.argv[1:]))
+    resolve_id_args(args)
+
+    # Handle init before loading config (config may not exist yet)
+    if args.group == "init":
+        from .commands.init import cmd_init
+        cmd_init(args)
+        return
+
+    # Load config and resolve token
+    from .config import load_config
+    config = load_config()
+
+    token = os.environ.get("CLICKUP_API_TOKEN") or config.get("api_token")
+    if not token:
+        error(
+            "No API token found. Set CLICKUP_API_TOKEN or run: clickup init"
+        )
+
+    client = ClickUpClient(token, dry_run=args.dry_run, debug=args.debug)
+    result = dispatch(client, args)
+
+    if result is not None:
+        output(result, pretty=args.pretty)

clickup_cli/client.py

@@ -0,0 +1,115 @@
+"""ClickUp API client with rate limiting, dry-run, and debug support."""
+
+import json as _json
+import sys
+import time
+
+import requests
+
+from .helpers import error
+
+
+class ClickUpClient:
+    BASE_V2 = "https://api.clickup.com/api/v2"
+    BASE_V3 = "https://api.clickup.com/api/v3"
+
+    def __init__(self, token, dry_run=False, debug=False):
+        self.token = token
+        self.dry_run = dry_run
+        self.debug = debug
+        self.session = requests.Session()
+        self.session.headers.update(
+            {
+                "Authorization": token,
+                "Content-Type": "application/json",
+            }
+        )
+
+    def _log(self, msg):
+        """Print debug message to stderr."""
+        if self.debug:
+            print(f"[debug] {msg}", file=sys.stderr)
+
+    def _check_rate_limit(self, response):
+        """Sleep proactively if rate limit is running low."""
+        remaining = response.headers.get("X-RateLimit-Remaining")
+        reset = response.headers.get("X-RateLimit-Reset")
+        if remaining is not None and int(remaining) < 10 and reset:
+            wait = max(0, int(reset) - int(time.time())) + 1
+            print(
+                f"Rate limit low ({remaining} remaining), waiting {wait}s...",
+                file=sys.stderr,
+            )
+            time.sleep(wait)
+
+    def _request(self, method, url, allow_dry_run=False, **kwargs):
+        """Make an HTTP request with rate limit handling and error reporting."""
+        if self.dry_run and not allow_dry_run:
+            return {"dry_run": True, "method": method, "url": url, "kwargs": kwargs}
+
+        self._log(f"{method} {url}")
+        if kwargs.get("params"):
+            self._log(f"  params: {kwargs['params']}")
+        if kwargs.get("json"):
+            self._log(f"  body: {_json.dumps(kwargs['json'], ensure_ascii=False)}")
+
+        def _do_request():
+            try:
+                return self.session.request(method, url, **kwargs)
+            except requests.ConnectionError:
+                error("Couldn't reach ClickUp API — check your network connection")
+
+        response = _do_request()
+        self._log(f"  → {response.status_code} ({len(response.text)} bytes)")
+
+        if response.status_code == 429:
+            reset = response.headers.get("X-RateLimit-Reset")
+            if reset:
+                wait = max(0, int(reset) - int(time.time())) + 1
+                print(f"Rate limited (429), waiting {wait}s...", file=sys.stderr)
+                time.sleep(wait)
+                response = _do_request()
+
+        if response.status_code == 401:
+            error(
+                "Authentication failed — check your API token"
+            )
+
+        if not response.ok:
+            body = response.text
+            try:
+                body = response.json()
+            except ValueError:
+                pass
+            error(f"API error {response.status_code} on {method} {url}: {body}")
+
+        self._check_rate_limit(response)
+
+        if response.status_code == 204 or not response.text:
+            return {}
+        return response.json()
+
+    def get_v2(self, path, params=None, allow_dry_run=False):
+        return self._request(
+            "GET", f"{self.BASE_V2}{path}", params=params, allow_dry_run=allow_dry_run
+        )
+
+    def post_v2(self, path, data=None):
+        return self._request("POST", f"{self.BASE_V2}{path}", json=data)
+
+    def put_v2(self, path, data=None):
+        return self._request("PUT", f"{self.BASE_V2}{path}", json=data)
+
+    def delete_v2(self, path):
+        return self._request("DELETE", f"{self.BASE_V2}{path}")
+
+    def get_v3(self, path, params=None, allow_dry_run=False):
+        return self._request(
+            "GET", f"{self.BASE_V3}{path}", params=params, allow_dry_run=allow_dry_run
+        )
+
+    def post_v3(self, path, data=None):
+        return self._request("POST", f"{self.BASE_V3}{path}", json=data)
+
+    def put_v3(self, path, data=None):
+        return self._request("PUT", f"{self.BASE_V3}{path}", json=data)

clickup_cli/commands/__init__.py

@@ -0,0 +1,71 @@
+"""Command handler registry — maps dispatch keys to handler functions."""
+
+from .tasks import (
+    cmd_tasks_list, cmd_tasks_get, cmd_tasks_create,
+    cmd_tasks_update, cmd_tasks_search,
+    cmd_tasks_delete, cmd_tasks_move, cmd_tasks_merge,
+)
+from .comments import (
+    cmd_comments_list, cmd_comments_add,
+    cmd_comments_update, cmd_comments_delete,
+    cmd_comments_thread, cmd_comments_reply,
+)
+from .docs import (
+    cmd_docs_list, cmd_docs_get, cmd_docs_create, cmd_docs_pages,
+    cmd_docs_get_page, cmd_docs_edit_page, cmd_docs_create_page,
+)
+from .spaces import cmd_spaces_list, cmd_spaces_get, cmd_spaces_statuses
+from .team import cmd_team_whoami, cmd_team_members
+from .tags import cmd_tags_list, cmd_tags_add, cmd_tags_remove
+from .folders import (
+    cmd_folders_list, cmd_folders_get, cmd_folders_create,
+    cmd_folders_update, cmd_folders_delete,
+)
+from .lists import (
+    cmd_lists_list, cmd_lists_get, cmd_lists_create,
+    cmd_lists_update, cmd_lists_delete,
+)
+
+# Keys use f"{args.group}_{args.command}" format from dispatch().
+# Some keys retain hyphens matching argparse subparser names.
+HANDLERS = {
+    "tasks_list": cmd_tasks_list,
+    "tasks_get": cmd_tasks_get,
+    "tasks_create": cmd_tasks_create,
+    "tasks_update": cmd_tasks_update,
+    "tasks_search": cmd_tasks_search,
+    "tasks_delete": cmd_tasks_delete,
+    "tasks_move": cmd_tasks_move,
+    "tasks_merge": cmd_tasks_merge,
+    "comments_list": cmd_comments_list,
+    "comments_add": cmd_comments_add,
+    "comments_update": cmd_comments_update,
+    "comments_delete": cmd_comments_delete,
+    "comments_thread": cmd_comments_thread,
+    "comments_reply": cmd_comments_reply,
+    "docs_list": cmd_docs_list,
+    "docs_get": cmd_docs_get,
+    "docs_create": cmd_docs_create,
+    "docs_pages": cmd_docs_pages,
+    "docs_get-page": cmd_docs_get_page,
+    "docs_edit-page": cmd_docs_edit_page,
+    "docs_create-page": cmd_docs_create_page,
+    "spaces_list": cmd_spaces_list,
+    "spaces_get": cmd_spaces_get,
+    "spaces_statuses": cmd_spaces_statuses,
+    "team_whoami": cmd_team_whoami,
+    "team_members": cmd_team_members,
+    "tags_list": cmd_tags_list,
+    "tags_add": cmd_tags_add,
+    "tags_remove": cmd_tags_remove,
+    "folders_list": cmd_folders_list,
+    "folders_get": cmd_folders_get,
+    "folders_create": cmd_folders_create,
+    "folders_update": cmd_folders_update,
+    "folders_delete": cmd_folders_delete,
+    "lists_list": cmd_lists_list,
+    "lists_get": cmd_lists_get,
+    "lists_create": cmd_lists_create,
+    "lists_update": cmd_lists_update,
+    "lists_delete": cmd_lists_delete,
+}

clickup_cli/commands/comments.py

@@ -0,0 +1,278 @@
+"""Comment command handlers — list, add, update, delete, thread, reply."""
+
+from ..helpers import read_content, error, fetch_all_comments, add_id_argument
+
+
+def register_parser(subparsers, F):
+    """Register all comments subcommands on the given subparsers object."""
+    comments_parser = subparsers.add_parser(
+        "comments",
+        formatter_class=F,
+        help="Full comment CRUD: list, add, update, delete, thread, reply",
+        description="""\
+Manage task comments — full CRUD plus threaded replies.
+
+Subcommands:
+  list    — list comments on a task
+  add     — add a comment to a task (mutating)
+  update  — edit an existing comment (mutating)
+  delete  — delete a comment (destructive)
+  thread  — get threaded replies to a comment
+  reply   — reply to a comment in a thread (mutating)""",
+        epilog="""\
+examples:
+  clickup comments list abc123
+  clickup comments add abc123 --text "Work complete"
+  clickup --dry-run comments add abc123 --file report.md""",
+    )
+    comments_sub = comments_parser.add_subparsers(dest="command", required=True)
+
+    # comments list
+    cl = comments_sub.add_parser(
+        "list",
+        formatter_class=F,
+        help="List comments on a task",
+        description="""\
+List comments on a task. By default returns the first page (up to 25).
+Use --all to paginate through every comment on the task.
+
+Use this when you need to read discussion or work logs on a task.""",
+        epilog="""\
+returns:
+  {"comments": [...], "count": N}
+
+examples:
+  clickup comments list abc123
+  clickup comments list abc123 --all
+  clickup --pretty comments list abc123""",
+    )
+    add_id_argument(cl, "task_id", "ClickUp task ID")
+    cl.add_argument(
+        "--all",
+        action="store_true",
+        dest="fetch_all",
+        help="Fetch all comment pages (default: first page only)",
+    )
+
+    # comments add
+    ca = comments_sub.add_parser(
+        "add",
+        formatter_class=F,
+        help="Add a comment to a task",
+        description="""\
+Add a comment to a task. This is a mutating command.
+
+Exactly one of --text or --file is required.
+Use --text for short inline comments. Use --file to post content from
+a file (useful for longer markdown or structured logs).
+
+Use --dry-run to preview the request body without posting the comment.
+Global flags may appear before or after the command group:
+  clickup --dry-run comments add abc123 --text "Preview this" """,
+        epilog="""\
+returns:
+  The created comment object from the API.
+
+examples:
+  clickup comments add abc123 --text "Task complete"
+  clickup comments add abc123 --file session_log.md
+  clickup --dry-run comments add abc123 --text "Test comment"
+
+notes:
+  --text and --file are mutually exclusive. Using both is an error.""",
+    )
+    add_id_argument(ca, "task_id", "ClickUp task ID")
+    ca.add_argument(
+        "--text", type=str, help="Inline comment text (mutually exclusive with --file)"
+    )
+    ca.add_argument(
+        "--file", type=str, help="Path to a file containing comment content"
+    )
+
+    # comments update
+    cu = comments_sub.add_parser(
+        "update",
+        formatter_class=F,
+        help="Edit an existing comment",
+        description="""\
+Edit an existing comment's text or resolved status. This is a mutating command.
+
+At least one change is required: --text/--file for new text, or
+--resolve/--unresolve to change the resolved state.
+
+Use --dry-run to preview without applying changes.
+Global flags may appear before or after the command group:
+  clickup --dry-run comments update 456 --text "Fixed text" """,
+        epilog="""\
+returns:
+  {"status": "ok", "action": "updated", "comment_id": "..."}
+
+examples:
+  clickup comments update 456 --text "Corrected info"
+  clickup comments update 456 --file updated_notes.md
+  clickup comments update 456 --resolve
+  clickup --dry-run comments update 456 --text "Test"
+
+notes:
+  --text and --file are mutually exclusive. Using both is an error.
+  --resolve and --unresolve are mutually exclusive.""",
+    )
+    add_id_argument(cu, "comment_id", "ClickUp comment ID")
+    cu.add_argument(
+        "--text", type=str, help="New comment text (mutually exclusive with --file)"
+    )
+    cu.add_argument(
+        "--file", type=str, help="Path to a file containing new comment text"
+    )
+    resolve_group = cu.add_mutually_exclusive_group()
+    resolve_group.add_argument(
+        "--resolve",
+        action="store_const",
+        const=True,
+        dest="resolved",
+        help="Mark the comment as resolved",
+    )
+    resolve_group.add_argument(
+        "--unresolve",
+        action="store_const",
+        const=False,
+        dest="resolved",
+        help="Mark the comment as unresolved",
+    )
+
+    # comments delete
+    cd = comments_sub.add_parser(
+        "delete",
+        formatter_class=F,
+        help="Delete a comment (destructive)",
+        description="""\
+Delete a comment permanently. This is a destructive, irreversible command.
+
+Use --dry-run to preview the operation without deleting anything.
+Global flags may appear before or after the command group:
+  clickup --dry-run comments delete 456""",
+        epilog="""\
+returns:
+  {"status": "ok", "action": "deleted", "comment_id": "..."}
+
+examples:
+  clickup --dry-run comments delete 456
+  clickup comments delete 456""",
+    )
+    add_id_argument(cd, "comment_id", "ClickUp comment ID to delete")
+
+    # comments thread
+    ct = comments_sub.add_parser(
+        "thread",
+        formatter_class=F,
+        help="Get threaded replies to a comment",
+        description="""\
+Get all threaded replies to a specific comment. The parent comment is NOT
+included in the response — only the replies.
+
+Use this to read conversation threads on tasks.""",
+        epilog="""\
+returns:
+  {"replies": [...], "count": N}
+
+examples:
+  clickup comments thread 456
+  clickup --pretty comments thread 456""",
+    )
+    add_id_argument(ct, "comment_id", "Parent comment ID")
+
+    # comments reply
+    cr = comments_sub.add_parser(
+        "reply",
+        formatter_class=F,
+        help="Reply to a comment in a thread",
+        description="""\
+Post a threaded reply to a specific comment. This is a mutating command.
+
+Exactly one of --text or --file is required.
+
+Use --dry-run to preview without posting.
+Global flags may appear before or after the command group:
+  clickup --dry-run comments reply 456 --text "Preview" """,
+        epilog="""\
+returns:
+  The created reply object from the API.
+
+examples:
+  clickup comments reply 456 --text "Agreed, let's proceed"
+  clickup comments reply 456 --file detailed_response.md
+  clickup --dry-run comments reply 456 --text "Test reply"
+
+notes:
+  --text and --file are mutually exclusive. Using both is an error.""",
+    )
+    add_id_argument(cr, "comment_id", "Parent comment ID to reply to")
+    cr.add_argument(
+        "--text", type=str, help="Inline reply text (mutually exclusive with --file)"
+    )
+    cr.add_argument("--file", type=str, help="Path to a file containing reply content")
+
+
+def cmd_comments_list(client, args):
+    if client.dry_run:
+        return {"dry_run": True, "action": "list_comments", "task_id": args.task_id}
+
+    resp = client.get_v2(f"/task/{args.task_id}/comment")
+    comments = resp.get("comments", [])
+
+    if not args.fetch_all or len(comments) < 25:
+        return {"comments": comments, "count": len(comments)}
+
+    # Paginate through all comments
+    all_comments = fetch_all_comments(client, args.task_id)
+    return {"comments": all_comments, "count": len(all_comments)}
+
+
+def cmd_comments_add(client, args):
+    text = read_content(args.text, args.file, "--text")
+    if not text:
+        error("Provide comment text via --text or --file")
+    body = {"comment_text": text, "notify_all": False}
+    return client.post_v2(f"/task/{args.task_id}/comment", data=body)
+
+
+def cmd_comments_update(client, args):
+    """Update an existing comment's text or resolved status."""
+    text = read_content(args.text, args.file, "--text")
+    body = {}
+    if text:
+        body["comment_text"] = text
+    if args.resolved is not None:
+        body["resolved"] = args.resolved
+    if not body:
+        error("Nothing to update — provide at least one of: --text, --file, --resolve, --unresolve")
+    if client.dry_run:
+        return {"dry_run": True, "action": "update", "comment_id": args.comment_id, "body": body}
+    client.put_v2(f"/comment/{args.comment_id}", data=body)
+    return {"status": "ok", "action": "updated", "comment_id": args.comment_id}
+
+
+def cmd_comments_delete(client, args):
+    """Delete a comment by ID."""
+    if client.dry_run:
+        return {"dry_run": True, "action": "delete", "comment_id": args.comment_id}
+    client.delete_v2(f"/comment/{args.comment_id}")
+    return {"status": "ok", "action": "deleted", "comment_id": args.comment_id}
+
+
+def cmd_comments_thread(client, args):
+    """Get threaded replies to a comment."""
+    resp = client.get_v2(f"/comment/{args.comment_id}/reply")
+    replies = resp.get("comments", resp if isinstance(resp, list) else [])
+    return {"replies": replies, "count": len(replies)}
+
+
+def cmd_comments_reply(client, args):
+    """Reply to a comment (threaded)."""
+    text = read_content(args.text, args.file, "--text")
+    if not text:
+        error("Provide reply text via --text or --file")
+    body = {"comment_text": text, "notify_all": False}
+    if client.dry_run:
+        return {"dry_run": True, "action": "reply", "comment_id": args.comment_id, "body": body}
+    return client.post_v2(f"/comment/{args.comment_id}/reply", data=body)