clickup-cli 1.2.0__py3-none-any.whl

clickup_cli/commands/team.py

@@ -0,0 +1,114 @@
+"""Team command handlers — whoami, members."""
+
+from ..config import WORKSPACE_ID
+
+
+def register_parser(subparsers, F):
+    """Register all team subcommands on the given subparsers object."""
+    team_parser = subparsers.add_parser(
+        "team",
+        formatter_class=F,
+        help="Workspace and team member information",
+        description="""\
+Inspect workspace and team details — authenticated user info and member list.
+
+Subcommands:
+  whoami   — show workspace info and authenticated user context
+  members  — list all members of the workspace
+
+All commands are read-only.""",
+        epilog="""\
+examples:
+  clickup team whoami
+  clickup team members
+  clickup --pretty team whoami""",
+    )
+    team_sub = team_parser.add_subparsers(dest="command", required=True)
+
+    # team whoami
+    team_sub.add_parser(
+        "whoami",
+        formatter_class=F,
+        help="Show workspace info and member context",
+        description="""\
+Show the workspace name, ID, and all members visible to the authenticated
+user. Use this as a quick sanity check to confirm which workspace and
+identity the CLI is operating under.""",
+        epilog="""\
+returns:
+  {"workspace": {"id": ..., "name": ...}, "members": [...], "member_count": N}
+
+examples:
+  clickup team whoami
+  clickup --pretty team whoami""",
+    )
+
+    # team members
+    team_sub.add_parser(
+        "members",
+        formatter_class=F,
+        help="List all workspace members",
+        description="""\
+List all members of the workspace with their IDs, usernames, emails,
+and roles. Use this to discover user IDs for task assignment or to
+verify team membership.""",
+        epilog="""\
+returns:
+  {"members": [...], "count": N}
+
+  Each member has: id, username, email, role, initials.
+
+examples:
+  clickup team members
+  clickup --pretty team members""",
+    )
+
+
+def _get_workspace(client):
+    """Fetch teams and find the configured workspace."""
+    resp = client.get_v2("/team")
+    teams = resp.get("teams", [])
+    for team in teams:
+        if str(team.get("id")) == WORKSPACE_ID:
+            return team
+    # Shouldn't happen, but return first team if workspace ID doesn't match
+    if teams:
+        return teams[0]
+    return resp
+
+
+def _format_member(m):
+    """Extract user fields from a member object."""
+    u = m.get("user", {})
+    return {
+        "id": u.get("id"),
+        "username": u.get("username"),
+        "email": u.get("email"),
+        "role": u.get("role_key"),
+        "initials": u.get("initials"),
+    }
+
+
+def cmd_team_whoami(client, args):
+    """Show authenticated user and workspace info."""
+    team = _get_workspace(client)
+    members = team.get("members", [])
+    return {
+        "workspace": {
+            "id": team.get("id"),
+            "name": team.get("name"),
+            "color": team.get("color"),
+        },
+        "members": [_format_member(m) for m in members],
+        "member_count": len(members),
+    }
+
+
+def cmd_team_members(client, args):
+    """List workspace members."""
+    team = _get_workspace(client)
+    members = team.get("members", [])
+    return {
+        "members": [_format_member(m) for m in members],
+        "count": len(members),
+    }

clickup_cli/config.py

