Quick Start¶

Get started with ClickUp auto-sync in minutes. Choose the method that fits your needs.

Prerequisites¶

You have a ClickUp API token (get one)
Your project uses devbox (or you're starting fresh)
Python 3.11+ available

Method 1: New Project from Template (Recommended)¶

Start a new project with everything pre-configured:

Step 1: Clone Template¶

cd ~/projects
git clone https://github.com/latentsp/bd-clickup-template.git my-project
cd my-project

Step 2: Run Install Script¶

./install.sh

This will: - Clone bd-clickup-integration to ~/projects/ - Install the package with uv add --editable - Initialize bd (bd init) - Set up ClickUp configuration interactively

Step 3: Add API Token¶

echo "CLICKUP_API_TOKEN=your_token_here" >> .env

Get your token from: https://app.clickup.com/settings/apps

Step 4: Verify Setup¶

devbox shell
bd create "Test sync" --type task --priority p3

You should see:

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

Step 5: Start Working¶

bd create "My first feature" --type feature --priority p1
bd list
bd update my-project-xxx --status in_progress

All commands automatically sync to ClickUp!

Method 2: Add to Existing Project¶

Already have a project? Add ClickUp sync:

Step 1: Clone Integration Package¶

git clone git@github.com:latentsp/bd-clickup-integration.git ~/projects/bd-clickup-integration

Step 2: Run Setup Script¶

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

This will: - Check prerequisites (devbox, bd) - Install the package with uv add --editable - Update devbox.json with PATH configuration - Set up .beads/integrations/clickup/config.yaml

Step 3: Configure ClickUp¶

The setup script will prompt you for: - ClickUp Workspace ID - Default List ID (optional)

Or manually edit .beads/integrations/clickup/config.yaml:

clickup:
  workspace_id: "9018124630"       # Your workspace ID
  default_list_id: "YOUR_LIST_ID"  # Get from ClickUp URL

sync:
  enabled: true
  direction: "bidirectional"

Step 4: Add API Token¶

echo "CLICKUP_API_TOKEN=your_token_here" >> .env

Make sure .env is in .gitignore!

Commands Reference¶

Automatic Sync (Recommended)¶

Just use bd commands - sync happens automatically:

# Create and sync
bd create "New feature" --type feature --priority p1

# Update and sync
bd update project-xxx --status in_progress

# Close and sync
bd close project-xxx --reason "Completed"

Manual Sync (If Needed)¶

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

# Full bidirectional sync
python -m beads_clickup.cli sync

# Pull from ClickUp only
python -m beads_clickup.cli pull

MCP Server (Cursor IDE)¶

The package includes an MCP server for Cursor IDE:

# In Cursor settings.json
{
  "mcp": {
    "servers": {
      "beads": {
        "command": "python3",
        "args": ["-m", "beads_clickup.mcp_server"],
        "env": {
          "PYTHONPATH": "$HOME/projects/bd-clickup-integration"
        }
      }
    }
  }
}

Then use natural language: - "Create a beads issue for the login bug" - "Show all open issues" - "Close issue project-xxx"

See MCP_SETUP.md for details.

Finding Your ClickUp IDs¶

Workspace ID¶

Open ClickUp and click your workspace name
Go to Settings → Workspace
Look at the URL: the number after /settings/ is your workspace ID

List ID¶

Navigate to your desired list in ClickUp
Look at the URL: https://app.clickup.com/.../v/li/123456
Copy the number (123456) - that's your list ID

What's Automatic Now¶

After setup, these commands automatically sync to ClickUp:

✅ bd create → Creates task in ClickUp
✅ bd update → Updates task in ClickUp
✅ bd close → Closes task in ClickUp
✅ Auto-detects project and config
✅ Loads .env automatically

No manual sync needed!

Troubleshooting¶

"Error: bd command not found"¶

Make sure native bd is installed:

which bd  # Should show path to bd

Install if missing — see the beads project for installation instructions.

"ClickUp integration not configured"¶

Check config file exists:

ls .beads/integrations/clickup/config.yaml

If missing, run setup again:

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

Sync fails silently¶

Check token is set:
```
echo $CLICKUP_API_TOKEN
```

Test package import:

python -c "from beads_clickup.sync_engine import SyncEngine; print('OK')"

Try manual sync:

python -m beads_clickup.cli push project-xxx

Wrong ClickUp list¶

Update default_list_id in .beads/integrations/clickup/config.yaml:

clickup:
  default_list_id: "YOUR_NEW_LIST_ID"

Next Steps¶

Customize Configuration¶

Edit .beads/integrations/clickup/config.yaml to:

Adjust status mappings
Configure priority mappings
Add sync filters (exclude labels, types)
Set conflict resolution strategy

See SETUP.md for all configuration options.

Set Up Webhooks (Optional)¶

For real-time sync when ClickUp tasks change:

# Start webhook server
python -m beads_clickup.cli webhook-start --port 8765

# Register with ClickUp
python -m beads_clickup.cli webhook-register https://your-url/webhook/clickup

See DEPLOY.md for production webhook deployment.

Generate Task Graphs (Optional)¶

Visualize your task relationships:

bd lifecycle-graph output.html

Requires OPENAI_API_KEY or ANTHROPIC_API_KEY for LLM classification.

The integration package is shared across all your projects!

To add to another project:

cd /path/to/another/project
~/projects/bd-clickup-integration/setup.sh

All projects use the same codebase - update once, benefit everywhere.

Need more details? See SETUP.md Architecture info? See ARCHITECTURE.md Questions? Check the main README.md