clickup-cli

clickup-cli is a command-line tool for calling the ClickUp API, designed for AI agents and human users, covering about 130 endpoints, 28 resource groups, and 4 utility commands.

Purpose The ClickUp API returns enormous responses; for example, querying just 5 tasks can return deeply nested JSON exceeding 12,000 tokens (status, assignees, priority, custom fields, checklists, dependencies, etc.). For AI agents running within a context window, a few API calls can exhaust most of the available context. clickup-cli solves this problem with token-efficient output by default: it flattens nested objects, selects only the necessary fields, and renders compact tables; use --output json when the full response is needed. The tool also provides a simple and predictable interface: clickup-cli <resource> <action> [ID] [flags], with no SDK, authentication boilerplate, or JSON parsing required.

Main capabilities

• Token-efficient output by default, while retaining the --output json option for full output.
• Automatic task ID detection from git branches: ClickUp default IDs (e.g. feat/CU-abc123-foo -> abc123), custom task IDs (e.g. PROJ-42-add-login -> PROJ-42, automatically injecting custom_task_ids=true&team_id=<ws>). Strippable prefixes include feature/, feat/, fix/, hotfix/, bugfix/, release/, chore/, docs/, refactor/, test/, ci/, perf/, build/, style/, etc. Destructive or ambiguous commands (task delete, task link, task unlink, guest share-task, guest unshare-task) are not auto-detected and the ID must be passed explicitly. This can be disabled for a single call via CLICKUP_GIT_DETECT=0, or permanently disabled in the configuration.
• Provides two AI agent integration methods: CLI mode (recommended) and MCP server mode. CLI mode injects a command reference costing about 1,000 tokens, with each command returning compact table output of about 150 tokens (5 tasks), and no tool schema consuming context, making it suitable for any LLM/agent framework; it automatically detects existing files (CLAUDE.md, agent.md, AGENT.md, .cursorrules, .github/copilot-instructions.md), and creates CLAUDE.md if none exists. MCP mode is aimed at tools such as Claude Desktop and Cursor that prefer native tool integration; it can automatically generate an MCP configuration or you can manually add .mcp.json, exposing 144 tools covering 100% of the ClickUp API, but the tool schema consumes more tokens than the CLI reference approach.
• MCP tools can be restricted: by default all 144 tools are exposed, but they can be restricted at startup via flags and environment variables such as --read-only, task-focused (only the task + comment + time groups), etc.; filtered tools are hidden in tools/list and rejected in tools/call.
• OAuth supports bring-your-own app: you can set CLICKUP_OAUTH_CLIENT_ID and CLICKUP_OAUTH_CLIENT_SECRET (or --client-id / --client-secret); you need to register the exact redirect address http://127.0.0.1:53682/callback（--redirect-port The port can be changed). Supports --no-browser, --keyring, auth status, auth logout. Does not include a maintainer key or proxy. Live loopback acceptance and token response validation are still pending.
• Token resolution priority: --token CLI flag (personal by default, --token-kind oauth selects OAuth) → CLICKUP_TOKEN environment variable (personal) → CLICKUP_OAUTH_TOKEN environment variable (OAuth) → nearest ancestor .clickup.toml → OS global configuration (~/.config/clickup-cli/config.toml on Linux). [auth] kind = "oauth" selects OAuth; if omitted, personal is the default. Default is file storage; storage = "keychain" explicitly selects the system keychain and fails if unavailable. Personal tokens send Authorization: <token>; OAuth tokens send Authorization: Bearer <token>, including uploads and MCP. CLICKUP_CONFIG can specify a single configuration path and disables discovery.
• Workspace resolution priority: --workspace CLI flag → CLICKUP_WORKSPACE environment variable → project-level .clickup.toml → global ~/.config/clickup-cli/config.toml.

Usage Installation methods include: npm (any platform with Node.js), Homebrew (macOS or Linux; Linux also has native x86_64 and arm64 binaries), macOS/Linux precompiled binaries, Alpine/musl Linux, Arch Linux (clickup-cli-bin from the AUR, no Rust toolchain required), Windows (download clickup-windows-x86_64.zip, extract it, and add clickup-cli.exe and optionally clkup.exe to PATH), crates.io (requires Rust 1.70+). Every installation method provides two binaries with identical behavior: clickup-cli (the canonical name, used for scripts, CI, and MCP configuration) and clkup (a short alias). You can verify the installation, create a project-level configuration (generates .clickup.toml; if it contains a token, add it to .gitignore; project configuration takes precedence over global configuration), use shell completion, and view the current configuration.

Use cases Users who need to provide ClickUp API access for AI agents or scripts, want to significantly reduce token consumption, or need to cover both CLI and MCP roles without relying on the Node/Python toolchain.

Limitations Specific pricing and fee information is not provided in the repository materials; OAuth live loopback acceptance and token response validation are still pending; destructive commands do not automatically identify task IDs. Other ClickUp-related tools exist in the community and can be chosen based on the use case.