clickup-agent-cli 0.2.1 → 0.4.0

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "clickup-agent-cli",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "CLI covering the entire ClickUp API v2 surface",
   "type": "module",
   "bin": {
-    "clickup": "./dist/bin/clickup.js"
+    "clickup": "dist/clickup.js"
   },
   "files": [
     "dist",
@@ -18,7 +18,8 @@
     "build": "tsup",
     "dev": "tsx bin/clickup.ts",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "version": "node scripts/sync-version.js"
   },
   "keywords": [
     "clickup",
@@ -45,5 +46,13 @@
     "tsx": "^4.0.0",
     "typescript": "^5.9.0",
     "vitest": "^3.0.0"
-  }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/henryreith/clickup-cli"
+  },
+  "bugs": {
+    "url": "https://github.com/henryreith/clickup-cli/issues"
+  },
+  "homepage": "https://github.com/henryreith/clickup-cli#readme"
 }

package/skills/clickup/SKILL.md

@@ -41,6 +41,7 @@ clickup <resource> <action> --help     # Full help text
 | `clickup-chat` | Chat channels, sending messages and notifications |
 | `clickup-webhooks` | Webhook registration and management |
 | `clickup-fields` | Custom fields, tags, custom task types |
+| `clickup-templates` | Templates: list available templates, apply task/list/folder templates |
 
 ## Recipe Skills (multi-step workflows)
 
@@ -57,6 +58,7 @@ Recipes accept natural language arguments. Scope them to any team, department, p
 | `clickup-sprint-closeout` | Close a sprint, carry over incomplete work |
 | `clickup-time-audit` | Audit time tracking and utilization |
 | `clickup-project-setup` | Scaffold a new project structure |
+| `clickup-rollout` | Roll out a saved process template (apply + configure) |
 | `clickup-capacity-check` | Check team workload and availability |
 | `clickup-blocker-report` | Find blocked tasks and dependency chains |
 | `clickup-goal-progress` | Report on goal/OKR completion |
@@ -81,6 +83,10 @@ clickup task list --list-id <id> --format quiet | xargs -I{} clickup task get {}
 
 All commands support: `--format json|table|csv|tsv|quiet|id|md`, `--dry-run`, `--debug`, `--no-color`
 
+Additional global flags:
+- `--profile <name>` -- select a named profile (accepts profile key, workspace name, or nickname)
+- `--token-file <path>` -- read API token from a file (useful in CI/CD and secret managers)
+
 Use `--format md` to render output as a markdown table -- ideal for displaying results in chat messages or documents.
 
 ## Auth
@@ -91,16 +97,45 @@ Requires a ClickUp API token.
 # Set up authentication
 clickup auth login --token pk_XXXXXXXX_YYYYYYYY
 
+# Read token from file (CI/CD-friendly)
+clickup auth login --token-file /run/secrets/clickup_token
+
 # Or use an environment variable
-export CLICKUP_TOKEN=pk_XXXXXXXX_YYYYYYYY
+export CLICKUP_API_TOKEN=pk_XXXXXXXX_YYYYYYYY
 
-# Store default workspace
-clickup config set workspace_id <id>
+# Auto-configure workspace after login (single workspace: auto-selects)
+clickup workspace setup
 
 # Check current auth status
 clickup auth status