@@ -0,0 +1,200 @@
+"""ClickUp CLI configuration — lazy-loaded from JSON file or environment variables.
+
+Config resolution order:
+1. CLICKUP_CONFIG_PATH env var → exact file path
+2. ~/.config/clickup-cli/config.json → XDG-ish default
+3. clickup-config.json in current working directory → project-local override
+4. Environment variables only (CLICKUP_API_TOKEN + CLICKUP_WORKSPACE_ID)
+
+workspace_id is auto-detected from the API when missing (single-workspace accounts).
+"""
+
+import json
+import os
+import sys
+
+from .helpers import error
+
+_config_cache = None
+
+
+def _auto_detect_workspace(token):
+    """Auto-detect workspace ID when only a token is available.
+
+    Returns workspace_id string. Exits with error if detection fails.
+    """
+    import requests
+
+    print("Auto-detecting workspace...", 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:
+        error("Could not reach ClickUp API to auto-detect workspace")
+
+    if resp.status_code == 401:
+        error("Authentication failed — check your API token")
+
+    if not resp.ok:
+        error(f"API error {resp.status_code} while detecting workspace: {resp.text}")
+
+    teams = resp.json().get("teams", [])
+
+    if not teams:
+        error("No workspaces found for this token")
+
+    if len(teams) == 1:
+        workspace_id = str(teams[0]["id"])
+        print(
+            f"Found workspace: {teams[0]['name']} (ID: {workspace_id})",
+            file=sys.stderr,
+        )
+        return workspace_id
+
+    # Multiple workspaces — can't auto-select
+    lines = ["Multiple workspaces found — set workspace_id manually:"]
+    for t in teams:
+        lines.append(f"  {t['name']}: {t['id']}")
+    lines.append("\nSet it in your config file or via: export CLICKUP_WORKSPACE_ID=<id>")
+    error("\n".join(lines))
+
+
+def _save_field_to_config(path, field, value):
+    """Update a single field in an existing config file."""
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            config = json.load(f)
+        config[field] = value
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(config, f, indent=2, ensure_ascii=False)
+            f.write("\n")
+        print(f"Saved {field} to {path}", file=sys.stderr)
+    except (OSError, json.JSONDecodeError):
+        pass  # Non-critical — config works in memory even if save fails
+
+
+def _find_config_path():
+    """Find config file using the fallback chain. Returns path or None."""
+    # 1. Explicit env var
+    env_path = os.environ.get("CLICKUP_CONFIG_PATH")
+    if env_path:
+        if os.path.exists(env_path):
+            return env_path
+        error(f"CLICKUP_CONFIG_PATH points to a missing file: {env_path}")
+
+    # 2. XDG-ish default
+    xdg_path = os.path.expanduser("~/.config/clickup-cli/config.json")
+    if os.path.exists(xdg_path):
+        return xdg_path
+
+    # 3. Current working directory
+    cwd_path = os.path.join(os.getcwd(), "clickup-config.json")
+    if os.path.exists(cwd_path):
+        return cwd_path
+
+    return None
+
+
+def _load_from_file(path):
+    """Load and validate config from a JSON file."""
+    with open(path, "r", encoding="utf-8") as f:
+        try:
+            config = json.load(f)
+        except json.JSONDecodeError as e:
+            error(f"Invalid JSON in {path}: {e}")
+
+    # Allow env var to override token from file
+    env_token = os.environ.get("CLICKUP_API_TOKEN")
+    if env_token:
+        config["api_token"] = env_token
+
+    if not config.get("api_token"):
+        error(
+            f"Missing required field in {path}: api_token\n"
+            "See clickup-config.example.json for the expected schema."
+        )
+
+    # Auto-detect workspace_id if missing
+    if not config.get("workspace_id"):
+        config["workspace_id"] = _auto_detect_workspace(config["api_token"])
+        _save_field_to_config(path, "workspace_id", config["workspace_id"])
+
+    return config
+
+
+def _load_from_env():
+    """Build minimal config from environment variables only."""
+    token = os.environ.get("CLICKUP_API_TOKEN")
+    if not token:
+        return None
+
+    workspace_id = os.environ.get("CLICKUP_WORKSPACE_ID")
+    if not workspace_id:
+        workspace_id = _auto_detect_workspace(token)
+
+    return {
+        "api_token": token,
+        "workspace_id": workspace_id,
+        "user_id": os.environ.get("CLICKUP_USER_ID", ""),
+        "spaces": {},
+    }
+
+
+def load_config():
+    """Load config from file or environment. Caches after first call."""
+    global _config_cache
+    if _config_cache is not None:
+        return _config_cache
+
+    path = _find_config_path()
+
+    if path:
+        _config_cache = _load_from_file(path)
+        return _config_cache
+
+    env_config = _load_from_env()
+    if env_config:
+        _config_cache = env_config
+        return _config_cache
+
+    error(
+        "No ClickUp configuration found.\n\n"
+        "Set up with one of:\n"
+        "  clickup init                          # interactive setup\n"
+        "  clickup init --token pk_YOUR_TOKEN    # non-interactive setup\n\n"
+        "Or configure manually:\n"
+        "  1. Copy clickup-config.example.json to ~/.config/clickup-cli/config.json\n"
+        "  2. Fill in your API token and workspace ID\n\n"
+        "Or set environment variables:\n"
+        "  export CLICKUP_API_TOKEN=pk_YOUR_TOKEN\n"
+        "  export CLICKUP_WORKSPACE_ID=YOUR_WORKSPACE_ID"
+    )
+
+
+def _reset():
+    """Reset cached config (for testing)."""
+    global _config_cache
+    _config_cache = None
+
+
+# Lazy attribute access — config is loaded on first use, not at import time.
+# This allows `clickup init` to run before any config file exists.
+_ATTR_MAP = {
+    "WORKSPACE_ID": lambda c: c["workspace_id"],
+    "USER_ID": lambda c: c.get("user_id", ""),
+    "SPACES": lambda c: c.get("spaces", {}),
+    "DEFAULT_TAGS": lambda c: c.get("default_tags", []),
+    "DRAFT_TAG": lambda c: c.get("draft_tag", "draft"),
+    "GOOD_AS_IS_TAG": lambda c: c.get("good_as_is_tag", "good as is"),
+    "DEFAULT_PRIORITY": lambda c: c.get("default_priority", 4),
+}
+
+
+def __getattr__(name):
+    if name in _ATTR_MAP:
+        config = load_config()
+        return _ATTR_MAP[name](config)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

clickup_cli/helpers.py

@@ -0,0 +1,163 @@
+"""Shared helper functions for output, errors, and content reading."""
+
+import argparse
+import json
+import sys
+
+
+def add_id_argument(parser, name, help_text):
+    """Add an argument that accepts both positional and --flag forms.
+
+    Agents naturally use flag forms (--task-id) while humans prefer positional.
+    This adds both so either style works.
+
+    Example:
+        add_id_argument(parser, 'task_id', 'ClickUp task ID')
+        # Accepts: `command abc123` OR `command --task-id abc123`
+    """
+    parser.add_argument(name, nargs="?", default=None, help=help_text)
+    flag = f"--{name.replace('_', '-')}"
+    parser.add_argument(
+        flag, dest=f"_{name}_flag", default=None, help=argparse.SUPPRESS
+    )
+
+
+def resolve_id_args(args):
+    """Resolve positional-or-flag ID arguments after parsing.
+
+    For each _<name>_flag attribute, merges with the positional <name>:
+    - If flag provided, use it
+    - If positional provided, use it
+    - If both provided, error
+    - If neither provided, error with helpful message
+    """
+    flag_attrs = [a for a in vars(args) if a.endswith("_flag") and a.startswith("_")]
+    for flag_attr in flag_attrs:
+        base_attr = flag_attr[1:-5]  # strip _ prefix and _flag suffix
+        flag_val = getattr(args, flag_attr)
+        pos_val = getattr(args, base_attr, None)
+        flag_name = f"--{base_attr.replace('_', '-')}"
+
+        if flag_val is not None and pos_val is not None:
+            error(f"Provide {base_attr} as positional or {flag_name}, not both")
+
+        if flag_val is not None:
+            setattr(args, base_attr, flag_val)
+        elif pos_val is None:
+            error(f"Missing required argument: {base_attr} (positional or {flag_name})")
+
+        delattr(args, flag_attr)
+
+
+def output(data, pretty=False):
+    """Print JSON to stdout."""
+    print(json.dumps(data, indent=2 if pretty else None, ensure_ascii=False))
+
+
+def error(msg):
+    """Print error to stderr and exit."""
+    print(f"Error: {msg}", file=sys.stderr)
+    sys.exit(1)
+
+
+def read_content(inline, file_path, flag_name="--content"):
+    """Read content from inline string or file path. Returns string or None."""
+    if inline and file_path:
+        error(f"Cannot use both {flag_name} and {flag_name}-file")
+    if file_path:
+        try:
+            with open(file_path, "r", encoding="utf-8") as f:
+                return f.read()
+        except FileNotFoundError:
+            error(f"File not found: {file_path}")
+    return inline
+
+
+def resolve_space_id(space_arg):
+    """Resolve a space name (from config) or raw space ID."""
+    from .config import SPACES
+
+    if space_arg in SPACES:
+        return SPACES[space_arg]["space_id"]
+    # If it's not numeric, it's likely a misspelled config name
+    if not space_arg.isdigit():
+        available = ", ".join(sorted(SPACES.keys())) if SPACES else "(none configured)"
+        error(f"Unknown space: {space_arg}. Available: {available}")
+    return space_arg
+
+
+def fetch_all_comments(client, task_id):
+    """Fetch all comments for a task, paginating through all pages."""
+    all_comments = []
+    params = None
+    while True:
+        resp = client.get_v2(f"/task/{task_id}/comment", params=params)
+        comments = resp.get("comments", [])
+        if not comments:
+            break
+        all_comments.extend(comments)
+        last = comments[-1]
+        params = {"start": str(last["date"]), "start_id": last["id"]}
+    return all_comments
+
+
+# Default fields for compact task output
+COMPACT_FIELDS = ["id", "name", "status", "priority", "url"]
+
+# Reverse map for priority numbers to names
+PRIORITY_NAMES = {1: "urgent", 2: "high", 3: "normal", 4: "low"}
+
+
+def _extract_status(task):
+    """Extract the status string from a task's status field."""
+    status = task.get("status")
+    return status.get("status") if isinstance(status, dict) else status
+
+
+def _extract_priority(task):
+    """Extract the priority string from a task's priority field."""
+    priority = task.get("priority")
+    if isinstance(priority, dict) and priority:
+        return priority.get("priority") or PRIORITY_NAMES.get(
+            priority.get("orderindex"), "unknown"
+        )
+    return None
+
+
+def compact_task(task):
+    """Return a compact view of a task with only essential fields."""
+    return {
+        "id": task.get("id"),
+        "name": task.get("name"),
+        "status": _extract_status(task),
+        "priority": _extract_priority(task),
+        "url": task.get("url"),
+    }
+
+
+def filter_task_fields(task, fields):
+    """Return only the requested fields from a task.
+
+    Supports nested status/priority extraction: if 'status' or 'priority'
+    is requested, returns the string name rather than the nested object.
+    """
+    extractors = {"status": _extract_status, "priority": _extract_priority}
+    result = {}
+    for field in fields:
+        extractor = extractors.get(field)
+        result[field] = extractor(task) if extractor else task.get(field)
+    return result
+
+
+def format_tasks(tasks, full=False, fields=None):
+    """Apply compact/fields/full formatting to a list of tasks.
+
+    - full=True: return raw API objects unchanged
+    - fields: return only those fields per task
+    - default: return compact view (id, name, status, priority, url)
+    """
+    if full:
+        return tasks
+    if fields:
+        return [filter_task_fields(t, fields) for t in tasks]
+    return [compact_task(t) for t in tasks]

clickup_cli-1.2.0.dist-info/METADATA

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: clickup-cli
+Version: 1.2.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
+Project-URL: Issues, https://github.com/efetoker/clickup-cli/issues
+Project-URL: Changelog, https://github.com/efetoker/clickup-cli/releases
+Author-email: Efe Toker <efetoker@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,api,cli,clickup,task-management
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Scheduling
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.20
+Requires-Dist: urllib3<2
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# clickup-cli
+
+The missing ClickUp CLI. Built for developers and AI agents.
+
+There's no official ClickUp CLI. If you're a developer who lives in the terminal, or an AI agent that needs structured data from ClickUp, this fills the gap. JSON stdout, errors to stderr, dry-run on every mutation.
+
+## Install
+
+```bash
+pip install clickup-cli
+```
+
+## Setup
+
+```bash
+clickup init
+```
+
+This prompts for your API token, discovers your workspaces and spaces, identifies your user, and writes a config file to `~/.config/clickup-cli/config.json`.
+
+If you have a single workspace, it's selected automatically. Same for user detection in single-member workspaces.
+
+Get your API token at [app.clickup.com/settings/apps](https://app.clickup.com/settings/apps).
+
+## Quick Start
+
+```bash
+clickup spaces list                                    # see your spaces
+clickup tasks list --space <name>                     # list tasks
+clickup tasks search "login bug"                       # search across workspace
+clickup tasks get abc123                               # get task + comments
+clickup --dry-run tasks create --space <name> --name "Fix auth"  # preview
+clickup tasks create --space <name> --name "Fix auth" # create for real
+clickup comments add abc123 --text "Done"              # add a comment
+```
+
+## For AI Agents
+
+This CLI is designed to be used by AI coding agents (Claude Code, Codex, etc.) as a tool for interacting with ClickUp.
+
+**What makes it agent-friendly:**
+- All output is JSON on stdout — easy to parse
+- Errors go to stderr with non-zero exit code — easy to detect
+- Every command has detailed `--help` — agents can self-discover usage
+- `--dry-run` on all mutations — agents can preview before acting
+- `--pretty` for readable output during debugging
+- **Flag aliases for all positional args** — agents can use `--task-id`, `--query`, `--doc-id`, `--comment-id` etc. instead of positional arguments (both forms work)
+- **Auto-infer `--space` from `--list`** — `tasks create --list 12345 --name "Fix bug"` works without `--space`
+
+**Plug-and-play skill file:** Copy `.claude/skills/clickup-cli.md` from this repo into your project's `.claude/skills/` directory. It teaches Claude Code how to use the CLI: command discovery, safety patterns, common workflows.
+
+**Minimal system prompt snippet:**
+```
+You have access to the `clickup` CLI for managing ClickUp tasks and docs.
+Use `clickup <group> --help` to discover commands.
+Always use `--dry-run` before mutating commands.
+Output is JSON on stdout; errors go to stderr.
+```
+
+## Commands
+
+| Group | Subcommands | Description |
+|-------|-------------|-------------|
+| `init` | — | Interactive workspace setup |
+| `tasks` | list, get, create, update, search, delete, move, merge | Full task CRUD |
+| `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 |
+| `folders` | list, get, create, update, delete | Folder CRUD |
+| `lists` | list, get, create, update, delete | List CRUD |
+| `spaces` | list, get, statuses | Space inspection |
+| `team` | whoami, members | Workspace and member info |
+| `tags` | list, add, remove | Tag management |
+
+Use `clickup <group> <command> --help` for detailed usage, examples, and return format.
+
+## Global Flags
+
+```
+--pretty     Pretty-print JSON output
+--dry-run    Preview mutations without executing
+--debug      Log API requests and responses to stderr
+--version    Show version
+```
+
+Global flags can appear before or after the command group:
+
+```bash
+clickup --pretty tasks list --space <name>
+clickup tasks list --space <name> --pretty
+```
+
+## Key Behaviors
+
+- **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`.
+- **`tasks create`** auto-infers `--space` from `--list` via API lookup. You can omit `--space` if `--list` is provided.
+- **`tasks get`** auto-fetches comments and appends them to the output. Use `--no-comments` to skip.
+- **`tasks search`** auto-detects task ID patterns like `PROJ-39` and applies prefix filtering.
+- **`tasks create`** checks for duplicates before creating. Use `--skip-dedup` to bypass.
+- **`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`.
+
+## Configuration
+
+### Config file
+
+`clickup init` creates `~/.config/clickup-cli/config.json`:
+
+```json
+{
+  "api_token": "pk_...",
+  "workspace_id": "12345",
+  "user_id": "67890",
+  "spaces": {
+    "myspace": {"space_id": "111", "list_id": "222"}
+  },
+  "default_tags": [],
+  "draft_tag": "draft",
+  "good_as_is_tag": "good as is",
+  "default_priority": 4
+}
+```
+
+### Config resolution order
+
+1. `CLICKUP_CONFIG_PATH` env var → exact file path
+2. `~/.config/clickup-cli/config.json` → default location
+3. `clickup-config.json` in current working directory → project-local override
+
+### Environment variables
+
+| Variable | Purpose |
+|----------|---------|
+| `CLICKUP_API_TOKEN` | API token (overrides config file token) |
+| `CLICKUP_WORKSPACE_ID` | Workspace ID (auto-detected if you have one workspace) |
+| `CLICKUP_USER_ID` | User ID for task assignment |
+| `CLICKUP_CONFIG_PATH` | Custom config file path |
+
+You can run without a config file by setting just `CLICKUP_API_TOKEN` — the workspace ID is auto-detected if your account has a single workspace. Set `CLICKUP_WORKSPACE_ID` explicitly for multi-workspace accounts.
+
+## Coverage and Gaps
+
+**Covered:** tasks, comments, docs/pages, folders, lists, spaces, tags, team/workspace info.
+
+**Not yet covered:** checklists, time tracking, custom fields, task relationships, attachments, goals, webhooks, automations.
+
+## Development Tools
+
+This repo includes automations for contributors using [Claude Code](https://claude.com/claude-code):
+
+- **Auto-lint hook** — ruff check + format runs on every Python file edit
+- **Sensitive file guard** — blocks accidental edits to `.env`, `.key`, `.pem`, and credentials files
+- **context7 MCP** — live ClickUp API docs available during development (via `.mcp.json`)
+- **Skills** — `/release` workflow, `add-command` step-by-step guide, `clickup-cli` usage reference
+- **Subagents** — `test-writer` generates pytest tests following project patterns
+
+These are configured in `.claude/` and `.mcp.json`. Non-Claude-Code contributors can ignore them.
+
+## Contributing
+
+```bash
+git clone https://github.com/efetoker/clickup-cli.git
+cd clickup-cli
+pip install -e ".[dev]"
+pytest -v
+```
+
+Issues and PRs welcome at [github.com/efetoker/clickup-cli](https://github.com/efetoker/clickup-cli).
+
+## License
+
+MIT