asana-cli-skill 1.0.0 → 1.2.0

package/README.md

@@ -1,17 +1,35 @@
-# asana-cli
+<p align="center">
+  <img src="https://raw.githubusercontent.com/giacomeli/asana-cli-skill/main/promo-assets/asana-cli-skill-readme-hero-1280x640.png" alt="asana-cli banner: Asana task management from your terminal, a minimal Node.js CLI that powers the asana skill for Claude Code" width="100%">
+</p>
 
-Minimal CLI for Asana task management. Built to power the `asana` skill for [Claude Code](https://claude.com/claude-code), but works standalone in any terminal.
+# asana-cli — Asana task management from your terminal
+
+**Minimal CLI for Asana task management. Built to power the `asana` skill for [Claude Code](https://claude.com/claude-code), but works standalone in any terminal.**
+
+[![npm version](https://img.shields.io/npm/v/asana-cli-skill)](https://www.npmjs.com/package/asana-cli-skill)
+[![node](https://img.shields.io/node/v/asana-cli-skill)](https://nodejs.org)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+`asana-cli` is a Node.js command-line tool for the [Asana API](https://developers.asana.com/reference): read tasks, list and create subtasks, add comments with attachments, and complete work — all from the terminal. It is the infrastructure layer behind the `asana` Claude Code skill, which lets an AI coding agent pick up an Asana task, build an implementation plan from its subtasks, and report progress back as the work advances.
 
 The CLI is a thin infrastructure layer over the Asana REST API. All orchestration logic (reading a task, generating a plan, executing steps, reporting progress) lives in the skill — see [The Claude Code skill](#the-claude-code-skill).
 
 ## Installation
 
+Install from [npm](https://www.npmjs.com/package/asana-cli-skill):
+
 ```bash
 npm install -g asana-cli-skill
 ```
 
 This makes the `asana-cli` command available globally.
 
+Or run it without installing — useful in scripts, CI, and AI agent environments:
+
+```bash
+npx asana-cli-skill task <url-or-id>
+```
+
 Or from source:
 
 ```bash
@@ -119,12 +137,84 @@ asana-cli comment 5678 -m "Screenshots attached" -a screenshot1.png -a screensho
 
 ### `asana-cli create-subtask <parent-id> -n "name"`
 
-Creates a new subtask under a task.
+Creates a new subtask under a task. Optional: `--notes`, `--assignee`, `--due`.
 
 ```bash
-asana-cli create-subtask 5678 -n "Implement toast component"
+asana-cli create-subtask 5678 -n "Implement toast component" --assignee me --due 2026-10-20
 ```
 
+New subtasks appear at the top of the parent's list; use `move` to reorder them.
+
+### `asana-cli me`
+
+Shows the authenticated user and their workspaces (with IDs).
+
+### `asana-cli search <query>`
+
+Searches by name in the workspace (Asana typeahead, available on every plan). Tasks by default; `--type project|portfolio|tag|user` for other resources, `--limit` up to 100.
+
+```bash
+asana-cli search "payment gateway"
+asana-cli search "Marketing" --type project
+```
+
+### `asana-cli projects`
+
+Lists the active projects of the workspace. `--filter <text>` narrows by name, `--archived` lists archived ones.
+
+### `asana-cli project <url-or-id>`
+
+Reads a project: its open tasks grouped by section, in board order. `--section <text>` keeps only matching sections, `--completed` includes completed tasks.
+
+```bash
+asana-cli project https://app.asana.com/0/1234/list --section "Sprint"
+```
+
+### `asana-cli my-tasks`
+
+Lists the open tasks assigned to you, earliest due date first. `--completed` includes completed ones.
+
+### `asana-cli comments <url-or-id>`
+
+Lists the comments of a task (author, date, text). `--last <n>` keeps only the most recent ones.
+
+### `asana-cli create-task -n "name" --project <url-or-id>`
+
+Creates a task in a project, optionally in a section (`--section`, by name or ID), with `--notes`, `--assignee` (`me`, a user ID or an email) and `--due` (`YYYY-MM-DD`). With `--parent <task>` instead of `--project`, creates a subtask.
+
+```bash
+asana-cli create-task -n "Review contract" -p 1234 -s "Backlog" --assignee me --notes "Line 1
+Line 2"
+```
+
+### `asana-cli update <url-or-id>`
+
+Updates a task: `--name`, `--notes` (replace), `--append-notes` (add to the end), `--assignee` (`none` unassigns), `--due` (`none` clears), `--complete` or `--reopen`, and custom fields with `--field "Name=Value"` (repeatable). Enum options match by name ignoring case, accents and icons, so `--field "Priority=Urgent"` selects an option shown with a leading icon.
+
+```bash
+asana-cli update 5678 --due 2026-10-31 --append-notes "Blocked by the vendor"
+```
+
+### `asana-cli move <url-or-id>`
+
+Moves a task under another parent (`--parent`) or reorders it among its sibling subtasks (`--before <id>` or `--after <id>`).
+
+```bash
+asana-cli move 9013 --after 9012
+```
+
+### `asana-cli delete-comment <comment-id>`
+
+Deletes a comment. The ID is shown by `comments`. Only comments can be deleted, not system events.
+
+### `asana-cli edit-comment <comment-id> -m "text"`
+
+Replaces the text of a comment and keeps its inline images.
+
+## Workspace
+
+`search`, `projects`, `my-tasks` and `create-task` need a workspace. They use, in order: `--workspace <id>`, the `ASANA_WORKSPACE` variable, or your only workspace (if you belong to several, the CLI lists them and asks for one).
+
 ## Accepted URL formats
 
 The CLI accepts any of these:
@@ -134,6 +224,8 @@ The CLI accepts any of these:
 - `https://app.asana.com/1/<workspace-id>/project/<project-id>/task/<task-id>`
 - Plain numeric ID (e.g. `1234567890`)
 
+Project commands (`project`, `create-task --project`) accept `https://app.asana.com/0/<project-id>/list`, `https://app.asana.com/1/<workspace-id>/project/<project-id>[/...]` or a plain project ID.
+
 ## The Claude Code skill
 
 The `skills/asana/` directory contains a Claude Code skill that orchestrates a full development workflow on top of this CLI: it reads an Asana task, builds an implementation plan from its subtasks (creating them if missing), executes step by step, and updates Asana with comments, commit hashes, and status as the work progresses.
@@ -154,6 +246,10 @@ cp -r "$(npm root -g)/asana-cli-skill/skills/asana" ~/.claude/skills/asana
 
 Then share any Asana task link in a Claude Code conversation, or use `/asana`.
 
+### Other AI coding agents
+
+The CLI itself is agent-agnostic: any coding agent (Codex, Cursor, Copilot, Gemini CLI, opencode) that can run shell commands can use it to read Asana tasks and report progress — `npx asana-cli-skill task <url>` works with zero setup beyond the token. The repository ships [llms.txt](llms.txt) with an LLM-friendly overview and [AGENTS.md](AGENTS.md) with conventions for agents working on the codebase. Ports of the skill to other agent platforms are a welcome [contribution](CONTRIBUTING.md).
+
 ## Project structure
 
 ```
@@ -186,6 +282,10 @@ asana-cli-skill/
 - `dotenv` for configuration
 - Native `fetch` (Node 18+)
 
+## Contributing
+
+Contributions are very welcome — bug reports, feature ideas, docs improvements, and pull requests. See [CONTRIBUTING.md](CONTRIBUTING.md) for the guidelines, project conventions, and ideas for a first contribution. Questions and workflow feedback are welcome in [Discussions](https://github.com/giacomeli/asana-cli-skill/discussions).
+
 ## License
 
 [MIT](LICENSE)

package/bin/asana-cli.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 
 import { config } from 'dotenv';
-import { join } from 'path';
+import { join, dirname } from 'path';
 import { homedir } from 'os';
-import { existsSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
 import { Command } from 'commander';
 import { AsanaClient } from '../src/client.js';
 import { initCommand } from '../src/commands/init.js';
@@ -12,6 +13,17 @@ import { subtasksCommand } from '../src/commands/subtasks.js';
 import { completeCommand } from '../src/commands/complete.js';
 import { commentCommand } from '../src/commands/comment.js';
 import { createSubtaskCommand } from '../src/commands/create-subtask.js';
+import { meCommand } from '../src/commands/me.js';
+import { searchCommand } from '../src/commands/search.js';
+import { projectsCommand } from '../src/commands/projects.js';
+import { projectCommand } from '../src/commands/project.js';
+import { myTasksCommand } from '../src/commands/my-tasks.js';
+import { commentsCommand } from '../src/commands/comments.js';
+import { createTaskCommand } from '../src/commands/create-task.js';
+import { updateCommand } from '../src/commands/update.js';
+import { moveCommand } from '../src/commands/move.js';
+import { deleteCommentCommand } from '../src/commands/delete-comment.js';
+import { editCommentCommand } from '../src/commands/edit-comment.js';
 import { formatError } from '../src/formatter.js';
 
 // Load .env from the current directory first, then from ~/.asana-cli/
@@ -30,12 +42,16 @@ function collectMultiple(value, prev) {
     return prev.concat([value]);
 }
 
+const pkg = JSON.parse(
+    readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8')
+);
+
 const program = new Command();
 
 program
     .name('asana-cli')
     .description('Minimal CLI for Asana task management')
-    .version('1.0.0');
+    .version(pkg.version);
 
 program
     .command('init')
@@ -83,10 +99,128 @@ program
     .description('Create a subtask under a task')
     .argument('<parent-id>', 'Parent task ID')
     .requiredOption('-n, --name <name>', 'Subtask name')
+    .option('--notes <text>', 'Description')
+    .option('--assignee <who>', '"me", a user ID or an email')
+    .option('--due <date>', 'Due date (YYYY-MM-DD)')
     .action(async (parentId, options) => {
         await createSubtaskCommand(parentId, options, getClient());
     });
 
+program
+    .command('me')
+    .description('Show the authenticated user and their workspaces')
+    .action(async () => {
+        await meCommand(getClient());
+    });
+
+program
+    .command('search')
+    .description('Search tasks (or projects, tags, users) by name')
+    .argument('<query>', 'Text to search for')
+    .option('-t, --type <type>', 'task, project, portfolio, tag or user', 'task')
+    .option('-l, --limit <n>', 'Maximum number of results (1-100)', '20')
+    .option('-w, --workspace <id>', 'Workspace ID (defaults to ASANA_WORKSPACE or your only workspace)')
+    .action(async (query, options) => {
+        await searchCommand(query, options, getClient());
+    });
+
+program
+    .command('projects')
+    .description('List the projects of a workspace')
+    .option('-f, --filter <text>', 'Only projects whose name contains this text')
+    .option('--archived', 'List archived projects instead of active ones')
+    .option('-w, --workspace <id>', 'Workspace ID (defaults to ASANA_WORKSPACE or your only workspace)')
+    .action(async (options) => {
+        await projectsCommand(options, getClient());
+    });
+
+program
+    .command('project')
+    .description('Read a project: its open tasks grouped by section')
+    .argument('<url-or-id>', 'Asana project URL or ID')
+    .option('-s, --section <name>', 'Only sections whose name contains this text')
+    .option('--completed', 'Include completed tasks')
+    .action(async (urlOrId, options) => {
+        await projectCommand(urlOrId, options, getClient());
+    });
+
+program
+    .command('my-tasks')
+    .description('List the open tasks assigned to you, earliest due date first')
+    .option('--completed', 'Include completed tasks')
+    .option('-w, --workspace <id>', 'Workspace ID (defaults to ASANA_WORKSPACE or your only workspace)')
+    .action(async (options) => {
+        await myTasksCommand(options, getClient());
+    });
+
+program
+    .command('comments')
+    .description('List the comments of a task')
+    .argument('<url-or-id>', 'Asana URL or task ID')
+    .option('--last <n>', 'Only the last N comments')
+    .action(async (urlOrId, options) => {
+        await commentsCommand(urlOrId, options, getClient());
+    });
+
+program
+    .command('create-task')
+    .description('Create a task in a project (or a subtask with --parent)')
+    .requiredOption('-n, --name <name>', 'Task name')
+    .option('-p, --project <url-or-id>', 'Project URL or ID')
+    .option('-s, --section <name-or-id>', 'Section of the project')
+    .option('--parent <url-or-id>', 'Create as a subtask of this task')
+    .option('--notes <text>', 'Description')
+    .option('--assignee <who>', '"me", a user ID or an email')
+    .option('--due <date>', 'Due date (YYYY-MM-DD)')
+    .option('-w, --workspace <id>', 'Workspace ID (defaults to ASANA_WORKSPACE or your only workspace)')
+    .action(async (options) => {
+        await createTaskCommand(options, getClient());
+    });
+
+program
+    .command('update')
+    .description('Update a task: name, description, assignee, due date, completion')
+    .argument('<url-or-id>', 'Asana URL or task ID')
+    .option('-n, --name <name>', 'New name')
+    .option('--notes <text>', 'Replace the description')
+    .option('--append-notes <text>', 'Append to the description')
+    .option('--assignee <who>', '"me", a user ID, an email, or "none" to unassign')
+    .option('--due <date>', 'Due date (YYYY-MM-DD), or "none" to clear')
+    .option('--complete', 'Mark as completed (without a comment)')
+    .option('--reopen', 'Mark as not completed')
+    .option('--field <name=value>', 'Set a custom field, e.g. "Priority=High" (repeatable)', collectMultiple, [])
+    .action(async (urlOrId, options) => {
+        await updateCommand(urlOrId, options, getClient());
+    });
+
+program
+    .command('move')
+    .description('Make a task a subtask of another, or reorder it among its sibling subtasks')
+    .argument('<url-or-id>', 'Asana URL or task ID')
+    .option('--parent <url-or-id>', 'New parent task (defaults to the current parent)')
+    .option('--before <id>', 'Place it right before this sibling subtask')
+    .option('--after <id>', 'Place it right after this sibling subtask')
+    .action(async (urlOrId, options) => {
+        await moveCommand(urlOrId, options, getClient());
+    });
+
+program
+    .command('delete-comment')
+    .description('Delete a comment (story ID from the comments command)')
+    .argument('<comment-id>', 'Comment ID')
+    .action(async (commentId) => {
+        await deleteCommentCommand(commentId, getClient());
+    });
+
+program
+    .command('edit-comment')
+    .description('Replace the text of a comment, keeping its inline images')
+    .argument('<comment-id>', 'Comment ID')
+    .requiredOption('-m, --message <text>', 'New text')
+    .action(async (commentId, options) => {
+        await editCommentCommand(commentId, options, getClient());
+    });
+
 program.parseAsync().catch((err) => {
     console.error(formatError(err.message));
     process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "asana-cli-skill",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Minimal CLI for Asana task management, built to power a Claude Code skill",
   "type": "module",
   "license": "MIT",
@@ -22,17 +22,27 @@
     "skills"
   ],
   "scripts": {
-    "start": "node bin/asana-cli.js"
+    "start": "node bin/asana-cli.js",
+    "test": "node --test"
   },
   "engines": {
     "node": ">=18"
   },
   "keywords": [
     "asana",
+    "asana-api",
     "cli",
+    "command-line",
     "claude-code",
+    "claude-code-skill",
+    "agent-skill",
+    "ai-agents",
+    "coding-agent",
     "skill",
-    "task-management"
+    "task-management",
+    "automation",
+    "productivity",
+    "developer-tools"
   ],
   "dependencies": {
     "chalk": "^5.4.1",

package/skills/asana/SKILL.md

@@ -137,7 +137,18 @@ Quick reference for `asana-cli`:
 | `asana-cli complete <id> -m "msg"` | Comment + mark as done |
 | `asana-cli comment <id> -m "msg"` | Comment only |
 | `asana-cli comment <id> -m "msg" -a <path>` | Comment with attachment (image, file) |
-| `asana-cli create-subtask <parent-id> -n "name"` | Create a subtask |
+| `asana-cli create-subtask <parent-id> -n "name" [--notes/--assignee/--due]` | Create a subtask (appears at the top; reorder with `move`) |
+| `asana-cli search "<text>" [-t project]` | Find a task or project by name |
+| `asana-cli projects [-f text]` | List projects |
+| `asana-cli project <url-or-id> [-s section]` | Read a project's open tasks by section |
+| `asana-cli my-tasks` | Open tasks assigned to the user |
+| `asana-cli comments <url-or-id> [--last n]` | Read a task's comments |
+| `asana-cli create-task -n "name" -p <project> [-s section]` | Create a task |
+| `asana-cli update <id> [--name/--notes/--append-notes/--assignee/--due/--complete/--reopen/--field "Name=Value"]` | Update a task, including custom fields |
+| `asana-cli move <id> --after <sibling-id>` | Reorder subtasks or change the parent |
+| `asana-cli edit-comment <comment-id> -m "text"` | Fix a comment's text, keeping inline images |
+| `asana-cli delete-comment <comment-id>` | Delete a comment (ID from `comments`) |
+| `asana-cli me` | Authenticated user and workspaces |
 
 ## Important Rules
 

package/src/client.js

@@ -1,5 +1,7 @@
 import { basename } from 'path';
 
+import { normalizeLabel } from './utils.js';
+
 const BASE_URL = 'https://app.asana.com/api/1.0';
 
 export class AsanaClient {
@@ -34,12 +36,139 @@ export class AsanaClient {
         return json.data;
     }
 
+    // Follows Asana's offset pagination and returns every item of a collection.
+    async requestAll(path) {
+        const items = [];
+        const separator = path.includes('?') ? '&' : '?';
+        let offset = null;
+        do {
+            const pagePath = `${path}${separator}limit=100${offset ? `&offset=${offset}` : ''}`;
+            const response = await fetch(`${BASE_URL}${pagePath}`, {
+                headers: { 'Authorization': `Bearer ${this.token}` },
+            });
+            if (!response.ok) {
+                const body = await response.json().catch(() => ({}));
+                const msg = body?.errors?.[0]?.message || response.statusText;
+                throw new Error(`Asana API error (${response.status}): ${msg}`);
+            }
+            const json = await response.json();
+            items.push(...json.data);
+            offset = json.next_page?.offset || null;
+        } while (offset);
+        return items;
+    }
+
+    async getMe() {
+        return this.request('/users/me?opt_fields=name,email,workspaces.name');
+    }
+
+    // Workspace used by search, projects and my-tasks: --workspace, then ASANA_WORKSPACE,
+    // then the only workspace of the user.
+    async resolveWorkspace(explicit) {
+        const chosen = explicit || process.env.ASANA_WORKSPACE;
+        if (chosen) return chosen;
+
+        const me = await this.getMe();
+        const workspaces = me.workspaces || [];
+        if (workspaces.length === 1) return workspaces[0].gid;
+
+        const list = workspaces.map((w) => `${w.name} (${w.gid})`).join(', ');
+        throw new Error(
+            `You belong to ${workspaces.length} workspaces: ${list}.\n` +
+            'Pass --workspace <id> or set ASANA_WORKSPACE.'
+        );
+    }
+
     async getTask(taskId) {
         return this.request(
-            `/tasks/${taskId}?opt_fields=name,notes,completed,assignee.name,memberships.project.name,custom_fields.name,custom_fields.enum_value,custom_fields.enum_options`
+            `/tasks/${taskId}?opt_fields=name,notes,completed,completed_at,due_on,created_at,permalink_url,parent.name,assignee.name,memberships.project.name,memberships.section.name,custom_fields.name,custom_fields.resource_subtype,custom_fields.enum_value,custom_fields.enum_options,custom_fields.display_value`
+        );
+    }
+
+    async getComments(taskId) {
+        const stories = await this.requestAll(
+            `/tasks/${taskId}/stories?opt_fields=type,resource_subtype,text,created_at,created_by.name`
+        );
+        return stories.filter((s) => s.type === 'comment');
+    }
+
+    async search(workspaceId, query, { type = 'task', count = 20 } = {}) {
+        const fields = {
+            task: 'name,completed,assignee.name,memberships.project.name,parent.name',
+            project: 'name,archived,owner.name',
+        }[type] || 'name';
+        const params = new URLSearchParams({
+            resource_type: type,
+            query,
+            count: String(count),
+            opt_fields: fields,
+        });
+        return this.request(`/workspaces/${workspaceId}/typeahead?${params}`);
+    }
+
+    async getProjects(workspaceId, { archived = false } = {}) {
+        return this.requestAll(
+            `/projects?workspace=${workspaceId}&archived=${archived}&opt_fields=name,archived,owner.name`
+        );
+    }
+
+    async getProject(projectId) {
+        return this.request(
+            `/projects/${projectId}?opt_fields=name,notes,archived,owner.name,permalink_url,workspace.name`
+        );
+    }
+
+    async getSections(projectId) {
+        return this.requestAll(`/projects/${projectId}/sections?opt_fields=name`);
+    }
+
+    // Without completed, only open tasks (completed_since=now is Asana's way to say so).
+    async getProjectTasks(projectId, { completed = false } = {}) {
+        const since = completed ? '' : '&completed_since=now';
+        return this.requestAll(
+            `/projects/${projectId}/tasks?opt_fields=name,completed,due_on,assignee.name,memberships.project.gid,memberships.section.name${since}`
+        );
+    }
+
+    async getMyTasks(workspaceId, { completed = false } = {}) {
+        const since = completed ? '' : '&completed_since=now';
+        return this.requestAll(
+            `/tasks?assignee=me&workspace=${workspaceId}&opt_fields=name,completed,due_on,memberships.project.name${since}`
         );
     }
 
+    async createTask(data) {
+        return this.request('/tasks', {
+            method: 'POST',
+            body: JSON.stringify({ data }),
+        });
+    }
+
+    async updateTask(taskId, data) {
+        return this.request(`/tasks/${taskId}`, {
+            method: 'PUT',
+            body: JSON.stringify({ data }),
+        });
+    }
+
+    // Moves a task under a parent (or reorders it among its siblings with insert_before/insert_after).
+    async setParent(taskId, parentId, { insertBefore, insertAfter } = {}) {
+        const data = { parent: parentId };
+        if (insertBefore) data.insert_before = insertBefore;
+        if (insertAfter) data.insert_after = insertAfter;
+        return this.request(`/tasks/${taskId}/setParent`, {
+            method: 'POST',
+            body: JSON.stringify({ data }),
+        });
+    }
+
+    async addTaskToSection(sectionId, taskId) {
+        return this.request(`/sections/${sectionId}/addTask`, {
+            method: 'POST',
+            body: JSON.stringify({ data: { task: taskId } }),
+        });
+    }
+
     async getSubtasks(taskId) {
         return this.request(
             `/tasks/${taskId}/subtasks?opt_fields=name,completed`
@@ -61,6 +190,21 @@ export class AsanaClient {
         });
     }
 
+    async getStory(storyId) {
+        return this.request(`/stories/${storyId}?opt_fields=type,text,html_text,target.name,created_by.name`);
+    }
+
+    async updateStoryHtml(storyId, htmlText) {
+        return this.request(`/stories/${storyId}`, {
+            method: 'PUT',
+            body: JSON.stringify({ data: { html_text: htmlText } }),
+        });
+    }
+
+    async deleteStory(storyId) {
+        return this.request(`/stories/${storyId}`, { method: 'DELETE' });
+    }
+
     async addHtmlComment(taskId, htmlText) {
         return this.request(`/tasks/${taskId}/stories`, {
             method: 'POST',
@@ -69,9 +213,16 @@ export class AsanaClient {
     }
 
     async setCustomFieldEnum(taskId, fieldName, optionName) {
+        return this.setCustomField(taskId, fieldName, optionName);
+    }
+
+    // Sets a custom field by name. Enum options match by name ignoring case, accents, spacing and
+    // decorations (an option shown as "[icon] Urgente" matches "urgente"); text and number fields
+    // take the value as is.
+    async setCustomField(taskId, fieldName, value) {
         const task = await this.getTask(taskId);
         const field = task.custom_fields?.find(
-            (f) => f.name.toLowerCase() === fieldName.toLowerCase()
+            (f) => normalizeLabel(f.name) === normalizeLabel(fieldName)
         );
         if (!field) {
             const available = task.custom_fields?.map((f) => f.name).join(', ') || 'none';
@@ -80,20 +231,31 @@ export class AsanaClient {
             );
         }
 
-        const option = field.enum_options?.find(
-            (o) => o.name.toLowerCase() === optionName.toLowerCase()
-        );
-        if (!option) {
-            const available = field.enum_options?.map((o) => o.name).join(', ') || 'none';
-            throw new Error(
-                `Option "${optionName}" not found in field "${fieldName}". Available options: ${available}`
+        let fieldValue;
+        if (field.resource_subtype === 'number') {
+            fieldValue = Number(value);
+            if (Number.isNaN(fieldValue)) {
+                throw new Error(`Field "${field.name}" is a number; got "${value}"`);
+            }
+        } else if (field.resource_subtype === 'text') {
+            fieldValue = value;
+        } else {
+            const option = field.enum_options?.find(
+                (o) => normalizeLabel(o.name) === normalizeLabel(value)
             );
+            if (!option) {
+                const available = field.enum_options?.map((o) => o.name).join(', ') || 'none';
+                throw new Error(
+                    `Option "${value}" not found in field "${field.name}". Available options: ${available}`
+                );
+            }
+            fieldValue = option.gid;
         }
 
         return this.request(`/tasks/${taskId}`, {
             method: 'PUT',
             body: JSON.stringify({
-                data: { custom_fields: { [field.gid]: option.gid } },
+                data: { custom_fields: { [field.gid]: fieldValue } },
             }),
         });
     }
@@ -139,10 +301,10 @@ export class AsanaClient {
         return json.data;
     }
 
-    async createSubtask(parentId, name) {
+    async createSubtask(parentId, name, extra = {}) {
         return this.request(`/tasks/${parentId}/subtasks`, {
             method: 'POST',
-            body: JSON.stringify({ data: { name } }),
+            body: JSON.stringify({ data: { name, ...extra } }),
         });
     }
 }

package/src/commands/comments.js

@@ -0,0 +1,17 @@
+import { parseTaskId } from '../utils.js';
+import { formatComments } from '../formatter.js';
+
+export async function commentsCommand(urlOrId, options, client) {
+    const taskId = parseTaskId(urlOrId);
+    let comments = await client.getComments(taskId);
+
+    if (options.last) {
+        const last = Number(options.last);
+        if (!Number.isInteger(last) || last < 1) {
+            throw new Error('--last must be a positive integer');
+        }
+        comments = comments.slice(-last);
+    }
+
+    console.log(formatComments(comments));
+}

package/src/commands/create-subtask.js

@@ -1,3 +1,4 @@
+import { buildTaskFields } from '../utils.js';
 import { formatSuccess } from '../formatter.js';
 
 export async function createSubtaskCommand(parentId, options, client) {
@@ -7,7 +8,8 @@ export async function createSubtaskCommand(parentId, options, client) {
         process.exit(1);
     }
 
-    const subtask = await client.createSubtask(parentId, name);
+    const { name: _name, ...extra } = buildTaskFields(options);
+    const subtask = await client.createSubtask(parentId, name, extra);
     const parent = await client.getTask(parentId);
 
     console.log(formatSuccess(`Subtask created: "${name}" (id: ${subtask.gid})\n   Parent: ${parent.name}`));

package/src/commands/create-task.js

@@ -0,0 +1,41 @@
+import { parseProjectId, parseTaskId, buildTaskFields } from '../utils.js';
+import { formatSuccess } from '../formatter.js';
+
+export async function createTaskCommand(options, client) {
+    if (!options.project && !options.parent) {
+        throw new Error('Pass --project (or --parent to create a subtask)');
+    }
+    if (options.section && !options.project) {
+        throw new Error('--section requires --project');
+    }
+
+    const data = buildTaskFields(options);
+    let task;
+
+    if (options.parent) {
+        task = await client.createSubtask(parseTaskId(options.parent), data.name, data);
+    } else {
+        const projectId = parseProjectId(options.project);
+        const workspace = await client.resolveWorkspace(options.workspace);
+        task = await client.createTask({ ...data, projects: [projectId], workspace });
+
+        if (options.section) {
+            const sections = await client.getSections(projectId);
+            const needle = options.section.toLowerCase();
+            const section = sections.find((s) => s.gid === options.section)
+                || sections.find((s) => s.name.toLowerCase() === needle)
+                || sections.find((s) => s.name.toLowerCase().includes(needle));
+            if (!section) {
+                const available = sections.map((s) => s.name).join(', ') || 'none';
+                throw new Error(`Task created (id: ${task.gid}), but no section matches "${options.section}". Sections: ${available}`);
+            }
+            await client.addTaskToSection(section.gid, task.gid);
+        }
+    }
+
+    const created = await client.getTask(task.gid);
+    const where = created.parent?.name
+        ? `Parent: ${created.parent.name}`
+        : `Project: ${created.memberships?.[0]?.project?.name || '-'}${created.memberships?.[0]?.section?.name ? ` / ${created.memberships[0].section.name}` : ''}`;
+    console.log(formatSuccess(`Task created: "${created.name}" (id: ${created.gid})\n   ${where}\n   URL: ${created.permalink_url}`));
+}

package/src/commands/delete-comment.js

@@ -0,0 +1,16 @@
+import { formatSuccess } from '../formatter.js';
+
+export async function deleteCommentCommand(commentId, client) {
+    if (!/^\d+$/.test(commentId)) {
+        throw new Error(`Invalid comment ID: ${commentId}`);
+    }
+
+    // Only comments: other stories (system events such as "completed this task") are not deletable.
+    const story = await client.getStory(commentId);
+    if (story.type !== 'comment') {
+        throw new Error(`Story ${commentId} is not a comment (type: ${story.type})`);
+    }
+
+    await client.deleteStory(commentId);
+    console.log(formatSuccess(`Comment deleted from "${story.target?.name || '-'}"\n   Text was: "${story.text}"`));
+}

package/src/commands/edit-comment.js

@@ -0,0 +1,29 @@
+import { unescapeNewlines } from '../utils.js';
+import { formatSuccess } from '../formatter.js';
+
+function escapeHtml(text) {
+    return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+export async function editCommentCommand(commentId, options, client) {
+    if (!/^\d+$/.test(commentId)) {
+        throw new Error(`Invalid comment ID: ${commentId}`);
+    }
+    if (!options.message) {
+        throw new Error('--message is required');
+    }
+
+    const story = await client.getStory(commentId);
+    if (story.type !== 'comment') {
+        throw new Error(`Story ${commentId} is not a comment (type: ${story.type})`);
+    }
+
+    // Inline images live in the HTML as <img data-asana-gid="..."/>; keep them after the new text.
+    const images = (story.html_text || '').match(/<img [^>]*data-asana-gid="\d+"[^>]*\/?>/g) || [];
+    const text = escapeHtml(unescapeNewlines(options.message));
+    const html = `<body>${text}${images.length > 0 ? '\n' + images.join('\n') : ''}</body>`;
+
+    await client.updateStoryHtml(commentId, html);
+    const kept = images.length > 0 ? `\n   Inline images kept: ${images.length}` : '';
+    console.log(formatSuccess(`Comment edited on "${story.target?.name || '-'}"${kept}`));
+}

package/src/commands/me.js

@@ -0,0 +1,6 @@
+import { formatMe } from '../formatter.js';
+
+export async function meCommand(client) {
+    const me = await client.getMe();
+    console.log(formatMe(me));
+}

package/src/commands/move.js

@@ -0,0 +1,28 @@
+import { parseTaskId } from '../utils.js';
+import { formatSuccess } from '../formatter.js';
+
+export async function moveCommand(urlOrId, options, client) {
+    const taskId = parseTaskId(urlOrId);
+
+    if (options.before && options.after) {
+        throw new Error('Use either --before or --after, not both');
+    }
+
+    let parentId = options.parent ? parseTaskId(options.parent) : null;
+    if (!parentId) {
+        const task = await client.getTask(taskId);
+        if (!task.parent) {
+            throw new Error('The task has no parent. Pass --parent to make it a subtask');
+        }
+        parentId = task.parent.gid;
+    }
+
+    await client.setParent(taskId, parentId, {
+        insertBefore: options.before && parseTaskId(options.before),
+        insertAfter: options.after && parseTaskId(options.after),
+    });
+
+    const [task, parent] = await Promise.all([client.getTask(taskId), client.getTask(parentId)]);
+    const position = options.before ? ` before ${options.before}` : options.after ? ` after ${options.after}` : '';
+    console.log(formatSuccess(`Task "${task.name}" moved under "${parent.name}"${position}`));
+}

package/src/commands/my-tasks.js

@@ -0,0 +1,7 @@
+import { formatMyTasks } from '../formatter.js';
+
+export async function myTasksCommand(options, client) {
+    const workspace = await client.resolveWorkspace(options.workspace);
+    const tasks = await client.getMyTasks(workspace, { completed: Boolean(options.completed) });
+    console.log(formatMyTasks(tasks));
+}

package/src/commands/project.js

@@ -0,0 +1,28 @@
+import { parseProjectId } from '../utils.js';
+import { formatProject } from '../formatter.js';
+
+export async function projectCommand(urlOrId, options, client) {
+    const projectId = parseProjectId(urlOrId);
+    const [project, sections, tasks] = await Promise.all([
+        client.getProject(projectId),
+        client.getSections(projectId),
+        client.getProjectTasks(projectId, { completed: Boolean(options.completed) }),
+    ]);
+
+    let shownSections = sections;
+    if (options.section) {
+        const needle = options.section.toLowerCase();
+        shownSections = sections.filter((s) => s.name.toLowerCase().includes(needle));
+        if (shownSections.length === 0) {
+            const available = sections.map((s) => s.name).join(', ') || 'none';
+            throw new Error(`No section matches "${options.section}". Sections: ${available}`);
+        }
+    }
+
+    const names = new Set(shownSections.map((s) => s.name));
+    const shownTasks = options.section
+        ? tasks.filter((t) => t.memberships?.some((m) => m.project?.gid === projectId && names.has(m.section?.name)))
+        : tasks;
+
+    console.log(formatProject(project, shownSections, shownTasks));
+}

package/src/commands/projects.js

@@ -0,0 +1,13 @@
+import { formatProjects } from '../formatter.js';
+
+export async function projectsCommand(options, client) {
+    const workspace = await client.resolveWorkspace(options.workspace);
+    let projects = await client.getProjects(workspace, { archived: Boolean(options.archived) });
+
+    if (options.filter) {
+        const needle = options.filter.toLowerCase();
+        projects = projects.filter((p) => p.name.toLowerCase().includes(needle));
+    }
+
+    console.log(formatProjects(projects));
+}

package/src/commands/search.js

@@ -0,0 +1,19 @@
+import { formatSearchResults } from '../formatter.js';
+
+const TYPES = ['task', 'project', 'portfolio', 'tag', 'user'];
+
+export async function searchCommand(query, options, client) {
+    const type = options.type || 'task';
+    if (!TYPES.includes(type)) {
+        throw new Error(`Invalid --type "${type}". Use one of: ${TYPES.join(', ')}`);
+    }
+
+    const count = Number(options.limit || 20);
+    if (!Number.isInteger(count) || count < 1 || count > 100) {
+        throw new Error('--limit must be an integer between 1 and 100');
+    }
+
+    const workspace = await client.resolveWorkspace(options.workspace);
+    const results = await client.search(workspace, query, { type, count });
+    console.log(formatSearchResults(results, type));
+}

package/src/commands/update.js

@@ -0,0 +1,40 @@
+import { parseTaskId, buildTaskFields, unescapeNewlines, parseFieldAssignments } from '../utils.js';
+import { formatSuccess } from '../formatter.js';
+
+export async function updateCommand(urlOrId, options, client) {
+    const taskId = parseTaskId(urlOrId);
+
+    if (options.notes !== undefined && options.appendNotes !== undefined) {
+        throw new Error('Use either --notes or --append-notes, not both');
+    }
+    if (options.complete && options.reopen) {
+        throw new Error('Use either --complete or --reopen, not both');
+    }
+
+    const data = buildTaskFields(options);
+
+    if (options.appendNotes !== undefined) {
+        const current = await client.getTask(taskId);
+        const addition = unescapeNewlines(options.appendNotes);
+        data.notes = current.notes ? `${current.notes}\n\n${addition}` : addition;
+    }
+    if (options.complete) data.completed = true;
+    if (options.reopen) data.completed = false;
+
+    const fields = parseFieldAssignments(options.field || []);
+
+    if (Object.keys(data).length === 0 && fields.length === 0) {
+        throw new Error('Nothing to update. Pass at least one of --name, --notes, --append-notes, --assignee, --due, --complete, --reopen, --field');
+    }
+
+    if (Object.keys(data).length > 0) {
+        await client.updateTask(taskId, data);
+    }
+    for (const { name, value } of fields) {
+        await client.setCustomField(taskId, name, value);
+    }
+
+    const task = await client.getTask(taskId);
+    const changed = [...Object.keys(data), ...fields.map((f) => f.name)];
+    console.log(formatSuccess(`Task "${task.name}" updated: ${changed.join(', ')}`));
+}

package/src/formatter.js

@@ -16,8 +16,30 @@ export function formatTask(task, subtasks) {
         lines.push(`   Assignee: ${task.assignee.name}`);
     }
 
+    const section = task.memberships?.[0]?.section?.name;
+    if (section) {
+        lines.push(`   Section: ${section}`);
+    }
+
+    if (task.parent?.name) {
+        lines.push(`   Parent: ${task.parent.name} (id: ${task.parent.gid})`);
+    }
+
+    if (task.due_on) {
+        lines.push(`   Due: ${task.due_on}`);
+    }
+
+    const filledFields = (task.custom_fields || []).filter((f) => f.display_value);
+    for (const field of filledFields) {
+        lines.push(`   ${field.name}: ${field.display_value}`);
+    }
+
     lines.push(`   ID: ${task.gid}`);
 
+    if (task.permalink_url) {
+        lines.push(`   URL: ${task.permalink_url}`);
+    }
+
     if (task.notes) {
         lines.push('');
         lines.push('   Description:');
@@ -62,6 +84,136 @@ export function formatSubtasks(subtasks) {
     return lines.join('\n');
 }
 
+function taskLine(task, extra = []) {
+    const check = task.completed ? chalk.green('x') : ' ';
+    const name = task.completed ? chalk.dim(task.name) : task.name;
+    const details = extra.filter(Boolean);
+    const suffix = details.length > 0 ? chalk.dim(` - ${details.join(' - ')}`) : '';
+    return `   [${check}] ${name} (id: ${task.gid})${suffix}`;
+}
+
+export function formatMe(me) {
+    const lines = ['', chalk.bold(`User: ${me.name}`), `   Email: ${me.email}`, `   ID: ${me.gid}`, '', '   Workspaces:'];
+    for (const ws of me.workspaces || []) {
+        lines.push(`   - ${ws.name} (id: ${ws.gid})`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+
+export function formatSearchResults(results, type) {
+    const lines = [''];
+    if (results.length === 0) {
+        lines.push(chalk.dim('   No results.'), '');
+        return lines.join('\n');
+    }
+
+    lines.push(`   Results (${results.length}):`);
+    for (const item of results) {
+        if (type === 'task') {
+            lines.push(taskLine(item, [
+                item.memberships?.[0]?.project?.name,
+                item.parent?.name && `subtask of: ${item.parent.name}`,
+                item.assignee?.name,
+            ]));
+        } else if (type === 'project') {
+            const archived = item.archived ? chalk.dim(' (archived)') : '';
+            lines.push(`   - ${item.name} (id: ${item.gid})${archived}`);
+        } else {
+            lines.push(`   - ${item.name} (id: ${item.gid})`);
+        }
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+
+export function formatProjects(projects) {
+    const lines = [''];
+    if (projects.length === 0) {
+        lines.push(chalk.dim('   No projects found.'), '');
+        return lines.join('\n');
+    }
+    lines.push(`   Projects (${projects.length}):`);
+    for (const p of projects) {
+        const owner = p.owner?.name ? chalk.dim(` - ${p.owner.name}`) : '';
+        const archived = p.archived ? chalk.dim(' (archived)') : '';
+        lines.push(`   - ${p.name} (id: ${p.gid})${owner}${archived}`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+
+// Tasks grouped by section, in the order the sections appear in the project.
+export function formatProject(project, sections, tasks) {
+    const lines = ['', chalk.bold(`Project: ${project.name}`), `   ID: ${project.gid}`];
+    if (project.owner?.name) lines.push(`   Owner: ${project.owner.name}`);
+    if (project.permalink_url) lines.push(`   URL: ${project.permalink_url}`);
+
+    const bySection = new Map(sections.map((s) => [s.name, []]));
+    const noSection = [];
+    for (const task of tasks) {
+        const membership = task.memberships?.find((m) => m.project?.gid === project.gid) || task.memberships?.[0];
+        const sectionName = membership?.section?.name;
+        if (sectionName && bySection.has(sectionName)) {
+            bySection.get(sectionName).push(task);
+        } else {
+            noSection.push(task);
+        }
+    }
+    if (noSection.length > 0) bySection.set('(no section)', noSection);
+
+    for (const [name, sectionTasks] of bySection) {
+        if (sectionTasks.length === 0) continue;
+        lines.push('', `   ${chalk.bold(name)} (${sectionTasks.length})`);
+        for (const task of sectionTasks) {
+            lines.push(taskLine(task, [task.assignee?.name, task.due_on && `due ${task.due_on}`]));
+        }
+    }
+
+    if (tasks.length === 0) lines.push('', chalk.dim('   No tasks found.'));
+    lines.push('');
+    return lines.join('\n');
+}
+
+export function formatMyTasks(tasks) {
+    const lines = [''];
+    if (tasks.length === 0) {
+        lines.push(chalk.dim('   No tasks assigned to you.'), '');
+        return lines.join('\n');
+    }
+    // Tasks with a due date first, earliest first; then the rest in Asana's order.
+    const sorted = [...tasks].sort((a, b) => {
+        if (a.due_on && b.due_on) return a.due_on.localeCompare(b.due_on);
+        if (a.due_on) return -1;
+        if (b.due_on) return 1;
+        return 0;
+    });
+    lines.push(`   My tasks (${tasks.length}):`);
+    for (const task of sorted) {
+        lines.push(taskLine(task, [task.memberships?.[0]?.project?.name, task.due_on && `due ${task.due_on}`]));
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+
+export function formatComments(comments) {
+    const lines = [''];
+    if (comments.length === 0) {
+        lines.push(chalk.dim('   No comments.'), '');
+        return lines.join('\n');
+    }
+    lines.push(`   Comments (${comments.length}):`);
+    for (const c of comments) {
+        const when = c.created_at ? c.created_at.slice(0, 16).replace('T', ' ') : '';
+        lines.push('', `   ${chalk.bold(c.created_by?.name || 'Unknown')} ${chalk.dim(`${when} UTC (id: ${c.gid})`)}`);
+        for (const line of (c.text || '').split('\n')) {
+            lines.push(`   ${line}`);
+        }
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+
 export function formatSuccess(message) {
     return `\n${chalk.green('OK')} ${message}\n`;
 }

package/src/utils.js

@@ -39,3 +39,100 @@ export function parseTaskId(input) {
         throw err;
     }
 }
+
+/**
+ * Extracts the project ID from an Asana URL, or returns the ID as-is.
+ *
+ * Supported formats:
+ * - https://app.asana.com/0/<project-id>/list (or /board, /<task-id>, ...)
+ * - https://app.asana.com/1/<workspace-id>/project/<project-id>[/...]
+ * - Plain numeric ID
+ */
+export function parseProjectId(input) {
+    if (/^\d+$/.test(input)) {
+        return input;
+    }
+
+    let url;
+    try {
+        url = new URL(input);
+    } catch {
+        throw new Error(`Invalid input (not a URL or numeric ID): ${input}`);
+    }
+    if (!url.hostname.includes('asana.com')) {
+        throw new Error(`URL is not an Asana URL: ${input}`);
+    }
+
+    const parts = url.pathname.split('/').filter(Boolean);
+
+    const projectIndex = parts.indexOf('project');
+    if (projectIndex !== -1 && /^\d+$/.test(parts[projectIndex + 1] || '')) {
+        return parts[projectIndex + 1];
+    }
+
+    if (parts[0] === '0' && /^\d+$/.test(parts[1] || '')) {
+        return parts[1];
+    }
+
+    throw new Error(`Could not extract a project ID from: ${input}`);
+}
+
+/**
+ * Converts the literal "\n" typed in a shell argument into a real line break.
+ */
+export function unescapeNewlines(text) {
+    return text.replace(/\\n/g, '\n');
+}
+
+/**
+ * Builds the Asana task fields shared by create-task, create-subtask and update
+ * from the command options. Only the options that were passed are included.
+ */
+export function buildTaskFields(options) {
+    const data = {};
+
+    if (options.name !== undefined) data.name = options.name;
+    if (options.notes !== undefined) data.notes = unescapeNewlines(options.notes);
+
+    if (options.assignee !== undefined) {
+        data.assignee = options.assignee === 'none' ? null : options.assignee;
+    }
+
+    if (options.due !== undefined) {
+        if (options.due === 'none') {
+            data.due_on = null;
+        } else if (/^\d{4}-\d{2}-\d{2}$/.test(options.due)) {
+            data.due_on = options.due;
+        } else {
+            throw new Error(`Invalid --due "${options.due}": use YYYY-MM-DD or "none"`);
+        }
+    }
+
+    return data;
+}
+
+/**
+ * Normalizes a field or option label for matching: lowercase, no accents, and only letters,
+ * digits and single spaces (icons and punctuation around the label are ignored).
+ */
+export function normalizeLabel(label) {
+    return String(label)
+        .normalize('NFD')
+        .replace(/\p{Diacritic}/gu, '')
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, ' ')
+        .trim();
+}
+
+/**
+ * Parses "Name=Value" pairs from repeated --field options.
+ */
+export function parseFieldAssignments(pairs) {
+    return pairs.map((pair) => {
+        const index = pair.indexOf('=');
+        if (index <= 0 || index === pair.length - 1) {
+            throw new Error(`Invalid --field "${pair}": use "Field name=Value"`);
+        }
+        return { name: pair.slice(0, index).trim(), value: pair.slice(index + 1).trim() };
+    });
+}