feat: add --parent flag to checklist add-item and edit-item for nested items (#54)

Kaiskii · web-flow · commit 6dff0620a999 · 2026-04-20T10:39:30.000+02:00
* feat: add --parent flag to checklist add-item and edit-item for nested items

* feat: render nested checklist items in view output
diff --git a/docs/commands.md b/docs/commands.md
@@ -868,7 +868,9 @@ cup checklist view abc123                           # view all checklists on a t
 cup checklist create abc123 "QA Checklist"           # add a checklist
 cup checklist delete <checklistId>                   # remove a checklist
 cup checklist add-item <checklistId> "Run tests"     # add an item
+cup checklist add-item <clId> "Sub step" --parent <itemId>   # nest under parent
 cup checklist edit-item <clId> <itemId> --resolved   # mark item done
+cup checklist edit-item <clId> <itemId> --parent <newParent> # reparent (use "null" to unnest)
 cup checklist delete-item <clId> <itemId>            # remove an item
 ```
 
@@ -877,11 +879,11 @@ cup checklist delete-item <clId> <itemId>            # remove an item
 | `view`        | `<taskId>`                       | Show all checklists   |
 | `create`      | `<taskId> <name>`                | Create a checklist    |
 | `delete`      | `<checklistId>`                  | Delete a checklist    |
-| `add-item`    | `<checklistId> <name>`           | Add checklist item    |
+| `add-item`    | `<checklistId> <name> [flags]`   | Add checklist item    |
 | `edit-item`   | `<checklistId> <itemId> [flags]` | Edit checklist item   |
 | `delete-item` | `<checklistId> <itemId>`         | Delete checklist item |
 
-`edit-item` flags: `--name <text>`, `--resolved`, `--unresolved`, `--assignee <userId>`. All subcommands support `--json`.
+`add-item` flags: `--parent <itemId>` to nest under a parent item. `edit-item` flags: `--name <text>`, `--resolved`, `--unresolved`, `--assignee <userId>`, `--parent <itemId>` (pass `"null"` to unnest). All subcommands support `--json`.
 
 Checklists are also shown inline in `cup task <id>` detail view.
 
diff --git a/skills/clickup-cli/SKILL.md b/skills/clickup-cli/SKILL.md
@@ -173,8 +173,8 @@ All commands support `--help` for full flag details. All commands support `--jso
 | `cup checklist view <id>`                                                                                                                                                                                                                                       | View checklists on a task                                                            |
 | `cup checklist create <id> <name>`                                                                                                                                                                                                                              | Create a checklist                                                                   |
 | `cup checklist delete <checklistId>`                                                                                                                                                                                                                            | Delete a checklist                                                                   |
-| `cup checklist add-item <checklistId> <name>`                                                                                                                                                                                                                   | Add item to checklist                                                                |
-| `cup checklist edit-item <checklistId> <itemId> [--name n] [--resolved] [--unresolved] [--assignee id]`                                                                                                                                                         | Edit checklist item                                                                  |
+| `cup checklist add-item <checklistId> <name> [--parent itemId]`                                                                                                                                                                                                 | Add item to checklist (nest under parent via `--parent`)                             |
+| `cup checklist edit-item <checklistId> <itemId> [--name n] [--resolved] [--unresolved] [--assignee id] [--parent itemId\|null]`                                                                                                                                 | Edit checklist item (reparent with `--parent`, use `"null"` to unnest)               |
 | `cup checklist delete-item <checklistId> <itemId>`                                                                                                                                                                                                              | Delete checklist item                                                                |
 | `cup time start <taskId> [-d desc]`                                                                                                                                                                                                                             | Start timer                                                                          |
 | `cup time stop`                                                                                                                                                                                                                                                 | Stop running timer                                                                   |
@@ -305,7 +305,9 @@ cup field abc123def --set "Story Points" 5
 cup tag abc123def --add "bug,frontend"
 cup checklist create abc123def "QA Steps"
 cup checklist add-item <clId> "Run unit tests"
+cup checklist add-item <clId> "Sub step" --parent <itemId>           # nest under parent
 cup checklist edit-item <clId> <itemId> --resolved
+cup checklist edit-item <clId> <itemId> --parent <newParent>         # reparent (use "null" to unnest)
 cup link abc123 def456
 cup attach abc123def ./screenshot.png
 cup time start abc123def -d "Working on feature"
diff --git a/src/api.ts b/src/api.ts
@@ -187,6 +187,7 @@ export interface ChecklistItem {
   assignee?: { id: number; username: string } | null
   orderindex: number
   parent?: string | null
+  children?: ChecklistItem[]
 }
 
 export interface Checklist {
@@ -974,10 +975,16 @@ export class ClickUpClient {
     await this.request<Record<string, never>>(`/checklist/${checklistId}`, { method: 'DELETE' })
   }
 
-  async createChecklistItem(checklistId: string, name: string): Promise<Checklist> {
+  async createChecklistItem(
+    checklistId: string,
+    name: string,
+    parent?: string | null,
+  ): Promise<Checklist> {
+    const body: Record<string, unknown> = { name }
+    if (parent !== undefined) body.parent = parent
     const data = await this.request<{ checklist: Checklist }>(
       `/checklist/${checklistId}/checklist_item`,
-      { method: 'POST', body: JSON.stringify({ name }) },
+      { method: 'POST', body: JSON.stringify(body) },
     )
     return expectRecordField(
       data as Record<string, unknown>,
@@ -989,7 +996,12 @@ export class ClickUpClient {
   async editChecklistItem(
     checklistId: string,
     checklistItemId: string,
-    updates: { name?: string; resolved?: boolean; assignee?: number | null },
+    updates: {
+      name?: string
+      resolved?: boolean
+      assignee?: number | null
+      parent?: string | null
+    },
   ): Promise<Checklist> {
     const data = await this.request<{ checklist: Checklist }>(
       `/checklist/${checklistId}/checklist_item/${checklistItemId}`,
diff --git a/src/commands/checklist.ts b/src/commands/checklist.ts
@@ -31,16 +31,22 @@ export async function addChecklistItem(
   config: Config,
   checklistId: string,
   name: string,
+  parent?: string | null,
 ): Promise<Checklist> {
   const client = new ClickUpClient(config)
-  return client.createChecklistItem(checklistId, name)
+  return client.createChecklistItem(checklistId, name, parent)
 }
 
 export async function editChecklistItem(
   config: Config,
   checklistId: string,
   checklistItemId: string,
-  updates: { name?: string; resolved?: boolean; assignee?: number | null },
+  updates: {
+    name?: string
+    resolved?: boolean
+    assignee?: number | null
+    parent?: string | null
+  },
 ): Promise<Checklist> {
   const client = new ClickUpClient(config)
   return client.editChecklistItem(checklistId, checklistItemId, updates)
@@ -56,33 +62,63 @@ export async function deleteChecklistItem(
   return { checklistId, checklistItemId }
 }
 
+function sortByOrder(items: ChecklistItem[]): ChecklistItem[] {
+  return [...items].sort((a, b) => (a.orderindex ?? 0) - (b.orderindex ?? 0))
+}
+
+function countItems(items: ChecklistItem[]): { total: number; resolved: number } {
+  let total = 0
+  let resolved = 0
+  for (const item of items) {
+    total++
+    if (item.resolved) resolved++
+    if (item.children?.length) {
+      const nested = countItems(item.children)
+      total += nested.total
+      resolved += nested.resolved
+    }
+  }
+  return { total, resolved }
+}
+
 export function formatChecklists(checklists: Checklist[]): string {
   if (checklists.length === 0) return 'No checklists'
   const lines: string[] = []
+  const renderItem = (item: ChecklistItem, depth: number): void => {
+    const indent = '  '.repeat(depth + 1)
+    const check = item.resolved ? chalk.green('[x]') : chalk.dim('[ ]')
+    const name = item.resolved ? chalk.dim(item.name) : item.name
+    const assignee = item.assignee ? chalk.dim(` @${item.assignee.username}`) : ''
+    lines.push(`${indent}${check} ${name}${assignee}`)
+    lines.push(chalk.dim(`${indent}    item-id: ${item.id}`))
+    for (const child of sortByOrder(item.children ?? [])) {
+      renderItem(child, depth + 1)
+    }
+  }
   for (const cl of checklists) {
-    const resolved = cl.items.filter(i => i.resolved).length
-    lines.push(chalk.bold(`${cl.name} (${resolved}/${cl.items.length})`))
+    const { total, resolved } = countItems(cl.items)
+    lines.push(chalk.bold(`${cl.name} (${resolved}/${total})`))
     lines.push(chalk.dim(`  ID: ${cl.id}`))
-    for (const item of cl.items) {
-      const check = item.resolved ? chalk.green('[x]') : chalk.dim('[ ]')
-      const name = item.resolved ? chalk.dim(item.name) : item.name
-      const assignee = item.assignee ? chalk.dim(` @${item.assignee.username}`) : ''
-      lines.push(`  ${check} ${name}${assignee}`)
-      lines.push(chalk.dim(`      item-id: ${item.id}`))
-    }
+    for (const item of sortByOrder(cl.items)) renderItem(item, 0)
   }
   return lines.join('\n')
 }
 
 export function formatChecklistsMarkdown(checklists: Checklist[]): string {
   if (checklists.length === 0) return 'No checklists'
+  const renderItem = (item: ChecklistItem, depth: number): string[] => {
+    const indent = '  '.repeat(depth)
+    const lines = [`${indent}- [${item.resolved ? 'x' : ' '}] ${item.name}`]
+    for (const child of sortByOrder(item.children ?? [])) {
+      lines.push(...renderItem(child, depth + 1))
+    }
+    return lines
+  }
   return checklists
     .map(cl => {
-      const resolved = cl.items.filter((i: ChecklistItem) => i.resolved).length
-      const header = `### ${cl.name} (${resolved}/${cl.items.length})`
-      const items = cl.items.map(
-        (item: ChecklistItem) => `- [${item.resolved ? 'x' : ' '}] ${item.name}`,
-      )
+      const { total, resolved } = countItems(cl.items)
+      const header = `### ${cl.name} (${resolved}/${total})`
+      const items = sortByOrder(cl.items).flatMap(item => renderItem(item, 0))
       return [header, '', ...items].join('\n')
     })
     .join('\n\n')
diff --git a/src/index.ts b/src/index.ts
@@ -1232,17 +1232,20 @@ export function buildProgram(programName = basename(process.argv[1] ?? 'cup')):
   checklistCmd
     .command('add-item <checklistId> <name>')
     .description('Add an item to a checklist')
+    .option('--parent <itemId>', 'Nest under a parent checklist item ID')
     .option('--json', 'Force JSON output even in terminal')
     .action(
-      wrapAction(async (checklistId: string, name: string, opts: { json?: boolean }) => {
-        const config = loadConfig(getProfileName())
-        const result = await addChecklistItem(config, checklistId, name)
-        if (shouldOutputJson(opts.json ?? false)) {
-          console.log(JSON.stringify(result, null, 2))
-        } else {
-          console.log(`Added item "${name}" to checklist ${checklistId}`)
-        }
-      }),
+      wrapAction(
+        async (checklistId: string, name: string, opts: { parent?: string; json?: boolean }) => {
+          const config = loadConfig(getProfileName())
+          const result = await addChecklistItem(config, checklistId, name, opts.parent)
+          if (shouldOutputJson(opts.json ?? false)) {
+            console.log(JSON.stringify(result, null, 2))
+          } else {
+            console.log(`Added item "${name}" to checklist ${checklistId}`)
+          }
+        },
+      ),
     )
 
   checklistCmd
@@ -1252,6 +1255,10 @@ export function buildProgram(programName = basename(process.argv[1] ?? 'cup')):
     .option('--resolved', 'Mark item as resolved')
     .option('--unresolved', 'Mark item as unresolved')
     .option('--assignee <userId>', 'Assign user by ID (use "null" to unassign)')
+    .option(
+      '--parent <itemId>',
+      'Reparent item under another checklist item ID (use "null" to unnest)',
+    )
     .option('--json', 'Force JSON output even in terminal')
     .action(
       wrapAction(
@@ -1263,11 +1270,17 @@ export function buildProgram(programName = basename(process.argv[1] ?? 'cup')):
             resolved?: boolean
             unresolved?: boolean
             assignee?: string
+            parent?: string
             json?: boolean
           },
         ) => {
           const config = loadConfig(getProfileName())
-          const updates: { name?: string; resolved?: boolean; assignee?: number | null } = {}
+          const updates: {
+            name?: string
+            resolved?: boolean
+            assignee?: number | null
+            parent?: string | null
+          } = {}
           if (opts.name) updates.name = opts.name
           if (opts.resolved) updates.resolved = true
           if (opts.unresolved) updates.resolved = false
@@ -1277,6 +1290,9 @@ export function buildProgram(programName = basename(process.argv[1] ?? 'cup')):
                 ? null
                 : parseOptionalNumberOption(opts.assignee, '--assignee')
           }
+          if (opts.parent !== undefined) {
+            updates.parent = opts.parent === 'null' ? null : opts.parent
+          }
           const result = await editChecklistItem(config, checklistId, checklistItemId, updates)
           if (shouldOutputJson(opts.json ?? false)) {
             console.log(JSON.stringify(result, null, 2))
diff --git a/tests/unit/api.test.ts b/tests/unit/api.test.ts
@@ -746,6 +746,24 @@ describe('checklist API methods', () => {
     )
   })
 
+  it('createChecklistItem includes parent in body when provided', async () => {
+    const checklist = {
+      id: 'cl1',
+      name: 'QA',
+      orderindex: 0,
+      items: [{ id: 'i1', name: 'Sub', resolved: false, orderindex: 0 }],
+    }
+    mockFetch.mockReturnValue(mockResponse({ checklist }))
+    await client.createChecklistItem('cl1', 'Sub', 'parent1')
+    expect(mockFetch).toHaveBeenCalledWith(
+      expect.stringContaining('/checklist/cl1/checklist_item'),
+      expect.objectContaining({
+        method: 'POST',
+        body: JSON.stringify({ name: 'Sub', parent: 'parent1' }),
+      }),
+    )
+  })
+
   it('editChecklistItem sends PUT to checklist item endpoint', async () => {
     const checklist = {
       id: 'cl1',
diff --git a/tests/unit/commands/checklist.test.ts b/tests/unit/commands/checklist.test.ts
@@ -108,9 +108,23 @@ describe('addChecklistItem', () => {
 
     const { addChecklistItem } = await import('../../../src/commands/checklist.js')
     const result = await addChecklistItem(config, 'cl1', 'Step 1')
-    expect(mockCreateChecklistItem).toHaveBeenCalledWith('cl1', 'Step 1')
+    expect(mockCreateChecklistItem).toHaveBeenCalledWith('cl1', 'Step 1', undefined)
     expect(result).toEqual(checklist)
   })
+
+  it('forwards parent item ID when provided', async () => {
+    const checklist = {
+      id: 'cl1',
+      name: 'QA',
+      orderindex: 0,
+      items: [{ id: 'item1', name: 'Sub step', resolved: false, orderindex: 0 }],
+    }
+    mockCreateChecklistItem.mockResolvedValue(checklist)
+
+    const { addChecklistItem } = await import('../../../src/commands/checklist.js')
+    await addChecklistItem(config, 'cl1', 'Sub step', 'parent1')
+    expect(mockCreateChecklistItem).toHaveBeenCalledWith('cl1', 'Sub step', 'parent1')
+  })
 })
 
 describe('editChecklistItem', () => {
@@ -177,6 +191,38 @@ describe('formatChecklists', () => {
     expect(output).toContain('i1')
     expect(output).toContain('i2')
   })
+
+  it('renders nested children with deeper indentation and includes them in totals', async () => {
+    const { formatChecklists } = await import('../../../src/commands/checklist.js')
+    const checklists = [
+      {
+        id: 'cl1',
+        name: 'QA Checks',
+        orderindex: 0,
+        items: [
+          {
+            id: 'p1',
+            name: 'Parent',
+            resolved: false,
+            orderindex: 0,
+            children: [
+              { id: 'c1', name: 'Child A', resolved: true, orderindex: 0 },
+              { id: 'c2', name: 'Child B', resolved: false, orderindex: 1 },
+            ],
+          },
+        ],
+      },
+    ]
+    const output = formatChecklists(checklists)
+    expect(output).toContain('1/3')
+    expect(output).toContain('Parent')
+    expect(output).toContain('Child A')
+    expect(output).toContain('Child B')
+    const parentLine = output.split('\n').find(l => l.includes('Parent')) ?? ''
+    const childLine = output.split('\n').find(l => l.includes('Child A')) ?? ''
+    const leading = (s: string) => s.match(/^\s*/)?.[0].length ?? 0
+    expect(leading(childLine)).toBeGreaterThan(leading(parentLine))
+  })
 })
 
 describe('formatChecklistsMarkdown', () => {
@@ -225,4 +271,28 @@ describe('formatChecklistsMarkdown', () => {
     expect(output).toContain('### Second (1/1)')
     expect(output).toContain('\n\n')
   })
+
+  it('renders nested children as indented markdown list items', async () => {
+    const { formatChecklistsMarkdown } = await import('../../../src/commands/checklist.js')
+    const checklists = [
+      {
+        id: 'cl1',
+        name: 'QA Checks',
+        orderindex: 0,
+        items: [
+          {
+            id: 'p1',
+            name: 'Parent',
+            resolved: false,
+            orderindex: 0,
+            children: [{ id: 'c1', name: 'Child A', resolved: true, orderindex: 0 }],
+          },
+        ],
+      },
+    ]
+    const output = formatChecklistsMarkdown(checklists)
+    expect(output).toContain('### QA Checks (1/2)')
+    expect(output).toContain('- [ ] Parent')
+    expect(output).toContain('  - [x] Child A')
+  })
 })
