open-wadah 1.0.6 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # open-wadah
 
-Open Wadah CLI for managing tasks in a shared workspace.
+Open Wadah CLI — shared task board for humans and agents. Use it from the terminal or from Cursor, Claude Code, and Kimi.
 
 ## Install
 
@@ -8,22 +8,13 @@ Open Wadah CLI for managing tasks in a shared workspace.
 npm install -g open-wadah
 ```
 
-Commands are available as `wadah`, `tm`, and `ow`.
+Commands: `wadah`, `tm`, `ow` (same CLI).
 
-## Quick Start
+## Quick start
 
-1. Make sure the API is reachable (default: `https://api.openwadah.com`).
-2. Sign up or log in:
-
-```bash
-wadah signup
-wadah login
-```
-
-`wadah login` uses browser sign-in by default.  
-Use `wadah login --password` for terminal email/password.
-
-3. Use the CLI:
+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 open
@@ -31,55 +22,67 @@ wadah add "Fix login issue"
 wadah complete <task-id>
 ```
 
-## Useful Commands
+## Commands
+
+| Command | Description |
+|--------|-------------|
+| **Auth** | `login`, `signup`, `logout`, `whoami` |
+| **Tasks** | `open`, `list`, `requested`, `add`, `complete`, `reopen`, `view`, `update`, `move`, `assign`, `comment`, `delete` |
+| **Board** | `boards`, `buckets`, `assignees`; `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]` |
 
-- `wadah --help`
-- `wadah whoami`
-- `wadah doctor`
-- `wadah list --open`
-- `wadah move <task-id> <bucket>`
-- `wadah update <task-id> --title "New title"`
-- `wadah state`
+Run `wadah --help` for full list and options.
 
-## Global Flags
+## Shell completion
 
-- `--profile <name>`: use a named profile (defaults to `default`)
-- `--token <token>`: use a token for this command only
-- `--json`: force machine-readable JSON output
-- `--quiet`: silence non-error output (also machine-friendly)
+**Bash:**
 
-## Stable Error Codes
+```bash
+wadah completion bash >> ~/.bashrc
+source ~/.bashrc
+```
 
-When `--json` is enabled (or output is non-interactive), errors return:
+**Zsh:**
 
-```json
-{"error":{"code":"auth_error","message":"Not authenticated"}}
+```bash
+wadah completion zsh >> ~/.zshrc
+source ~/.zshrc
 ```
 
-Common codes:
+## Agent / AI use
 
-- `auth_error`
-- `validation_error`
-- `network_error`
-- `api_error`
-- `server_error`
-- `authorization_pending`
-- `invalid_device_code`
-- `token_expired`
-- `login_timeout`
+- Set `TASK_MANAGER_TOKEN` (create a token in the app under **Agent access**).
+- Use `--json` for machine-readable output: `wadah open --json`, `wadah list --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.
 
-## API URL Override
+## Global flags
 
-Use env var:
+- `--api <url>` — API base URL
+- `--profile <name>` — config profile
+- `--token <token>` — auth token for this run
+- `--json` — JSON output
+- `--quiet` — minimal output
 
-```bash
-TASK_MANAGER_API_URL=https://api.openwadah.com wadah open
-```
+## Develop & test
 
-Or pass per command:
+From the repo root:
 
 ```bash
-wadah --api https://api.openwadah.com open
+npm run install:all
+npm run tm -- --help
+cd task-manager-cli && npm test
 ```
 
-Use your own API URL if self-hosting (for example `https://api.yourcompany.com`).
+## Error codes (with `--json`)
+
+- `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`)

package/cli.js

@@ -6,8 +6,9 @@ import Conf from 'conf'
 import { input, password as promptPassword } from '@inquirer/prompts'
 import { webcrypto } from 'node:crypto'
 import { spawn } from 'node:child_process'
-import { readFileSync } from 'node:fs'
-import { dirname, resolve } from 'node:path'
+import { readFileSync, existsSync, createReadStream } from 'node:fs'
+import FormData from 'form-data'
+import { dirname, resolve, basename } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const randomUUID = () => webcrypto.randomUUID()
@@ -203,12 +204,11 @@ function handleError(err) {
 async function resolveMyAssigneeId(state) {
   try {
     const me = await api('/api/auth/me')
+    if (me.assigneeId) return me.assigneeId
     const userId = me.user?.id
-    // Match by user_id field on assignee (if backend returns it)
     const byUserId = state.assignees.find((a) => a.user_id === userId)
     if (byUserId) return byUserId.id
   } catch {}
-  // Fallback: 'Me' assignee
   return state.assignees.find((a) => a.name === 'Me')?.id ?? null
 }
 
@@ -266,6 +266,106 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms))
 }
 
