clickup-cli 1.2.0__tar.gz

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

@@ -0,0 +1,39 @@
+---
+name: test-writer
+description: Generate pytest tests for clickup-cli commands following existing test patterns in tests/test_cli.py
+---
+
+# Test Writer Agent
+
+You generate pytest tests for the clickup-cli project.
+
+## Before Writing Tests
+
+1. Read `tests/conftest.py` for the test config setup pattern
+2. Read `tests/test_cli.py` for existing patterns (FakeClient, Namespace, etc.)
+3. Read the source file you're writing tests for
+
+## Conventions
+
+- Use `unittest.TestCase` classes (matching existing style)
+- Use `FakeClient` for API call mocking — do NOT make real HTTP calls
+- Use `unittest.mock.patch` and `MagicMock` for things FakeClient doesn't cover
+- Use `argparse.Namespace` to construct fake args
+- Test these for every command:
+  - Argument parsing (parser accepts the expected args)
+  - `--dry-run` behavior (mutating commands return preview, don't call API)
+  - Normal execution with mocked responses
+  - Error cases (missing required args, API errors)
+- All output assertions should check JSON structure
+- Put tests in `tests/test_cli.py` or a new `tests/test_<group>.py` file
+
+## Example Pattern
+
+```python
+class TestTasksSearch(unittest.TestCase):
+    def test_search_dry_run(self):
+        client = FakeClient(dry_run=True)
+        args = Namespace(query="test", space="testspace", ...)
+        result = cmd_tasks_search(client, args)
+        self.assertIn("dry_run", result)
+```

clickup_cli-1.2.0/.claude/settings.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "filepath=\"$TOOL_INPUT_FILE_PATH$TOOL_INPUT_file_path\"; if echo \"$filepath\" | grep -qE '\\.py$'; then ruff check --fix --quiet \"$filepath\" 2>/dev/null; ruff format --quiet \"$filepath\" 2>/dev/null; fi; true"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "filepath=\"$TOOL_INPUT_FILE_PATH$TOOL_INPUT_file_path\"; if echo \"$filepath\" | grep -qE '\\.(env|secret|pem|key)$|credentials'; then echo 'BLOCKED: refusing to edit sensitive file'; exit 1; fi"
+          }
+        ]
+      }
+    ]
+  }
+}

clickup_cli-1.2.0/.claude/skills/add-command.md

@@ -0,0 +1,75 @@
+---
+name: add-command
+description: Step-by-step workflow for adding a new CLI command to clickup-cli, with verification at each step.
+---
+
+# Add a New CLI Command
+
+Follow these steps in order when adding a new command or subcommand.
+
+## 1. Create or extend the command module
+
+- If this is a new command group, create `src/clickup_cli/commands/<group>.py`
+- If extending an existing group, add the handler function to the existing file
+- Handler signature: `def cmd_<group>_<command>(client, args):`
+- Return a dict (will be output as JSON)
+- Mutating commands must check `client.dry_run` and return a dry-run preview instead of calling the API
+
+## 2. Add or extend the parser in the same module
+
+- Each command module owns its parser via `register_parser(subparsers, F)`
+- If extending an existing group, add the new subparser inside the existing `register_parser()`
+- If creating a new group, add a `register_parser(subparsers, F)` function that creates the group parser and all its subparsers
+- Add the subparser with:
+  - `description=` — what this command does
+  - `epilog=` — usage examples (at least 2)
+  - `formatter_class=F` (passed in as argument)
+- Add all arguments with `help=` text
+- For mutating commands, `--dry-run` is handled globally (no per-command flag needed)
+
+## 3. Register the handler
+
+- Open `src/clickup_cli/commands/__init__.py`
+- Import the new handler function
+- Add it to the `HANDLERS` dict with key `"<group>_<command>"`
+
+## 3b. Wire up new command groups in cli.py (new groups only)
+
+- If this is a new command group, open `src/clickup_cli/cli.py`
+- Import `register_parser` from the new module
+- Call it in `build_parser()` alongside the other `register_parser()` calls
+
+## 4. Write help text
+
+- The `--help` output must be self-sufficient for an agent to use the command correctly
+- Include concrete examples in the epilog
+- Never use real workspace IDs, space names, or tokens in examples — use `<placeholders>`
+
+## 5. Add tests
+
+- Open `tests/test_cli.py` (or create a new test file if the group is large)
+- Test argument parsing (parser accepts the new args)
+- Test dry-run behavior (mutating commands return dry-run preview)
+- Test core logic with `FakeClient`
+
+## 6. Verify
+
+Run these commands and confirm all pass before considering the work done:
+
+```bash
+# Lint
+ruff check src/ tests/
+
+# Tests
+pytest -v
+
+# Help text renders correctly
+clickup <group> <command> --help
+
+# Validate CLI output contract
+scripts/validate-cli-output.sh
+```
+
+## 7. Update the skill (if needed)
+
+If the new command adds a new workflow pattern, update `.claude/skills/clickup-cli.md` with a usage example.

