feat: improve onboarding - helpful init intro, token URL in errors, non-TTY detection, clearer README for agents

Author: krodak

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
 

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.0
 
-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.0, update with `npm install -g @krodak/clickup-cli` and refresh this skill with `cup skill`.
 
 ## Install & Configure
 

src/commands/init.ts

@@ -8,34 +8,80 @@ export interface InitOptions {
   team?: string
 }
 
+const TOKEN_URL = 'https://app.clickup.com/settings/apps'
+
+const 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_"
+`
+
+const 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}`
+
+const 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: string): void {
+  if (!token.startsWith('pk_')) {
+    throw new Error(
+      `Invalid token format. Personal API tokens start with "pk_".\n${TOKEN_HELP}`,
+    )
+  }
+}
+
+async function verifyToken(apiToken: string): Promise<string> {
+  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}\n\nCheck the token is correct and not expired.\n${TOKEN_HELP}`,
+      { cause: err },
+    )
+  }
+}
+
 export async function runInitCommand(opts?: InitOptions): Promise<void> {
   if (opts?.token && opts?.team) {
     const apiToken = opts.token.trim()
-    if (!apiToken.startsWith('pk_')) throw new Error('Token must start with pk_')
-
-    const client = new ClickUpClient({ apiToken })
-    let username: string
-    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,
-      })
-    }
-
+    validateTokenFormat(apiToken)
+    const username = await verifyToken(apiToken)
     process.stdout.write(`Authenticated as @${username}\n`)
     writeConfig({ apiToken, teamId: opts.team })
-    process.stdout.write(`Config written to ${getConfigPath()}\n`)
+    process.stdout.write(`Config written to ${getConfigPath()}\n${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 configPath = getConfigPath()
 
+  process.stdout.write('\nWelcome to ClickUp CLI!\n')
+  process.stdout.write(TOKEN_HELP)
+  process.stdout.write('\n')
+
   if (fs.existsSync(configPath)) {
     const overwrite = await confirm({
       message: `Config already exists at ${configPath}. Overwrite?`,
@@ -47,23 +93,17 @@ export async function runInitCommand(opts?: InitOptions): Promise<void> {
     }
   }
 
-  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: string
-  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}\n`)
 
+  const client = new ClickUpClient({ apiToken })
   const teams = await client.getTeams()
   if (teams.length === 0) throw new Error('No workspaces found for this token.')
 
@@ -81,5 +121,5 @@ export async function runInitCommand(opts?: InitOptions): Promise<void> {
   }
 
   writeConfig({ apiToken, teamId })
-  process.stdout.write(`Config written to ${configPath}\n`)
+  process.stdout.write(`\nConfig written to ${configPath}\n${NEXT_STEPS}`)
 }

src/config.ts

@@ -217,7 +217,14 @@ export function loadConfig(profileName?: string): Config {
     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\n' +
+        'To get started:\n' +
+        '  cup init\n\n' +
+        'For scripts or AI agents:\n' +
+        '  cup init --token pk_YOUR_TOKEN --team YOUR_TEAM_ID\n\n' +
+        'Get your API token: https://app.clickup.com/settings/apps',
+    )
   }
 
   const { parsed } = parseRawConfig(path)

tests/unit/commands/init.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
 
 const mockPassword = vi.fn()
 const mockConfirm = vi.fn()
@@ -41,12 +41,22 @@ vi.mock('fs', async importOriginal => {
 })
 
 describe('runInitCommand', () => {
+  const originalIsTTY = process.stdin.isTTY
+
   beforeEach(() => {
     vi.clearAllMocks()
     mockGetMe.mockResolvedValue({ id: 1, username: 'testuser' })
     mockGetTeams.mockResolvedValue([{ id: 'team1', name: 'My Workspace' }])
     mockPassword.mockResolvedValue('pk_testtoken')
     mockExistsSync.mockReturnValue(false)
+    Object.defineProperty(process.stdin, 'isTTY', { value: true, configurable: true })
+  })
+
+  afterEach(() => {
+    Object.defineProperty(process.stdin, 'isTTY', {
+      value: originalIsTTY,
+      configurable: true,
+    })
   })
 
   it('writes config with apiToken and teamId when single workspace', async () => {
@@ -99,6 +109,39 @@ describe('runInitCommand', () => {
     await expect(runInitCommand()).rejects.toThrow('No workspaces')
   })
 
+  it('shows API token help intro in interactive mode', async () => {
+    const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true)
+    const { runInitCommand } = await import('../../../src/commands/init.js')
+    await runInitCommand()
+    const output = writeSpy.mock.calls.map(c => c[0]).join('')
+    expect(output).toContain('Welcome to ClickUp CLI')
+    expect(output).toContain('https://app.clickup.com/settings/apps')
+    expect(output).toContain('API Token')
+    writeSpy.mockRestore()
+  })
+
+  it('shows next-steps hint after successful config write', async () => {
+    const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true)
+    const { runInitCommand } = await import('../../../src/commands/init.js')
+    await runInitCommand()
+    const output = writeSpy.mock.calls.map(c => c[0]).join('')
+    expect(output).toContain('Next steps')
+    expect(output).toContain('cup auth')
+    writeSpy.mockRestore()
+  })
+
+  it('throws with non-TTY help when stdin is not a terminal', async () => {
+    Object.defineProperty(process.stdin, 'isTTY', { value: false, configurable: true })
+    const { runInitCommand } = await import('../../../src/commands/init.js')
+    await expect(runInitCommand()).rejects.toThrow('cup init --token')
+  })
+
+  it('invalid token error includes token URL', async () => {
+    mockPassword.mockResolvedValue('nottoken')
+    const { runInitCommand } = await import('../../../src/commands/init.js')
+    await expect(runInitCommand()).rejects.toThrow('app.clickup.com/settings/apps')
+  })
+
   describe('non-interactive mode', () => {
     it('writes config with --token and --team without prompts', async () => {
       const { runInitCommand } = await import('../../../src/commands/init.js')
@@ -137,7 +180,7 @@ describe('runInitCommand', () => {
       mockGetMe.mockRejectedValue(new Error('Unauthorized'))
       const { runInitCommand } = await import('../../../src/commands/init.js')
       await expect(runInitCommand({ token: 'pk_badtoken', team: 'team123' })).rejects.toThrow(
-        'Invalid token',
+        'Token verification failed',
       )
     })
   })

tests/unit/config.test.ts

@@ -47,10 +47,10 @@ describe('loadConfig', () => {
     restoreConfigEnv()
   })
 
-  it('throws with path hint when config file does not exist and no env vars', async () => {
+  it('throws with onboarding help when config file does not exist and no env vars', async () => {
     vi.mocked(fs.existsSync).mockReturnValue(false)
     const { loadConfig } = await import('../../src/config.js')
-    expect(() => loadConfig()).toThrow('apiToken')
+    expect(() => loadConfig()).toThrow('cup init')
   })
 
   it('throws on invalid JSON', async () => {