+// ── natural language (do) ─────────────────────────────────────────────────────
+
+const DO_SYSTEM_PROMPT = `You are a parser for the "wadah" CLI (task board). Given the user's natural language request, output exactly one JSON object with no markdown or extra text:
+{"command": "<command>", "args": [<array of string arguments>]}
+
+Available commands and their args (use these exact command names):
+- add: args = [task title string]. Example: add a task "Fix login" -> {"command": "add", "args": ["Fix login"]}
+- folder create (or mkdir): args = [folder name]. Example: create a folder called Reports -> {"command": "folder create", "args": ["Reports"]}
+- upload: args = [file path]. Optional: include "--folder", "<folder-id>" in args if user says to put in a folder. Example: upload report.pdf -> {"command": "upload", "args": ["report.pdf"]}
+- open: args = []. List open tasks.
+- list: args = []. List all tasks.
+- complete: args = [task id]. Mark task done. Example: complete task abc123 -> {"command": "complete", "args": ["abc123"]}
+- requested: args = []. List tasks I requested.
+- view: args = [task id]. Show task details.
+- boards: args = []. List boards.
+- 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.
+- assign: args = [task id, assignee name]. Assign a task.
+- whoami: args = []. Show current user/workspace.
+- folders: args = []. List folders.
+- files: args = []. List files; optionally include "--folder", "<id>" in args.
+- members: args = []. List workspace members.
+- calendar: args = []. List calendar events.
+- calendar add: args = []; include "--title", "<t>", "--start", "<iso>", "--end", "<iso>" for new event (start/end required).
+- docs: args = []. List workspace docs.
+- doc create: args = [title]. Create a doc. Optional: "--parent", "<id>", "--emoji", "<char>".
+- doc show: args = [doc id]. Show one doc.
+- doc update: args = [doc id]. Optional: "--title", "<t>", "--content", "<json>", "--emoji", "--parent", "<id>".
+- doc delete: args = [doc id]. Delete a doc.
+- agent-tokens: args = []. List agent tokens.
+- agent-token create: args = [name]. Create agent token; optional "--assignee-name", "<text>".
+- agent-token delete: args = [token id]. Revoke token.
+- board create: args = [board name]. Create board.
+- board delete: args = [board id]. Delete board.
+- bucket create: args = [column title]. Optional "--board", "<id>".
+- bucket update: args = [bucket id]. Optional "--title", "<t>", "--order", "<n>".
+- bucket delete: args = [bucket id]. Delete column.
+- assignee create: args = [name]. Optional "--type", "human" or "agent".
+- assignee update: args = [assignee id]. Optional "--name", "--type".
+- assignee delete: args = [assignee id]. Delete assignee.
+
+If the request is unclear or not a valid CLI action, return {"command": "", "args": []}. Output only the JSON object.`
+
+async function parseNaturalLanguage(message) {
+  const apiKey = process.env.OPENAI_API_KEY || process.env.WADAH_OPENAI_API_KEY
+  if (!apiKey || !apiKey.trim()) {
+    throw new CliError('config', 'Set OPENAI_API_KEY or WADAH_OPENAI_API_KEY to use natural language (wadah do "...")')
+  }
+  const res = await fetch('https://api.openai.com/v1/chat/completions', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${apiKey.trim()}`,
+    },
+    body: JSON.stringify({
+      model: 'gpt-4o-mini',
+      messages: [
+        { role: 'system', content: DO_SYSTEM_PROMPT },
+        { role: 'user', content: String(message).trim() },
+      ],
+      max_tokens: 200,
+      temperature: 0,
+    }),
+  })
+  const data = await res.json().catch(() => ({}))
+  if (!res.ok) {
+    const err = data.error?.message || data.message || res.statusText
+    throw new CliError('api_error', `LLM request failed: ${err}`)
+  }
+  const text = data.choices?.[0]?.message?.content?.trim() || ''
+  const jsonMatch = text.match(/\{[\s\S]*\}/)
+  const raw = jsonMatch ? jsonMatch[0] : text
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch (_) {
+    throw new CliError('api_error', 'Could not parse LLM response as JSON')
+  }
+  const cmd = parsed.command && String(parsed.command).trim()
+  const args = Array.isArray(parsed.args) ? parsed.args.map(String) : []
+  return { command: cmd, args }
+}
+
+function runResolvedCommand(command, args) {
+  const cliPath = resolve(__dirname, 'cli.js')
+  const childArgs = [cliPath]
+  if (runtimeApiBase) childArgs.push('--api', runtimeApiBase)
+  if (runtimeToken) childArgs.push('--token', runtimeToken)
+  if (runtimeProfile) childArgs.push('--profile', runtimeProfile)
+  const cmdParts = String(command).split(/\s+/).filter(Boolean)
+  childArgs.push(...cmdParts, ...args)
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, childArgs, { stdio: 'inherit', env: process.env, shell: false })
+    child.on('error', reject)
+    child.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`Exit ${code}`))))
+  })
+}
+
 function openBrowser(url) {
   let cmd
   let args
@@ -308,6 +408,27 @@ program.hook('preAction', (_, actionCommand) => {
   runtimeQuietOutput = Boolean(opts.quiet)
 })
 
+// ── do (natural language) ──────────────────────────────────────────────────────
+
+program
+  .command('do <message>')
+  .description('Run a command from natural language (e.g. "add a task to fix the login bug")')
+  .action(async (message) => {
+    try {
+      const { command, args } = await parseNaturalLanguage(message)
+      if (!command) {
+        console.error(chalk.yellow('\nCould not understand. Try a direct command, e.g:\n  wadah add "Fix bug"\n  wadah folder create "Reports"\n  wadah open\n'))
+        process.exit(1)
+      }
+      if (!runtimeQuietOutput && process.stdout.isTTY) {
+        console.log(chalk.gray(`Running: wadah ${command} ${args.join(' ')}\n`))
+      }
+      await runResolvedCommand(command, args)
+    } catch (err) {
+      handleError(err)
+    }
+  })
+
 // ── tm login ──────────────────────────────────────────────────────────────────
 
 program
@@ -955,6 +1076,503 @@ program
     } catch (err) { handleError(err) }
   })
 
+// ── board CRUD ────────────────────────────────────────────────────────────────
+
+const boardCmd = program.command('board').description('Create or delete a board (list: wadah boards)')
+
+boardCmd
+  .command('create <name>')
+  .description('Create a new board')
+  .action(async (name) => {
+    try {
+      const board = await api('/api/boards', { method: 'POST', body: JSON.stringify({ name: String(name).trim() }) })
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(board, null, runtimeJsonOutput ? 2 : 0))
+      } else {
+        console.log(chalk.green('\n✓ Board created') + `  ${chalk.bold(board.name)}  ${chalk.gray(board.id?.slice(0, 8))}\n`)
+      }
+    } catch (err) { handleError(err) }
+  })
+
+boardCmd
+  .command('delete <id>')
+  .description('Delete a board (cannot delete the last one)')
+  .action(async (id) => {
+    try {
+      await api(`/api/boards/${id}`, { method: 'DELETE' })
+      if (!runtimeQuietOutput) console.log(chalk.green('\n✓ Board deleted\n'))
+    } catch (err) { handleError(err) }
+  })
+
+// ── bucket CRUD ──────────────────────────────────────────────────────────────
+
+const bucketCmd = program.command('bucket').description('Create, update, or delete a column/bucket (list: wadah buckets)')
+
+bucketCmd
+  .command('create <title>')
+  .description('Create a new bucket (column)')
+  .option('--board <id>', 'Board id (optional)')
+  .action(async function (title) {
+    try {
+      const body = { title: String(title).trim() }
+      if (this.opts().board) body.boardId = this.opts().board
+      const bucket = await api('/api/buckets', { method: 'POST', body: JSON.stringify(body) })
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(bucket, null, runtimeJsonOutput ? 2 : 0))
+      } else {
+        console.log(chalk.green('\n✓ Bucket created') + `  ${chalk.bold(bucket.title)}  ${chalk.gray(bucket.id?.slice(0, 8))}\n`)
+      }
+    } catch (err) { handleError(err) }
+  })
+
+bucketCmd
+  .command('update <id>')
+  .description('Update a bucket')
+  .option('--title <text>', 'New title')
+  .option('--order <n>', 'Order (number)', parseInt)
+  .action(async function (id) {
+    const opts = this.opts()
+    try {
+      const patch = {}
+      if (opts.title !== undefined) patch.title = opts.title
+      if (opts.order !== undefined && !Number.isNaN(opts.order)) patch.order = opts.order
+      if (Object.keys(patch).length === 0) return fail('Provide --title or --order to update')
+      await api(`/api/buckets/${id}`, { method: 'PATCH', body: JSON.stringify(patch) })
+      if (!runtimeQuietOutput) console.log(chalk.green('\n✓ Bucket updated\n'))
+    } catch (err) { handleError(err) }
+  })
+
+bucketCmd
+  .command('delete <id>')
+  .description('Delete a bucket (tasks move to another column)')
+  .action(async (id) => {
+    try {
+      await api(`/api/buckets/${id}`, { method: 'DELETE' })
+      if (!runtimeQuietOutput) console.log(chalk.green('\n✓ Bucket deleted\n'))
+    } catch (err) { handleError(err) }
+  })
+
+// ── assignee CRUD ────────────────────────────────────────────────────────────
+
+const assigneeCmd = program.command('assignee').description('Create, update, or delete an assignee (list: wadah assignees)')
+
+assigneeCmd
+  .command('create <name>')
+  .description('Create a new assignee')
+  .option('--type <type>', 'Type: human or agent', 'human')
+  .action(async function (name) {
+    try {
+      const body = { name: String(name).trim(), type: this.opts().type || 'human' }
+      const assignee = await api('/api/assignees', { method: 'POST', body: JSON.stringify(body) })
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(assignee, null, runtimeJsonOutput ? 2 : 0))
+      } else {
+        console.log(chalk.green('\n✓ Assignee created') + `  ${chalk.bold(assignee.name)}  ${chalk.gray(assignee.id?.slice(0, 8))}\n`)
+      }
+    } catch (err) { handleError(err) }
+  })
+
+assigneeCmd
+  .command('update <id>')
+  .description('Update an assignee')
+  .option('--name <text>', 'New name')
+  .option('--type <type>', 'Type: human or agent')
+  .action(async function (id) {
+    const opts = this.opts()
+    try {
+      const patch = {}
+      if (opts.name !== undefined) patch.name = opts.name
+      if (opts.type !== undefined) patch.type = opts.type
+      if (Object.keys(patch).length === 0) return fail('Provide --name or --type to update')
+      await api(`/api/assignees/${id}`, { method: 'PATCH', body: JSON.stringify(patch) })
+      if (!runtimeQuietOutput) console.log(chalk.green('\n✓ Assignee updated\n'))
+    } catch (err) { handleError(err) }
+  })
+
+assigneeCmd
+  .command('delete <id>')
+  .description('Delete an assignee (tasks unassigned)')
+  .action(async (id) => {
+    try {
+      await api(`/api/assignees/${id}`, { method: 'DELETE' })
+      if (!runtimeQuietOutput) console.log(chalk.green('\n✓ Assignee deleted\n'))
+    } catch (err) { handleError(err) }
+  })
+
+program
+  .command('folders')
+  .description('List all folders (Files tab)')
+  .action(async () => {
+    try {
+      const folders = await api('/api/folders').catch(() => [])
+      const list = Array.isArray(folders) ? folders : []
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(list, null, runtimeJsonOutput ? 2 : 0))
+      } else if (list.length === 0) {
+        console.log(chalk.gray('\nNo folders. Create one: wadah folder create "Name"\n'))
+      } else {
+        console.log()
+        list.forEach((f) => console.log(`  ${chalk.bold(f.name)}  ${chalk.gray(`id: ${f.id}`)}`))
+        console.log()
+      }
+    } catch (err) { handleError(err) }
+  })
+
+program
+  .command('files')
+  .description('List all files in the workspace')
+  .option('--folder <id>', 'Filter by folder id')
+  .action(async function () {
+    const opts = this.opts()
+    try {
+      const state = await api('/api/state')
+      let files = state.files ?? []
+      if (opts.folder) files = files.filter((f) => (f.folderId || f.folder_id) === opts.folder)
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(files, null, runtimeJsonOutput ? 2 : 0))
+      } else if (files.length === 0) {
+        console.log(chalk.gray('\nNo files. Upload one: wadah upload <path>\n'))
+      } else {
+        console.log()
+        files.forEach((f) => {
+          const name = f.name || f.id
+          const url = f.storageUrl || f.storage_url
+          console.log(`  ${chalk.bold(name)}  ${chalk.gray(url ? url.slice(0, 50) + '…' : f.id)}`)
+        })
+        console.log()
+      }
+    } catch (err) { handleError(err) }
+  })
+
+program
+  .command('members')
+  .description('List workspace members')
+  .action(async () => {
+    try {
+      const members = await api('/api/workspace/members')
+      const list = Array.isArray(members) ? members : []
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(list, null, runtimeJsonOutput ? 2 : 0))
+      } else if (list.length === 0) {
+        console.log(chalk.gray('\nNo members.\n'))
+      } else {
+        console.log()
+        list.forEach((m) => console.log(`  ${chalk.bold(m.role)}  ${chalk.gray(m.user_id?.slice(0, 8) ?? '—')}`))
+        console.log()
+      }
+    } catch (err) { handleError(err) }
+  })
+
+// ── agent tokens ──────────────────────────────────────────────────────────────
+
+program
+  .command('agent-tokens')
+  .description('List agent tokens for this workspace')
+  .action(async () => {
+    try {
+      const list = await api('/api/agent-tokens').catch(() => [])
+      const arr = Array.isArray(list) ? list : []
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(arr, null, runtimeJsonOutput ? 2 : 0))
+      } else if (arr.length === 0) {
+        console.log(chalk.gray('\nNo agent tokens. Create one: wadah agent-token create "Bot name"\n'))
+      } else {
+        console.log()
+        arr.forEach((t) => {
+          const as = t.assigneeName ? chalk.gray(` · acts as ${t.assigneeName}`) : ''
+          console.log(`  ${chalk.bold(t.name)}  ${chalk.gray(`id: ${t.id?.slice(0, 8)}${as}`)}`)
+        })
+        console.log()
+      }
+    } catch (err) { handleError(err) }
+  })
+
+const agentTokenCmd = program.command('agent-token').description('Create or delete an agent token (for CLI/CI)')
+
+agentTokenCmd
+  .command('create [name]')
+  .description('Create an agent token; token is shown once — store it as TASK_MANAGER_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) {
+    const opts = this.opts()
+    const name = (nameArg || opts.name || 'CLI Agent').trim()
+    try {
+      const body = { name }
+      if (opts.assigneeName) body.assigneeName = opts.assigneeName
+      const result = await api('/api/agent-tokens', { method: 'POST', body: JSON.stringify(body) })
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(result, null, runtimeJsonOutput ? 2 : 0))
+      } else {
+        console.log(chalk.green('\n✓ Agent token created'))
+        console.log(chalk.gray(`  Name: ${result.name}  Id: ${result.id?.slice(0, 8)}  Acts as: ${result.assigneeName ?? result.name}`))
+        console.log(chalk.yellow('\n  Token (save it — shown once):'))
+        console.log(`  ${result.token}`)
+        console.log(chalk.gray('\n  Use: export TASK_MANAGER_TOKEN="<token>"\n'))
+      }
+    } catch (err) { handleError(err) }
+  })
+
+agentTokenCmd
+  .command('delete <id>')
+  .description('Revoke an agent token')
+  .action(async (id) => {
+    try {
+      await api(`/api/agent-tokens/${id}`, { method: 'DELETE' })
+      if (!runtimeQuietOutput) console.log(chalk.green('\n✓ Agent token revoked\n'))
+    } catch (err) { handleError(err) }
+  })
+
+// ── calendar events ──────────────────────────────────────────────────────────
+
+const calendarCmd = program
+  .command('calendar')
+  .description('List calendar events (optional: --assignee, --task, --from, --to)')
+  .option('--assignee <id>', 'Filter by assignee id')
+  .option('--task <id>', 'Filter by task id')
+  .option('--from <iso>', 'From date (ISO)')
+  .option('--to <iso>', 'To date (ISO)')
+  .action(async function () {
+    const opts = this.opts()
+    try {
+      let path = '/api/calendar-events'
+      const q = []
+      if (opts.assignee) q.push(`assigneeId=${encodeURIComponent(opts.assignee)}`)
+      if (opts.task) q.push(`taskId=${encodeURIComponent(opts.task)}`)
+      if (opts.from) q.push(`from=${encodeURIComponent(opts.from)}`)
+      if (opts.to) q.push(`to=${encodeURIComponent(opts.to)}`)
+      if (q.length) path += '?' + q.join('&')
+      const list = await api(path).catch(() => [])
+      const arr = Array.isArray(list) ? list : []
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(arr, null, runtimeJsonOutput ? 2 : 0))
+      } else if (arr.length === 0) {
+        console.log(chalk.gray('\nNo calendar events.\n'))
+      } else {
+        console.log()
+        arr.forEach((e) => {
+          const start = e.startTime ? new Date(e.startTime).toLocaleString() : '—'
+          const end = e.endTime ? new Date(e.endTime).toLocaleString() : '—'
+          console.log(`  ${chalk.bold(e.title || 'Untitled')}  ${chalk.gray(`${start} → ${end}`)}  ${chalk.gray(`id: ${e.id?.slice(0, 8)}`)}`)
+        })
+        console.log()
+      }
+    } catch (err) { handleError(err) }
+  })
+
+calendarCmd
+  .command('add')
+  .description('Create a calendar event (--start and --end required, ISO or YYYY-MM-DD)')
+  .option('--title <text>', 'Event title', 'Work block')
+  .option('--start <iso>', 'Start time (ISO or YYYY-MM-DD)')
+  .option('--end <iso>', 'End time (ISO or YYYY-MM-DD)')
+  .option('--task <id>', 'Task id')
+  .option('--assignee <id>', 'Assignee id')
+  .option('--color <hex>', 'Color')
+  .action(async function () {
+    const opts = this.opts()
+    try {
+      if (!opts.start || !opts.end) return fail('--start and --end are required')
+      const startTime = new Date(opts.start).toISOString()
+      const endTime = new Date(opts.end).toISOString()
+      const body = { title: opts.title, startTime, endTime }
+      if (opts.task) body.taskId = opts.task
+      if (opts.assignee) body.assigneeId = opts.assignee
+      if (opts.color) body.color = opts.color
+      const event = await api('/api/calendar-events', { method: 'POST', body: JSON.stringify(body) })
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(event, null, runtimeJsonOutput ? 2 : 0))
+      } else {
+        console.log(chalk.green('\n✓ Event created') + `  ${chalk.bold(event.title)}  ${chalk.gray(event.id?.slice(0, 8))}\n`)
+      }
+    } catch (err) { handleError(err) }
+  })
+
+calendarCmd
+  .command('update <id>')
+  .description('Update a calendar event')
+  .option('--title <text>', 'Event title')
+  .option('--start <iso>', 'Start time')
+  .option('--end <iso>', 'End time')
+  .option('--task <id>', 'Task id')
+  .option('--assignee <id>', 'Assignee id')
+  .option('--color <hex>', 'Color')
+  .action(async function (id) {
+    const opts = this.opts()
+    try {
+      const patch = {}
+      if (opts.title !== undefined) patch.title = opts.title
+      if (opts.start !== undefined) patch.startTime = new Date(opts.start).toISOString()
+      if (opts.end !== undefined) patch.endTime = new Date(opts.end).toISOString()
+      if (opts.task !== undefined) patch.taskId = opts.task
+      if (opts.assignee !== undefined) patch.assigneeId = opts.assignee
+      if (opts.color !== undefined) patch.color = opts.color
+      if (Object.keys(patch).length === 0) return fail('Provide at least one option to update')
+      await api(`/api/calendar-events/${id}`, { method: 'PATCH', body: JSON.stringify(patch) })
+      if (!runtimeQuietOutput) console.log(chalk.green('\n✓ Event updated\n'))
+    } catch (err) { handleError(err) }
+  })
+
+calendarCmd
+  .command('delete <id>')
+  .description('Delete a calendar event')
+  .action(async (id) => {
+    try {
+      await api(`/api/calendar-events/${id}`, { method: 'DELETE' })
+      if (!runtimeQuietOutput) console.log(chalk.green('\n✓ Event deleted\n'))
+    } catch (err) { handleError(err) }
+  })
+
+// ── workspace docs ─────────────────────────────────────────────────────────────
+
+program
+  .command('docs')
+  .description('List workspace docs')
+  .action(async () => {
+    try {
+      const list = await api('/api/docs').catch(() => [])
+      const arr = Array.isArray(list) ? list : []
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(arr, null, runtimeJsonOutput ? 2 : 0))
+      } else if (arr.length === 0) {
+        console.log(chalk.gray('\nNo docs.\n'))
+      } else {
+        console.log()
+        arr.forEach((d) => console.log(`  ${chalk.bold(d.title || 'Untitled')}  ${chalk.gray(`id: ${d.id?.slice(0, 8)}`)}`))
+        console.log()
+      }
+    } catch (err) { handleError(err) }
+  })
+
+const docCmd = program.command('doc').description('Workspace doc (create, show, update, delete)')
+
+docCmd
+  .command('create [title]')
+  .description('Create a workspace doc')
+  .option('--title <text>', 'Doc title (if not passed as argument)')
+  .option('--parent <id>', 'Parent doc id')
+  .option('--emoji <char>', 'Emoji')
+  .action(async function (titleArg) {
+    const opts = this.opts()
+    const title = (titleArg || opts.title || 'Untitled').trim()
+    try {
+      const body = { title }
+      if (opts.parent) body.parentId = opts.parent
+      if (opts.emoji) body.emoji = opts.emoji
+      const doc = await api('/api/docs', { method: 'POST', body: JSON.stringify(body) })
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(doc, null, runtimeJsonOutput ? 2 : 0))
+      } else {
+        console.log(chalk.green('\n✓ Doc created') + `  ${chalk.bold(doc.title)}  ${chalk.gray(doc.id?.slice(0, 8))}\n`)
+      }
+    } catch (err) { handleError(err) }
+  })
+
+docCmd
+  .command('show <id>')
+  .description('Show a workspace doc')
+  .action(async (id) => {
+    try {
+      const doc = await api(`/api/docs/${id}`)
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(doc, null, runtimeJsonOutput ? 2 : 0))
+      } else {
+        console.log()
+        console.log(chalk.bold(doc.title || 'Untitled'))
+        console.log(chalk.gray(`id: ${doc.id}`))
+        if (doc.content && typeof doc.content === 'object') {
+          const text = JSON.stringify(doc.content)
+          console.log(chalk.gray(text.slice(0, 200) + (text.length > 200 ? '…' : '')))
+        }
+        console.log()
+      }
+    } catch (err) { handleError(err) }
+  })
+
+docCmd
+  .command('update <id>')
+  .description('Update a workspace doc')
+  .option('--title <text>', 'Doc title')
+  .option('--content <json>', 'Content as JSON string')
+  .option('--emoji <char>', 'Emoji')
+  .option('--parent <id>', 'Parent doc id')
+  .action(async function (id) {
+    const opts = this.opts()
+    try {
+      const patch = {}
+      if (opts.title !== undefined) patch.title = opts.title
+      if (opts.content !== undefined) {
+        try {
+          patch.content = typeof opts.content === 'string' ? JSON.parse(opts.content) : opts.content
+        } catch (_) {
+          return fail('--content must be valid JSON')
+        }
+      }
+      if (opts.emoji !== undefined) patch.emoji = opts.emoji
+      if (opts.parent !== undefined) patch.parentId = opts.parent
+      if (Object.keys(patch).length === 0) return fail('Provide at least one option to update')
+      await api(`/api/docs/${id}`, { method: 'PATCH', body: JSON.stringify(patch) })
+      if (!runtimeQuietOutput) console.log(chalk.green('\n✓ Doc updated\n'))
+    } catch (err) { handleError(err) }
+  })
+
+docCmd
+  .command('delete <id>')
+  .description('Delete a workspace doc')
+  .action(async (id) => {
+    try {
+      await api(`/api/docs/${id}`, { method: 'DELETE' })
+      if (!runtimeQuietOutput) console.log(chalk.green('\n✓ Doc deleted\n'))
+    } catch (err) { handleError(err) }
+  })
+
+program
+  .command('folder create <name>')
+  .alias('mkdir')
+  .description('Create a folder in the workspace (Files tab)')
+  .action(async (name) => {
+    try {
+      const folder = await api('/api/folders', {
+        method: 'POST',
+        body: JSON.stringify({ name: String(name).trim() }),
+      })
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(folder, null, runtimeJsonOutput ? 2 : 0))
+      } else {
+        console.log(chalk.green('\n✓ Folder created') + `  ${chalk.bold(folder.name)}  ${chalk.gray(`(id: ${folder.id})\n`)}`)
+      }
+    } catch (err) { handleError(err) }
+  })
+
+program
+  .command('upload <path>')
+  .description('Upload a file to the workspace (optional: --folder <id>)')
+  .option('--folder <id>', 'Put the file in this folder id')
+  .action(async (pathArg, opts) => {
+    try {
+      await ensureAuth()
+      const filePath = resolve(pathArg)
+      if (!existsSync(filePath)) return fail(`File not found: ${filePath}`)
+      const form = new FormData()
+      form.append('file', createReadStream(filePath), { filename: basename(filePath) })
+      if (opts.folder) form.append('folderId', String(opts.folder).trim())
+      const headers = { ...authHeaders() }
+      delete headers['Content-Type']
+      const res = await fetch(`${getApiBase()}/api/files/upload`, {
+        method: 'POST',
+        headers: { ...headers, ...form.getHeaders() },
+        body: form,
+      })
+      const data = await res.json().catch(() => ({}))
+      if (!res.ok) throw new CliError(data.error ?? 'Upload failed', data.error ?? res.statusText)
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(data, null, runtimeJsonOutput ? 2 : 0))
+      } else {
+        console.log(chalk.green('\n✓ Uploaded') + `  ${chalk.bold(data.name)}  ${chalk.gray(`→ ${data.storageUrl ?? data.id}\n`)}`)
+      }
+    } catch (err) { handleError(err) }
+  })
+
 program
   .command('state')
   .description('Print full workspace state as JSON')
@@ -1115,4 +1733,39 @@ program
     console.log()
   })
 
+// ── shell completion ──────────────────────────────────────────────────────────
+
+const CLI_COMMANDS = [
+  'add', 'agent-token', 'agent-tokens', 'assign', 'assignee', 'assignees', 'board', 'boards',
+  'bucket', 'buckets', 'calendar', 'comment', 'complete', 'config', 'delete', 'doc', 'docs',
+  'do', 'doctor', 'files', 'folder', 'folders', 'invite', 'list', 'login', 'members', 'mkdir',
+  'move', 'open', 'reopen', 'requested', 'signup', 'state', 'update', 'upload', 'view', 'whoami',
+]
+
+program
+  .command('completion [shell]')
+  .description('Print shell completion script (bash or zsh). Add to your profile: wadah completion bash >> ~/.bashrc')
+  .action((shell) => {
+    const sh = (shell || process.env.SHELL || 'bash').toLowerCase()
+    if (sh.includes('zsh')) {
+      console.log(`# zsh completion for wadah
+_wadah() {
+  local cur
+  cur=\${words[CURRENT]}
+  reply=(${CLI_COMMANDS.join(' ')})
+}
+compctl -K _wadah wadah tm ow
+`)
+    } else {
+      console.log(`# bash completion for wadah
+_wadah_completion() {
+  local cur=\${COMP_WORDS[COMP_CWORD]}
+  local cmds="${CLI_COMMANDS.join(' ')}"
+  COMPREPLY=( $(compgen -W "$cmds" -- "$cur") )
+}
+complete -F _wadah_completion wadah tm ow
+`)
+    }
+  })
+
 program.parse()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-wadah",
-  "version": "1.0.6",
+  "version": "1.1.0",
   "description": "Open Wadah CLI — shared task board for humans and agents",
   "type": "module",
   "bin": {
@@ -9,13 +9,15 @@
     "tm": "cli.js"
   },
   "scripts": {
-    "start": "node cli.js"
+    "start": "node cli.js",
+    "test": "node --test test/cli.test.js"
   },
   "dependencies": {
     "@inquirer/prompts": "^8.3.0",
     "chalk": "^5.4.1",
     "commander": "^13.1.0",
     "conf": "^13.1.0",
+    "form-data": "^4.0.0",
     "node-fetch": "^3.3.2"
   }
 }

package/test/cli.test.js

@@ -0,0 +1,67 @@
+import { spawn } from 'node:child_process'
+import { test } from 'node:test'
+import { strict as assert } from 'node:assert'
+import { resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const cliPath = resolve(__dirname, '../cli.js')
+
+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: '' },
+    })
+    let stdout = ''
+    let stderr = ''
+    child.stdout?.on('data', (d) => { stdout += d })
+    child.stderr?.on('data', (d) => { stderr += d })
+    child.on('close', (code) => resolvePromise({ code, stdout, stderr }))
+    child.on('error', reject)
+  })
+}
+
+test('wadah --help exits 0 and prints usage', async () => {
+  const { code, stdout } = await runCli(['--help'])
+  assert.equal(code, 0)
+  assert.match(stdout, /Open Wadah|Usage|Commands/)
+})
+
+test('wadah --version exits 0 and prints version', async () => {
+  const { code, stdout } = await runCli(['--version'])
+  assert.equal(code, 0)
+  assert.match(stdout, /\d+\.\d+\.\d+/)
+})
+
+test('wadah (no args) prints help or exits', async () => {
+  const { code, stdout, stderr } = await runCli([])
+  assert(code === 0 || code === 1)
+  const out = stdout + stderr
+  assert.match(out, /Usage|Commands|Open Wadah/)
+})
+
+test('wadah open --help shows open command help', async () => {
+  const { code, stdout } = await runCli(['open', '--help'])
+  assert.equal(code, 0)
+  assert.match(stdout, /open|List/)
+})
+
+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
+  assert(code === 0 || code === 1)
+})
+
+test('wadah completion bash prints script', async () => {
+  const { code, stdout } = await runCli(['completion', 'bash'])
+  assert.equal(code, 0)
+  assert.match(stdout, /complete -F _wadah_completion/)
+  assert.match(stdout, /wadah tm ow/)
+})
+
+test('wadah completion zsh prints script', async () => {
+  const { code, stdout } = await runCli(['completion', 'zsh'])
+  assert.equal(code, 0)
+  assert.match(stdout, /compctl|_wadah/)
+})