clickup-cli 1.2.0__py3-none-any.whl

clickup_cli/commands/init.py

@@ -0,0 +1,153 @@
+"""Init command — interactive workspace setup."""
+
+import json
+import os
+import sys
+
+import requests
+
+
+def cmd_init(args):
+    """Set up ClickUp CLI configuration interactively or via --token."""
+    token = getattr(args, "token", None)
+
+    if not token:
+        print("Enter your ClickUp API token (starts with pk_):")
+        print("  Find it at: https://app.clickup.com/settings/apps")
+        try:
+            token = input("> ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print("\nAborted.", file=sys.stderr)
+            sys.exit(1)
+
+    if not token:
+        print("Error: API token is required.", file=sys.stderr)
+        sys.exit(1)
+
+    # Fetch workspaces
+    print("Fetching workspaces...", file=sys.stderr)
+    headers = {"Authorization": token, "Content-Type": "application/json"}
+
+    try:
+        resp = requests.get(
+            "https://api.clickup.com/api/v2/team", headers=headers, timeout=15
+        )
+    except requests.ConnectionError:
+        print("Error: Could not reach ClickUp API. Check your network.", file=sys.stderr)
+        sys.exit(1)
+
+    if resp.status_code == 401:
+        print("Error: Invalid API token.", file=sys.stderr)
+        sys.exit(1)
+
+    if not resp.ok:
+        print(f"Error: API returned {resp.status_code}: {resp.text}", file=sys.stderr)
+        sys.exit(1)
+
+    teams = resp.json().get("teams", [])
+    if not teams:
+        print("Error: No workspaces found for this token.", file=sys.stderr)
+        sys.exit(1)
+
+    # Select workspace
+    if len(teams) == 1:
+        team = teams[0]
+        print(f"Found workspace: {team['name']} (ID: {team['id']})", file=sys.stderr)
+    else:
+        print(f"\nFound {len(teams)} workspaces:", file=sys.stderr)
+        for i, t in enumerate(teams, 1):
+            print(f"  {i}. {t['name']} (ID: {t['id']})", file=sys.stderr)
+        try:
+            choice = input(f"Select workspace [1-{len(teams)}]: ").strip()
+            idx = int(choice) - 1
+            if idx < 0 or idx >= len(teams):
+                raise ValueError
+            team = teams[idx]
+        except (ValueError, EOFError, KeyboardInterrupt):
+            print("\nAborted.", file=sys.stderr)
+            sys.exit(1)
+
+    workspace_id = str(team["id"])
+
+    # Find authenticated user
+    user_id = ""
+    members = team.get("members", [])
+    if len(members) == 1:
+        u = members[0].get("user", {})
+        user_id = str(u.get("id", ""))
+        print(f"Found user: {u.get('username', 'unknown')} (ID: {user_id})", file=sys.stderr)
+    elif members:
+        print(f"\nFound {len(members)} members:", file=sys.stderr)
+        for i, m in enumerate(members, 1):
+            u = m.get("user", {})
+            print(
+                f"  {i}. {u.get('username', 'unknown')} — {u.get('email', '')} (ID: {u.get('id')})",
+                file=sys.stderr,
+            )
+        try:
+            choice = input(f"Which one is you? [1-{len(members)}] (Enter to skip): ").strip()
+            if choice:
+                idx = int(choice) - 1
+                if 0 <= idx < len(members):
+                    u = members[idx].get("user", {})
+                    user_id = str(u.get("id", ""))
+                else:
+                    raise ValueError
+        except (ValueError, EOFError, KeyboardInterrupt):
+            print("Skipped — set user_id in config later if needed.", file=sys.stderr)
+
+    # Fetch spaces
+    print("Fetching spaces...", file=sys.stderr)
+    try:
+        resp = requests.get(
+            f"https://api.clickup.com/api/v2/team/{workspace_id}/space",
+            headers=headers,
+            timeout=15,
+        )
+    except requests.ConnectionError:
+        print("Error: Could not fetch spaces.", file=sys.stderr)
+        sys.exit(1)
+
+    spaces_raw = resp.json().get("spaces", [])
+
+    # Build spaces config
+    spaces = {}
+    for s in spaces_raw:
+        # Use lowercase name as key, sanitized for CLI use
+        key = s["name"].lower().replace(" ", "-")
+        lists_resp = requests.get(
+            f"https://api.clickup.com/api/v2/space/{s['id']}/list",
+            headers=headers,
+            timeout=15,
+        )
+        lists = lists_resp.json().get("lists", [])
+        default_list_id = lists[0]["id"] if lists else ""
+        spaces[key] = {"space_id": str(s["id"]), "list_id": default_list_id}
+        status = f" (default list: {default_list_id})" if default_list_id else " (no lists)"
+        print(f"  {key}: {s['name']}{status}", file=sys.stderr)
+
+    config = {
+        "api_token": token,
+        "workspace_id": workspace_id,
+        "user_id": user_id,
+        "spaces": spaces,
+        "default_tags": [],
+        "draft_tag": "draft",
+        "good_as_is_tag": "good as is",
+        "default_priority": 4,
+    }
+
+    # Write config
+    config_dir = os.path.expanduser("~/.config/clickup-cli")
+    config_path = os.path.join(config_dir, "config.json")
+    os.makedirs(config_dir, exist_ok=True)
+
+    with open(config_path, "w", encoding="utf-8") as f:
+        json.dump(config, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+
+    print(f"\nConfig saved to {config_path}", file=sys.stderr)
+    print(f"Workspace: {team['name']} ({len(spaces)} spaces)", file=sys.stderr)
+    print("\nTry it out:", file=sys.stderr)
+    print("  clickup spaces list", file=sys.stderr)
+    print("  clickup team whoami", file=sys.stderr)

clickup_cli/commands/lists.py

@@ -0,0 +1,258 @@
+"""List command handlers — list, get, create, update, delete."""
+
+from ..helpers import read_content, error, resolve_space_id, add_id_argument
+
+
+def register_parser(subparsers, F):
+    """Register all lists subcommands on the given subparsers object."""
+    lists_parser = subparsers.add_parser(
+        "lists",
+        formatter_class=F,
+        help="Full list CRUD: list, get, create, update, delete",
+        description="""\
+Manage ClickUp lists — the containers that hold tasks.
+
+Lists can live directly in a space (folderless) or inside a folder.
+Use --folder or --space to specify the parent depending on the context.
+
+Subcommands:
+  list    — list lists in a folder or folderless lists in a space
+  get     — fetch full details of a list by ID
+  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)""",
+        epilog="""\
+examples:
+  clickup lists list --folder 12345
+  clickup lists list --space <name>
+  clickup lists get 12345
+  clickup --dry-run lists create --folder 12345 --name "Tasks"
+  clickup lists create --space <name> --name "Backlog"
+  clickup lists update 12345 --name "Renamed list"
+  clickup --dry-run lists delete 12345""",
+    )
+    lists_sub = lists_parser.add_subparsers(dest="command", required=True)
+
+    # lists list
+    ll = lists_sub.add_parser(
+        "list",
+        formatter_class=F,
+        help="List lists in a folder or folderless lists in a space",
+        description="""\
+List lists in a specific context. Exactly one of --folder or --space
+is required:
+
+  --folder <id>   — lists all lists inside a folder
+  --space <name>  — lists only folderless lists in a space""",
+        epilog="""\
+returns:
+  {"lists": [...], "count": N}
+
+examples:
+  clickup lists list --folder 12345
+  clickup lists list --space <name>
+  clickup --pretty lists list --space <name>
+
+notes:
+  --folder and --space are mutually exclusive.
+  --space only returns folderless lists. To see lists inside folders,
+  use 'folders list --space <name>' first to find folder IDs, then
+  'lists list --folder <id>' for each folder.""",
+    )
+    ll_target = ll.add_mutually_exclusive_group(required=True)
+    ll_target.add_argument(
+        "--folder", type=str, help="Folder ID — list all lists inside this folder"
+    )
+    ll_target.add_argument(
+        "--space",
+        type=str,
+        help="Space name or ID — list folderless lists in this space",
+    )
+
+    # lists get
+    lg = lists_sub.add_parser(
+        "get",
+        formatter_class=F,
+        help="Fetch full details of a list by ID",
+        description="""\
+Fetch full details of a list by its ClickUp list ID.
+
+Returns list metadata including name, content, task count, statuses,
+folder, and space information.""",
+        epilog="""\
+returns:
+  One list JSON object with all fields.
+
+examples:
+  clickup lists get 901816700000
+  clickup --pretty lists get 12345""",
+    )
+    add_id_argument(lg, "list_id", "ClickUp list ID")
+
+    # lists create
+    lc = lists_sub.add_parser(
+        "create",
+        formatter_class=F,
+        help="Create a new list in a folder or space",
+        description="""\
+Create a new list. This is a mutating command.
+
+Exactly one of --folder or --space is required:
+
+  --folder <id>   — creates the list inside a folder
+  --space <name>  — creates a folderless list directly in a space
+
+Use --dry-run to preview the request body without creating the list.
+Global flags may appear before or after the command group:
+  clickup --dry-run lists create --folder 12345 --name "Tasks" """,
+        epilog="""\
+returns:
+  The created list object from the API.
+
+examples:
+  clickup lists create --folder 12345 --name "Tasks"
+  clickup lists create --space <name> --name "Backlog"
+  clickup --dry-run lists create --space <name> --name "Test list"
+
+notes:
+  --folder and --space are mutually exclusive. Using both is an error.""",
+    )
+    lc_target = lc.add_mutually_exclusive_group(required=True)
+    lc_target.add_argument(
+        "--folder", type=str, help="Folder ID — create list inside this folder"
+    )
+    lc_target.add_argument(
+        "--space",
+        type=str,
+        help="Space name or ID — create a folderless list in this space",
+    )
+    lc.add_argument("--name", required=True, help="List name (required)")
+    lc.add_argument("--content", type=str, help="List description/content")
+    lc.add_argument("--status", type=str, help="Initial list status")
+
+    # lists update
+    lu = lists_sub.add_parser(
+        "update",
+        formatter_class=F,
+        help="Update a list (name, content, status)",
+        description="""\
+Update a list's name, content, or status. This is a mutating command.
+
+At least one mutable field is required: --name, --content, --content-file,
+or --status. If none are provided, the command exits with an error.
+
+Use --dry-run to preview the request body without applying changes.
+Global flags may appear before or after the command group:
+  clickup --dry-run lists update 12345 --name "New name" """,
+        epilog="""\
+returns:
+  The updated list object from the API.
+
+examples:
+  clickup lists update 12345 --name "Renamed list"
+  clickup lists update 12345 --content "Updated description"
+  clickup --dry-run lists update 12345 --name "Test rename" """,
+    )
+    add_id_argument(lu, "list_id", "ClickUp list ID to update")
+    lu.add_argument("--name", type=str, help="New list name")
+    lu.add_argument(
+        "--content",
+        type=str,
+        help="Inline description (mutually exclusive with --content-file)",
+    )
+    lu.add_argument(
+        "--content-file", type=str, help="Path to a file containing list description"
+    )
+    lu.add_argument("--status", type=str, help="New list status")
+
+    # lists delete
+    ld = lists_sub.add_parser(
+        "delete",
+        formatter_class=F,
+        help="Delete a list (destructive)",
+        description="""\
+Delete a list permanently. This is a destructive, irreversible command.
+
+Deleting a list also deletes all tasks inside it. Use with extreme caution.
+
+Use --dry-run to preview the operation without deleting anything.
+Global flags may appear before or after the command group:
+  clickup --dry-run lists delete 12345""",
+        epilog="""\
+returns:
+  {"status": "ok", "action": "deleted", "list_id": "..."}
+
+examples:
+  clickup --dry-run lists delete 12345
+  clickup lists delete 12345""",
+    )
+    add_id_argument(ld, "list_id", "ClickUp list ID to delete")
+
+
+def _resolve_list_parent(args):
+    """Resolve folder or space target for list operations."""
+    if args.folder:
+        return f"/folder/{args.folder}/list", {"folder_id": args.folder}
+    elif args.space:
+        space_id = resolve_space_id(args.space)
+        return f"/space/{space_id}/list", {"space_id": space_id}
+    else:
+        error("Provide either --folder <folder_id> or --space <name|id>")
+
+
+def cmd_lists_list(client, args):
+    """List lists in a folder or folderless lists in a space."""
+    path, _ = _resolve_list_parent(args)
+    resp = client.get_v2(path)
+    lists = resp.get("lists", [])
+    return {"lists": lists, "count": len(lists)}
+
+
+def cmd_lists_get(client, args):
+    """Get full details of a list by ID."""
+    return client.get_v2(f"/list/{args.list_id}")
+
+
+def cmd_lists_create(client, args):
+    """Create a list in a folder or directly in a space (folderless)."""
+    body = {"name": args.name}
+    if args.content:
+        body["content"] = args.content
+    if args.status:
+        body["status"] = args.status
+
+    endpoint, target = _resolve_list_parent(args)
+
+    if client.dry_run:
+        return {"dry_run": True, "action": "create_list", **target, "body": body}
+
+    return client.post_v2(endpoint, data=body)
+
+
+def cmd_lists_update(client, args):
+    """Update a list (name, content, status)."""
+    desc = read_content(args.content, args.content_file, "--content")
+    body = {}
+    if args.name:
+        body["name"] = args.name
+    if desc:
+        body["content"] = desc
+    if args.status:
+        body["status"] = args.status
+
+    if not body:
+        error("Nothing to update — provide at least one of: --name, --content, --content-file, --status")
+
+    if client.dry_run:
+        return {"dry_run": True, "action": "update_list", "list_id": args.list_id, "body": body}
+
+    return client.put_v2(f"/list/{args.list_id}", data=body)
+
+
+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}
+
+    client.delete_v2(f"/list/{args.list_id}")
+    return {"status": "ok", "action": "deleted", "list_id": args.list_id}

clickup_cli/commands/spaces.py

@@ -0,0 +1,137 @@
+"""Space command handlers — list, get, statuses."""
+
+from ..config import WORKSPACE_ID
+from ..helpers import resolve_space_id, add_id_argument
+
+
+def register_parser(subparsers, F):
+    """Register all spaces subcommands on the given subparsers object."""
+    spaces_parser = subparsers.add_parser(
+        "spaces",
+        formatter_class=F,
+        help="List spaces, view details, and discover statuses",
+        description="""\
+Inspect workspace spaces — list all spaces, view space details, and
+discover valid statuses per space.
+
+Subcommands:
+  list      — list all spaces in the workspace
+  get       — fetch full details of a specific space
+  statuses  — list valid statuses for a space
+
+All commands are read-only. Configured space names and raw ClickUp
+space IDs are both accepted.""",
+        epilog="""\
+examples:
+  clickup spaces list
+  clickup spaces get <space>
+  clickup spaces statuses <space>
+
+notes:
+  These commands hit the API directly — no caching.
+  Use 'spaces statuses' to find valid status names before setting
+  task statuses, avoiding "Status does not exist" errors.""",
+    )
+    spaces_sub = spaces_parser.add_subparsers(dest="command", required=True)
+
+    # spaces list
+    spaces_sub.add_parser(
+        "list",
+        formatter_class=F,
+        help="List all spaces in the workspace",
+        description="""\
+List all spaces in the workspace. Returns space names, IDs, and basic
+metadata for every space the authenticated user can access.
+
+Use this for discovery — find available spaces and their IDs without
+relying on hardcoded configuration.""",
+        epilog="""\
+returns:
+  {"spaces": [...], "count": N}
+
+examples:
+  clickup spaces list
+  clickup --pretty spaces list""",
+    )
+
+    # spaces get
+    sg = spaces_sub.add_parser(
+        "get",
+        formatter_class=F,
+        help="Fetch full details of a specific space",
+        description="""\
+Fetch full details of a space including statuses, features, and members.
+
+Accepts a configured space name or a raw ClickUp space ID.
+Use 'spaces list' to discover available spaces.""",
+        epilog="""\
+returns:
+  One space JSON object with all fields (statuses, features, members, etc.)
+
+examples:
+  clickup spaces get <space>
+  clickup spaces get 901810200000
+  clickup --pretty spaces get <space>""",
+    )
+    add_id_argument(sg, "space", "Space name (from config) or raw space ID")
+
+    # spaces statuses
+    ss = spaces_sub.add_parser(
+        "statuses",
+        formatter_class=F,
+        help="List valid statuses for a space",
+        description="""\
+List the valid workflow statuses for a space. Returns the status name,
+type (open, closed, custom), color, and order.
+
+Use this before setting a task status to avoid "Status does not exist"
+errors. Status names are space-specific — each space has its own set.""",
+        epilog="""\
+returns:
+  {"space": "<name>", "statuses": [...], "count": N}
+
+  Each status has: status (name), type, color, orderindex.
+
+examples:
+  clickup spaces statuses <space>
+  clickup spaces statuses 901810200000
+  clickup --pretty spaces statuses <space>
+
+notes:
+  Accepts a configured space name or raw space ID.
+  Statuses can only be modified via the ClickUp UI, not the API.""",
+    )
+    add_id_argument(ss, "space", "Space name (from config) or raw space ID")
+
+
+def cmd_spaces_list(client, args):
+    """List all spaces in the workspace."""
+    resp = client.get_v2(f"/team/{WORKSPACE_ID}/space")
+    spaces = resp.get("spaces", [])
+    return {"spaces": spaces, "count": len(spaces)}
+
+
+def cmd_spaces_get(client, args):
+    """Get full details of a specific space."""
+    space_id = resolve_space_id(args.space)
+    return client.get_v2(f"/space/{space_id}")
+
+
+def cmd_spaces_statuses(client, args):
+    """List valid statuses for a space."""
+    space_id = resolve_space_id(args.space)
+    resp = client.get_v2(f"/space/{space_id}")
+    statuses = resp.get("statuses", [])
+    return {
+        "space": args.space,
+        "statuses": [
+            {
+                "status": s.get("status"),
+                "type": s.get("type"),
+                "color": s.get("color"),
+                "orderindex": s.get("orderindex"),
+            }
+            for s in statuses
+        ],
+        "count": len(statuses),
+    }

clickup_cli/commands/tags.py

@@ -0,0 +1,132 @@
+"""Tag command handlers — list, add, remove."""
+
+from ..helpers import resolve_space_id, add_id_argument
+
+
+def register_parser(subparsers, F):
+    """Register all tags subcommands on the given subparsers object."""
+    tags_parser = subparsers.add_parser(
+        "tags",
+        formatter_class=F,
+        help="List space tags, add/remove tags on tasks",
+        description="""\
+Manage tags — list available tags in a space, add or remove tags on tasks.
+
+Subcommands:
+  list    — list all tags in a space
+  add     — add a tag to a task (mutating)
+  remove  — remove a tag from a task (mutating)
+
+Tag names are lowercase in the API, even if they display with title case
+in the ClickUp UI. The CLI lowercases tag names automatically.""",
+        epilog="""\
+examples:
+  clickup tags list --space <name>
+  clickup tags add abc123 --tag "in review"
+  clickup tags remove abc123 --tag "draft" """,
+    )
+    tags_sub = tags_parser.add_subparsers(dest="command", required=True)
+
+    # tags list
+    tgl = tags_sub.add_parser(
+        "list",
+        formatter_class=F,
+        help="List all tags in a space",
+        description="""\
+List all tags available in a space. Returns tag names, colors, and metadata.
+
+Accepts a configured space name or a raw space ID.""",
+        epilog="""\
+returns:
+  {"tags": [...], "count": N}
+
+examples:
+  clickup tags list --space <name>
+  clickup --pretty tags list --space <name>""",
+    )
+    tgl.add_argument(
+        "--space",
+        required=True,
+        type=str,
+        help="Space name (from config) or raw space ID",
+    )
+
+    # tags add
+    tga = tags_sub.add_parser(
+        "add",
+        formatter_class=F,
+        help="Add a tag to a task",
+        description="""\
+Add a tag to a task. This is a mutating command.
+
+The tag name is automatically lowercased (ClickUp API requirement).
+The tag must already exist in the space — this command does not create tags.
+
+Use --dry-run to preview without applying.
+Global flags may appear before or after the command group:
+  clickup --dry-run tags add abc123 --tag "in review" """,
+        epilog="""\
+returns:
+  {"status": "ok", "action": "tag_added", "task_id": "...", "tag": "..."}
+
+examples:
+  clickup tags add abc123 --tag "in review"
+  clickup --dry-run tags add abc123 --tag "draft" """,
+    )
+    add_id_argument(tga, "task_id", "ClickUp task ID")
+    tga.add_argument(
+        "--tag", required=True, type=str, help="Tag name to add (auto-lowercased)"
+    )
+
+    # tags remove
+    tgr = tags_sub.add_parser(
+        "remove",
+        formatter_class=F,
+        help="Remove a tag from a task",
+        description="""\
+Remove a tag from a task. This is a mutating command.
+
+The tag name is automatically lowercased (ClickUp API requirement).
+
+Use --dry-run to preview without applying.
+Global flags may appear before or after the command group:
+  clickup --dry-run tags remove abc123 --tag "draft" """,
+        epilog="""\
+returns:
+  {"status": "ok", "action": "tag_removed", "task_id": "...", "tag": "..."}
+
+examples:
+  clickup tags remove abc123 --tag "draft"
+  clickup --dry-run tags remove abc123 --tag "in review" """,
+    )
+    add_id_argument(tgr, "task_id", "ClickUp task ID")
+    tgr.add_argument(
+        "--tag", required=True, type=str, help="Tag name to remove (auto-lowercased)"
+    )
+
+
+def cmd_tags_list(client, args):
+    """List all tags in a space."""
+    space_id = resolve_space_id(args.space)
+    resp = client.get_v2(f"/space/{space_id}/tag")
+    tags = resp.get("tags", [])
+    return {"tags": tags, "count": len(tags)}
+
+
+def _tag_action(client, args, method, dry_action, done_action):
+    """Shared logic for tag add/remove."""
+    tag_name = args.tag.lower()
+    if client.dry_run:
+        return {"dry_run": True, "action": dry_action, "task_id": args.task_id, "tag": tag_name}
+    method(f"/task/{args.task_id}/tag/{tag_name}", **({"data": {}} if method == client.post_v2 else {}))
+    return {"status": "ok", "action": done_action, "task_id": args.task_id, "tag": tag_name}
+
+
+def cmd_tags_add(client, args):
+    """Add a tag to a task."""
+    return _tag_action(client, args, client.post_v2, "add_tag", "tag_added")
+
+
+def cmd_tags_remove(client, args):
+    """Remove a tag from a task."""
+    return _tag_action(client, args, client.delete_v2, "remove_tag", "tag_removed")