Agent skill

clickup-setup-guide

Complete setup and installation guide for the ClickUp Framework CLI with troubleshooting

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/setup-guide

SKILL.md

ClickUp Framework Setup Guide

Complete guide to installing and configuring the ClickUp Framework CLI.

Prerequisites

  • Python 3.8 or higher
  • pip (Python package installer)
  • Git (for installation from repository)
  • ClickUp API Token (Get one here)

Installation

Method 1: Install from GitHub (Recommended)

Install the latest version directly from GitHub:

bash
pip install --upgrade --force-reinstall git+https://github.com/SOELexicon/clickup_framework.git

Flags explained:

  • --upgrade: Upgrade if already installed
  • --force-reinstall: Force reinstall even if up-to-date
  • git+https://...: Install from Git repository

Method 2: Install in Virtual Environment (Recommended for Development)

bash
# Create virtual environment
python -m venv venv

# Activate it
source venv/bin/activate  # On Linux/Mac
# or
venv\Scripts\activate     # On Windows

# Install the framework
pip install git+https://github.com/SOELexicon/clickup_framework.git

Method 3: Development Installation

If you're developing the framework itself:

bash
# Clone the repository
git clone https://github.com/SOELexicon/clickup_framework.git
cd clickup_framework

# Install in editable mode
pip install -e .

# Use the module directly
python -m clickup_framework.cli --help

Configuration

1. Get Your ClickUp API Token

  1. Go to ClickUp Settings > Apps
  2. Click "Generate" under "API Token"
  3. Copy your token (it looks like: pk_12345678_ABCDEFGHIJKLMNOPQRSTUVWXYZ)

2. Set Environment Variable

Linux/Mac (Temporary - current session only):

bash
export CLICKUP_API_TOKEN="pk_your_token_here"

Linux/Mac (Permanent - add to ~/.bashrc or ~/.zshrc):

bash
echo 'export CLICKUP_API_TOKEN="pk_your_token_here"' >> ~/.bashrc
source ~/.bashrc

Windows (PowerShell):

powershell
$env:CLICKUP_API_TOKEN="pk_your_token_here"

# Or permanently:
[System.Environment]::SetEnvironmentVariable('CLICKUP_API_TOKEN', 'pk_your_token_here', 'User')

3. Verify Installation

bash
# Check if command is available
cum --version
# or
clickup --version

# Test with demo mode (no token required)
cum demo

# Test with your token
cum show

4. Set Up Context

Set your default workspace and list for easier command usage:

bash
# Set workspace (find ID in ClickUp URL or use cum demo)
cum set workspace <workspace_id>

# Set default list
cum set list <list_id>

# Set default assignee (your user ID)
cum set assignee <user_id>

# Verify context
cum show

Optional: Enable Tab Completion

Bash

bash
# Install argcomplete if not already installed
pip install argcomplete

# Add to ~/.bashrc
echo 'eval "$(register-python-argcomplete cum)"' >> ~/.bashrc
source ~/.bashrc

Zsh

bash
# Install argcomplete if not already installed
pip install argcomplete

# Add to ~/.zshrc
echo 'eval "$(register-python-argcomplete cum)"' >> ~/.zshrc
source ~/.zshrc

Verification Checklist

Run these commands to verify everything is working:

bash
# 1. Command is available
which cum
# Should show: /usr/local/bin/cum or similar

# 2. Token is set
echo $CLICKUP_API_TOKEN
# Should show: pk_...

# 3. Can connect to API
cum show
# Should show: Current context (even if empty)

# 4. Can view tasks
cum a
# Should show: Your assigned tasks

# 5. Context is working
cum set workspace <workspace_id>
cum show
# Should show: Current workspace ID

Troubleshooting

Issue: command not found: cum

Solution 1: Reinstall the package

bash
pip install --upgrade --force-reinstall git+https://github.com/SOELexicon/clickup_framework.git

Solution 2: Use the module directly

