ClickUp Framework CLI Reference

Quick reference for the ClickUp Framework CLI (cum / clickup)

Installation

Install from GitHub (Latest)

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

Verify Installation

cum --version
# or
clickup --version

Required: API Token Setup

export CLICKUP_API_TOKEN="your_token_here"
# Or add to ~/.bashrc or ~/.zshrc for persistence

Command Invocation

In Development Environment (working in the repo):

python -m clickup_framework.cli <command> [args]

In Installed Environment:

cum <command> [args]
# or
clickup <command> [args]

How to determine which to use:

1. First check if cum command is available with: which cum or command -v cum
2. If NOT available (returns empty/error), use: python -m clickup_framework.cli
3. If available, use: cum

Quick Reference: All Short Codes

View: h ls l c f fil d st a Context: set show clear Tasks: tc tu td ta tua tss tsp tst tad trd tal trl Comments: ca cl cu cd Docs: dl dg dc du de di pl pc pu

View Commands

Context Management

Context Types: workspace, space, folder, list, task, assignee

Task Management

Task Create Options

IMPORTANT: Task name comes FIRST as a positional argument!

cum tc "Task Name" --list <list_id> [options]
cum tc "Task Name" --parent <parent_id> [options]  # For subtasks

Options:
--list LIST_ID              # List to create task in (or "current")
--parent TASK_ID           # Create as subtask (no --list needed if parent provided)
--description TEXT          # Task description (text)
--description-file PATH     # Task description (from file)
--status STATUS            # Initial status
--priority {1|2|3|4|urgent|high|normal|low}
--tags TAG [...]           # Tags to add
--assignees USER_ID [...]  # Assign users (defaults to context assignee)

Note: --description and --description-file are mutually exclusive.

Task Update Options

--name TEXT                # Update name
--description TEXT         # Update description (text)
--description-file PATH    # Update description (from file)
--status STATUS           # Update status
--priority PRIORITY       # Update priority

Note: --description and --description-file are mutually exclusive.

Comment Management

Comment Options

# Add/Update comments with text or file
comment_text               # Direct text input
--comment-file PATH        # Read comment text from file

Note: Comment text and --comment-file are mutually exclusive.

Docs & Pages

Global Format Options

Presets

Priority Values

Status Codes (3-Letter)

Tasks display with color-coded 3-letter status codes:

• [CLS] Closed/Complete
• [OPN] Open
• [PRG] In Progress
• [REV] In Review
• [BLK] Blocked
• [TDO] To Do
• Custom statuses use first 3 letters

Special Keywords

• current - Use currently set resource from context
• Works with: task_id, list_id, workspace_id, etc.

Common Workflows

# Set up context (using short codes!)
cum set workspace 90151898946
cum set list 901517404278
cum set assignee 68483025

# Quick task view
cum h current                                    # Hierarchy view
cum a                                            # Your assigned tasks
cum st current                                   # Task statistics

# Create and manage tasks (using short codes!)
cum tc "New feature" --list current              # Auto-assigned to default assignee
cum tc "Feature" --list current --description-file spec.md  # With description from file
cum tc "Subtask" --parent <parent_id>            # Create subtask
cum tu current --description-file updated_spec.md    # Update from file
cum tss current "in progress"                    # Set status
cum tst current --add bug critical               # Add tags
cum td <task_id>                                 # Delete task

# Add comments (using short codes!)
cum ca current "Initial thoughts"                # Add comment directly
cum ca current --comment-file notes.txt          # Comment from file
cum cl current                                   # List comments

# Filter tasks
cum fil current --status "in progress"
cum fil current --priority urgent --view-mode flat

# Work with docs (using short codes!)
cum dl 90151898946                               # List docs
cum dc 90151898946 "API Docs"                    # Create doc
cum pc 90151898946 <doc_id> --name "Overview"    # Add page
cum de 90151898946 --output-dir ./docs           # Export all docs

Configuration

Settings stored in ~/.clickup_context.json:

• Current workspace/list/task/assignee
• ANSI color preference
• Last updated timestamp

Tips

• Use short codes everywhere! cum tc instead of cum task_create, cum h instead of cum hierarchy
• Set context once with cum set, use current everywhere
• Default assignee auto-assigns new tasks
• assigned (cum a) command sorts by dependency difficulty
• demo mode works without API token for testing
• Use --description-file and --comment-file for longer content
• Tab complete works with both full commands and short codes
• Most commands support --help for details

Tab Completion

Enable tab completion for bash/zsh (if argcomplete installed):

eval "$(register-python-argcomplete cum)"

Troubleshooting

Command not found: cum

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

# Or use the module directly
python -m clickup_framework.cli --help

API Token Issues

# Check if token is set
echo $CLICKUP_API_TOKEN

# Set it permanently in ~/.bashrc or ~/.zshrc
echo 'export CLICKUP_API_TOKEN="your_token_here"' >> ~/.bashrc
source ~/.bashrc

Permission Errors

# Use virtual environment (recommended)
python -m venv venv
source venv/bin/activate
pip install git+https://github.com/SOELexicon/clickup_framework.git

Getting Help

# General help
cum --help

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

# Examples
cum tc --help
cum h --help
cum tss --help