clickup-restish-cli

A lightweight ClickUp CLI setup using Restish and ClickUp's official OpenAPI specs. Covers the full v2 + v3 API surface — tasks, comments with @mentions, Chat messaging, members, sprints, and more.

No code generation. No build step. Restish reads the OpenAPI spec at runtime, so new ClickUp endpoints are available automatically.

Why this exists

ClickUp's existing CLI tools only cover the v2 API (tasks, comments, sprints). The v3 API — which includes Chat, Docs, and newer endpoints — has no CLI coverage anywhere. ClickUp's MCP server is similarly limited: no @mention support in comments, no structured rich text.

This setup gives you:

Capability	ClickUp MCP	This
Task CRUD	Yes	Yes
Comments with @mentions	No	Yes
Chat messages (v3)	Plain text only	Yes
Members, Spaces, Sprints	Yes	Yes
Speed	Slow (MCP overhead)	~0.6s per call
Token cost (AI agents)	High (schema in context)	Low (JSON in/out)

Setup

1. Install Restish

# Linux (amd64)
gh release download --repo rest-sh/restish --pattern 'restish-*-linux-amd64.tar.gz' --dir /tmp
tar -xzf /tmp/restish-*-linux-amd64.tar.gz -C /tmp
mv /tmp/restish ~/.local/bin/restish
chmod +x ~/.local/bin/restish

# macOS (Apple Silicon)
gh release download --repo rest-sh/restish --pattern 'restish-*-darwin-arm64.tar.gz' --dir /tmp
tar -xzf /tmp/restish-*-darwin-arm64.tar.gz -C /tmp
mv /tmp/restish /usr/local/bin/restish

# Or via Homebrew
brew install restish

2. Get your ClickUp API token

Go to ClickUp → Settings → ClickUp API → Personal API Tokens and generate a token (pk_...).

3. Configure Restish

mkdir -p ~/.config/restish
cp apis-template.json ~/.config/restish/apis.json

Edit ~/.config/restish/apis.json and replace YOUR_TOKEN_HERE with your API token.

4. Verify

# Should return your workspace info
restish clickup-v2/team/YOUR_WORKSPACE_ID

# Should list chat channels
restish clickup-v3/workspaces/YOUR_WORKSPACE_ID/chat/channels

Find your workspace ID in the ClickUp URL: https://app.clickup.com/WORKSPACE_ID/home

Usage

Tasks

# Get a task
restish clickup-v2/task/TASK_ID

# Create a task
echo '{"name": "New task", "description": "Details"}' | restish post clickup-v2/list/LIST_ID/task

# Update a task
echo '{"status": "in progress"}' | restish put clickup-v2/task/TASK_ID

# Search tasks (by list)
restish clickup-v2/list/LIST_ID/task

Comments with @mentions

Plain comments:

echo '{"comment_text": "Deployed to staging"}' | restish post clickup-v2/task/TASK_ID/comment

Comments with real @mentions (triggers notifications):

# Using the wrapper script
python3 clickup_mention_comment.py --task TASK_ID --message "Hey @Roman Naidenko check this"

# Multiple mentions
python3 clickup_mention_comment.py --task TASK_ID --message "@Alice @Bob ready for QA"

Or construct the structured JSON manually:

echo '{
  "comment": [
    {"text": "Hey "},
    {"type": "tag", "user": {"id": USER_ID}},
    {"text": " can you review this?"}
  ]
}' | restish post clickup-v2/task/TASK_ID/comment

Chat messages (v3)

# Send a message
restish post clickup-v3/workspaces/WORKSPACE_ID/chat/channels/CHANNEL_ID/messages \
  type: message, content: "Hello from the CLI"

# List channels
restish clickup-v3/workspaces/WORKSPACE_ID/chat/channels

# Get messages from a channel
restish clickup-v3/workspaces/WORKSPACE_ID/chat/channels/CHANNEL_ID/messages

Members

# List all workspace members (get user IDs for @mentions)
restish clickup-v2/team/WORKSPACE_ID

The @mention wrapper

clickup_mention_comment.py is a thin Python script that:

1. Fetches workspace members from the ClickUp API
2. Parses @Name references in your message (case-insensitive, longest match first)
3. Builds the structured comment array with "type": "tag" blocks
4. Posts via Restish

Requirements: Python 3.8+, requests, python-dotenv, Restish on PATH.

pip install requests python-dotenv

Set CLICKUP_API_TOKEN as an environment variable or in a .env file.

Known limitations

• Chat @mentions are not possible. The ClickUp v3 Chat API has no mention mechanism — this is an API-level limitation, not a tooling gap. Plain text messages work fine.
• Restish doesn't auto-generate subcommands. You use URI paths directly (e.g., restish clickup-v2/task/ID), not restish task get ID. This is actually an advantage — any new endpoint ClickUp adds works immediately without a CLI update.

How it works

Restish is a generic REST client that reads OpenAPI specs at runtime. The apis-template.json config points it at ClickUp's official specs:

• v2: https://developer.clickup.com/openapi/clickup-api-v2-reference.json — tasks, comments, lists, spaces, members, sprints, goals, webhooks, etc.
• v3: https://developer.clickup.com/openapi/ClickUp_PUBLIC_API_V3.yaml — chat, docs, attachments, audit logs (35 endpoints, 19 of which are Chat).

When ClickUp updates their API and publishes new endpoints in the spec, they're available in Restish automatically.

License

MIT