clickup_cli-1.2.0/.claude/skills/clickup-cli.md

@@ -0,0 +1,93 @@
+---
+name: clickup-cli
+description: Use the clickup CLI to manage ClickUp tasks, comments, docs, folders, lists, spaces, and tags from the command line. JSON output, dry-run support.
+---
+
+# ClickUp CLI Skill
+
+You have access to the `clickup` CLI for managing ClickUp workspaces.
+
+## Discovery
+
+Always start by discovering available commands:
+
+```bash
+clickup --help                    # list all command groups
+clickup <group> --help            # list subcommands in a group
+clickup <group> <command> --help  # full usage for a specific command
+```
+
+## Safety
+
+Before any mutating command (create, update, delete), use `--dry-run`:
+
+```bash
+clickup --dry-run tasks create --space <space_name> --name "New task"
+```
+
+Global flags (`--pretty`, `--dry-run`, `--debug`) can appear before or after the command group.
+
+## Output
+
+- Successful output is always JSON on stdout
+- Errors go to stderr with non-zero exit code
+- Use `--pretty` for indented JSON when reading output
+- Use `--full` on task list/search for raw API response
+
+## Common Workflows
+
+### Find and read a task
+```bash
+clickup tasks search "login bug" --space <space_name>
+clickup tasks get <task_id>
+```
+
+### Create a task
+```bash
+clickup --dry-run tasks create --space <space_name> --name "Fix auth" --desc "Details"
+clickup tasks create --space <space_name> --name "Fix auth" --desc "Details"
+```
+
+### Add a comment
+```bash
+clickup comments add <task_id> --text "Work complete"
+clickup comments add <task_id> --file report.md
+```
+
+### Read and edit docs
+```bash
+clickup docs list --space <space_name>
+clickup docs pages <doc_id>
+clickup docs get-page <doc_id> <page_id>
+clickup docs edit-page <doc_id> <page_id> --content-file updated.md
+clickup docs edit-page <doc_id> <page_id> --content "New section" --append
+```
+
+### Discover workspace structure
+```bash
+clickup spaces list
+clickup folders list --space <space_name>
+clickup lists list --folder <folder_id>
+clickup spaces statuses <space_name>
+```
+
+## Configuration
+
+The CLI loads config from (in order):
+1. `CLICKUP_CONFIG_PATH` env var
+2. `~/.config/clickup-cli/config.json`
+3. `clickup-config.json` in current directory
+
+Or use environment variables only:
+- `CLICKUP_API_TOKEN` (required)
+- `CLICKUP_WORKSPACE_ID` (auto-detected for single-workspace accounts)
+
+Run `clickup init` for interactive setup.
+
+## Key Behaviors
+
+- `tasks get` auto-fetches comments (use `--no-comments` to skip)
+- `tasks search` auto-detects task ID patterns (e.g. "PROJ-39") and applies prefix filtering
+- `tasks create` checks for duplicates before creating (use `--skip-dedup` to bypass)
+- Tag names are auto-lowercased (ClickUp API requirement)
+- Doc ID ≠ page ID — always use `docs pages` to find page IDs first