+
+# Validate token and show identity
+clickup config validate
+```
+
+## Named Profiles (Multi-Account)
+
+Profiles store credentials per workspace. A single-workspace setup is transparent -- no `--profile` flag needed.
+
+```bash
+# List profiles
+clickup config profile list
+
+# Switch active profile
+clickup config profile use "Acme Corp"
+
+# Set a short nickname
+clickup config profile nickname acme-corp acme
+
+# Use a specific profile for one command
+clickup task list --list-id 123 --profile acme
 ```
 
+Profile resolution for `--profile` accepts:
+1. The profile key (e.g. `default`)
+2. Workspace name, case-insensitive (e.g. `"Henry's Workspace"`)
+3. Nickname if set (e.g. `acme`)
+
 ## Creating Custom Skills
 
 Users can create their own skills alongside the built-in ones. Add a SKILL.md to `.claude/skills/<name>/` in any project:

package/skills/clickup-fields/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: clickup-fields
 description: Manages ClickUp custom fields, tags, and custom task types. Use when the user asks about custom fields, wants to set field values on tasks, manage tags, or work with custom task types.
-allowed-tools: Bash(clickup custom-field *), Bash(clickup tag *), Bash(clickup custom-task-type *), Bash(clickup schema field*), Bash(clickup schema tag*)
+allowed-tools: Bash(clickup custom-field *), Bash(clickup tag *), Bash(clickup custom-task-type *), Bash(clickup attachment *), Bash(clickup schema field*), Bash(clickup schema tag*)
 ---
 
 # ClickUp Custom Fields, Tags, and Task Types
@@ -13,7 +13,7 @@ Custom fields are defined at the list level and set on individual tasks.
 ```bash
 clickup field list --list-id <id>                              # List field definitions
 clickup field set --task-id <id> --field-id <fid> --value <v>  # Set a field value
-clickup field remove --task-id <id> --field-id <fid>           # Clear a field value
+clickup field remove --task-id <id> --field-id <fid> --confirm # Clear a field value
 ```
 
 ### Value formats by field type
@@ -69,9 +69,20 @@ clickup field list --list-id 998877 --format json
 clickup field list --list-id 998877 --format md
 ```
 
+## Attachment Commands
+
+```bash
+clickup attachment upload --task-id <id> --file <path> [--filename <name>]
+clickup attachment list --task-id <id>
+clickup attachment download --task-id <id> --attachment-id <id> [--output <path>] [--force]
+```
+
+`attachment download` fetches the file with the auth header and writes to `--output` (default: `./attachment-<id>-<title>`). Refuses to overwrite an existing file unless `--force` is passed. Shows a spinner during download.
+
 ## Discovery
 
 ```bash
 clickup schema fields.set      # Show field set options
 clickup schema tags.create     # Show tag create fields
+clickup schema attachment.list # Show attachment list options
 ```

package/skills/clickup-rollout/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: clickup-rollout
+description: Rolls out a saved process template in ClickUp by applying it to a target location, then configuring assignees, due dates, and custom fields. Use when the user says "start a new [project/process/sprint/onboarding]" or wants to kick off a repeatable workflow from a template.
+disable-model-invocation: true
+context: fork
+agent: general-purpose
+argument-hint: "[template name or ID] [target location] [optional: assignee, due date, custom fields]"
+allowed-tools: Bash(clickup *)
+---
+
+# Template Rollout
+
+Apply a saved ClickUp template and configure the resulting task, list, or folder for a new instance of the process.
+
+## Workflow
+
+### Step 1: Find the template
+
+```bash
+# List all templates to find the right one
+clickup template list --format json
+```
+
+If the user gave a template name, find its ID by matching the `name` field. If they gave an ID directly, skip this step.
+
+### Step 2: Determine the template type and target
+
+Based on what the user wants to create:
+- **Task template**: needs a `--list-id` target
+- **List template**: needs a `--folder-id` or `--space-id` target
+- **Folder template**: needs a `--space-id` target
+
+If the user hasn't specified a target, find it:
+```bash
+clickup space list --format json
+clickup folder list --space-id <id> --format json
+clickup list list --folder-id <id> --format json
+```
+
+### Step 3: Apply the template
+
+```bash
+# Task template
+TASK_ID=$(clickup template apply-task \
+  --list-id <list-id> \
+  --template-id <tmpl-id> \
+  --name "<instance-name>" \
+  --format id)
+
+# List template (into folder)
+LIST_ID=$(clickup template apply-list \
+  --folder-id <folder-id> \
+  --template-id <tmpl-id> \
+  --name "<instance-name>" \
+  --format id)
+
+# List template (into space, folderless)
+LIST_ID=$(clickup template apply-list \
+  --space-id <space-id> \
+  --template-id <tmpl-id> \
+  --name "<instance-name>" \
+  --format id)
+
+# Folder template
+FOLDER_ID=$(clickup template apply-folder \
+  --space-id <space-id> \
+  --template-id <tmpl-id> \
+  --name "<instance-name>" \
+  --format id)
+```
+
+### Step 4: Configure the created resource
+
+For a task template result, set assignees, dates, and custom fields:
+```bash
+# Assign team members
+clickup task update "$TASK_ID" --assignee-add <user-id>
+
+# Set start and due dates (Unix milliseconds)
+clickup task update "$TASK_ID" --start-date <ms> --due-date <ms>
+
+# Fill in custom fields
+clickup field set --task-id "$TASK_ID" --field-id <field-id> --value "<value>"
+```
+
+For a list template result, populate it with initial tasks if needed:
+```bash
+clickup task list --list-id "$LIST_ID" --format json  # review what the template created
+```
+
+For a folder template result, review the created structure:
+```bash
+clickup list list --folder-id "$FOLDER_ID" --format table
+```
+
+### Step 5: Confirm and summarize
+
+Report what was created:
+- Resource type and ID
+- Name used
+- Assignees set
+- Dates configured
+- Custom fields populated
+- Link or path in the ClickUp hierarchy
+
+## Tips
+
+- Use `--name` to give each rollout a unique name (e.g. "Client Onboarding - Acme Corp" or "Sprint 14 - Apr 7")
+- Templates carry over all custom field definitions -- just fill in the values after applying
+- Task IDs from `--format id` can be piped directly into update and field commands
+- If rolling out multiple instances at once, loop over a list of names or targets

