open-wadah 1.2.2 → 1.3.0

package/README.md

@@ -1,6 +1,15 @@
 # open-wadah
 
-Open WADAH CLI — shared task board for humans and agents. Use it from the terminal or from Cursor, Claude Code, and Kimi.
+Command-line interface for Wadah task boards and autonomous agent workflows.
+
+`open-wadah` gives teams and AI agents a fast, scriptable way to plan, assign, and deliver work from the terminal.
+
+## Why teams use Wadah CLI
+
+- Manage tasks, assignees, and board flow without leaving your terminal.
+- Automate workflows with stable JSON output for scripts and CI.
+- Power autonomous agents with scoped agent tokens.
+- Keep human and agent work on the same board and process.
 
 ## Install
 
@@ -8,83 +17,135 @@ Open WADAH CLI — shared task board for humans and agents. Use it from the term
 npm install -g open-wadah
 ```
 
-Commands: `wadah`, `tm`, `ow` (same CLI).
+Available commands: `wadah`, `ow`, `tm`.
 
-## Quick start
+## 60-second quick start
 
-1. API must be reachable (default: `https://api.openwadah.com`). Override: `TASK_MANAGER_API_URL` or `--api <url>`.
-2. Sign in: `wadah login` (browser) or `wadah login --password` (terminal).
-3. Use the board:
+1. Sign in:
+
+```bash
+wadah login
+```
+
+2. Open your assigned tasks:
 
 ```bash
 wadah open
-wadah add "Fix login issue"
+```
+
+3. Create and move work:
+
+```bash
+wadah add "Fix login issue" --board "Main"
+wadah move <task-id> <bucket-id>
 wadah complete <task-id>
 ```
 
-## Commands
+Default API URL is `https://api.openwadah.com`. Override with `--api <url>` or `WADAH_API_URL`.
 
-| Command | Description |
-|--------|-------------|
-| **Auth** | `login`, `signup`, `logout`, `whoami` |
-| **Tasks** | `open`, `list`, `search`, `requested`, `add`, `complete`, `reopen`, `view`, `update`, `move`, `assign`, `comment`, `delete` |
-| **Relationships** | `add --blocks <id>`, `add --blocked-by <id>`, `update --blocks <id>` |
-| **Board** | `boards --json`, `buckets --json`, `assignees --json`; `board create/delete`, `bucket create/update/delete`, `assignee create/update/delete` |
-| **Files** | `folders`, `files`, `folder create` / `mkdir`, `upload` |
-| **Calendar** | `calendar` (list; `--assignee`, `--task`, `--from`, `--to`), `calendar add`, `calendar update <id>`, `calendar delete <id>` |
-| **Docs** | `docs` (list), `doc create [title]`, `doc show <id>`, `doc update <id>`, `doc delete <id>` |
-| **Agent tokens** | `agent-tokens` (list), `agent-token create [name]`, `agent-token delete <id>` |
-| **Workspace** | `state`, `members`, `invite`, `config` |
-| **Other** | `do "<sentence>"` (natural language, needs `OPENAI_API_KEY`), `doctor`, `completion [bash\|zsh]` |
+## Core workflows
 
-Run `wadah --help` for full list and options.
+### Daily task operations
 
-## Shell completion
+```bash
+wadah list --board "Main"
+wadah search "billing"
+wadah view <task-id>
+wadah update <task-id> --notes "Root cause + next steps"
+wadah comment <task-id> "Investigating now"
+```
+
+### Dependencies and subtasks
+
+```bash
+wadah add "Ship release notes" --blocks <task-id>
+wadah subtask add <task-id> "Write tests"
+wadah subtask list <task-id>
+wadah subtask toggle <task-id> <subtask-id>
+```
 
-**Bash:**
+### Board administration
 
 ```bash
-wadah completion bash >> ~/.bashrc
-source ~/.bashrc
+wadah board create "Backend"
+wadah bucket create "In Review" --board <board-id>
+wadah assignee create "Cursor Agent" --type agent
+wadah buckets --board "Backend" --json
 ```
 
-**Zsh:**
+## Command surface
+
+| Area | Commands |
+|---|---|
+| Auth | `login`, `signup`, `logout`, `whoami` |
+| Tasks | `open`, `list`, `search`, `requested`, `add`, `view`, `update`, `move`, `assign`, `comment`, `complete`, `reopen`, `delete` |
+| Subtasks | `subtask list`, `subtask add`, `subtask toggle`, `subtask delete` |
+| Boards & members | `boards`, `buckets`, `assignees`, `board create/delete`, `bucket create/update/delete`, `assignee create/update/delete` |
+| Docs | `docs`, `doc create/show/update/delete` |
+| Calendar | `calendar`, `calendar add/update/delete` |
+| Files | `folders`, `files`, `folder create`, `mkdir`, `upload` |
+| Agent tokens | `agent-tokens`, `agent-token create/delete` |
+| Utilities | `doctor`, `completion bash`, `completion zsh`, `state`, `members`, `invite`, `config`, `do` |
+
+Use `wadah --help` or `wadah <command> --help` for full flags and examples.
+
+## AI agent mode
+
+For autonomous workflows (Cursor, Claude Code, GitHub Actions):
+
+- Create an agent token:
 
 ```bash
-wadah completion zsh >> ~/.zshrc
-source ~/.zshrc
+wadah agent-token create "My Agent"
 ```
 