clickup_cli-1.2.0/.claude/skills/release/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: release
+description: Bump version, validate, tag, and build for PyPI release
+disable-model-invocation: true
+---
+
+# Release Workflow
+
+Follow these steps to publish a new release of clickup-cli.
+
+## 1. Pre-flight checks
+
+```bash
+ruff check src/ tests/
+pytest -v
+clickup --help  # smoke test
+```
+
+All must pass before proceeding.
+
+## 2. Bump version
+
+The version is in `src/clickup_cli/__init__.py`. Update it following semver:
+- **patch** (0.x.Y): bug fixes
+- **minor** (0.X.0): new commands or features
+- **major** (X.0.0): breaking changes
+
+## 3. Update changelog
+
+If `CHANGELOG.md` exists, add an entry for the new version with a summary of changes since the last tag:
+
+```bash
+git log $(git describe --tags --abbrev=0)..HEAD --oneline
+```
+
+## 4. Commit and tag
+
+```bash
+git add -A
+git commit -m "release: v<version>"
+git tag v<version>
+```
+
+## 5. Build
+
+```bash
+pip install build
+python -m build
+```
+
+Verify the dist/ output looks correct (check file sizes, version in filenames).
+
+## 6. Publish (requires user confirmation)
+
+**Ask the user before running this step.**
+
+```bash
+pip install twine
+twine upload dist/*
+```
+
+## 7. Push
+
+```bash
+git push origin main --tags
+```

clickup_cli-1.2.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.11", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check src/ tests/
+
+      - name: Test
+        run: pytest -v

clickup_cli-1.2.0/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Config with real tokens
+clickup-config.json
+.env
+.env.*
+
+# Workflow artifacts
+.planning/
+.audit/
+
+# Local-only Claude Code settings (permissions, etc.)
+.claude/settings.local.json

clickup_cli-1.2.0/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
+    }
+  }
+}

clickup_cli-1.2.0/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+## 1.2.0 (2026-03-29)
+
+- Accept flag aliases for all positional arguments — agents can now use `--task-id`, `--query`, `--doc-id`, `--page-id`, `--folder-id`, `--list-id`, `--comment-id`, `--space` instead of positional args. Both forms work; positional args are unchanged for backwards compatibility.
+- Auto-infer `--space` from `--list` on `tasks create` — when `--list` is provided without `--space`, the CLI fetches the list metadata via API to resolve its parent space automatically. Eliminates the most common agent error (12+ failures in 3 days).
+- Make `--space` optional on `tasks create` (was required) — now only required if `--list` is also absent.
+- Expand test suite to 305 tests — full behavioral coverage for `cmd_init` (12 tests), `main()` integration (4 tests), `cmd_docs_create` content paths (3 tests), and 429 retry edge case (1 test).
+- Simplify codebase: use shared `error()` in config.py, DRY up tag add/remove, task list/search epilogue, list folder/space resolution, client retry logic. -24 net lines across 7 files.
+
+## 1.1.3 (2026-03-29)
+
+- Refactor: split 1633-line `build_parser()` — each command module now owns its parser via `register_parser()`
+- Refactor: extract shared `_paginate_tasks()` helper, removing duplicate pagination logic in tasks list/search
+- Refactor: extract `_extract_status()` and `_extract_priority()` helpers in helpers.py, deduplicating field extraction
+- Clean up dead code in `client.py` (unreachable None guards, pointless variable rename)
+- Expand test suite from 55 to 89 tests — comprehensive parser coverage for all 8 command groups
+- Fix stale version assertion in tests (was checking 1.1.0 instead of current version)
+
+## 1.1.2 (2026-03-29)
+
+- Add auto-lint hook — ruff check/format runs automatically on every Python file edit
+- Add sensitive file guard — blocks edits to `.env`, `.secret`, `.pem`, `.key`, and credentials files
+- Add context7 MCP server (`.mcp.json`) — live ClickUp API docs for contributors
+- Add `test-writer` subagent (`.claude/agents/`) — generates pytest tests following project patterns
+- Add `/release` skill — version bump, validate, tag, build, publish workflow
+- Clean up permission allowlist in `.claude/settings.local.json`
+
+## 1.1.1 (2026-03-29)
+
+- Add `.env` and `.env.*` to `.gitignore` for API token safety
+- Add `scripts/validate-cli-output.sh` — validates all CLI help commands, error routing, and version flag
+- Add `.claude/skills/add-command.md` — prescriptive dev workflow for adding new commands
+- Replace hardcoded `myspace` with `<name>` / `<space_name>` placeholders in skill and README
+
+## 1.1.0 (2026-03-29)
+
+- Auto-detect workspace ID for single-workspace accounts — no need to set it manually
+- Fix user detection in `clickup init` — now prompts for selection in multi-member workspaces
+- workspace_id is saved back to config file after auto-detection
+- Add `--debug` flag — logs API requests and responses to stderr for troubleshooting
+- Improve space name resolution — clear error with available names when a space isn't found in config
+- Fix comment pagination — no longer hardcodes page size assumption
+
+## 1.0.0 (2026-03-28)
+
+Initial public release.
+
+- 8 command groups: tasks, comments, docs, folders, lists, spaces, team, tags
+- Full task CRUD with search, move, merge
+- Full comment CRUD with threading
+- Docs management with page editing
+- Folder and list management
+- Tag management
+- Workspace discovery via `clickup init`
+- JSON-only stdout, errors to stderr
+- Dry-run mode for all mutations
+- Rate limit handling with automatic retry
+- Config via JSON file or environment variables

