@krodak/clickup-cli 1.16.2 → 1.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/dist/index.js +165 -6
  3. package/package.json +1 -1
  4. package/skills/clickup-cli/SKILL.md +63 -55
package/.claude-plugin/plugin.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "clickup-cli",
3
3
  "description": "ClickUp CLI skills for managing tasks, sprints, comments, checklists, custom fields, tags, and time tracking via the cup command",
4
- "version": "1.16.2",
4
+ "version": "1.17.0",
5
5
  "author": {
6
6
  "name": "Krzysztof Rodak"
7
7
  },
package/dist/index.js CHANGED
@@ -176,9 +176,22 @@ var ClickUpClient = class {
176
176
  const me = await this.getMe();
177
177
  baseParams.append("assignees[]", String(me.id));
178
178
  }
179
+ if (filters.assignees) {
180
+ for (const id of filters.assignees) baseParams.append("assignees[]", String(id));
181
+ }
179
182
  for (const s of filters.statuses ?? []) baseParams.append("statuses[]", s);
180
183
  for (const id of filters.listIds ?? []) baseParams.append("list_ids[]", id);
181
184
  for (const id of filters.spaceIds ?? []) baseParams.append("space_ids[]", id);
185
+ for (const tag of filters.tags ?? []) baseParams.append("tags[]", tag);
186
+ if (filters.dueDateGt) baseParams.set("due_date_gt", String(filters.dueDateGt));
187
+ if (filters.dueDateLt) baseParams.set("due_date_lt", String(filters.dueDateLt));
188
+ if (filters.dateCreatedGt) baseParams.set("date_created_gt", String(filters.dateCreatedGt));
189
+ if (filters.dateCreatedLt) baseParams.set("date_created_lt", String(filters.dateCreatedLt));
190
+ if (filters.dateUpdatedGt) baseParams.set("date_updated_gt", String(filters.dateUpdatedGt));
191
+ if (filters.dateUpdatedLt) baseParams.set("date_updated_lt", String(filters.dateUpdatedLt));
192
+ if (filters.customFields?.length) {
193
+ baseParams.set("custom_fields", JSON.stringify(filters.customFields));
194
+ }
182
195
  return this.paginate((page) => {
183
196
  const params = new URLSearchParams(baseParams);
184
197
  params.set("page", String(page));
@@ -2855,6 +2868,13 @@ var commandMetadata = [
2855
2868
  "--type",
2856
2869
  "--all",
2857
2870
  "--include-closed",
2871
+ "--assignee",
2872
+ "--tag",
2873
+ "--due-before",
2874
+ "--due-after",
2875
+ "--created-after",
2876
+ "--created-before",
2877
+ "--field",
2858
2878
  "--json"
2859
2879
  ],
2860
2880
  quickReference: [
@@ -3059,7 +3079,21 @@ var commandMetadata = [
3059
3079
  {
3060
3080
  name: "search",
3061
3081
  description: "Search my tasks by name (use --all for all tasks)",
3062
- flags: ["--status", "--all", "--include-closed", "--json"],
3082
+ flags: [
3083
+ "--status",
3084
+ "--list",
3085
+ "--space",
3086
+ "--all",
3087
+ "--include-closed",
3088
+ "--assignee",
3089
+ "--tag",
3090
+ "--due-before",
3091
+ "--due-after",
3092
+ "--created-after",
3093
+ "--created-before",
3094
+ "--field",
3095
+ "--json"
3096
+ ],
3063
3097
  quickReference: [
3064
3098
  { section: "read", usage: "search <query>", description: "Search my tasks by name" }
3065
3099
  ]
@@ -3819,7 +3853,15 @@ ${renderZshTopLevelCommands(name)}
3819
3853
  '--space[Filter by space ID]:space_id:' \\
3820
3854
  '--name[Filter by name]:query:' \\
3821
3855
  '--type[Filter by task type]:type:' \\
3856
+ '--all[Include all tasks, not just mine]' \\
3822
3857
  '--include-closed[Include done/closed tasks]' \\
3858
+ '--assignee[Filter by assignee]:user_id:' \\
3859
+ '--tag[Filter by tag name]:tag:' \\
3860
+ '--due-before[Tasks due before date]:date:' \\
3861
+ '--due-after[Tasks due after date]:date:' \\
3862
+ '--created-after[Tasks created after date]:date:' \\
3863
+ '--created-before[Tasks created before date]:date:' \\
3864
+ '--field[Filter by custom field]:field_name_and_value:' \\
3823
3865
  '--json[Force JSON output]'
3824
3866
  ;;
3825
3867
  task)
@@ -3933,8 +3975,17 @@ ${renderZshTopLevelCommands(name)}
3933
3975
  _arguments \\
3934
3976
  '1:query:' \\
3935
3977
  '--status[Filter by status]:status:(open "in progress" "in review" done closed)' \\
3936
- '--include-closed[Include done/closed tasks in search]' \\
3978
+ '--list[Filter by list ID]:list_id:' \\
3979
+ '--space[Filter by space ID]:space_id:' \\
3937
3980
  '--all[Search all workspace tasks, not just mine]' \\
3981
+ '--include-closed[Include done/closed tasks in search]' \\
3982
+ '--assignee[Filter by assignee]:user_id:' \\
3983
+ '--tag[Filter by tag name]:tag:' \\
3984
+ '--due-before[Tasks due before date]:date:' \\
3985
+ '--due-after[Tasks due after date]:date:' \\
3986
+ '--created-after[Tasks created after date]:date:' \\
3987
+ '--created-before[Tasks created before date]:date:' \\
3988
+ '--field[Filter by custom field]:field_name_and_value:' \\
3938
3989
  '--json[Force JSON output]'
3939
3990
  ;;
3940
3991
  summary)
@@ -4623,7 +4674,19 @@ async function searchTasks(config, query, opts = {}) {
4623
4674
  }
4624
4675
  const client = new ClickUpClient(config);
4625
4676
  const [allTasks, customTypes] = await Promise.all([
4626
- client.getMyTasks(config.teamId, { all: opts.all, includeClosed: opts.includeClosed }),
4677
+ client.getMyTasks(config.teamId, {
4678
+ all: opts.all,
4679
+ includeClosed: opts.includeClosed,
4680
+ listIds: opts.listIds,
4681
+ spaceIds: opts.spaceIds,
4682
+ assignees: opts.assignees,
4683
+ tags: opts.tags,
4684
+ dueDateGt: opts.dueDateGt,
4685
+ dueDateLt: opts.dueDateLt,
4686
+ dateCreatedGt: opts.dateCreatedGt,
4687
+ dateCreatedLt: opts.dateCreatedLt,
4688
+ customFields: opts.customFields
4689
+ }),
4627
4690
  client.getCustomTaskTypes(config.teamId)
4628
4691
  ]);
4629
4692
  const typeMap = buildTypeMap(customTypes);
@@ -5923,9 +5986,49 @@ function buildProgram(programName = basename(process.argv[1] ?? "cup")) {
5923
5986
  program.command("tasks").description("List tasks assigned to me (use --all for all tasks)").option("--status <status>", 'Filter by status (e.g. "in progress")').option("--list <listId>", "Filter by list ID").option("--space <spaceId>", "Filter by space ID").option("--name <partial>", "Filter by name (case-insensitive contains)").option(
5924
5987
  "--type <type>",
5925
5988
  'Filter by task type (e.g. "task", "initiative", or custom type name/ID)'
5926
- ).option("--all", "Include all tasks, not just mine").option("--include-closed", "Include done/closed tasks").option("--json", "Force JSON output even in terminal").action(
5989
+ ).option("--all", "Include all tasks, not just mine").option("--include-closed", "Include done/closed tasks").option("--assignee <userId>", 'Filter by assignee (user ID or "me")').option("--tag <tag>", "Filter by tag name").option("--due-before <date>", "Tasks due before date (YYYY-MM-DD)").option("--due-after <date>", "Tasks due after date (YYYY-MM-DD)").option("--created-after <date>", "Tasks created after date (YYYY-MM-DD)").option("--created-before <date>", "Tasks created before date (YYYY-MM-DD)").option("--field <nameAndValue...>", 'Filter by custom field: --field "Name" value').option("--json", "Force JSON output even in terminal").action(
5927
5990
  wrapAction(async (opts) => {
5928
5991
  const config = loadConfig(getProfileName());
5992
+ let assigneeIds;
5993
+ if (opts.assignee) {
5994
+ if (opts.assignee === "me") {
5995
+ const client = new ClickUpClient(config);
5996
+ const me = await client.getMe();
5997
+ assigneeIds = [me.id];
5998
+ } else {
5999
+ assigneeIds = [Number(opts.assignee)];
6000
+ }
6001
+ }
6002
+ const parseDateFilter = (d) => {
6003
+ const parts = d.split("-");
6004
+ return new Date(Number(parts[0]), Number(parts[1]) - 1, Number(parts[2])).getTime();
6005
+ };
6006
+ let customFields;
6007
+ if (opts.field?.length) {
6008
+ if (opts.field.length % 2 !== 0) {
6009
+ throw new Error('--field requires pairs: --field "Name" value');
6010
+ }
6011
+ if (!opts.list) {
6012
+ throw new Error("--field filtering requires --list to resolve field names");
6013
+ }
6014
+ const client = new ClickUpClient(config);
6015
+ const fields = await client.getListCustomFields(opts.list);
6016
+ customFields = [];
6017
+ for (let i = 0; i < opts.field.length; i += 2) {
6018
+ const fieldName = opts.field[i];
6019
+ const fieldValue = opts.field[i + 1];
6020
+ const match = fields.find((f) => f.name.toLowerCase() === fieldName.toLowerCase());
6021
+ if (!match) {
6022
+ const available = fields.map((f) => f.name).join(", ");
6023
+ throw new Error(`Field "${fieldName}" not found. Available: ${available}`);
6024
+ }
6025
+ customFields.push({
6026
+ field_id: match.id,
6027
+ operator: "=",
6028
+ value: fieldValue
6029
+ });
6030
+ }
6031
+ }
5929
6032
  const tasks = await fetchMyTasks(config, {
5930
6033
  typeFilter: opts.type,
5931
6034
  statuses: opts.status ? [opts.status] : void 0,
@@ -5933,6 +6036,13 @@ function buildProgram(programName = basename(process.argv[1] ?? "cup")) {
5933
6036
  spaceIds: opts.space ? [opts.space] : void 0,
5934
6037
  name: opts.name,
5935
6038
  all: opts.all,
6039
+ assignees: assigneeIds,
6040
+ tags: opts.tag ? [opts.tag] : void 0,
6041
+ dueDateLt: opts.dueBefore ? parseDateFilter(opts.dueBefore) : void 0,
6042
+ dueDateGt: opts.dueAfter ? parseDateFilter(opts.dueAfter) : void 0,
6043
+ dateCreatedGt: opts.createdAfter ? parseDateFilter(opts.createdAfter) : void 0,
6044
+ dateCreatedLt: opts.createdBefore ? parseDateFilter(opts.createdBefore) : void 0,
6045
+ customFields,
5936
6046
  includeClosed: opts.includeClosed
5937
6047
  });
5938
6048
  await printTasks(tasks, opts.json ?? false, config);
@@ -6159,14 +6269,63 @@ function buildProgram(programName = basename(process.argv[1] ?? "cup")) {
6159
6269
  await openTask(config, query, opts);
6160
6270
  })
6161
6271
  );
6162
- program.command("search <query>").description("Search my tasks by name (use --all for all tasks)").option("--status <status>", "Filter by status").option("--all", "Search all tasks, not just mine").option("--include-closed", "Include done/closed tasks in search").option("--json", "Force JSON output even in terminal").action(
6272
+ program.command("search <query>").description("Search my tasks by name (use --all for all tasks)").option("--status <status>", "Filter by status").option("--list <listId>", "Filter by list ID").option("--space <spaceId>", "Filter by space ID").option("--all", "Search all tasks, not just mine").option("--include-closed", "Include done/closed tasks in search").option("--assignee <userId>", 'Filter by assignee (user ID or "me")').option("--tag <tag>", "Filter by tag name").option("--due-before <date>", "Tasks due before date (YYYY-MM-DD)").option("--due-after <date>", "Tasks due after date (YYYY-MM-DD)").option("--created-after <date>", "Tasks created after date (YYYY-MM-DD)").option("--created-before <date>", "Tasks created before date (YYYY-MM-DD)").option("--field <nameAndValue...>", 'Filter by custom field: --field "Name" value').option("--json", "Force JSON output even in terminal").action(
6163
6273
  wrapAction(
6164
6274
  async (query, opts) => {
6165
6275
  const config = loadConfig(getProfileName());
6276
+ let assigneeIds;
6277
+ if (opts.assignee) {
6278
+ if (opts.assignee === "me") {
6279
+ const client = new ClickUpClient(config);
6280
+ const me = await client.getMe();
6281
+ assigneeIds = [me.id];
6282
+ } else {
6283
+ assigneeIds = [Number(opts.assignee)];
6284
+ }
6285
+ }
6286
+ const parseDateFilter = (d) => {
6287
+ const parts = d.split("-");
6288
+ return new Date(Number(parts[0]), Number(parts[1]) - 1, Number(parts[2])).getTime();
6289
+ };
6290
+ let customFields;
6291
+ if (opts.field?.length) {
6292
+ if (opts.field.length % 2 !== 0) {
6293
+ throw new Error('--field requires pairs: --field "Name" value');
6294
+ }
6295
+ if (!opts.list) {
6296
+ throw new Error("--field filtering requires --list to resolve field names");
6297
+ }
6298
+ const client = new ClickUpClient(config);
6299
+ const fields = await client.getListCustomFields(opts.list);
6300
+ customFields = [];
6301
+ for (let i = 0; i < opts.field.length; i += 2) {
6302
+ const fieldName = opts.field[i];
6303
+ const fieldValue = opts.field[i + 1];
6304
+ const match = fields.find((f) => f.name.toLowerCase() === fieldName.toLowerCase());
6305
+ if (!match) {
6306
+ const available = fields.map((f) => f.name).join(", ");
6307
+ throw new Error(`Field "${fieldName}" not found. Available: ${available}`);
6308
+ }
6309
+ customFields.push({
6310
+ field_id: match.id,
6311
+ operator: "=",
6312
+ value: fieldValue
6313
+ });
6314
+ }
6315
+ }
6166
6316
  const tasks = await searchTasks(config, query, {
6167
6317
  status: opts.status,
6168
6318
  all: opts.all,
6169
- includeClosed: opts.includeClosed
6319
+ includeClosed: opts.includeClosed,
6320
+ listIds: opts.list ? [opts.list] : void 0,
6321
+ spaceIds: opts.space ? [opts.space] : void 0,
6322
+ assignees: assigneeIds,
6323
+ tags: opts.tag ? [opts.tag] : void 0,
6324
+ dueDateLt: opts.dueBefore ? parseDateFilter(opts.dueBefore) : void 0,
6325
+ dueDateGt: opts.dueAfter ? parseDateFilter(opts.dueAfter) : void 0,
6326
+ dateCreatedGt: opts.createdAfter ? parseDateFilter(opts.createdAfter) : void 0,
6327
+ dateCreatedLt: opts.createdBefore ? parseDateFilter(opts.createdBefore) : void 0,
6328
+ customFields
6170
6329
  });
6171
6330
  await printTasks(tasks, opts.json ?? false, config);
6172
6331
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@krodak/clickup-cli",
3
- "version": "1.16.2",
3
+ "version": "1.17.0",
4
4
  "description": "ClickUp CLI for AI agents and humans",
5
5
  "type": "module",
6
6
  "license": "MIT",
package/skills/clickup-cli/SKILL.md CHANGED
@@ -48,39 +48,39 @@ All commands support `--help` for full flag details. All commands support `--jso
48
48
 
49
49
  ### Read
50
50
 
51
- | Command | What it returns |
52
- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
53
- | `cup tasks [--status s] [--name q] [--type t] [--list id] [--space id] [--all] [--include-closed]` | My tasks (filter by status, name, type, list, space). `--all` for all tasks in workspace |
54
- | `cup assigned [--status s] [--include-closed]` | All my tasks grouped by status |
55
- | `cup sprint [--status s] [--space nameOrId] [--folder id] [--include-closed]` | Tasks in active sprint (auto-detected) |
56
- | `cup sprints [--space nameOrId]` | List all sprints (marks active with \*) |
57
- | `cup search <query> [--status s] [--all] [--include-closed]` | Search my tasks by name. `--all` for all tasks |
58
- | `cup task <id>` | Single task details (custom fields, checklists, attachments, deps, links) |
59
- | `cup subtasks <id> [--status s] [--name q] [--include-closed]` | Subtasks of a task |
60
- | `cup comments <id>` | Comments on a task |
61
- | `cup activity <id>` | Task details + comment history combined |
62
- | `cup inbox [--days n] [--include-closed]` | Tasks updated in last n days (default 30) |
63
- | `cup summary [--hours n]` | Standup: completed, in-progress, overdue |
64
- | `cup overdue [--include-closed]` | Tasks past due date (most overdue first) |
65
- | `cup spaces [--name partial] [--my]` | List/filter workspace spaces |
66
- | `cup lists <spaceId> [--name partial]` | Lists in a space (including folder lists) |
67
- | `cup folders <spaceId> [--name partial]` | Folders in a space (with their lists) |
68
- | `cup members` | Workspace members (username, ID, email) |
69
- | `cup fields <listId>` | Custom fields on a list (type, required, options) |
70
- | `cup tags <spaceId>` | Tags available in a space |
71
- | `cup goals` | Workspace goals with progress |
72
- | `cup key-results <goalId>` | Key results for a goal |
73
- | `cup docs [query]` | Workspace docs (optionally filter by name) |
74
- | `cup doc <docId> [pageId]` | Doc metadata + page tree, or a specific page |
75
- | `cup doc-pages <docId>` | All pages in a doc with content |
76
- | `cup task-types` | Custom task types (for `--custom-item-id`) |
77
- | `cup templates` | Task templates (for `--template`) |
78
- | `cup list-templates` | List templates (for `list-from-template`) |
79
- | `cup folder-templates` | Folder templates |
80
- | `cup views <listId>` | List views on a list |
81
- | `cup view <viewId>` | Get view details |
82
- | `cup open <query>` | Open task in browser by ID or name |
83
- | `cup auth` | Check authentication status |
51
+ | Command | What it returns |
52
+ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
53
+ | `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]` | My tasks (filter by status, name, type, list, space, assignee, tag, dates, custom fields). `--all` for all tasks in workspace |
54
+ | `cup assigned [--status s] [--include-closed]` | All my tasks grouped by status |
55
+ | `cup sprint [--status s] [--space nameOrId] [--folder id] [--include-closed]` | Tasks in active sprint (auto-detected) |
56
+ | `cup sprints [--space nameOrId]` | List all sprints (marks active with \*) |
57
+ | `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 my tasks by name. `--all` for all tasks |
58
+ | `cup task <id>` | Single task details (custom fields, checklists, attachments, deps, links) |
59
+ | `cup subtasks <id> [--status s] [--name q] [--include-closed]` | Subtasks of a task |
60
+ | `cup comments <id>` | Comments on a task |
61
+ | `cup activity <id>` | Task details + comment history combined |
62
+ | `cup inbox [--days n] [--include-closed]` | Tasks updated in last n days (default 30) |
63
+ | `cup summary [--hours n]` | Standup: completed, in-progress, overdue |
64
+ | `cup overdue [--include-closed]` | Tasks past due date (most overdue first) |
65
+ | `cup spaces [--name partial] [--my]` | List/filter workspace spaces |
66
+ | `cup lists <spaceId> [--name partial]` | Lists in a space (including folder lists) |
67
+ | `cup folders <spaceId> [--name partial]` | Folders in a space (with their lists) |
68
+ | `cup members` | Workspace members (username, ID, email) |
69
+ | `cup fields <listId>` | Custom fields on a list (type, required, options) |
70
+ | `cup tags <spaceId>` | Tags available in a space |
71
+ | `cup goals` | Workspace goals with progress |
72
+ | `cup key-results <goalId>` | Key results for a goal |
73
+ | `cup docs [query]` | Workspace docs (optionally filter by name) |
74
+ | `cup doc <docId> [pageId]` | Doc metadata + page tree, or a specific page |
75
+ | `cup doc-pages <docId>` | All pages in a doc with content |
76
+ | `cup task-types` | Custom task types (for `--custom-item-id`) |
77
+ | `cup templates` | Task templates (for `--template`) |
78
+ | `cup list-templates` | List templates (for `list-from-template`) |
79
+ | `cup folder-templates` | Folder templates |
80
+ | `cup views <listId>` | List views on a list |
81
+ | `cup view <viewId>` | Get view details |
82
+ | `cup open <query>` | Open task in browser by ID or name |
83
+ | `cup auth` | Check authentication status |
84
84
 
85
85
  ### Write
86
86
 
@@ -157,28 +157,31 @@ All commands support `--help` for full flag details. All commands support `--jso
157
157
 
158
158
  ## Flags & Conventions
159
159
 
160
- | Topic | Detail |
161
- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
162
- | Task IDs | Native (`abc123def`) or custom (`PROJ-123`). Custom IDs auto-detected by `PREFIX-DIGITS` format |
163
- | `--status` | Fuzzy matching: exact > starts-with > contains. Prints match to stderr |
164
- | `--priority` | Names (`urgent`, `high`, `normal`, `low`) or numbers (1-4) |
165
- | `--due-date` | `YYYY-MM-DD` format |
166
- | `--assignee` | User ID or `me` |
167
- | `--tags` | Comma-separated (e.g. `--tags "bug,frontend"`) |
168
- | `--time-estimate` | Duration: `"2h"`, `"30m"`, `"1h30m"`, or raw milliseconds |
169
- | `--type` | `task` (regular) or custom type name/ID (e.g. `initiative`, `Bug`) |
170
- | `--custom-item-id` | Custom task type ID for `cup create` (find with `cup task-types`) |
171
- | `--space` | Partial name match or exact ID |
172
- | `--name` | Partial match, case-insensitive |
173
- | `--all` | Show all tasks in workspace, not just assigned to me. Available on `tasks`, `search`, `overdue`. Default: my tasks only (smaller output for agent context windows) |
174
- | `--include-closed` | Include closed/done tasks |
175
- | `--list` on create | Optional when `--parent` is given (auto-detected) |
176
- | `cup field --set` | Supports: text, number, checkbox (true/false), dropdown (option name), date (YYYY-MM-DD), url, email. Names resolved case-insensitively; errors list available fields/options |
177
- | `cup field-create` | Use `--options "a,b,c"` for `drop_down` and `labels` types (required). Other types don't need `--options` |
178
- | `cup sprint` | Auto-detects active sprint by folder name (sprint/iteration/cycle/scrum), parses multiple date formats. Override with `--folder <id>` or `cup config set sprintFolderId <id>` |
179
- | `cup link` | Both IDs must be the same type (both custom or both native) |
180
- | `cup delete` | DESTRUCTIVE. Requires `--confirm` in non-interactive mode. Cannot be undone |
181
- | Errors | stderr with exit code 1. Strict parsing - excess/unknown arguments rejected |
160
+ | Topic | Detail |
161
+ | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
162
+ | Task IDs | Native (`abc123def`) or custom (`PROJ-123`). Custom IDs auto-detected by `PREFIX-DIGITS` format |
163
+ | `--status` | Fuzzy matching: exact > starts-with > contains. Prints match to stderr |
164
+ | `--priority` | Names (`urgent`, `high`, `normal`, `low`) or numbers (1-4) |
165
+ | `--due-date` | `YYYY-MM-DD` format |
166
+ | `--assignee` | User ID or `me` |
167
+ | `--tags` | Comma-separated (e.g. `--tags "bug,frontend"`) |
168
+ | `--time-estimate` | Duration: `"2h"`, `"30m"`, `"1h30m"`, or raw milliseconds |
169
+ | `--type` | `task` (regular) or custom type name/ID (e.g. `initiative`, `Bug`) |
170
+ | `--custom-item-id` | Custom task type ID for `cup create` (find with `cup task-types`) |
171
+ | `--space` | Partial name match or exact ID |
172
+ | `--name` | Partial match, case-insensitive |
173
+ | `--all` | Show all tasks in workspace, not just assigned to me. Available on `tasks`, `search`, `overdue`. Default: my tasks only (smaller output for agent context windows) |
174
+ | `--include-closed` | Include closed/done tasks |
175
+ | `--list` on create | Optional when `--parent` is given (auto-detected) |
176
+ | `cup field --set` | Supports: text, number, checkbox (true/false), dropdown (option name), date (YYYY-MM-DD), url, email. Names resolved case-insensitively; errors list available fields/options |
177
+ | `cup field-create` | Use `--options "a,b,c"` for `drop_down` and `labels` types (required). Other types don't need `--options` |
178
+ | `--field` filter | `--field "Name" value` on `tasks` and `search` requires `--list` to resolve field names to IDs |
179
+ | `--due-before/after` | `YYYY-MM-DD` date filters for due date range |
180
+ | `--created-before/after` | `YYYY-MM-DD` date filters for creation date range |
181
+ | `cup sprint` | Auto-detects active sprint by folder name (sprint/iteration/cycle/scrum), parses multiple date formats. Override with `--folder <id>` or `cup config set sprintFolderId <id>` |
182
+ | `cup link` | Both IDs must be the same type (both custom or both native) |
183
+ | `cup delete` | DESTRUCTIVE. Requires `--confirm` in non-interactive mode. Cannot be undone |
184
+ | Errors | stderr with exit code 1. Strict parsing - excess/unknown arguments rejected |
182
185
 
183
186
  ## Agent Workflow Examples
184
187
 
@@ -199,8 +202,13 @@ cup tasks --status "in progress" # by status
199
202
  cup tasks --name "login" # by partial name
200
203
  cup tasks --type initiative # initiatives only
201
204
  cup tasks --list 12345 --all # all tasks in list, not just mine
205
+ cup tasks --tag "bug" --status "to do" # by tag and status
206
+ cup tasks --list 123 --field "Sprint" "Week 1" # by custom field
207
+ cup tasks --due-before 2026-04-01 # due before a date
208
+ cup tasks --assignee me --created-after 2026-03-01 # my tasks created recently
202
209
  cup search "payment flow" # multi-word search
203
210
  cup search auth --status "prog" # fuzzy status match
211
+ cup search "auth" --list 123 --space 456 # search within list and space
204
212
  cup sprint # current sprint
205
213
  cup assigned # all my tasks by status
206
214
  cup overdue # past due date