clickup

Files (1)

• SKILL.md

SKILL.md (first lines)

# ClickUp CLI (`cup`) - skill version 1.46.2

Reference for AI agents using the `cup` CLI tool. Covers task management, sprint tracking, comments, time tracking, custom fields, goals, Docs, Chat, views, webhooks, workspace structure, export, and project workflows.

> **Version check:** Run `cup --version`. If your installed version is older than 1.46.2, update with `npm install -g @krodak/clickup-cli` and refresh this skill with `cup skill` (`cup skill --path <file>` installs to a custom location, `cup skill --print` writes it to stdout).

## Install & Configure

### Prerequisites

Node.js 22+ required.

### Install

```bash
npm install -g @krodak/clickup-cli
```

Or via Homebrew:

```bash
brew tap krodak/tap && brew install clickup-cli
```

### Get an API token

The user needs a personal API token from ClickUp:

1. Open https://app.clickup.com/settings/apps
2. Under "API Token", click "Generate" (or copy existing)
3. The token starts with `pk_`

### Configure

**Non-interactive (recommended for agents):**

```bash
cup init --token pk_USER_TOKEN --team TEAM_ID
```

To find the team/workspace ID, the user can check their ClickUp URL: `https://app.clickup.com/TEAM_ID/...`

**Interactive (for humans in a terminal):**

```bash
cup init
```

**Environment variables (no config file needed):**

```bash
export CU_API_TOKEN="pk_..."
export CU_TEAM_ID="12345678"
```

### Verify

```bash
cup auth
```

This prints the authenticated username and workspace. If it fails, the token or config is invalid.

## Setup

Config stored at `~/.config/cup/config.json` with named profiles. Each profile has `apiToken` and `teamId`. Optional: `sprintFolderId` to pin sprint detection to a specific folder.

Multiple profiles supported - use `cup profile add <name>` to create, `cup profile use <name>` to switch, or `-p <name>` flag for one-off overrides.

`CU_PROFILE` environment variable selects a profile (overridden by `-p` flag).

## Saved Filters (Quick Shortcuts)

At the start of each session, run `cup filter list` to discover saved shortcuts for this workspace.

| Command | What it does |
| --- | --- |
| `cup filter list [--json]` | List all saved shortcuts with commands and descriptions |
| `cup filter run <name>` | Execute a saved shortcut (identical to running the full command) |
| `cup filter save <name> <cmd> [args...] [-d desc]` | Save a command shortcut |
| `cup filter delete <name>` | Remove a shortcut |
| `cup filter show <name> [--json]` | Show a single shortcut's details |

Example: `cup filter save sprint-tasks tasks --status "in progress" --list l1 -d "Current sprint tasks"`
Then: `cup filter run sprint-tasks` is equivalent to `cup tasks --status "in progress" --list l1`

## Output Modes

| Context | Default output | Override |
| --- | --- | --- |
| Terminal (TTY) | Interactive picker UI | `--json` for JSON |
| Piped / non-TTY | Markdown tables | `--json` for JSON |

- Default piped output is **Markdown** - optimized for agent context windows
- `cup task <id>` outputs a Markdown summary when piped; use `--json` for the full raw API object
- Set `CU_OUTPUT=json` to always get JSON when piped
- Agents typically don't need `--json` unless parsing structured data with `jq`

## Commands

All commands support `--help` for full flag details. All commands support `--json`.

### Read

| Command | What it returns |
| --- | --- |
| `cup tasks [--status s] [--name q] [--type t] [--list id] [--space id] [--all] [--include-closed] [--assignee id\|me] [--tag t] [--due-before d] [--due-after d] [--created-after d] [--created-before d] [--field "Name" val]` | Tasks assigned to you (filter by status, name, type, list, space, assignee, tag, dates, custom fields). `--all` for all assignees |
| `cup assigned [--status s] [--include-closed]` | All my tasks grouped by status |
| `cup sprint [--status s] [--space nameOrId] [--folder id] [--include-closed]` | Tasks in active sprint (auto-detected) |
| `cup sprints [--space nameOrId]` | List all sprints (marks active with \*) |
| `cup search [query] [--status s] [--list id] [--space id] [--all] [--include-closed] [--assignee id\|me] [--tag t] [--due-before d] [--due-after d] [--created-after d] [--created-before d] [--field "Name" val]` | Search tasks by name, or list tasks filtered by flags when no query is given. `--all` for all assignees |
| `cup task <id>` | Single task details (custom fields, checklists, attachments, deps, links) |
| `cup subtasks <id> [--status s] [--name q] [--include-closed]` | Subtasks of a task |
| `cup comments <id>` | Comments on a task |
| `cup activity <id>` | Task details + comment history combined |
| `cup inbox [--days n] [--include-closed]` | Tasks updated in last n days (default 30) |
| `cup summary [--hours n]` | Standup: completed, in-progress, overdue |
| `cup overdue [--all] [--include-closed]` | Tasks past due date (most overdue first) |
| `cup spaces [--name partial] [--my] [--archived]` | List/filter workspace spaces |

From krodak/clickup-cli, MIT.

More from krodak/clickup-cli