clickup_cli-1.2.0/CLAUDE.md

@@ -0,0 +1,76 @@
+# ClickUp CLI — Development Instructions
+
+## What This Is
+
+A ClickUp CLI for developers and AI agents. JSON-only stdout, errors to stderr, dry-run on all mutations.
+
+## Package Structure
+
+```
+src/clickup_cli/
+├── cli.py           # root parser, dispatch, main() — delegates to command modules
+├── client.py        # ClickUpClient API wrapper (rate limiting, dry-run, debug)
+├── config.py        # Config loader (lazy, fallback chain, workspace auto-detect)
+├── helpers.py       # output(), error(), compact_task(), etc.
+└── commands/
+    ├── __init__.py  # HANDLERS dict
+    ├── tasks.py     # tasks parser + handlers (list/get/create/update/search/delete/move/merge)
+    ├── comments.py  # comments parser + handlers (list/add/update/delete/thread/reply)
+    ├── docs.py      # docs parser + handlers (list/get/create/pages/get-page/edit-page/create-page)
+    ├── folders.py   # folders parser + handlers (list/get/create/update/delete)
+    ├── lists.py     # lists parser + handlers (list/get/create/update/delete)
+    ├── spaces.py    # spaces parser + handlers (list/get/statuses)
+    ├── tags.py      # tags parser + handlers (list/add/remove)
+    ├── team.py      # team parser + handlers (whoami/members)
+    └── init.py      # clickup init setup command
+```
+
+Each command module owns both its argparse parser definition (`register_parser()`) and its handler functions. `cli.py` builds the root parser and delegates to each module's `register_parser(subparsers, F)`.
+
+## Argument Pattern: Positional + Flag Aliases
+
+Every positional argument (task_id, query, doc_id, page_id, etc.) also accepts a `--flag` form via `add_id_argument()` from helpers.py. This makes the CLI usable by both humans (positional) and AI agents (flags).
+
+```python
+# In register_parser():
+add_id_argument(parser, "task_id", "ClickUp task ID")
+
+# Accepts both:
+#   clickup tasks get abc123
+#   clickup tasks get --task-id abc123
+```
+
+Resolution happens in `cli.py` via `resolve_id_args(args)` after parsing. If both forms are provided, it errors. If neither is provided, it errors with a helpful message.
+
+When adding new commands with ID arguments, always use `add_id_argument()` instead of `parser.add_argument()` for positional IDs.
+
+## Space Inference
+
+`tasks create` auto-infers `--space` from `--list` via a lazy API lookup (`GET /v2/list/{id}`). The `_infer_space_from_list()` function in tasks.py reverse-maps the space ID to a config name. This eliminates the most common agent error.
+
+## Development Setup
+
+```bash
+pip install -e ".[dev]"
+pytest -v
+ruff check src/ tests/
+```
+
+## Adding a New Command
+
+1. Create or extend a file in `src/clickup_cli/commands/`
+2. Add the handler function and `register_parser()` in the same module
+3. Register the handler in `commands/__init__.py` HANDLERS dict
+4. If it's a new command group, call `register_parser()` from `cli.py`'s `build_parser()`
+5. Add detailed `--help` text (description + epilog with examples)
+6. Mutating commands must support `--dry-run`
+7. All output goes to stdout as JSON, errors to stderr
+8. Add tests in `tests/`
+
+## Rules
+
+- Help text must be self-sufficient — an agent should use `--help` to discover correct usage
+- No workspace-specific values in help text or source code
+- Stdout is always JSON. Errors and warnings go to stderr.
+- Every mutation supports `--dry-run`
+- Config is lazy-loaded — the `init` command works without any config file

clickup_cli-1.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Efe Toker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.