-## Agent / AI use
+- Set it as `WADAH_AGENT_TOKEN` in your environment.
+- Use `--json` for deterministic machine output (`wadah open --json`).
+- Optional natural-language command:
+
+```bash
+wadah do "add a task to fix onboarding bug"
+```
 
-- Set `TASK_MANAGER_TOKEN` (create a token: `wadah agent-token create "My Agent"`).
-- Use `--json` for machine-readable output: `wadah open --json`, `wadah list --json`, `wadah buckets --json`.
-- Natural language: `wadah do "add a task to fix the bug"` (requires `OPENAI_API_KEY`).
-- In Cursor/Claude/Kimi: see **WADAH_CLI.md** in the repo root for a short reference.
-- For autonomous 24/7 agents with GitHub Actions: see **AGENTS.md** in the repo root.
+`wadah do` requires `OPENAI_API_KEY`.
 
 ## Global flags
 
-- `--api <url>` — API base URL
-- `--profile <name>` — config profile
-- `--token <token>` — auth token for this run
-- `--json` — JSON output
-- `--quiet` — minimal output
+- `--api <url>`: API base URL
+- `--profile <name>`: config profile
+- `--token <token>`: token for current command only
+- `--json`: machine-readable output
+- `--quiet`: reduce non-essential output
 
-## Develop & test
+## Environment variables
 
-From the repo root:
+- `WADAH_AGENT_TOKEN`: preferred auth token for automation
+- `WADAH_API_URL`: override API base URL
+- `OPENAI_API_KEY`: required for `wadah do`
+
+## Shell completion
+
+```bash
+# Bash
+wadah completion bash >> ~/.bashrc && source ~/.bashrc
+
+# Zsh
+wadah completion zsh >> ~/.zshrc && source ~/.zshrc
+```
+
+## Development
 
 ```bash
-npm run install:all
-npm run tm -- --help
-cd task-manager-cli && npm test
+npm test
+node cli.js --help
 ```
 
-## Error codes (with `--json`)
+## JSON error codes
+
+When running with `--json`, failures include structured error codes:
 
-- `auth_error` — not authenticated
-- `validation_error` — bad input
-- `network_error` — request failed
-- `api_error` — API returned an error
-- `config` — missing config (e.g. OPENAI_API_KEY for `do`)
+- `auth_error`
+- `validation_error`
+- `network_error`
+- `api_error`
+- `config`

package/cli.js

