open-wadah 1.2.3 → 1.2.4

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,92 +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`.
+
+## 60-second quick start
 
-## Quick start
+1. Sign in:
 
-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:
+```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`.
+
+## Core workflows
 
-| Command | Description |
-|--------|-------------|
-| **Auth** | `login`, `signup`, `logout`, `whoami` |
-| **Tasks** | `open`, `list`, `search`, `requested`, `add`, `complete`, `reopen`, `view`, `update`, `move`, `assign`, `comment`, `subtask list/add/toggle/delete`, `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]` |
+### Daily task operations
 
-Run `wadah --help` for full list and options.
+```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"
+```
 
-Subtask examples:
+### 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>
-wadah subtask delete <task-id> <subtask-id>
 ```
 
-## Shell completion
-
-**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()}`))
@@ -400,7 +413,7 @@ Available commands and their args (use these exact command names):
 - buckets: args = []. List columns.
 - assignees: args = []. List assignees.
 - state: args = []. Full state JSON.
-- move: args = [task id, bucket name or id]. Move task to another column.
+- move: args = [task id, bucket name or id]. Move task to another column. Use --board <name> to move to another board (lands in first column). Add --bucket <name> to specify the column on that board.
 - assign: args = [task id, "--to", "assignee[,assignee2]", "--mode", "set|add|remove"]. Assign one or more people.
 - whoami: args = []. Show current user/workspace.
 - folders: args = []. List folders.
@@ -738,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({
@@ -771,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) {
@@ -1089,11 +1102,49 @@ program
   })
 
 program
-  .command('move <id> <bucket>')
-  .description('Move a task to another column')
-  .action(async (id, bucketQuery) => {
+  .command('move <id> [bucket]')
+  .description('Move a task to another column or board')
+  .option('--board <name>', 'Target board (name or id)')
+  .option('--bucket <name>', 'Target column on that board (defaults to first column)')
+  .action(async (id, bucketArg, opts) => {
     try {
       const state = await getState()
+
+      // --board flag: resolve board then pick column
+      if (opts.board) {
+        const boardQuery = opts.board.toLowerCase()
+        const board = state.boards.find((b) => b.id === opts.board || b.name.toLowerCase().includes(boardQuery))
+        if (!board) return fail(`Board not found: ${opts.board}`)
+
+        const boardBuckets = state.buckets
+          .filter((b) => b.boardId === board.id)
+          .sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
+        if (boardBuckets.length === 0) return fail(`Board "${board.name}" has no columns`)
+
+        let bucket
+        if (opts.bucket) {
+          const bq = opts.bucket.toLowerCase()
+          bucket = boardBuckets.find((b) => b.id === opts.bucket || b.title.toLowerCase().includes(bq))
+          if (!bucket) return fail(`Column "${opts.bucket}" not found on board "${board.name}"`)
+        } else if (bucketArg) {
+          const bq = bucketArg.toLowerCase()
+          bucket = boardBuckets.find((b) => b.id === bucketArg || b.title.toLowerCase().includes(bq))
+          if (!bucket) return fail(`Column "${bucketArg}" not found on board "${board.name}"`)
+        } else {
+          bucket = boardBuckets[0]
+        }
+
+        const task = await api(`/api/tasks/${id}`, {
+          method: 'PATCH',
+          body:   JSON.stringify({ bucketId: bucket.id, boardId: board.id }),
+        })
+        console.log(chalk.green('\n✓ Moved') + `  ${chalk.bold(task.title)} → ${board.name} / ${bucket.title}\n`)
+        return
+      }
+
+      // positional bucket arg (original behaviour — cross-board if bucket is on another board)
+      const bucketQuery = bucketArg ?? opts.bucket
+      if (!bucketQuery) return fail('Provide a column name/id, or use --board <name>')
       const bucket = findBucket(state.buckets, bucketQuery)
       if (!bucket) return fail(`Bucket not found: ${bucketQuery}`)
       const patch = { bucketId: bucket.id }
@@ -1471,13 +1522,42 @@ 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) }
   })
@@ -1858,7 +1938,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) {
@@ -1876,9 +1956,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) }
   })
@@ -2202,12 +2282,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')
     }
@@ -2233,7 +2313,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) {
@@ -2359,7 +2439,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,
@@ -2372,7 +2452,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}`))
@@ -2461,7 +2541,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')
@@ -2525,18 +2605,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 {
@@ -2546,7 +2626,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`}`)
@@ -2554,10 +2634,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.3",
+  "version": "1.2.4",
   "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 = ''