package/skills/clickup-spaces/SKILL.md

@@ -11,12 +11,15 @@ Manage the organizational hierarchy: Workspace > Space > Folder > List. Lists co
 ## Workspace Commands
 
 ```bash
+clickup workspace setup                         # Auto-configure workspace (run after auth login)
 clickup workspace list                          # List all workspaces
 clickup workspace get [--workspace-id <id>]     # Get workspace details
 clickup workspace seats [--workspace-id <id>]   # Show seat usage
 clickup workspace plan [--workspace-id <id>]    # Show billing plan
 ```
 
+`workspace setup` calls `GET /team`, auto-selects if only one workspace exists, prompts in TTY if multiple, and saves the workspace to the active profile. After running it, `--workspace-id` is not needed for subsequent commands.
+
 ## Space Commands
 
 ```bash

package/skills/clickup-tasks/SKILL.md

@@ -33,7 +33,7 @@ clickup task get <task-id> [--include-subtasks] [--include-markdown-description]
 ```bash
 clickup task create --list-id <id> --name <name>
     [--description <text>] [--markdown-description <md>]
-    [--status <s>] [--priority <1-4>] [--due-date <ts>] [--start-date <ts>]
+    [--status <s>] [--priority <1-4|urgent|high|normal|low>] [--due-date <ts>] [--start-date <ts>]
     [--assignee <id>...] [--tag <name>...] [--time-estimate <ms>]
     [--parent <task-id>] [--custom-field <id=value>...]
 ```
@@ -41,15 +41,28 @@ clickup task create --list-id <id> --name <name>
 ### Update a task
 ```bash
 clickup task update <task-id> [--name <name>] [--description <text>]
-    [--status <s>] [--priority <1-4>] [--due-date <ts>] [--start-date <ts>]
+    [--status <s>] [--priority <1-4|urgent|high|normal|low>] [--due-date <ts>] [--start-date <ts>]
     [--assignee-add <id>...] [--assignee-remove <id>...] [--archived <bool>]
 ```
 
+Priority accepts both integers (`1`-`4`) and strings (`urgent`, `high`, `normal`, `low`). Mapping: urgent=1, high=2, normal=3, low=4.
+
 ### Delete a task
 ```bash
 clickup task delete <task-id> --confirm
 ```
 
+### Bulk operations (concurrency limit 3)
+```bash
+# Apply the same update to multiple tasks
+clickup task bulk-update --task-id <id> --task-id <id> ... [same update flags as task update]
+
+# Delete multiple tasks
+clickup task bulk-delete --task-id <id> --task-id <id> ... --confirm
+```
+
+Both bulk commands output a results table with `task_id | name | result`.
+
 ### Time in status
 ```bash
 clickup task time-in-status <task-id>