bash
python -m clickup_framework.cli --help

Solution 3: Check your PATH

bash
# Find where pip installs executables
pip show clickup_framework | grep Location

# Add to PATH if needed (in ~/.bashrc or ~/.zshrc)
export PATH="$PATH:$HOME/.local/bin"

Issue: 401 Unauthorized or API errors

Causes:

  • Token not set
  • Token expired or invalid
  • Token doesn't have required permissions

Solution:

bash
# Check if token is set
echo $CLICKUP_API_TOKEN

# If empty, set it
export CLICKUP_API_TOKEN="pk_your_token_here"

# Test the token
cum show

# If still failing, regenerate token in ClickUp settings

Issue: Permission denied or pip warnings

Symptom:

WARNING: The directory '/root/.cache/pip' or its parent directory is not owned...
WARNING: Running pip as the 'root' user...

Solution: Use a virtual environment (recommended)

bash
python -m venv venv
source venv/bin/activate
pip install git+https://github.com/SOELexicon/clickup_framework.git

Issue: Python version too old

Symptom:

ERROR: Package requires Python '>=3.8'

Solution: Upgrade Python

bash
# Ubuntu/Debian
sudo apt update
sudo apt install python3.10

# Mac (using Homebrew)
brew install python@3.10

# Verify
python3 --version

Issue: SSL Certificate errors

Symptom:

SSL: CERTIFICATE_VERIFY_FAILED

Solution:

bash
# Update certificates (Mac)
/Applications/Python\ 3.x/Install\ Certificates.command

# Or upgrade certifi
pip install --upgrade certifi

# Or temporarily disable (not recommended for production)
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org git+https://github.com/SOELexicon/clickup_framework.git

Issue: Commands are slow

Causes:

  • Network latency
  • Large task lists
  • Complex hierarchies

Solutions:

bash
# Use minimal preset for faster rendering
cum h current --preset minimal

# Filter to specific status
cum fil current --status "in progress"

# Disable colors if terminal is slow
cum ansi disable

# Use flat view instead of hierarchy
cum f current

Updating

Update to Latest Version

bash
pip install --upgrade --force-reinstall git+https://github.com/SOELexicon/clickup_framework.git

Check Current Version

bash
cum --version

Update in Virtual Environment

bash
# Activate venv
source venv/bin/activate

# Update
pip install --upgrade --force-reinstall git+https://github.com/SOELexicon/clickup_framework.git

Uninstallation

bash
# Uninstall the package
pip uninstall clickup_framework

# Remove configuration (optional)
rm ~/.clickup_context.json

# Remove environment variable (remove from ~/.bashrc or ~/.zshrc)
# Then reload shell:
source ~/.bashrc

Docker Installation (Advanced)

Create a Dockerfile for containerized usage:

dockerfile
FROM python:3.10-slim

# Install ClickUp Framework
RUN pip install --no-cache-dir git+https://github.com/SOELexicon/clickup_framework.git

# Set token via environment
ENV CLICKUP_API_TOKEN=""

# Default command
CMD ["cum", "--help"]

Build and run:

bash
# Build
docker build -t clickup-cli .

# Run (pass token)
docker run -e CLICKUP_API_TOKEN="pk_your_token" clickup-cli cum a

Next Steps

After installation:

  1. Set up context: Run cum set workspace <id> and cum set list <id>
  2. View your tasks: Run cum a to see assigned tasks
  3. Learn the workflow: See the Workflow skill or run /workflow in Claude Code
  4. Explore commands: Run /cum for complete CLI reference
  5. Enable tab completion: Follow the optional steps above

Getting Help

bash
# General help
cum --help

# Command-specific help
cum <command> --help

# Demo mode (no token required)
cum demo

# Show current context
cum show

Resources

For command reference: See the CLI Reference skill or run /cum in Claude Code. For workflow guide: See the Workflow skill or run /workflow in Claude Code.

Didn't find tool you were looking for?

Be as detailed as possible for better results