npm - @krodak/clickup-cli - Versions diffs - 0.13.2 → 0.15.0 - Mend

@krodak/clickup-cli 0.13.2 → 0.15.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

package/README.md +160 -441
package/dist/index.js +553 -4
package/package.json +1 -1
package/skills/clickup-cli/SKILL.md +27 -2

package/README.md CHANGED Viewed

@@ -8,503 +8,218 @@
 [![CI](https://github.com/krodak/clickup-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/krodak/clickup-cli/actions/workflows/ci.yml)
 ```bash
-npm install -g @krodak/clickup-cli   # or: brew tap krodak/tap && brew install clickup-cli
-cu init                               # walks you through API token + workspace setup
+npm install -g @krodak/clickup-cli && cu init
 ```
-You need a ClickUp personal API token (`pk_...` from https://app.clickup.com/settings/apps).
+## Talk to your agent
-## Using with AI agents
+Install `cu`, install the skill file, and your agent works with ClickUp. No API knowledge needed.
-This is the primary use case. Install the tool, install the skill file, and your agent knows how to work with ClickUp.
+> **"Read task abc123, do the work, then mark it in review and leave a comment with the commit hash."**
-### 1. Install the skill
+> **"What's my standup? What did I finish, what's in progress, what's overdue?"**
-The repo includes a skill file at `skills/clickup-cli/SKILL.md` that teaches agents all available commands and when to use them. It's also packaged as a Claude Code plugin.
+> **"Create a subtask under the initiative for the edge case we found."**
-**Claude Code (plugin - recommended):**
+> **"Check my sprint and tell me what's behind schedule."**
-The repo ships as a Claude Code plugin. Point Claude Code at the repo or installed npm package:
+> **"Update the description with your findings and flag blockers in a comment."**
-```bash
-claude --plugin-dir ./node_modules/@krodak/clickup-cli
-```
-Or copy the skill manually:
-```bash
-mkdir -p ~/.claude/skills/clickup
-cp skills/clickup-cli/SKILL.md ~/.claude/skills/clickup/SKILL.md
-```
-Then reference it in your `CLAUDE.md` or project instructions.
-**OpenCode:**
-```bash
-mkdir -p ~/.config/opencode/skills/clickup
-cp skills/clickup-cli/SKILL.md ~/.config/opencode/skills/clickup/SKILL.md
-```
-**Codex / other agents:**
-Copy the contents of `skills/clickup-cli/SKILL.md` into your system prompt or project instructions. It's a standalone markdown document.
-### 2. Talk to your agent
-Once the skill is installed, you just tell the agent what you need in plain language. It figures out which `cu` commands to run.
-```
-"Read the description of task <id>, do the work, then mark it in review and leave a comment with the commit hash."
+The agent reads the skill file, picks the right `cu` commands, and handles everything. You don't need to learn the CLI - the agent does.
-"Check all subtasks under initiative <id> and improve their descriptions based on what's in the codebase."
+## Setup
-"What's my standup summary? What did I finish yesterday, what's in progress, what's overdue?"
+You need Node 22+ and a ClickUp personal API token (`pk_...` from [ClickUp Settings > Apps](https://app.clickup.com/settings/apps)).
-"Do exploratory work for task <id>, update the description with your findings, and flag blockers in a comment."
+<details open>
+<summary>&nbsp;<img src="https://cdn.simpleicons.org/openai/999999" height="16" align="center">&nbsp;<strong>OpenCode</strong></summary>
-"Create a subtask under <id> for the edge case we just found."
-"Check my sprint and tell me what's overdue."
-```
-You don't need to learn the CLI commands yourself. The agent handles it.
-### Why a CLI and not MCP?
-A CLI + skill file has fewer moving parts. No extra server process, no protocol layer. The agent already knows how to run shell commands - the skill file just teaches it which ones exist. This matches what Peter Steinberger and the OpenClaw project have found: for tool-use with coding agents, CLI + instructions tends to work better than MCP in practice.
-### Scoped output
-Most commands return only your tasks by default. `cu tasks`, `cu sprint`, `cu overdue`, `cu summary` all scope to what's assigned to you. `cu spaces --my` filters to spaces where you have tasks. This keeps output small and relevant - important when it's going into an agent's context window.
-## Using from the terminal
-When you run `cu` in a terminal directly, you get an interactive mode with tables and a task picker.
-```bash
-cu tasks                          # interactive table with checkbox picker
-cu sprint                         # your sprint tasks, auto-detected
-cu summary                        # standup helper: completed / in progress / overdue
-cu overdue                        # tasks past their due date
-cu open "login bug"               # fuzzy search, opens in browser
-cu update abc123 -s "done"        # update status
-cu assign abc123 --to me          # assign yourself
-```
-Pass `--json` to any read command to force JSON output instead of the default format.
-When output is piped (no TTY), all commands output **Markdown** by default - optimized for AI agent context windows. Pass `--json` to any command for JSON output. Set `CU_OUTPUT=json` environment variable to always get JSON when piped.
-## Commands
-29 commands total. All support `--help` for full flag details.
-### `cu init`
-First-time setup. Prompts for your API token, verifies it, auto-detects your workspace, and writes `~/.config/cu/config.json`.
+**1. Install the CLI**
 ```bash
+npm install -g @krodak/clickup-cli
 cu init
 ```
-### `cu tasks`
-List tasks assigned to me. By default shows all task types. Use `--type` to filter by task type.
-```bash
-cu tasks
-cu tasks --status "in progress"
-cu tasks --name "login"
-cu tasks --type task                  # regular tasks only
-cu tasks --type initiative            # initiatives only
-cu tasks --type "Bug"                 # custom task type by name
-cu tasks --list <listId>
-cu tasks --space <spaceId>
-cu tasks --include-closed
-cu tasks --json
-```
-### `cu sprint`
-List my tasks in the currently active sprint (auto-detected from sprint folder date ranges).
-```bash
-cu sprint
-cu sprint --status "in progress"
-cu sprint --include-closed
-cu sprint --json
-```
-### `cu sprints`
-List all sprints across sprint folders. Marks the currently active sprint.
-```bash
-cu sprints
-cu sprints --space "Engineering"
-cu sprints --json
-```
-### `cu assigned`
-All tasks assigned to me, grouped by pipeline stage (code review, in progress, to do, etc.).
-```bash
-cu assigned
-cu assigned --status "in progress"
-cu assigned --include-closed
-cu assigned --json
-```
-### `cu inbox`
-Tasks assigned to me that were recently updated, grouped by time period (today, yesterday, last 7 days, etc.). Default lookback is 30 days.
-```bash
-cu inbox
-cu inbox --days 7
-cu inbox --include-closed
-cu inbox --json
-```
-### `cu task <id>`
-Get task details including custom fields. Pretty summary in terminal, JSON when piped.
-```bash
-cu task abc123
-cu task abc123 --json
-```
-**Note:** When piped, `cu task` outputs a structured Markdown summary of the task. For the full raw API response with all fields (custom fields, checklists, etc.), use `--json`.
-### `cu subtasks <id>`
-List subtasks of a task.
-```bash
-cu subtasks abc123
-cu subtasks abc123 --status "in progress"
-cu subtasks abc123 --name "auth"
-cu subtasks abc123 --include-closed
-cu subtasks abc123 --json
-```
-### `cu update <id>`
-Update a task. Provide at least one option.
-```bash
-cu update abc123 -s "in progress"
-cu update abc123 -n "New task name"
-cu update abc123 -d "Updated description with **markdown**"
-cu update abc123 --priority high
-cu update abc123 --due-date 2025-03-15
-cu update abc123 --assignee me
-cu update abc123 --assignee 12345
-cu update abc123 -n "New name" -s "done" --priority urgent
-cu update abc123 --time-estimate 2h
-cu update abc123 --parent parentTaskId   # make it a subtask
-cu update abc123 -s "in progress" --json
-```
-| Flag                         | Description                                                                 |
-| ---------------------------- | --------------------------------------------------------------------------- |
-| `-n, --name <text>`          | New task name                                                               |
-| `-d, --description <text>`   | New description (markdown supported)                                        |
-| `-s, --status <status>`      | New status, supports fuzzy matching (e.g. `"prog"` matches `"in progress"`) |
-| `--priority <level>`         | Priority: `urgent`, `high`, `normal`, `low` (or 1-4)                        |
-| `--due-date <date>`          | Due date (`YYYY-MM-DD`)                                                     |
-| `--time-estimate <duration>` | Time estimate (e.g. `"2h"`, `"30m"`, `"1h30m"`)                             |
-| `--assignee <userId>`        | Add assignee by user ID or `"me"`                                           |
-| `--parent <taskId>`          | Set parent task (makes this a subtask)                                      |
-| `--json`                     | Force JSON output even in terminal                                          |
-### `cu create`
-Create a new task. If `--parent` is given, list is auto-detected from the parent task.
-```bash
-cu create -n "Fix login bug" -l <listId>
-cu create -n "Subtask name" -p <parentTaskId>    # --list auto-detected
-cu create -n "Task" -l <listId> -d "desc" -s "open"
-cu create -n "Task" -l <listId> --priority high --due-date 2025-06-01
-cu create -n "Task" -l <listId> --assignee me --tags "bug,frontend"
-cu create -n "Initiative" -l <listId> --custom-item-id 1
-cu create -n "Task" -l <listId> --time-estimate 2h
-cu create -n "Fix bug" -l <listId> --json
-```
-| Flag                         | Required         | Description                                          |
-| ---------------------------- | ---------------- | ---------------------------------------------------- |
-| `-n, --name <name>`          | yes              | Task name                                            |
-| `-l, --list <listId>`        | if no `--parent` | Target list ID                                       |
-| `-p, --parent <taskId>`      | no               | Parent task (list auto-detected)                     |
-| `-d, --description <text>`   | no               | Description (markdown)                               |
-| `-s, --status <status>`      | no               | Initial status                                       |
-| `--priority <level>`         | no               | Priority: `urgent`, `high`, `normal`, `low` (or 1-4) |
-| `--due-date <date>`          | no               | Due date (`YYYY-MM-DD`)                              |
-| `--time-estimate <duration>` | no               | Time estimate (e.g. `"2h"`, `"30m"`, `"1h30m"`)      |
-| `--assignee <userId>`        | no               | Assignee by user ID or `"me"`                        |
-| `--tags <tags>`              | no               | Comma-separated tag names                            |
-| `--custom-item-id <id>`      | no               | Custom task type ID (e.g. for creating initiatives)  |
-| `--json`                     | no               | Force JSON output even in terminal                   |
-### `cu delete <id>`
-Delete a task. **DESTRUCTIVE - cannot be undone.**
-```bash
-cu delete abc123
-cu delete abc123 --confirm
-cu delete abc123 --confirm --json
-```
-In TTY mode without `--confirm`: shows the task name and prompts for confirmation (default: No). In non-interactive/piped mode, `--confirm` is required.
-| Flag        | Description                                                 |
-| ----------- | ----------------------------------------------------------- |
-| `--confirm` | Skip confirmation prompt (required in non-interactive mode) |
-| `--json`    | Force JSON output                                           |
-### `cu field <id>`
-Set or remove a custom field value. Field names are resolved case-insensitively; errors list available fields/options.
-```bash
-cu field abc123 --set "Priority Level" high
-cu field abc123 --set "Story Points" 5
-cu field abc123 --set "Approved" true
-cu field abc123 --set "Category" "Bug Fix"
-cu field abc123 --set "Due" 2025-06-01
-cu field abc123 --set "Website" "https://example.com"
-cu field abc123 --set "Contact" "user@example.com"
-cu field abc123 --remove "Priority Level"
-cu field abc123 --set "Points" 3 --remove "Old Field"
-cu field abc123 --set "Points" 3 --json
-```
-| Flag                       | Description                                                                                                                      |
-| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `--set "Field Name" <val>` | Set a custom field by name. Supports: text, number, checkbox (true/false), dropdown (option name), date (YYYY-MM-DD), url, email |
-| `--remove "Field Name"`    | Remove a custom field value                                                                                                      |
-| `--json`                   | Force JSON output                                                                                                                |
-Both `--set` and `--remove` can be used together in one invocation.
-### `cu comment <id>`
-Post a comment on a task.
-```bash
-cu comment abc123 -m "Addressed in PR #42"
-cu comment abc123 -m "Done" --json
-```
-### `cu comments <id>`
-List comments on a task. Formatted view in terminal, JSON when piped.
-```bash
-cu comments abc123
-cu comments abc123 --json
-```
-### `cu activity <id>`
-View task details and comment history together. Combines `cu task` and `cu comments` into a single view.
-```bash
-cu activity abc123
-cu activity abc123 --json
-```
-### `cu lists <spaceId>`
-List all lists in a space, including lists inside folders. Useful for discovering list IDs needed by `--list` filter and `cu create -l`.
-```bash
-cu lists <spaceId>
-cu lists <spaceId> --name "sprint"
-cu lists <spaceId> --json
-```
-| Flag               | Description                        |
-| ------------------ | ---------------------------------- |
-| `--name <partial>` | Filter lists by partial name match |
-| `--json`           | Force JSON output                  |
-### `cu spaces`
-List spaces in your workspace. Useful for getting space IDs for the `--space` filter.
-```bash
-cu spaces
-cu spaces --name "eng"
-cu spaces --my
-cu spaces --json
-```
-| Flag               | Description                                  |
-| ------------------ | -------------------------------------------- |
-| `--name <partial>` | Filter spaces by partial name match          |
-| `--my`             | Show only spaces where I have assigned tasks |
-| `--json`           | Force JSON output                            |
-### `cu open <query>`
-Open a task in the browser. Accepts a task ID or partial name.
-```bash
-cu open abc123
-cu open "login bug"
-cu open abc123 --json
-```
-If the query matches multiple tasks by name, all matches are listed and the first is opened.
-### `cu search <query>`
-Search my tasks by name. Supports multi-word queries with case-insensitive matching. Status filter supports fuzzy matching.
-```bash
-cu search "login bug"
-cu search auth
-cu search "payment flow" --json
-cu search auth --status "prog"     # fuzzy matches "in progress"
-cu search "old task" --include-closed
-```
-### `cu summary`
-Daily standup helper. Shows tasks grouped into: recently completed, in progress, and overdue.
+**2. Install the skill**
 ```bash
-cu summary
-cu summary --hours 48
-cu summary --json
+mkdir -p ~/.config/opencode/skills/clickup
+cp $(npm root -g)/@krodak/clickup-cli/skills/clickup-cli/SKILL.md ~/.config/opencode/skills/clickup/SKILL.md
 ```
-| Flag          | Description                                        |
-| ------------- | -------------------------------------------------- |
-| `--hours <n>` | Lookback for recently completed tasks (default 24) |
-| `--json`      | Force JSON output                                  |
+</details>
-### `cu overdue`
+<details>
+<summary>&nbsp;<img src="https://cdn.simpleicons.org/anthropic/D97757" height="16" align="center">&nbsp;<strong>Claude Code</strong></summary>
-List tasks that are past their due date (excludes done/closed tasks by default). Sorted most overdue first.
+**1. Install the CLI**
 ```bash
-cu overdue
-cu overdue --include-closed
-cu overdue --json
+npm install -g @krodak/clickup-cli
+cu init
 ```
-### `cu assign <id>`
-Assign or unassign users from a task. Supports `me` as shorthand for your user ID.
+**2. Install the skill**
 ```bash
-cu assign abc123 --to 12345
-cu assign abc123 --to me
-cu assign abc123 --remove 12345
-cu assign abc123 --to me --remove 67890
-cu assign abc123 --to me --json
+mkdir -p ~/.claude/skills/clickup
+cp $(npm root -g)/@krodak/clickup-cli/skills/clickup-cli/SKILL.md ~/.claude/skills/clickup/SKILL.md
 ```
-| Flag                | Description                       |
-| ------------------- | --------------------------------- |
-| `--to <userId>`     | Add assignee (user ID or `me`)    |
-| `--remove <userId>` | Remove assignee (user ID or `me`) |
-| `--json`            | Force JSON output                 |
-### `cu depend <id>`
-Add or remove task dependencies. Set a task as waiting on or blocking another task.
+Then reference it in your `CLAUDE.md` or project instructions.
-```bash
-cu depend abc123 --on def456          # abc123 depends on (waits for) def456
-cu depend abc123 --blocks def456      # abc123 blocks def456
-cu depend abc123 --on def456 --remove # remove the dependency
-cu depend abc123 --blocks def456 --remove
-cu depend abc123 --on def456 --json
-```
+</details>
-| Flag                | Description                                 |
-| ------------------- | ------------------------------------------- |
-| `--on <taskId>`     | Task that this task depends on (waiting on) |
-| `--blocks <taskId>` | Task that this task blocks                  |
-| `--remove`          | Remove the dependency instead of adding it  |
-| `--json`            | Force JSON output                           |
+<details>
+<summary>&nbsp;<img src="https://cdn.simpleicons.org/anthropic/D97757" height="16" align="center">&nbsp;<strong>Claude Desktop</strong></summary>
-### `cu move <id>`
+Claude Desktop doesn't run CLI tools directly. Use it alongside a coding agent (Claude Code, OpenCode) that has `cu` installed, or run `cu` commands manually in your terminal.
-Add or remove a task from a list. Tasks can belong to multiple lists in ClickUp.
+**Install the CLI:**
 ```bash
-cu move abc123 --to <listId>                    # add task to a list
-cu move abc123 --remove <listId>                # remove task from a list
-cu move abc123 --to <newListId> --remove <oldListId>  # move between lists
-cu move abc123 --to <listId> --json
+npm install -g @krodak/clickup-cli
+cu init
 ```
-| Flag                | Description                |
-| ------------------- | -------------------------- |
-| `--to <listId>`     | Add task to this list      |
-| `--remove <listId>` | Remove task from this list |
-| `--json`            | Force JSON output          |
+</details>
-### `cu tag <id>`
-Add or remove tags on a task. Both `--add` and `--remove` can be used together.
+<details>
+<summary>&nbsp;<img src="https://cdn.simpleicons.org/homebrew/FBB040" height="16" align="center">&nbsp;<strong>Homebrew</strong></summary>
 ```bash
-cu tag abc123 --add "bug"
-cu tag abc123 --add "bug,frontend,urgent"
-cu tag abc123 --remove "wontfix"
-cu tag abc123 --add "bug" --remove "triage"
-cu tag abc123 --add "bug" --json
+brew tap krodak/tap
+brew install clickup-cli
+cu init
 ```
-| Flag              | Description                         |
-| ----------------- | ----------------------------------- |
-| `--add <tags>`    | Comma-separated tag names to add    |
-| `--remove <tags>` | Comma-separated tag names to remove |
-| `--json`          | Force JSON output                   |
+Then install the skill for your agent (see OpenCode or Claude Code sections above).
-### `cu auth`
+</details>
-Check authentication status. Validates your API token and shows your user info.
+<details>
+<summary>&nbsp;<img src="https://cdn.simpleicons.org/openai/999999" height="16" align="center">&nbsp;<strong>Codex / Other agents</strong></summary>
-```bash
-cu auth
-cu auth --json
-```
-### `cu config`
-Manage CLI configuration.
+**1. Install the CLI**
 ```bash
-cu config get apiToken
-cu config set teamId 12345
-cu config path
+npm install -g @krodak/clickup-cli
+cu init
 ```
-Valid keys: `apiToken`, `teamId`. Setting `apiToken` validates the `pk_` prefix.
+**2. Add the skill to your agent**
-### `cu completion <shell>`
+Copy `skills/clickup-cli/SKILL.md` into your agent's system prompt or project instructions. It's a standalone markdown document that teaches the agent all available commands.
-Output shell completion script. Supports `bash`, `zsh`, and `fish`.
+</details>
-```bash
-eval "$(cu completion bash)"                                    # Bash
-eval "$(cu completion zsh)"                                     # Zsh
-cu completion fish > ~/.config/fish/completions/cu.fish          # Fish
-```
+## Commands
-## Config
+36 commands total. [Full reference with examples and flags](docs/commands.md).
+### Tasks
+| Command               | Description                                                 |
+| --------------------- | ----------------------------------------------------------- |
+| `cu tasks`            | List my tasks (filter by status, name, type, list, space)   |
+| `cu task <id>`        | Task details with custom fields and checklists              |
+| `cu subtasks <id>`    | List subtasks of a task                                     |
+| `cu create`           | Create a task or subtask                                    |
+| `cu update <id>`      | Update task fields (status, name, priority, assignee, etc.) |
+| `cu delete <id>`      | Delete a task (requires confirmation)                       |
+| `cu assign <id>`      | Assign/unassign users                                       |
+| `cu depend <id>`      | Add/remove task dependencies                                |
+| `cu move <id>`        | Add/remove task from lists                                  |
+| `cu open <query>`     | Open task in browser by ID or name                          |
+| `cu search <query>`   | Search my tasks by name                                     |
+| _`cu duplicate <id>`_ | _Copy a task - coming soon_                                 |
+| _`cu bulk`_           | _Bulk task operations - coming soon_                        |
+### Sprints & Planning
+| Command       | Description                                     |
+| ------------- | ----------------------------------------------- |
+| `cu sprint`   | My tasks in the active sprint (auto-detected)   |
+| `cu sprints`  | List all sprints                                |
+| `cu assigned` | All my tasks grouped by status                  |
+| `cu summary`  | Standup helper: completed, in progress, overdue |
+| `cu overdue`  | Tasks past their due date                       |
+| `cu inbox`    | Recently updated tasks                          |
+### Comments
+| Command                    | Description                      |
+| -------------------------- | -------------------------------- |
+| `cu comment <id>`          | Post a comment on a task         |
+| `cu comments <id>`         | List comments on a task          |
+| `cu comment-edit <id>`     | Edit an existing comment         |
+| `cu activity <id>`         | Task details + comments combined |
+| _`cu comment-delete <id>`_ | _Delete a comment - coming soon_ |
+### Custom Fields
+| Command                | Description                                                                         |
+| ---------------------- | ----------------------------------------------------------------------------------- |
+| `cu field <id>`        | Set/remove custom field values (text, number, dropdown, date, checkbox, url, email) |
+| _`cu fields <listId>`_ | _List available custom fields for a list - coming soon_                             |
+### Checklists
+| Command                                  | Description                                      |
+| ---------------------------------------- | ------------------------------------------------ |
+| `cu checklist view <id>`                 | View all checklists on a task                    |
+| `cu checklist create <id> <name>`        | Create a checklist                               |
+| `cu checklist delete <id>`               | Delete a checklist                               |
+| `cu checklist add-item <id> <name>`      | Add item to a checklist                          |
+| `cu checklist edit-item <id> <itemId>`   | Edit a checklist item (name, resolved, assignee) |
+| `cu checklist delete-item <id> <itemId>` | Delete a checklist item                          |
+### Tags
+| Command               | Description                                         |
+| --------------------- | --------------------------------------------------- |
+| `cu tag <id>`         | Add/remove tags on a task                           |
+| _`cu tags <spaceId>`_ | _List/create/delete space-level tags - coming soon_ |
+### Workspace
+| Command                  | Description                               |
+| ------------------------ | ----------------------------------------- |
+| `cu spaces`              | List workspace spaces                     |
+| `cu lists <spaceId>`     | Lists in a space (including folder lists) |
+| `cu auth`                | Check authentication status               |
+| _`cu folders <spaceId>`_ | _List folders in a space - coming soon_   |
+| _`cu members`_           | _List workspace members - coming soon_    |
+### Time Tracking
+| Command                       | Description                                     |
+| ----------------------------- | ----------------------------------------------- |
+| `cu time start <id>`          | Start tracking time on a task                   |
+| `cu time stop`                | Stop the running timer                          |
+| `cu time status`              | Show the currently running timer                |
+| `cu time log <id> <duration>` | Log a manual time entry (e.g. "2h", "30m")      |
+| `cu time list`                | List recent time entries (default: last 7 days) |
+### Setup
+| Command                 | Description                       |
+| ----------------------- | --------------------------------- |
+| `cu init`               | First-time setup wizard           |
+| `cu config`             | Get/set config values             |
+| `cu completion <shell>` | Shell completions (bash/zsh/fish) |
+## Output Modes
+| Context        | Default                     | Override                     |
+| -------------- | --------------------------- | ---------------------------- |
+| Terminal (TTY) | Interactive tables + picker | `--json`                     |
+| Piped (no TTY) | Markdown (optimized for AI) | `--json` or `CU_OUTPUT=json` |
+Most commands scope to your assigned tasks by default - keeping output small and relevant for agent context windows.
+## Configuration
 ### Config file
@@ -529,6 +244,10 @@ Environment variables override config file values:
 When both are set, the config file is not required. Useful for CI/CD and containerized agents.
+## Why a CLI and not MCP?
+A CLI + skill file has fewer moving parts. No server process, no protocol layer. The agent already knows how to run shell commands - the skill file teaches it which ones exist. For tool-use with coding agents, CLI + instructions tends to work better than MCP in practice.
 ## Development
 ```bash