package/skills/clickup-templates/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: clickup-templates
+description: Lists and applies ClickUp templates to create tasks, lists, and folders from saved process templates. Use when the user wants to roll out a repeatable process, create items from a template, or find what templates are available in the workspace.
+allowed-tools: Bash(clickup template *), Bash(clickup schema template*)
+---
+
+# ClickUp Templates
+
+List available templates and apply them to create tasks, lists, and folders. Templates are defined in the ClickUp UI and can be rolled out repeatedly via the CLI.
+
+## List Templates
+
+```bash
+clickup template list [--workspace-id <id>] [--page <n>]
+```
+
+Returns all task templates in the workspace. Use this to find template IDs before applying them.
+
+## Apply a Task Template
+
+```bash
+clickup template apply-task --list-id <id> --template-id <id> [--name <override-name>]
+```
+
+Creates a new task in the specified list using the template structure, including all custom fields defined on the template.
+
+## Apply a List Template
+
+```bash
+# Into a folder
+clickup template apply-list --folder-id <id> --template-id <id> [--name <override-name>]
+
+# Into a space (folderless)
+clickup template apply-list --space-id <id> --template-id <id> [--name <override-name>]
+```
+
+Provide exactly one of `--folder-id` or `--space-id`.
+
+## Apply a Folder Template
+
+```bash
+clickup template apply-folder --space-id <id> --template-id <id> [--name <override-name>]
+```
+
+Creates an entire folder structure (with nested lists and tasks) from the template.
+
+## Common Patterns
+
+```bash
+# Step 1: Find available templates
+clickup template list --format json
+
+# Step 2: Apply a task template and capture the new task ID
+TASK_ID=$(clickup template apply-task --list-id <id> --template-id <tmpl_id> --format id)
+
+# Step 3: Set assignee and due date on the created task
+clickup task update "$TASK_ID" --assignee-add 112233 --due-date 1735689600000
+
+# Step 4: Fill in custom fields
+clickup field set --task-id "$TASK_ID" --field-id cf_001 --value "In Review"
+
+# Roll out a named instance of a process template
+clickup template apply-list --folder-id <id> --template-id <tmpl_id> --name "Q1 Launch - March 2026"
+
+# Apply a folder template to scaffold a whole project
+clickup template apply-folder --space-id <id> --template-id <tmpl_id> --name "Client Onboarding - Acme Corp"
+```
+
+## Discovery
+
+```bash
+clickup schema template               # List all template actions
+clickup schema template.apply-task    # Show apply-task fields
+clickup schema template.apply-list    # Show apply-list fields
+clickup schema template.apply-folder  # Show apply-folder fields
+```

package/skills/clickup-time/SKILL.md

@@ -25,7 +25,7 @@ clickup time update <timer-id> --workspace-id <id>
     [--description <text>] [--duration <ms>] [--start <ts>]
     [--tag-action <add|remove>] [--tag <name>...] [--billable <bool>]
 
-clickup time delete <timer-id> --workspace-id <id>
+clickup time delete <timer-id> --workspace-id <id> --confirm
 ```
 
 ### Get / History
@@ -77,7 +77,8 @@ clickup time list --workspace-id 9876543 --format md
 
 - Duration is always in **milliseconds** (1 hour = 3600000, 1 minute = 60000)
 - Start timestamps are Unix milliseconds
-- `time delete` does **not** require `--confirm` (unlike most delete commands)
+- `time delete` requires `--confirm` in non-interactive mode (like all delete commands)
+- `--billable` accepts only `true` or `false`; anything else errors (exit 2)
 
 ## Discovery