@krodak/clickup-cli 1.22.0 → 1.22.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "clickup-cli",
   "description": "ClickUp CLI skills for managing tasks, sprints, comments, checklists, custom fields, tags, and time tracking via the cup command",
-  "version": "1.22.0",
+  "version": "1.22.2",
   "author": {
     "name": "Krzysztof Rodak"
   },

package/README.md

@@ -16,13 +16,24 @@ npm install -g @krodak/clickup-cli && cup init
 
 ## For AI Agents
 
-Paste this into any AI agent to get started immediately:
+Paste this into any AI agent (Claude Code, Codex, Cursor, OpenCode, etc.):
 
 ```
-Fetch and follow instructions from https://raw.githubusercontent.com/krodak/clickup-cli/main/skills/clickup-cli/SKILL.md
+Install and configure the ClickUp CLI for me. Fetch the setup guide from:
+https://raw.githubusercontent.com/krodak/clickup-cli/main/skills/clickup-cli/SKILL.md
+
+Then walk me through installing the CLI, getting a ClickUp API token,
+and running cup init. Finally, install the skill with `cup skill` so
+you have persistent access to the full command reference.
 ```
 
-Or install the skill permanently with `cup skill` (see [Set up your agent](#set-up-your-agent) below).
+The fetched SKILL.md contains everything the agent needs: install commands,
+where to get a ClickUp API token, non-interactive setup with `cup init --token --team`,
+and the complete command reference. After setup, the agent can run any `cup` command
+to manage your tasks, sprints, comments, time tracking, and more.
+
+**Already have the CLI installed?** Just run `cup skill` to install the agent skill to
+all detected locations (see [Set up your agent](#set-up-your-agent) below).
 
 ## Talk to your agent
 

package/dist/index.js

@@ -1021,7 +1021,9 @@ function loadConfig(profileName) {
     if (envToken || envTeamId) {
       throw new Error("Both CU_API_TOKEN and CU_TEAM_ID must be set, or run: cup init");
     }
-    throw new Error("Config missing required field: apiToken.\nSet CU_API_TOKEN or run: cup init");
+    throw new Error(
+      "No ClickUp CLI configuration found.\n\nTo get started:\n  cup init\n\nFor scripts or AI agents:\n  cup init --token pk_YOUR_TOKEN --team YOUR_TEAM_ID\n\nGet your API token: https://app.clickup.com/settings/apps"
+    );
   }
   const { parsed } = parseRawConfig(path);
   if (isOldFormat(parsed)) {
@@ -2065,31 +2067,75 @@ async function getTask(config, taskId) {
 // src/commands/init.ts
 import { password, select, confirm as confirm2 } from "@inquirer/prompts";
 import fs2 from "fs";
+var TOKEN_URL = "https://app.clickup.com/settings/apps";
+var TOKEN_HELP = `
+How to get a ClickUp API token:
+  1. Open ${TOKEN_URL}
+  2. Find the "API Token" section, click "Generate" (or copy the existing one)
+  3. The token starts with "pk_"
+`;
+var NON_TTY_HELP = `cup init requires an interactive terminal.
+
+For scripts, CI, or AI agents, use flags:
+  cup init --token pk_YOUR_TOKEN --team YOUR_TEAM_ID
+
+Or set environment variables:
+  export CU_API_TOKEN=pk_YOUR_TOKEN
+  export CU_TEAM_ID=YOUR_TEAM_ID
+${TOKEN_HELP}`;
+var NEXT_STEPS = `
+Next steps:
+  cup auth      # verify setup
+  cup tasks     # list your assigned tasks
+  cup sprint    # show current sprint
+  cup --help    # see all commands
+`;
+function validateTokenFormat(token) {
+  if (!token.startsWith("pk_")) {
+    throw new Error(
+      `Invalid token format. Personal API tokens start with "pk_".
+${TOKEN_HELP}`
+    );
+  }
+}
+async function verifyToken(apiToken) {
+  const client = new ClickUpClient({ apiToken });
+  try {
+    const me = await client.getMe();
+    return me.username;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `Token verification failed: ${msg}
+
+Check the token is correct and not expired.
+${TOKEN_HELP}`,
+      { cause: err }
+    );
+  }
+}
 async function runInitCommand(opts) {
   if (opts?.token && opts?.team) {
     const apiToken2 = opts.token.trim();
-    if (!apiToken2.startsWith("pk_")) throw new Error("Token must start with pk_");
-    const client2 = new ClickUpClient({ apiToken: apiToken2 });
-    let username2;
-    try {
-      const me = await client2.getMe();
-      username2 = me.username;
-    } catch (err) {
-      throw new Error(`Invalid token: ${err instanceof Error ? err.message : String(err)}`, {
-        cause: err
-      });
-    }
+    validateTokenFormat(apiToken2);
+    const username2 = await verifyToken(apiToken2);
     process.stdout.write(`Authenticated as @${username2}
 `);
     writeConfig({ apiToken: apiToken2, teamId: opts.team });
     process.stdout.write(`Config written to ${getConfigPath()}
-`);
+${NEXT_STEPS}`);
     return;
   }
   if (opts?.token || opts?.team) {
     throw new Error("Both --token and --team are required for non-interactive setup");
   }
+  if (!process.stdin.isTTY) {
+    throw new Error(NON_TTY_HELP);
+  }
   const configPath3 = getConfigPath();
+  process.stdout.write("\nWelcome to ClickUp CLI!\n");
+  process.stdout.write(TOKEN_HELP);
+  process.stdout.write("\n");
   if (fs2.existsSync(configPath3)) {
     const overwrite = await confirm2({
       message: `Config already exists at ${configPath3}. Overwrite?`,
@@ -2100,20 +2146,14 @@ async function runInitCommand(opts) {
       return;
     }
   }
-  const apiToken = (await password({ message: "ClickUp API token (pk_...):" })).trim();
-  if (!apiToken.startsWith("pk_")) throw new Error("Token must start with pk_");
-  const client = new ClickUpClient({ apiToken });
-  let username;
-  try {
-    const me = await client.getMe();
-    username = me.username;
-  } catch (err) {
-    throw new Error(`Invalid token: ${err instanceof Error ? err.message : String(err)}`, {
-      cause: err
-    });
-  }
+  const apiToken = (await password({
+    message: "Paste your ClickUp API token (starts with pk_):"
+  })).trim();
+  validateTokenFormat(apiToken);
+  const username = await verifyToken(apiToken);
   process.stdout.write(`Authenticated as @${username}
 `);
+  const client = new ClickUpClient({ apiToken });
   const teams = await client.getTeams();
   if (teams.length === 0) throw new Error("No workspaces found for this token.");
   let teamId;
@@ -2130,8 +2170,9 @@ async function runInitCommand(opts) {
     });
   }
   writeConfig({ apiToken, teamId });
-  process.stdout.write(`Config written to ${configPath3}
-`);
+  process.stdout.write(`
+Config written to ${configPath3}
+${NEXT_STEPS}`);
 }
 
 // src/commands/sprint.ts
@@ -3136,9 +3177,15 @@ function printTimeInStatus(result, forceJson) {
 var commandMetadata = [
   {
     name: "init",
-    description: "Set up cup for the first time",
+    description: "Set up cup (interactive). Use --token and --team for non-interactive/agent setup",
     flags: ["--token", "--team"],
-    quickReference: [{ section: "setup", usage: "init", description: "First-time setup wizard" }]
+    quickReference: [
+      {
+        section: "setup",
+        usage: "init",
+        description: "First-time setup (interactive, or use --token --team for agents)"
+      }
+    ]
   },
   {
     name: "auth",
@@ -4026,7 +4073,7 @@ function parseCommandFlags(flags = []) {
 }
 function commandDescription(command, programName = "cup") {
   if (command.name === "init") {
-    return `Set up ${programName} for the first time`;
+    return `Set up ${programName} (interactive). Use --token and --team for non-interactive/agent setup`;
   }
   return command.description;
 }
@@ -6599,7 +6646,9 @@ function buildProgram(programName = basename(process.argv[1] ?? "cup")) {
   function getProfileName() {
     return program.opts().profile;
   }
-  program.command("init").description(`Set up ${programName} for the first time`).option("--token <token>", "API token (pk_...) for non-interactive setup").option("--team <teamId>", "Workspace/team ID for non-interactive setup").action(
+  program.command("init").description(
+    `Set up ${programName} (interactive). Use --token and --team for non-interactive/agent setup`
+  ).option("--token <token>", "API token (pk_...) for non-interactive setup").option("--team <teamId>", "Workspace/team ID for non-interactive setup").action(
     wrapAction(async (opts) => {
       await runInitCommand(opts);
     })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krodak/clickup-cli",
-  "version": "1.22.0",
+  "version": "1.22.2",
   "description": "ClickUp CLI for AI agents and humans",
   "type": "module",
   "license": "MIT",

package/skills/clickup-cli/SKILL.md

@@ -3,11 +3,11 @@ name: clickup
 description: 'Use when managing ClickUp tasks, sprints, or comments via the `cup` CLI tool. Triggers: task queries, status updates, sprint tracking, creating subtasks, posting comments, threaded replies, standup summaries, searching tasks, checking overdue items, assigning tasks, listing spaces and lists, opening tasks in browser, checking auth or config, setting custom fields, deleting tasks, managing tags, managing checklists, editing comments, task links, time tracking, attachments, file uploads, listing members, listing fields, duplicating tasks, bulk operations, goals, key results, saved filters, favorites.'
 ---
 
-# ClickUp CLI (`cup`) - skill version 1.17.0
+# ClickUp CLI (`cup`) - skill version 1.22.2
 
-Reference for AI agents using the `cup` CLI tool. Covers task management, sprint tracking, comments, and project workflows.
+Reference for AI agents using the `cup` CLI tool. Covers task management, sprint tracking, comments, time tracking, custom fields, goals, docs, and project workflows.
 
-> **Version check:** Run `cup --version`. If your installed version is older than 1.18.0, update with `npm install -g @krodak/clickup-cli` and refresh this skill with `cup skill`.
+> **Version check:** Run `cup --version`. If your installed version is older than 1.22.2, update with `npm install -g @krodak/clickup-cli` and refresh this skill with `cup skill`.
 
 ## Install & Configure