devreport

DevReport is a command-line tool that generates automated individual activity reports from ClickUp tasks. It pulls tasks, computes stats (total, completed, by status/source/type), and renders beautiful HTML/PDF reports with summaries and detailed tables.

Features

• One-command reports: Fetch from GitHub/ClickUp → Generate HTML/PDF + JSON export
• Smart stats: Auto-calculates totals, completion rates, breakdowns by status/source/type
• Cross-platform: Pre-built binaries for macOS, Linux, Windows (AMD64/ARM64)
• Optional AI Rephrasing: Integrates with Ollama for task rewording

Prerequisites

• GitHub Account: Personal access token for API access (optional, for private repos)
• ClickUp Account: Access to tasks via API
• Terminal: sh/Zsh/PowerShell
• Optional: Browser to view HTML reports
• Optional: Ollama running locally (port 11434) for AI rephrasing

Installing Ollama and Gemma3 on linux

1. Install Ollama:

   curl -fsSL https://ollama.com/install.sh | sh

2. Start Ollama:

   ollama serve

3. Pull the Gemma3 model:

   ollama pull gemma3

4. Verify installation:

   curl http://localhost:11434/api/tags

---

Installation

Option 1: Download Pre-built Binary (Recommended)

1. Go to the Releases page

2. Download the archive for your platform:

   • macOS Intel: devreport_darwin_amd64.tar.gz
   • macOS Apple Silicon: devreport_darwin_arm64.tar.gz
   • Linux AMD64: devreport_linux_amd64.tar.gz
   • Linux ARM64: devreport_linux_arm64.tar.gz
   • Windows: devreport_windows_amd64.zip

3. Extract and install (macOS/Linux):

   tar -xzf devreport_darwin_amd64.tar.gz
   chmod +x devreport
   sudo mv devreport /usr/local/bin/

4. Verify installation:

   devreport --help

Option 2: Build from Source

git clone https://github.com/Afrawles/devreport.git
cd devreport
go build -o devreport ./cmd/devreport
./devreport --help

---

Getting Your ClickUp API Token

1. Log in to ClickUp
2. Click your profile picture → Settings
3. Go to Apps → API Token
4. Click Generate and copy your token
5. Use it with the --clickup-token flag

---

Finding Your ClickUp List IDs

1. In the ClickUp sidebar, hover over a List

2. Click the ellipsis (...) → Copy link

3. Example:

   https://app.clickup.com/12345678/v/li/987654321

4. The number after /li/ is your List ID (987654321)

5. Use commas to separate multiple lists:

   987654321,123456789

---

Finding Your ClickUp Assignee IDs

curl -H "Authorization: YOUR_API_TOKEN" \
  "https://api.clickup.com/api/v2/team"

---

Getting Your GitHub Personal Access Token

1. Log in to GitHub
2. Click your profile picture → Settings
3. Go to Developer settings → Personal access tokens → Tokens (classic)
4. Click Generate new token (classic)
5. Select scopes: repo (for private repos), read:org (for org repos)
6. Copy the token and use it with the --github-token flag

---

Finding Your GitHub Organizations

To fetch activities from organization repositories, specify org names (e.g., "microsoft,google").

Note: DevReport fetches from repos where you have recent activities in the date range to limit API calls.

---

Usage

When working with multiple ClickUp lists, DevReport maps text by list order.

• Use commas (,) to separate different lists
• Use pipes (|) within each list group to separate sentences belonging to that list

Example Layout

--clickup-listid "11111111,33333333" \
--challenges "Delayed client feedback|Unclear UI specifications|Integration issues with payment service, Server maintenance downtime|Third-party API instability|Deployment delays" \
--support-required "Product team review|QA support for test coverage|DevOps for CI/CD automation, Management alignment|Database admin support|Load testing assistance" \
--support-from "Product Management|QA Department|DevOps Team, IT Infrastructure|Backend Team|Project Management Office" \
--follow-up "Conduct sprint retrospective|Optimize frontend performance|Write integration tests, Refactor legacy modules|Enhance documentation|Evaluate monitoring tools"