@@ -31,7 +31,7 @@ function normalizeApiUrl(url) {
 const conf = new Conf({ projectName: 'open-wadah' })
 
 function getProfile() {
-  const profile = (process.env.TASK_MANAGER_PROFILE ?? runtimeProfile ?? 'default').trim()
+  const profile = (process.env.WADAH_PROFILE ?? runtimeProfile ?? 'default').trim()
   return profile || 'default'
 }
 
@@ -55,15 +55,28 @@ function confDelete(key) {
 
 function getApiBase() {
   return (
-    (process.env.TASK_MANAGER_API_URL ?? '').trim() ||
+    (process.env.WADAH_API_URL ?? '').trim() ||
     runtimeApiBase ||
     confGet('api_url') ||
     DEFAULT_API_BASE
   )
 }
 
+/** Agent token from env: reads WADAH_AGENT_TOKEN. */
+function envAgentToken() {
+  const w = (process.env.WADAH_AGENT_TOKEN ?? '').trim()
+  return w || null
+}
+
+/** Which env var supplied the agent token (for status output). */
+function envAgentTokenVarName() {
+  if ((process.env.WADAH_AGENT_TOKEN ?? '').trim()) return 'WADAH_AGENT_TOKEN'
+  return null
+}
+
 function getAuthToken() {
-  if (process.env.TASK_MANAGER_TOKEN) return process.env.TASK_MANAGER_TOKEN
+  const fromEnv = envAgentToken()
+  if (fromEnv) return fromEnv
   if (runtimeToken) return runtimeToken
   return confGet('access_token') ?? null
 }
@@ -99,7 +112,7 @@ async function refreshAccessToken() {
 }
 
 async function ensureAuth() {
-  if (process.env.TASK_MANAGER_TOKEN) return   // agent token, no refresh needed
+  if (envAgentToken()) return   // agent token, no refresh needed
   const expires = confGet('token_expires')
   // Refresh if within 5 minutes of expiry or already expired
   if (expires && Date.now() > (expires * 1000) - 300_000) {
@@ -120,7 +133,7 @@ async function api(path, options = {}, retry = true) {
   }
 
   // If 401 and we have a refresh token, try once more
-  if (res.status === 401 && retry && !process.env.TASK_MANAGER_TOKEN) {
+  if (res.status === 401 && retry && !envAgentToken()) {
     const refreshed = await refreshAccessToken()
     if (refreshed) return api(path, options, false)
   }
@@ -197,7 +210,7 @@ function handleError(err) {
   } else if (authLike) {
     console.error(chalk.red('\n✗ Not authenticated.'))
     console.error(chalk.gray('  Humans:  wadah login'))
-    console.error(chalk.gray('  Agents:  TASK_MANAGER_TOKEN=<token> wadah open\n'))
+    console.error(chalk.gray('  Agents:  WADAH_AGENT_TOKEN=<token> wadah open\n'))
   } else if (code === 'network_error') {
     console.error(chalk.red('\n✗ Network error — could not reach the API.'))
     console.error(chalk.gray(`  Check your connection or API URL: ${getApiBase()}`))
@@ -279,6 +292,23 @@ function findBucket(buckets, query) {
   return buckets.find((b) => b.id === query || b.title.toLowerCase().includes(q)) ?? null
 }
 
+function findSubtask(subtasks, query) {
+  const raw = String(query ?? '').trim()
+  if (!raw) return null
+  const q = raw.toLowerCase()
+  const byId = subtasks.filter((s) => s.id === raw || s.id.startsWith(raw))
+  if (byId.length === 1) return byId[0]
+  if (byId.length > 1) {
+    throw new CliError('validation_error', `Ambiguous subtask id prefix: ${raw}`)
+  }
+  const byTitle = subtasks.filter((s) => String(s.title ?? '').toLowerCase() === q)
+  if (byTitle.length === 1) return byTitle[0]
+  if (byTitle.length > 1) {
+    throw new CliError('validation_error', `Multiple subtasks have title: ${raw}`)
+  }
+  return null
+}
+
 function parseCompletedFlag(value) {
   if (typeof value !== 'string') return null
   const v = value.trim().toLowerCase()
@@ -410,6 +440,8 @@ Available commands and their args (use these exact command names):
 - repo add: args = [github url or owner/repo]. Link a GitHub repository to your workspace.
 - repo list (or repos): args = []. List linked GitHub repositories.
 - repo remove: args = [repo id]. Unlink a repository.
+- pr link: args = [task id, pr url]. Attach a PR URL to a task.
+- pr open: args = [task id]. Open the linked PR URL for a task.
 
 If the request is unclear or not a valid CLI action, return {"command": "", "args": []}. Output only the JSON object.`
 
@@ -719,7 +751,7 @@ program
   .action(async () => {
     if (isMachineOutput()) {
       try {
-        if (process.env.TASK_MANAGER_TOKEN || runtimeToken) {
+        if (envAgentToken() || runtimeToken) {
           const me = await api('/api/auth/me')
           const ws = me.workspaces?.[0] ?? null
           console.log(JSON.stringify({
@@ -752,8 +784,8 @@ program
       return
     }
 
-    if (process.env.TASK_MANAGER_TOKEN) {
-      console.log(chalk.bold('\nAgent') + '  (TASK_MANAGER_TOKEN)')
+    if (envAgentToken()) {
+      console.log(chalk.bold('\nAgent') + `  (${envAgentTokenVarName()})`)
     } else {
       const email = confGet('user_email')
       if (!email) {
@@ -1233,7 +1265,16 @@ program
       if (requester) console.log(chalk.gray(`  Requested: ${requester}`))
       if (task.dueDate) console.log(chalk.gray(`  Due:       ${formatDate(task.dueDate)}`))
       if (task.repo) console.log(chalk.gray(`  Repo:      ${task.repo}`))
-      if (task.contextUrl) console.log(chalk.gray(`  Link:      ${task.contextUrl}`))
+      if (Array.isArray(task.contextLinks) && task.contextLinks.length > 0) {
+        console.log(chalk.gray('\n  Links:'))
+        task.contextLinks.forEach((l) => {
+          const lab = l.label ? `${l.label}: ` : ''
+          console.log(chalk.gray(`    ${lab}${l.url}`))
+        })
+        if (task.contextUrl) console.log(chalk.gray(`  Primary:   ${task.contextUrl}`))
+      } else if (task.contextUrl) {
+        console.log(chalk.gray(`  Link:      ${task.contextUrl}`))
+      }
       if (task.tags?.length) {
         const relTags = task.tags.filter((t) => t.startsWith('blocks:') || t.startsWith('blocked-by:'))
         const plainTags = task.tags.filter((t) => !t.startsWith('blocks:') && !t.startsWith('blocked-by:'))
@@ -1280,6 +1321,87 @@ program
     } catch (err) { handleError(err) }
   })
 
+const subtaskCmd = program.command('subtask').description('Manage task subtasks')
+
+subtaskCmd
+  .command('list <taskId>')
+  .description('List subtasks on a task')
+  .action(async (taskId) => {
+    try {
+      const task = await api(`/api/tasks/${taskId}`)
+      const subtasks = task.subtasks ?? []
+      if (isMachineOutput()) {
+        console.log(JSON.stringify({ taskId, subtasks }, null, runtimeJsonOutput ? 2 : 0))
+        return
+      }
+      console.log()
+      if (subtasks.length === 0) {
+        console.log(chalk.gray('  No subtasks.\n'))
+        return
+      }
+      console.log(chalk.bold(task.title))
+      subtasks.forEach((s) => {
+        const status = s.completed ? chalk.green('✓') : '○'
+        console.log(`  ${status}  ${s.title}  ${chalk.gray(s.id.slice(0, 8))}`)
+      })
+      console.log()
+    } catch (err) { handleError(err) }
+  })
+
+subtaskCmd
+  .command('add <taskId> <title>')
+  .description('Add a subtask to a task')
+  .action(async (taskId, title) => {
+    try {
+      const trimmedTitle = String(title ?? '').trim()
+      if (!trimmedTitle) return fail('Subtask title is required')
+      const task = await api(`/api/tasks/${taskId}`)
+      const nextSubtask = { id: randomUUID(), title: trimmedTitle, completed: false }
+      await api(`/api/tasks/${taskId}`, {
+        method: 'PATCH',
+        body: JSON.stringify({ subtasks: [...(task.subtasks ?? []), nextSubtask] }),
+      })
+      console.log(chalk.green('\n✓ Subtask added') + `  ${chalk.bold(nextSubtask.title)} ${chalk.gray(`(${nextSubtask.id.slice(0, 8)})`)}\n`)
+    } catch (err) { handleError(err) }
+  })
+
+subtaskCmd
+  .command('toggle <taskId> <subtaskId>')
+  .description('Toggle subtask completion')
+  .action(async (taskId, subtaskId) => {
+    try {
+      const task = await api(`/api/tasks/${taskId}`)
+      const subtasks = task.subtasks ?? []
+      const target = findSubtask(subtasks, subtaskId)
+      if (!target) return fail(`Subtask not found: ${subtaskId}`)
+      const nextSubtasks = subtasks.map((s) => s.id === target.id ? { ...s, completed: !s.completed } : s)
+      await api(`/api/tasks/${taskId}`, {
+        method: 'PATCH',
+        body: JSON.stringify({ subtasks: nextSubtasks }),
+      })
+      const marker = !target.completed ? chalk.green('✓') : '○'
+      console.log(chalk.green('\n✓ Subtask updated') + `  ${marker} ${chalk.bold(target.title)}\n`)
+    } catch (err) { handleError(err) }
+  })
+
+subtaskCmd
+  .command('delete <taskId> <subtaskId>')
+  .description('Delete a subtask from a task')
+  .action(async (taskId, subtaskId) => {
+    try {
+      const task = await api(`/api/tasks/${taskId}`)
+      const subtasks = task.subtasks ?? []
+      const target = findSubtask(subtasks, subtaskId)
+      if (!target) return fail(`Subtask not found: ${subtaskId}`)
+      const nextSubtasks = subtasks.filter((s) => s.id !== target.id)
+      await api(`/api/tasks/${taskId}`, {
+        method: 'PATCH',
+        body: JSON.stringify({ subtasks: nextSubtasks }),
+      })
+      console.log(chalk.green('\n✓ Subtask deleted') + `  ${chalk.bold(target.title)}\n`)
+    } catch (err) { handleError(err) }
+  })
+
 // ── tm boards ─────────────────────────────────────────────────────────────────
 
 program
@@ -1371,13 +1493,65 @@ const boardCmd = program.command('board').description('Create or delete a board
 boardCmd
   .command('create <name>')
   .description('Create a new board')
-  .action(async (name) => {
+  .option('--flow <columns>', 'Comma-separated column flow, e.g. "Backlog,Ready,Doing,QA,Done"')
+  .action(async function (name) {
     try {
+      const opts = this.opts()
       const board = await api('/api/boards', { method: 'POST', body: JSON.stringify({ name: String(name).trim() }) })
+      const createdBuckets = []
+      if (opts.flow) {
+        const flowColumns = String(opts.flow)
+          .split(',')
+          .map((c) => c.trim())
+          .filter(Boolean)
+        if (flowColumns.length === 0) {
+          return fail('Flow is empty. Provide comma-separated columns, e.g. --flow "Backlog,Doing,Done".')
+        }
+        for (const column of flowColumns) {
+          if (!column) continue
+          const bucket = await api('/api/buckets', {
+            method: 'POST',
+            body: JSON.stringify({ title: column, boardId: board.id }),
+          })
+          createdBuckets.push(bucket)
+        }
+      }
       if (isMachineOutput()) {
-        console.log(JSON.stringify(board, null, runtimeJsonOutput ? 2 : 0))
+        console.log(JSON.stringify(
+          { ...board, flow: createdBuckets.map((b) => ({ id: b.id, title: b.title })) },
+          null,
+          runtimeJsonOutput ? 2 : 0
+        ))
       } else {
         console.log(chalk.green('\n✓ Board created') + `  ${chalk.bold(board.name)}  ${chalk.gray(board.id?.slice(0, 8))}\n`)
+        if (createdBuckets.length > 0) {
+          console.log(chalk.gray('  Flow columns:'))
+          createdBuckets.forEach((b) => console.log(`   - ${b.title} ${chalk.gray(b.id?.slice(0, 8))}`))
+          console.log()
+        }
+      }
+    } catch (err) { handleError(err) }
+  })
+
+boardCmd
+  .command('rename <id> <name>')
+  .description('Rename a board')
+  .action(async (id, name) => {
+    try {
+      const payload = JSON.stringify({ name: String(name).trim() })
+      let board
+      try {
+        board = await api(`/api/boards/${id}`, { method: 'PATCH', body: payload })
+      } catch (err) {
+        // Backward compatibility: some deployments only support PUT for board rename.
+        const notFound = err instanceof CliError && err.code === 'api_error' && String(err.message).toLowerCase().includes('not found')
+        if (!notFound) throw err
+        board = await api(`/api/boards/${id}`, { method: 'PUT', body: payload })
+      }
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(board, null, runtimeJsonOutput ? 2 : 0))
+      } else {
+        console.log(chalk.green('\n✓ Board renamed') + `  ${chalk.bold(board.name)}  ${chalk.gray(board.id?.slice(0, 8))}\n`)
       }
     } catch (err) { handleError(err) }
   })
@@ -1630,6 +1804,179 @@ repoCmd
     } catch (err) { handleError(err) }
   })
 
+const prCmd = program.command('pr').description('Attach and open pull requests on tasks')
+
+prCmd
+  .command('link <taskId> <prUrl>')
+  .description('Attach a PR URL to a task')
+  .option('--comment', 'Add a task comment with the PR link')
+  .action(async function (taskId, prUrl) {
+    const opts = this.opts()
+    try {
+      let parsed
+      try {
+        parsed = new URL(String(prUrl).trim())
+      } catch {
+        return fail('Provide a valid PR URL (e.g. https://github.com/owner/repo/pull/123)')
+      }
+      if (!['http:', 'https:'].includes(parsed.protocol)) {
+        return fail('PR URL must start with http:// or https://')
+      }
+      const normalizedUrl = parsed.toString()
+
+      const task = await api(`/api/tasks/${taskId}`)
+      await api(`/api/tasks/${taskId}`, {
+        method: 'PATCH',
+        body: JSON.stringify({ contextUrl: normalizedUrl }),
+      })
+      if (opts.comment) {
+        const comment = {
+          id: randomUUID(),
+          text: `Linked PR: ${normalizedUrl}`,
+          createdAt: Date.now(),
+        }
+        await api(`/api/tasks/${taskId}`, {
+          method: 'PATCH',
+          body: JSON.stringify({ comments: [...(task.comments ?? []), comment] }),
+        })
+      }
+
+      if (isMachineOutput()) {
+        console.log(JSON.stringify({ taskId, prUrl: normalizedUrl, linked: true, commented: Boolean(opts.comment) }, null, runtimeJsonOutput ? 2 : 0))
+      } else {
+        console.log(chalk.green('\n✓ PR linked') + `  ${chalk.bold(task.title)}`)
+        console.log(chalk.gray(`  ${normalizedUrl}${opts.comment ? '  ·  comment added' : ''}\n`))
+      }
+    } catch (err) { handleError(err) }
+  })
+
+prCmd
+  .command('open <taskId>')
+  .description('Open the linked PR URL for a task')
+  .option('--no-browser', "Don't auto-open browser; print URL only")
+  .action(async function (taskId) {
+    const opts = this.opts()
+    try {
+      const task = await api(`/api/tasks/${taskId}`)
+      const url = task?.contextUrl ? String(task.contextUrl).trim() : ''
+      if (!url) return fail('This task has no linked PR URL. Use: wadah pr link <task-id> <pr-url>')
+
+      if (isMachineOutput()) {
+        console.log(JSON.stringify({ taskId, prUrl: url }, null, runtimeJsonOutput ? 2 : 0))
+        return
+      }
+
+      console.log(chalk.gray(`\nPR: ${url}`))
+      if (opts.browser) {
+        const opened = await openBrowser(url)
+        if (opened) console.log(chalk.green('✓ Opened in browser\n'))
+        else console.log(chalk.yellow('Could not open browser automatically. Open the URL manually.\n'))
+      } else {
+        console.log()
+      }
+    } catch (err) { handleError(err) }
+  })
+
+const linkCmd = program.command('link').description('Attach labeled URLs to tasks (Vercel, Figma, docs — without replacing the PR)')
+
+function normalizeHttpUrlForLink(input) {
+  let parsed
+  try {
+    parsed = new URL(String(input).trim())
+  } catch {
+    return null
+  }
+  if (!['http:', 'https:'].includes(parsed.protocol)) return null
+  return parsed.toString()
+}
+
+const MAX_TASK_LINKS = 20
+
+linkCmd
+  .command('add <taskId> <url>')
+  .description('Append a URL to a task (use --label for display)')
+  .option('--label <text>', 'Short label, e.g. Vercel, Figma', '')
+  .action(async function (taskId, url) {
+    const opts = this.opts()
+    try {
+      const normalizedUrl = normalizeHttpUrlForLink(url)
+      if (!normalizedUrl) return fail('Provide a valid http(s) URL')
+
+      const task = await api(`/api/tasks/${taskId}`)
+      const existing = Array.isArray(task.contextLinks) ? task.contextLinks : []
+      if (existing.length >= MAX_TASK_LINKS) {
+        return fail(`A task can have at most ${MAX_TASK_LINKS} links. Remove one with: wadah link remove <task-id> <link-id>`)
+      }
+      const label = String(opts.label ?? '').trim().slice(0, 64)
+      const next = [...existing, { id: randomUUID(), label, url: normalizedUrl }]
+
+      await api(`/api/tasks/${taskId}`, {
+        method: 'PATCH',
+        body: JSON.stringify({ contextLinks: next }),
+      })
+
+      if (isMachineOutput()) {
+        console.log(JSON.stringify({ taskId, url: normalizedUrl, label, added: true, links: next }, null, runtimeJsonOutput ? 2 : 0))
+      } else {
+        console.log(chalk.green('\n✓ Link added') + `  ${chalk.bold(task.title)}`)
+        console.log(chalk.gray(`  ${label ? `${label} · ` : ''}${normalizedUrl}\n`))
+      }
+    } catch (err) { handleError(err) }
+  })
+
+linkCmd
+  .command('list <taskId>')
+  .description('List URLs attached to a task')
+  .action(async (taskId) => {
+    try {
+      const task = await api(`/api/tasks/${taskId}`)
+      const links = Array.isArray(task.contextLinks) ? task.contextLinks : []
+      if (isMachineOutput()) {
+        console.log(JSON.stringify({ taskId, links, contextUrl: task.contextUrl ?? null }, null, runtimeJsonOutput ? 2 : 0))
+        return
+      }
+      if (links.length === 0) {
+        console.log(chalk.gray('\nNo links on this task. Add one: wadah link add <task-id> <url> --label Vercel\n'))
+        return
+      }
+      console.log()
+      links.forEach((l) => {
+        const lab = l.label ? chalk.cyan(l.label) : chalk.gray('link')
+        console.log(`  ${chalk.dim(l.id)}  ${lab}`)
+        console.log(chalk.gray(`    ${l.url}`))
+      })
+      if (task.contextUrl) {
+        console.log(chalk.gray(`\n  Primary (e.g. wadah pr open): ${task.contextUrl}\n`))
+      } else {
+        console.log()
+      }
+    } catch (err) { handleError(err) }
+  })
+
+linkCmd
+  .command('remove <taskId> <linkId>')
+  .description('Remove a link by id (from wadah link list --json)')
+  .action(async (taskId, linkId) => {
+    try {
+      const task = await api(`/api/tasks/${taskId}`)
+      const existing = Array.isArray(task.contextLinks) ? task.contextLinks : []
+      const needle = String(linkId).trim()
+      const next = existing.filter((l) => l.id !== needle)
+      if (next.length === existing.length) {
+        return fail(`No link with id matching "${needle}". Use: wadah link list ${taskId} --json`)
+      }
+      await api(`/api/tasks/${taskId}`, {
+        method: 'PATCH',
+        body: JSON.stringify({ contextLinks: next }),
+      })
+      if (isMachineOutput()) {
+        console.log(JSON.stringify({ taskId, removed: needle, links: next }, null, runtimeJsonOutput ? 2 : 0))
+      } else {
+        console.log(chalk.green('\n✓ Link removed') + `  ${chalk.bold(task.title)}\n`)
+      }
+    } catch (err) { handleError(err) }
+  })
+
 // ── agent tokens ──────────────────────────────────────────────────────────────
 
 program
@@ -1662,7 +2009,7 @@ const agentTokenCmd = program.command('agent-token').description('Create or dele
 
 agentTokenCmd
   .command('create [name]')
-  .description('Create an agent token; token is shown once — store it as TASK_MANAGER_TOKEN')
+  .description('Create an agent token; token is shown once — store it as WADAH_AGENT_TOKEN')
   .option('--name <text>', 'Token name (if not passed as argument)')
   .option('--assignee-name <text>', 'Display name for the agent (default: same as name)')
   .action(async function (nameArg) {
@@ -1680,9 +2027,9 @@ agentTokenCmd
         console.log(chalk.yellow('\n  Token (store it now — shown once):'))
         console.log(`  ${result.token}`)
         console.log(chalk.gray('\n  Store it so you don’t lose it:'))
-        console.log(chalk.gray('  · GitHub Actions: Repo → Settings → Secrets and variables → Actions → New secret → TASK_MANAGER_TOKEN'))
-        console.log(chalk.gray('  · Cursor: Settings → Environment variables → TASK_MANAGER_TOKEN'))
-        console.log(chalk.gray('  · Shell: export TASK_MANAGER_TOKEN="<paste token here>"\n'))
+        console.log(chalk.gray('  · GitHub Actions: Repo → Settings → Secrets and variables → Actions → New secret → WADAH_AGENT_TOKEN'))
+        console.log(chalk.gray('  · Cursor: Settings → Environment variables → WADAH_AGENT_TOKEN'))
+        console.log(chalk.gray('  · Shell: export WADAH_AGENT_TOKEN="<paste token here>"\n'))
       }
     } catch (err) { handleError(err) }
   })
@@ -2006,12 +2353,12 @@ program
       addCheck('api_ping', 'fail', `API ping failed: ${err.message}`)
     }
 
-    const hasEnvToken = Boolean(process.env.TASK_MANAGER_TOKEN || runtimeToken)
+    const hasEnvToken = Boolean(envAgentToken() || runtimeToken)
     const hasSavedToken = Boolean(confGet('access_token'))
     if (!hasEnvToken && !hasSavedToken) {
       addCheck('auth_token', 'warn', 'No token available. Run wadah login.')
     } else if (hasEnvToken) {
-      addCheck('auth_token', 'pass', 'Using agent token from env/flag (TASK_MANAGER_TOKEN)')
+      addCheck('auth_token', 'pass', `Using agent token from env/flag (${envAgentTokenVarName()})`)
     } else {
       addCheck('auth_token', 'pass', 'Using token from profile config')
     }
@@ -2037,7 +2384,7 @@ program
         addCheck('auth_me', 'warn', `Auth check failed: ${err.message}`)
       }
 
-      // Agent-specific checks (only when TASK_MANAGER_TOKEN is set)
+      // Agent-specific checks (only when an env agent token is set)
       if (hasEnvToken && meBody) {
         const isAgent = meBody.workspaces?.[0]?.role === 'agent'
         if (!isAgent) {
@@ -2163,7 +2510,7 @@ program
     const config = {
       api_url: getApiBase(),
       signed_in_as: confGet('user_email') ?? null,
-      agent_mode: Boolean(process.env.TASK_MANAGER_TOKEN || runtimeToken),
+      agent_mode: Boolean(envAgentToken() || runtimeToken),
       profile: getProfile(),
       default_board: defaultBoard ?? null,
       config_file: conf.path,
@@ -2176,7 +2523,7 @@ program
     console.log(chalk.bold('CLI config'))
     console.log(chalk.gray(`  API URL:       ${config.api_url}`))
     console.log(chalk.gray(`  Signed in as:  ${config.signed_in_as ?? '—'}`))
-    console.log(chalk.gray(`  Agent mode:    ${config.agent_mode ? 'yes (TASK_MANAGER_TOKEN set)' : 'no'}`))
+    console.log(chalk.gray(`  Agent mode:    ${config.agent_mode ? `yes (${envAgentTokenVarName() ?? 'token flag'} set)` : 'no'}`))
     console.log(chalk.gray(`  Default board: ${defaultBoard ?? '— (not set, use: wadah config --default-board "Name")'}`))
     console.log(chalk.gray(`  Profile:       ${getProfile()}`))
     console.log(chalk.gray(`  Config file:   ${config.config_file}`))
@@ -2255,7 +2602,7 @@ const CLI_COMMANDS = [
   'add', 'agent-token', 'agent-tokens', 'assign', 'assignee', 'assignees', 'board', 'board-view', 'boards',
   'bucket', 'buckets', 'calendar', 'comment', 'complete', 'config', 'delete', 'doc', 'docs',
   'do', 'doctor', 'files', 'folder', 'folders', 'invite', 'list', 'login', 'members', 'mkdir',
-  'forget', 'memory', 'memory-export', 'memory-log', 'move', 'open', 'repo', 'repos', 'reopen', 'remember', 'requested', 'search', 'setup-agent', 'signup', 'state', 'update', 'upload', 'view', 'whoami',
+  'forget', 'memory', 'memory-export', 'memory-log', 'move', 'open', 'pr', 'repo', 'repos', 'reopen', 'remember', 'requested', 'search', 'setup-agent', 'signup', 'state', 'update', 'upload', 'view', 'whoami',
 ]
 
 // ── wadah setup-agent ─────────────────────────────────────────────────────────
@@ -2265,7 +2612,7 @@ program
   .description('Interactive wizard: create an agent token, write it to your shell profile, and verify everything works')
   .option('--name <name>', 'Agent name (skip prompt)')
   .option('--board <board>', 'Default board name (skip prompt)')
-  .option('--skip-env', 'Skip writing TASK_MANAGER_TOKEN to shell profile (print instructions only)')
+  .option('--skip-env', 'Skip writing WADAH_AGENT_TOKEN to shell profile (print instructions only)')
   .action(async (opts) => {
     const readline = await import('node:readline/promises')
     const os = await import('node:os')
@@ -2329,18 +2676,18 @@ program
 
     // Step 4: write env var to shell profile
     console.log()
-    console.log(chalk.bold('Step 4/5  Setting up TASK_MANAGER_TOKEN…'))
+    console.log(chalk.bold('Step 4/5  Setting up WADAH_AGENT_TOKEN…'))
 
     const shell = process.env.SHELL ?? ''
     const profileMap = { zsh: '.zshrc', bash: '.bashrc', fish: '.config/fish/config.fish' }
     const profileKey = Object.keys(profileMap).find((k) => shell.includes(k))
     const profileFile = profileKey ? path.join(os.homedir(), profileMap[profileKey]) : null
     const marker = '# added by wadah setup-agent'
-    const exportLine = `\nexport TASK_MANAGER_TOKEN="${rawToken}"  ${marker}\n`
+    const exportLine = `\nexport WADAH_AGENT_TOKEN="${rawToken}"  ${marker}\n`
 
     if (opts.skipEnv || !profileFile) {
       console.log(chalk.gray('  Skipping automatic profile write. Add this line manually:'))
-      console.log(chalk.gray(`  export TASK_MANAGER_TOKEN="${rawToken}"`))
+      console.log(chalk.gray(`  export WADAH_AGENT_TOKEN="${rawToken}"`))
       const rcGuess = shell.includes('zsh') ? '~/.zshrc' : shell.includes('fish') ? '~/.config/fish/config.fish' : '~/.bashrc'
       console.log(chalk.gray(`  Then reload: source ${rcGuess}`))
     } else {
@@ -2350,7 +2697,7 @@ program
           const existing = fs.existsSync(profileFile) ? fs.readFileSync(profileFile, 'utf8') : ''
           const filtered = existing
             .split('\n')
-            .filter((line) => !line.includes('TASK_MANAGER_TOKEN=') && !line.includes(marker))
+            .filter((line) => !line.includes('WADAH_AGENT_TOKEN=') && !line.includes(marker))
             .join('\n')
           const next = `${filtered.trimEnd()}${exportLine}`
           fs.writeFileSync(profileFile, `${next.endsWith('\n') ? next : `${next}\n`}`)
@@ -2358,10 +2705,10 @@ program
           console.log(chalk.gray(`  Reload now: source ${profileFile}`))
         } catch (e) {
           console.log(chalk.yellow(`  ⚠ Could not write to ${profileFile}: ${e.message}`))
-          console.log(chalk.gray(`  Add manually: export TASK_MANAGER_TOKEN="${rawToken}"`))
+          console.log(chalk.gray(`  Add manually: export WADAH_AGENT_TOKEN="${rawToken}"`))
         }
       } else {
-        console.log(chalk.gray(`  Skipped. Add manually: export TASK_MANAGER_TOKEN="${rawToken}"`))
+        console.log(chalk.gray(`  Skipped. Add manually: export WADAH_AGENT_TOKEN="${rawToken}"`))
       }
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-wadah",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "Open Wadah CLI — shared task board for humans and agents",
   "type": "module",
   "bin": {

package/test/cli.test.js

@@ -11,7 +11,7 @@ function runCli(args) {
   return new Promise((resolvePromise, reject) => {
     const child = spawn(process.execPath, [cliPath, ...args], {
       stdio: ['ignore', 'pipe', 'pipe'],
-      env: { ...process.env, TASK_MANAGER_TOKEN: '' },
+      env: { ...process.env, WADAH_AGENT_TOKEN: '' },
     })
     let stdout = ''
     let stderr = ''
@@ -47,6 +47,12 @@ test('wadah open --help shows open command help', async () => {
   assert.match(stdout, /open|List/)
 })
 
+test('wadah link --help shows link subcommands', async () => {
+  const { code, stdout } = await runCli(['link', '--help'])
+  assert.equal(code, 0)
+  assert.match(stdout, /add|list|remove/)
+})
+
 test('wadah doctor runs without crashing', async () => {
   const { code } = await runCli(['doctor'])
   // Doctor may exit 0 or 1 depending on API/token; we only assert it doesn't throw