Complete Setup Guide¶

Comprehensive guide for adding ClickUp auto-sync to any bd project.

Quick setup? See QUICKSTART.md for a 30-second version.

Table of Contents¶

Prerequisites
Installation
Configuration
Testing
Usage
Field Mappings
Filters
Troubleshooting
Advanced

Prerequisites¶

BD installed and initialized (bd init)
Devbox configured (optional but recommended)
ClickUp account with API access
Python 3.11+ with requests and pyyaml

Installation¶

Recommended: Interactive Setup Script¶

Clone the integration package and run scripts/setup.sh from your project directory:

# Clone once (first time only)
git clone git@github.com:latentsp/bd-clickup-integration.git ~/projects/bd-clickup-integration

# Run interactive setup from your project
cd /path/to/your/project
~/projects/bd-clickup-integration/scripts/setup.sh

The script prompts you to configure: - Core files (CLAUDE.md, AGENTS.md, issue templates) - ClickUp integration (config, API token, field detection) - Cursor MCP and Claude Code plugin - Git and bd initialisation

Run with --yes for non-interactive (all defaults):

~/projects/bd-clickup-integration/scripts/setup.sh --yes

Manual Installation¶

If you prefer to set things up manually:

Step 1: Clone and Install Package¶

# Clone the repository (first time only)
git clone git@github.com:latentsp/bd-clickup-integration.git ~/projects/bd-clickup-integration

# Install in your project
cd /path/to/your/project
uv add --editable ~/projects/bd-clickup-integration

Why editable mode? All projects share the same code — update once, all projects benefit.

Step 2: Configure PATH¶

Add the wrapper to your PATH so bd commands trigger auto-sync.

Option A: Shell Profile

Add to ~/.bashrc or ~/.zshrc:

export PATH="$HOME/projects/bd-clickup-integration:$PATH"

Option B: Alias

Add to ~/.bashrc or ~/.zshrc:

alias bd='~/projects/bd-clickup-integration/bd'

Configuration¶

Step 3: Create Integration Directory¶

mkdir -p .beads/integrations/clickup

Step 4: Create Configuration File¶

Copy the example and customize:

cp ~/projects/bd-clickup-integration/config.yaml.example \
   .beads/integrations/clickup/config.yaml

Or create from scratch:

# ClickUp Integration Configuration
# Package: ~/projects/bd-clickup-integration

clickup:
  workspace_id: "YOUR_WORKSPACE_ID"
  default_list_id: "YOUR_LIST_ID"

sync:
  enabled: true
  direction: "bidirectional"
  auto_create: true
  auto_update: true

field_mapping:
  status:
    open: "to do"
    in_progress: "in progress"
    completed: "completed"
    closed: "completed"

  priority:
    p0: 1  # Urgent
    p1: 2  # High
    p2: 3  # Normal
    p3: 4  # Low
    p4: 4  # Low

  labels_to_tags: true
  use_external_ref: true

filters:
  exclude_labels: ["no-sync"]

conflict_resolution:
  strategy: "last-write-wins"

advanced:
  sync_hierarchical: true
  max_retries: 3

Step 5: Set API Token¶

Add to your project's .env file:

echo "CLICKUP_API_TOKEN=pk_your_token_here" >> .env

Get your token: 1. Visit https://app.clickup.com/settings/apps 2. Click "Generate" under "API Token" 3. Copy the token (starts with pk_)

Important: Ensure .env is in your .gitignore!

Step 6: Find Your ClickUp List ID¶

Open ClickUp and navigate to your desired list
Look at the URL: https://app.clickup.com/.../v/li/123456789
The number after /li/ is your default_list_id
Update config.yaml with this ID

Testing¶

Verify Setup¶

# Enter devbox shell (if using devbox)
devbox shell

# Check wrapper is in PATH
which bd
# Should show: /home/tom/projects/bd-clickup-integration/bd

# Verify it's the wrapper
head -3 $(which bd)
# Should show: #!/bin/bash
#              # Seamless bd wrapper

Test Sync¶

# Create a test issue
bd create "Test ClickUp sync" --type task --priority p3 \
  --description "Testing automatic synchronization to ClickUp"

Expected output:

Created issue: project-xxx
  Title: Test ClickUp sync
  Priority: P3
  Status: open

Syncing project-xxx to ClickUp...
Synced to ClickUp (Task ID: 86evxxx)

Verify in ClickUp: 1. Go to your ClickUp list 2. Find the newly created task 3. Check that title, priority, and description match

Test Update¶

bd update project-xxx --status in_progress

Should show sync confirmation and update the ClickUp task status.

Usage¶

Automatic Sync (Default)¶

These commands automatically sync to ClickUp:

# Create issue
bd create "New feature" --type feature --priority p1

# Update issue
bd update project-abc --status in_progress
bd update project-abc --priority p0

# Close issue
bd close project-abc --reason "Completed and deployed"

Manual Sync¶

If you need to manually sync:

# Sync specific issue
python -m beads_clickup.cli push project-abc

# Sync all issues
python -m beads_clickup.cli sync

# Pull from ClickUp
python -m beads_clickup.cli pull clickup-task-id

Non-Syncing Commands¶

These commands work normally without triggering sync:

bd list
bd show project-abc
bd search "query"
bd sync  # Git sync, not ClickUp

Field Mappings¶

Status Mapping¶

Map beads statuses to ClickUp status names:

