Collect ClickUp API diagnostic information for troubleshooting and support. Use when encountering persistent issues, preparing support tickets, or collecting API connectivity and rate limit diagnostics. Trigger: "clickup debug", "clickup diagnostics", "clickup support bundle", "collect clickup logs", "clickup health check".
Collect diagnostic information for troubleshooting ClickUp API v2 issues. Generates a redacted bundle safe for sharing with support.
#!/bin/bash
echo "=== ClickUp Quick Health Check ==="
# 1. Auth verification
echo -n "Auth: "
AUTH_RESULT=$(curl -s -w "\n%{http_code}" \
https://api.clickup.com/api/v2/user \
-H "Authorization: $CLICKUP_API_TOKEN")
HTTP_CODE=$(echo "$AUTH_RESULT" | tail -1)
[ "$HTTP_CODE" = "200" ] && echo "OK (200)" || echo "FAILED ($HTTP_CODE)"
# 2. Rate limit status
echo -n "Rate limits: "
HEADERS=$(curl -s -D - -o /dev/null \
https://api.clickup.com/api/v2/user \
-H "Authorization: $CLICKUP_API_TOKEN" 2>&1)
REMAINING=$(echo "$HEADERS" | grep -i "X-RateLimit-Remaining" | awk '{print $2}' | tr -d '\r')
LIMIT=$(echo "$HEADERS" | grep -i "X-RateLimit-Limit" | awk '{print $2}' | tr -d '\r')
echo "${REMAINING}/${LIMIT} remaining"
# 3. Workspace access
echo "Workspaces:"
curl -s https://api.clickup.com/api/v2/team \
-H "Authorization: $CLICKUP_API_TOKEN" | \
python3 -c "import sys,json; [print(f' {t[\"id\"]}: {t[\"name\"]}') for t in json.load(sys.stdin).get('teams',[])]" 2>/dev/null
# 4. ClickUp platform status
echo -n "ClickUp status: "
curl -s https://status.clickup.com/api/v2/summary.json 2>/dev/null | \
python3 -c "import sys,json; print(json.load(sys.stdin)['status']['description'])" 2>/dev/null || echo "Unable to check"
# 5. API latency
echo -n "API latency: "
LATENCY=$(curl -s -o /dev/null -w "%{time_total}" \
https://api.clickup.com/api/v2/user \
-H "Authorization: $CLICKUP_API_TOKEN")
echo "${LATENCY}s"
#!/bin/bash
# clickup-debug-bundle.sh - Generates redacted diagnostic archive
BUNDLE_DIR="clickup-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"
cat > "$BUNDLE_DIR/summary.txt" <<HEADER
ClickUp Debug Bundle
Generated: $(date -Iseconds)
Hostname: $(hostname)
Node: $(node --version 2>/dev/null || echo 'N/A')
CLICKUP_API_TOKEN: ${CLICKUP_API_TOKEN:+[SET (${#CLICKUP_API_TOKEN} chars)]}
HEADER
# Auth check with full response headers
echo -e "\n--- Auth Check ---" >> "$BUNDLE_DIR/summary.txt"
curl -s -D "$BUNDLE_DIR/auth-headers.txt" -o "$BUNDLE_DIR/auth-response.json" \
https://api.clickup.com/api/v2/user \
-H "Authorization: $CLICKUP_API_TOKEN"
echo "HTTP status: $(head -1 "$BUNDLE_DIR/auth-headers.txt")" >> "$BUNDLE_DIR/summary.txt"
# Rate limit headers
echo -e "\n--- Rate Limit Headers ---" >> "$BUNDLE_DIR/summary.txt"
grep -i "ratelimit" "$BUNDLE_DIR/auth-headers.txt" >> "$BUNDLE_DIR/summary.txt" 2>/dev/null
# Workspace enumeration
echo -e "\n--- Workspaces ---" >> "$BUNDLE_DIR/summary.txt"
curl -s https://api.clickup.com/api/v2/team \
-H "Authorization: $CLICKUP_API_TOKEN" > "$BUNDLE_DIR/teams.json"
# Redact sensitive fields from all JSON files
for f in "$BUNDLE_DIR"/*.json; do
[ -f "$f" ] && sed -i 's/"email":"[^"]*"/"email":"[REDACTED]"/g' "$f"
done
# Remove raw auth headers (may contain token)
rm -f "$BUNDLE_DIR/auth-headers.txt"
# Package
tar -czf "$BUNDLE_DIR.tar.gz" "$BUNDLE_DIR"
rm -rf "$BUNDLE_DIR"
echo "Bundle: $BUNDLE_DIR.tar.gz"
interface ClickUpDiagnostics {
auth: { ok: boolean; userId?: number; username?: string };
rateLimit: { limit: number; remaining: number; resetAt: string };
workspaces: Array<{ id: string; name: string; memberCount: number }>;
latencyMs: number;
platformStatus: string;
}
async function collectDiagnostics(): Promise<ClickUpDiagnostics> {
const start = Date.now();
const response = await fetch('https://api.clickup.com/api/v2/user', {
headers: { 'Authorization': process.env.CLICKUP_API_TOKEN! },
});
const latencyMs = Date.now() - start;
const rateLimit = {
limit: parseInt(response.headers.get('X-RateLimit-Limit') ?? '0'),
remaining: parseInt(response.headers.get('X-RateLimit-Remaining') ?? '0'),
resetAt: new Date(
parseInt(response.headers.get('X-RateLimit-Reset') ?? '0') * 1000
).toISOString(),
};
let auth: ClickUpDiagnostics['auth'];
if (response.ok) {
const data = await response.json();
auth = { ok: true, userId: data.user.id, username: data.user.username };
} else {
auth = { ok: false };
}
// Get workspaces
const teamsRes = await fetch('https://api.clickup.com/api/v2/team', {
headers: { 'Authorization': process.env.CLICKUP_API_TOKEN! },
});
const teams = teamsRes.ok ? await teamsRes.json() : { teams: [] };
return {
auth,
rateLimit,
workspaces: teams.teams.map((t: any) => ({
id: t.id, name: t.name, memberCount: t.members?.length ?? 0,
})),
latencyMs,
platformStatus: auth.ok ? 'reachable' : 'auth_failed',
};
}
| Issue | Diagnostic Check | Solution |
|---|---|---|
| Auth failing | Check HTTP status on /user | Regenerate token |
| High latency (>2s) | Check latencyMs | Network/region issue |
| Rate limited (0 remaining) | Check X-RateLimit-Remaining | Wait for reset or upgrade plan |
| Workspace missing | Check teams.json | Re-authorize workspace |
For rate limit issues, see clickup-rate-limits.