Explanation:

• Everything before the first comma (,) belongs to List 11111111
• Everything after the comma belongs to List 33333333
• Within each group, | separates sentences for that list

---

Basic Command (ClickUp)

./devreport \
  --user "Uzumaki.Gon" \
  --start "2025-10-01" \
  --end "2025-10-31" \
  --author "Killua Uzumaki" \
  --period "Month of October" \
  --year 2025 \
  --category "Improvements, New Features, and Bug Fixes" \
  --clickup-token "your_clickup_token_here" \
  --clickup-assignees 1234536,1728383 \
  --clickup-listid "11111111,33333333" \
  --challenges "Delayed client feedback|Unclear UI specifications|Integration issues with payment service, Server maintenance downtime|Third-party API instability|Deployment delays" \
  --support-required "Product team review|QA support for test coverage|DevOps for CI/CD automation, Management alignment|Database admin support|Load testing assistance" \
  --support-from "Product Management|QA Department|DevOps Team, IT Infrastructure|Backend Team|Project Management Office" \
  --follow-up "Conduct sprint retrospective|Optimize frontend performance|Write integration tests, Refactor legacy modules|Enhance documentation|Evaluate monitoring tools"

GitHub Command

./devreport \
  --user "gon" \
  --start "2025-10-01" \
  --end "2025-10-31" \
  --author "Gon Freecss" \
  --period "Month of October" \
  --year 2025 \
  --github-token "your_github_token_here" \
  --github-orgs "hunterxhunter,chimera-ant" \
  --github-include-reviewed-prs \
  --github-include-assigned-issues

Combined Command (GitHub + ClickUp)

./devreport \
  --user "gon" \
  --start "2025-10-01" \
  --end "2025-10-31" \
  --author "Gon Freecss" \
  --period "Month of October" \
  --year 2025 \
  --clickup-token "clickup_token" \
  --clickup-assignees 12345 \
  --clickup-listid "11111" \
  --github-token "github_token" \
  --github-orgs "hunterxhunter" \
  --github-include-reviewed-prs

After execution, open the generated report:

reports/report_Uzumaki.Gon_20251030.html

This file (report export) contains the task summary, categorized sections, and AI-rephrased content (if Ollama is available).

For Operations & Business Teams

devreport summary --period <period> --clickup-token "<token>" --clickup-folderid <folder-id>

Supported Periods

Period	Description	Example
today	Current day	Tasks created today
yesterday	Previous day	Tasks created yesterday
this-week or thisweek	Current week (Mon-Sun)	Tasks from Monday to now
last-week or lastweek	Previous week (Mon-Sun)	Tasks from last Monday to Sunday
this-month or thismonth	Current month	Tasks from 1st to now
last-month or lastmonth	Previous month	Tasks from 1st to last day of previous month
all-time or alltime	All time	All tasks ever created

Examples

ClickUp Examples

# Weekly report
devreport summary --period this-week --clickup-token "pk_xxx" --clickup-folderid 123456

# Monthly report
devreport summary --period this-month --clickup-token "pk_xxx" --clickup-folderid 123456

# Filter by specific assignees
devreport summary --period this-week --clickup-token "pk_xxx" --clickup-folderid 123456 --clickup-assignees "user1,user2"

# Use environment variables
export CLICKUP_API_KEY="pk_xxx"
export CLICKUP_FOLDERID="123456"
devreport summary --period this-week

GitHub Examples

# GitHub activities report
devreport --user "gon" --start "2025-10-01" --end "2025-10-31" --github-token "ghp_xxx" --github-orgs "hunterxhunter"

# Include reviewed PRs
devreport --user "gon" --start "2025-10-01" --end "2025-10-31" --github-token "ghp_xxx" --github-orgs "hunterxhunter" --github-include-reviewed-prs

# Use environment variables
export GITHUB_TOKEN="ghp_xxx"
export GITHUB_ORGS="hunterxhunter,chimera-ant"
devreport --user "gon" --period this-month