field_mapping:
  status:
    open: "to do"
    in_progress: "in progress"
    completed: "completed"
    closed: "completed"
    cancelled: "cancelled"

Important: ClickUp status names are case-sensitive and must match exactly!

Finding your ClickUp statuses: 1. Go to your ClickUp list 2. Click any task 3. Look at the status dropdown 4. Use the exact names (including spaces and capitalization)

Priority Mapping¶

Map beads priorities (P0-P4) to ClickUp priorities (1-5):

field_mapping:
  priority:
    p0: 1  # Urgent (red flag)
    p1: 2  # High (yellow flag)
    p2: 3  # Normal (blue flag)
    p3: 4  # Low (gray flag)
    p4: 4  # Low (gray flag)

ClickUp priority values: - 1 = Urgent (red) - 2 = High (yellow) - 3 = Normal (blue) - 4 = Low (gray) - null or omit = No priority

Labels to Tags¶

Enable to sync beads labels as ClickUp tags:

field_mapping:
  labels_to_tags: true

Labels are created automatically in ClickUp if they don't exist.

Custom Fields¶

Store beads issue ID in a ClickUp custom field:

field_mapping:
  clickup_custom_field_name: "beads_id"

Note: The custom field must exist in your ClickUp list first.

Filters¶

Control which issues get synced to ClickUp.

Sync by Labels¶

Only sync issues with specific labels:

filters:
  sync_labels: ["customer-facing", "external", "public"]

Empty list [] = sync all labels.

Exclude by Labels¶

Never sync issues with these labels:

filters:
  exclude_labels: ["no-sync", "internal-only", "draft"]

Sync by Priority¶

Only sync high-priority issues:

filters:
  sync_priorities: ["p0", "p1", "p2"]

Empty list [] = sync all priorities.

Sync by Type¶

Only sync specific issue types:

filters:
  sync_types: ["bug", "feature", "task"]

Empty list [] = sync all types.

Troubleshooting¶

Wrapper Not Found¶

Error: bd: command not found

Fix: 1. Check PATH:

echo $PATH | grep bd-clickup-integration

2. Verify wrapper exists:

ls -l ~/projects/bd-clickup-integration/bd

3. If using devbox, restart shell:

exit
devbox shell

Config Not Found¶

Error: ClickUp integration not configured (no config.yaml found)

Fix: 1. Check config exists:

ls .beads/integrations/clickup/config.yaml

2. Verify you're in project root (has .beads directory) 3. Create config if missing (see Configuration)

API Token Not Set¶

Error: ClickUp API token is required

Fix: 1. Check token is in .env:

grep CLICKUP_API_TOKEN .env

2. Check token is loaded:

echo $CLICKUP_API_TOKEN

3. If using devbox, restart shell after adding to .env

Sync Fails¶

Error: Sync failed: ...

Common causes:

Invalid List ID
Verify default_list_id in config
Get correct ID from ClickUp URL
Invalid Status Name
Check status names match exactly (case-sensitive)
Update field_mapping.status in config
Permissions
Ensure API token has write access to the list
Check you're not trying to sync to an archived list
Network Issues
Check internet connection
Verify ClickUp is accessible

Debug:

# Test manual sync with verbose output
python -c "
from beads_clickup.sync_engine import SyncEngine
import logging
logging.basicConfig(level=logging.DEBUG)
engine = SyncEngine('.beads/integrations/clickup/config.yaml')
engine.sync_issue_to_clickup('project-xxx')
"

Package Import Fails¶

Error: ModuleNotFoundError: No module named 'beads_clickup'

Fix: 1. Check package is installed:

pip list | grep bd-clickup

2. Reinstall if needed:

uv add --editable ~/projects/bd-clickup-integration

3. Verify you're in correct virtual environment

Advanced¶

Sync Direction¶

Control sync flow:

sync:
  direction: "bidirectional"  # Both ways
  # direction: "beads-to-clickup"  # One way: beads -> ClickUp
  # direction: "clickup-to-beads"  # One way: ClickUp -> beads

Conflict Resolution¶

Handle simultaneous updates:

conflict_resolution:
  strategy: "last-write-wins"  # Most recent change wins
  # strategy: "beads-priority"  # Beads always wins
  # strategy: "clickup-priority"  # ClickUp always wins
  # strategy: "manual"  # Log conflicts for manual resolution

Hierarchical Sync¶

Sync parent-child relationships:

advanced:
  sync_hierarchical: true  # Create subtasks for child issues

Batch Processing¶

Control sync performance:

advanced:
  batch_size: 50  # Max issues per sync
  max_retries: 3  # Retry failed syncs
  retry_delay: 5  # Seconds between retries

Sync Comments¶

Note: Not yet implemented

advanced:
  sync_comments: false  # Future: sync issue comments

Updating the Package¶

When the package is updated:

cd ~/projects/bd-clickup-integration
git pull

All projects using it are immediately updated (editable install). No need to reinstall!

Multiple Projects¶

To use in multiple projects:

Install in each project: uv add --editable ~/projects/bd-clickup-integration
Configure PATH in each project's devbox.json
Create project-specific config.yaml in each .beads/integrations/clickup/
Each project can use different ClickUp lists, filters, and settings

Support¶

Documentation: See README.md
Quick Start: See QUICKSTART.md
Config Example: See config.yaml.example
Issues: Open an issue in the repository

Next Steps: - Setup complete! - Customize field mappings for your workflow - Add filters to control what syncs - Use bd commands as normal - sync is automatic!