Clickup Setup Guide

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:

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)

# 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:

# 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):

export CLICKUP_API_TOKEN="pk_your_token_here"

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

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

Windows (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

# 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:

# 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

# Install argcomplete if not already installed
pip install argcomplete

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

Zsh

# 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:

# 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

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

Solution 2: Use the module directly

python -m clickup_framework.cli --help

Solution 3: Check your PATH

# 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:

# 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)

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

# 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:

# 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:

# 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

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

Check Current Version

cum --version

Update in Virtual Environment

# Activate venv
source venv/bin/activate

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

Uninstallation

# 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:

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:

# 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

# General help
cum --help

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

# Demo mode (no token required)
cum demo

# Show current context
cum show

Resources

• GitHub Repository: https://github.com/SOELexicon/clickup_framework
• ClickUp API Docs: https://clickup.com/api
• Get API Token: https://app.clickup.com/settings/apps

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.