asana-cli-skill 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Juliano Giacomeli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# asana-cli
+
+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.
+
+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
+
+```bash
+npm install -g asana-cli-skill
+```
+
+This makes the `asana-cli` command available globally.
+
+Or from source:
+
+```bash
+git clone https://github.com/giacomeli/asana-cli-skill.git
+cd asana-cli-skill
+npm install
+npm link
+```
+
+Requires Node.js 18+ (native `fetch`).
+
+## Configuration
+
+### Option 1: Interactive command
+
+```bash
+asana-cli init
+```
+
+Prompts for your Personal Access Token and saves it to `~/.asana-cli/.env`.
+
+### Option 2: Manual
+
+Create `~/.asana-cli/.env` (or a `.env` in your working directory):
+
+```
+ASANA_TOKEN=your-token-here
+```
+
+You can generate a token at: Asana > Settings > Apps > Developer > Personal Access Tokens.
+
+### Optional: progress custom field
+
+By default, `asana-cli complete` marks the task as completed (the Asana checkbox). If your workspace tracks progress with an enum custom field instead (common on board-style projects), configure it:
+
+```
+ASANA_PROGRESS_FIELD=Task Progress
+ASANA_PROGRESS_VALUE=Done
+```
+
+With these set, `complete` sets the custom field to that value instead of checking the task off. Use `--close` to also check it off.
+
+## Commands
+
+### `asana-cli task <url-or-id>`
+
+Reads a full task: title, description, project, assignee, and subtasks.
+
+```bash
+asana-cli task https://app.asana.com/0/1234/5678
+```
+
+Output:
+
+```
+Task: Implement notification system
+   Status: In progress
+   Project: Sprint 42
+   Assignee: Juliano
+   ID: 5678
+
+   Description:
+   Build a push notification system...
+
+   Subtasks (2):
+   [ ] Create schema (id: 9012)
+   [x] Define endpoints (id: 9013)
+```
+
+### `asana-cli subtasks <url-or-id>`
+
+Lists only the subtasks of a task.
+
+```bash
+asana-cli subtasks 5678
+```
+
+### `asana-cli complete <task-id> -m "message"`
+
+Adds a comment and marks the task as done (completed checkbox, or the configured progress custom field).
+
+```bash
+asana-cli complete 9012 -m "Done\n\nSchema created with Zod validation\n\nCommit: abc1234\nBranch: feature/notifications"
+```
+
+Literal `\n` sequences are converted to real line breaks automatically.
+
+Flags:
+
+- `--close` — also mark the task as completed (checkbox) and complete any pending subtasks. Useful when a progress custom field is configured and you want both.
+
+### `asana-cli comment <task-id> -m "message"`
+
+Adds a comment without changing the task status.
+
+```bash
+asana-cli comment 5678 -m "Task completed\n\nCommit summary..."
+```
+
+Attach files (repeatable, images are embedded inline):
+
+```bash
+asana-cli comment 5678 -m "Screenshots attached" -a screenshot1.png -a screenshot2.png
+```
+
+### `asana-cli create-subtask <parent-id> -n "name"`
+
+Creates a new subtask under a task.
+
+```bash
+asana-cli create-subtask 5678 -n "Implement toast component"
+```
+
+## Accepted URL formats
+
+The CLI accepts any of these:
+
+- `https://app.asana.com/0/<project-id>/<task-id>`
+- `https://app.asana.com/0/<project-id>/<task-id>/f`
+- `https://app.asana.com/1/<workspace-id>/project/<project-id>/task/<task-id>`
+- Plain numeric ID (e.g. `1234567890`)
+
+## 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.
+
+To install it, copy (or symlink) the skill into your Claude Code skills directory.
+
+From a cloned repo:
+
+```bash
+cp -r skills/asana ~/.claude/skills/asana
+```
+
+From the npm global install (the package ships the skill):
+
+```bash
+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`.
+
+## Project structure
+
+```
+asana-cli-skill/
+├── bin/
+│   └── asana-cli.js          # Entry point, command registration
+├── src/
+│   ├── client.js             # HTTP client for the Asana API
+│   ├── formatter.js          # Human-readable terminal output
+│   ├── utils.js              # URL parsing, helpers
+│   └── commands/
+│       ├── init.js            # Token setup
+│       ├── task.js            # Read a task
+│       ├── subtasks.js        # List subtasks
+│       ├── complete.js        # Complete + comment
+│       ├── comment.js         # Comment
+│       └── create-subtask.js  # Create a subtask
+├── skills/
+│   └── asana/
+│       └── SKILL.md          # Claude Code skill
+├── package.json
+└── .gitignore
+```
+
+## Stack
+
+- Node.js (native ESM, no build step)
+- `commander` for argument parsing
+- `chalk` for terminal colors
+- `dotenv` for configuration
+- Native `fetch` (Node 18+)
+
+## License
+
+[MIT](LICENSE)

package/bin/asana-cli.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+
+import { config } from 'dotenv';
+import { join } from 'path';
+import { homedir } from 'os';
+import { existsSync } from 'fs';
+import { Command } from 'commander';
+import { AsanaClient } from '../src/client.js';
+import { initCommand } from '../src/commands/init.js';
+import { taskCommand } from '../src/commands/task.js';
+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 { formatError } from '../src/formatter.js';
+
+// Load .env from the current directory first, then from ~/.asana-cli/
+config({ path: join(process.cwd(), '.env') });
+
+const globalEnv = join(homedir(), '.asana-cli', '.env');
+if (existsSync(globalEnv)) {
+    config({ path: globalEnv });
+}
+
+function getClient() {
+    return new AsanaClient(process.env.ASANA_TOKEN);
+}
+
+function collectMultiple(value, prev) {
+    return prev.concat([value]);
+}
+
+const program = new Command();
+
+program
+    .name('asana-cli')
+    .description('Minimal CLI for Asana task management')
+    .version('1.0.0');
+
+program
+    .command('init')
+    .description('Configure your Asana Personal Access Token')
+    .action(initCommand);
+
+program
+    .command('task')
+    .description('Read a full task with its subtasks')
+    .argument('<url-or-id>', 'Asana URL or task ID')
+    .action(async (urlOrId) => {
+        await taskCommand(urlOrId, getClient());
+    });
+
+program
+    .command('subtasks')
+    .description('List the subtasks of a task')
+    .argument('<url-or-id>', 'Asana URL or task ID')
+    .action(async (urlOrId) => {
+        await subtasksCommand(urlOrId, getClient());
+    });
+
+program
+    .command('complete')
+    .description('Mark a task as done with a comment (custom progress field or completed checkbox)')
+    .argument('<task-id>', 'Task ID')
+    .requiredOption('-m, --message <text>', 'Comment message')
+    .option('--close', 'Also mark the task as completed (checkbox), including pending subtasks')
+    .action(async (taskId, options) => {
+        await completeCommand(taskId, options, getClient());
+    });
+
+program
+    .command('comment')
+    .description('Add a comment and/or attachments to a task')
+    .argument('<task-id>', 'Task ID')
+    .option('-m, --message <text>', 'Comment message')
+    .option('-a, --attachment <path>', 'File to attach (repeatable)', collectMultiple, [])
+    .action(async (taskId, options) => {
+        await commentCommand(taskId, options, getClient());
+    });
+
+program
+    .command('create-subtask')
+    .description('Create a subtask under a task')
+    .argument('<parent-id>', 'Parent task ID')
+    .requiredOption('-n, --name <name>', 'Subtask name')
+    .action(async (parentId, options) => {
+        await createSubtaskCommand(parentId, options, getClient());
+    });
+
+program.parseAsync().catch((err) => {
+    console.error(formatError(err.message));
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "asana-cli-skill",
+  "version": "1.0.0",
+  "description": "Minimal CLI for Asana task management, built to power a Claude Code skill",
+  "type": "module",
+  "license": "MIT",
+  "author": "Juliano Giacomeli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/giacomeli/asana-cli-skill.git"
+  },
+  "homepage": "https://github.com/giacomeli/asana-cli-skill#readme",
+  "bugs": {
+    "url": "https://github.com/giacomeli/asana-cli-skill/issues"
+  },
+  "bin": {
+    "asana-cli": "./bin/asana-cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills"
+  ],
+  "scripts": {
+    "start": "node bin/asana-cli.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "asana",
+    "cli",
+    "claude-code",
+    "skill",
+    "task-management"
+  ],
+  "dependencies": {
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0",
+    "dotenv": "^16.5.0"
+  }
+}

package/skills/asana/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: asana
+description: >
+  Asana integration for task management during development.
+  Use this skill whenever the user shares an Asana link (app.asana.com),
+  mentions "asana", "asana task", "pick up this task", or uses /asana.
+  The skill reads the task, creates an implementation plan based on its
+  subtasks, and updates Asana automatically as the work progresses
+  (comments + status). It MUST be used whenever an Asana link appears in
+  the conversation or the user mentions anything related to Asana tasks.
+---
+
+# Skill: Asana Task Integration
+
+Orchestrates the development workflow from an Asana task: reads the task, generates a plan, executes it, and updates Asana with progress and commits.
+
+## Prerequisite
+
+The `asana-cli` command must be installed globally.
+If `asana-cli` is not found, instruct the user:
+```
+npm install -g asana-cli-skill
+asana-cli init
+```
+
+## Full Workflow
+
+### 1. Read the Task
+
+When you receive a link or a mention of an Asana task:
+
+```bash
+asana-cli task <url>
+```
+
+This returns the title, description, project, assignee, and subtasks. Use this information as context for the plan.
+
+### 2. Analyze and Plan
+
+Based on the task you read:
+
+- **If the task already has subtasks:** use them as the plan steps. Each subtask becomes a step.
+- **If the task has no subtasks:** analyze the title and description to derive steps. Create the corresponding subtasks in Asana:
+  ```bash
+  asana-cli create-subtask <task-id> --name "Step name"
+  ```
+- **If extra steps are needed** beyond the existing subtasks: create them in Asana as well.
+
+Generate the plan in the project's standard format (if a `spec-plan` or `writing-plans` skill is available, use it). The plan must include an Asana tracking section:
+
+```markdown
+## Asana Tracking
+
+Task: [Task Name](asana-url)
+
+| Step | Subtask | Asana ID | Status | Commit |
+|------|---------|----------|--------|--------|
+| 1 | Step name | 1234567890 | Pending | - |
+| 2 | Step name | 1234567891 | Pending | - |
+```
+
+Save the plan in `specs/plans/` (or the project's standard location).
+
+### 3. Execute the Plan
+
+Execute the plan step by step. When each step is finished:
+
+#### a. Commit
+
+Commit normally, following the project's conventions.
+
+#### b. Capture the commit hash
+
+```bash
+git log -1 --format="%h"
+```
+
+#### c. Capture the current branch
+
+```bash
+git branch --show-current
+```
+
+#### d. Update Asana
+
+Mark the subtask as done with a descriptive comment:
+
+```bash
+asana-cli complete <subtask-id> --message "Done
+
+<short description of what was implemented>
+
+Commit: <hash>
+Branch: <branch>"
+```
+
+#### e. Update the plan
+
+Update the tracking table in the plan with the status and commit:
+
+```markdown
+| 1 | Step name | 1234567890 | Done | abc1234 |
+```
+
+Also include the output of `asana-cli complete` in the plan for documentation.
+
+### 4. Finish
+
+Once all steps are done:
+
+#### a. Comment on the parent task
+
+```bash
+asana-cli comment <task-id> --message "Task completed
+
+Summary:
+- Step 1: <name> -> commit <hash>
+- Step 2: <name> -> commit <hash>
+- Step 3: <name> -> commit <hash>
+
+Branch: <branch>
+Total commits: <N>"
+```
+
+#### b. Do NOT mark the parent task as complete
+
+The parent task must be closed manually by the user or tech lead. Only subtasks are completed automatically.
+
+## Available Commands
+
+Quick reference for `asana-cli`:
+
+| Command | Purpose |
+|---------|---------|
+| `asana-cli task <url>` | Read a task with its subtasks |
+| `asana-cli subtasks <url-or-id>` | List subtasks only |
+| `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 |
+
+## Important Rules
+
+1. **Always read the task before acting.** Never assume its content — run `asana-cli task`.
+2. **Never skip the Asana update.** After each completed step, Asana MUST be updated.
+3. **Never mark the parent task as complete.** Only subtasks are completed automatically.
+4. **CLI output goes into the plan.** The output of each `asana-cli complete` must be recorded in the plan.
+5. **IDs are required.** Always use the numeric Asana ID with `complete`, `comment`, and `create-subtask`. The ID is shown in the output of `asana-cli task`.

package/src/client.js

@@ -0,0 +1,148 @@
+import { basename } from 'path';
+
+const BASE_URL = 'https://app.asana.com/api/1.0';
+
+export class AsanaClient {
+    constructor(token) {
+        if (!token) {
+            throw new Error(
+                'ASANA_TOKEN is not set.\n' +
+                'Run: asana-cli init'
+            );
+        }
+        this.token = token;
+    }
+
+    async request(path, options = {}) {
+        const url = `${BASE_URL}${path}`;
+        const response = await fetch(url, {
+            ...options,
+            headers: {
+                'Authorization': `Bearer ${this.token}`,
+                'Content-Type': 'application/json',
+                ...options.headers,
+            },
+        });
+
+        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();
+        return json.data;
+    }
+
+    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`
+        );
+    }
+
+    async getSubtasks(taskId) {
+        return this.request(
+            `/tasks/${taskId}/subtasks?opt_fields=name,completed`
+        );
+    }
+
+    async completeTask(taskId) {
+        return this.request(`/tasks/${taskId}`, {
+            method: 'PUT',
+            body: JSON.stringify({ data: { completed: true } }),
+        });
+    }
+
+    async addComment(taskId, text) {
+        const parsed = text.replace(/\\n/g, '\n');
+        return this.request(`/tasks/${taskId}/stories`, {
+            method: 'POST',
+            body: JSON.stringify({ data: { text: parsed } }),
+        });
+    }
+
+    async addHtmlComment(taskId, htmlText) {
+        return this.request(`/tasks/${taskId}/stories`, {
+            method: 'POST',
+            body: JSON.stringify({ data: { html_text: htmlText } }),
+        });
+    }
+
+    async setCustomFieldEnum(taskId, fieldName, optionName) {
+        const task = await this.getTask(taskId);
+        const field = task.custom_fields?.find(
+            (f) => f.name.toLowerCase() === fieldName.toLowerCase()
+        );
+        if (!field) {
+            const available = task.custom_fields?.map((f) => f.name).join(', ') || 'none';
+            throw new Error(
+                `Custom field "${fieldName}" not found. Available fields: ${available}`
+            );
+        }
+
+        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}`
+            );
+        }
+
+        return this.request(`/tasks/${taskId}`, {
+            method: 'PUT',
+            body: JSON.stringify({
+                data: { custom_fields: { [field.gid]: option.gid } },
+            }),
+        });
+    }
+
+    async uploadAttachment(taskId, filePath) {
+        const url = `${BASE_URL}/tasks/${taskId}/attachments`;
+        const fileName = basename(filePath);
+        const ext = fileName.toLowerCase().slice(fileName.lastIndexOf('.'));
+        const mimeTypes = {
+            '.png': 'image/png',
+            '.jpg': 'image/jpeg',
+            '.jpeg': 'image/jpeg',
+            '.gif': 'image/gif',
+            '.webp': 'image/webp',
+            '.bmp': 'image/bmp',
+            '.svg': 'image/svg+xml',
+            '.pdf': 'application/pdf',
+        };
+        const mimeType = mimeTypes[ext] || 'application/octet-stream';
+
+        const { readFile } = await import('fs/promises');
+        const fileBuffer = await readFile(filePath);
+        const blob = new Blob([fileBuffer], { type: mimeType });
+
+        const form = new FormData();
+        form.append('file', blob, fileName);
+
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${this.token}`,
+            },
+            body: form,
+        });
+
+        if (!response.ok) {
+            const body = await response.json().catch(() => ({}));
+            const msg = body?.errors?.[0]?.message || response.statusText;
+            throw new Error(`Asana API error uploading attachment (${response.status}): ${msg}`);
+        }
+
+        const json = await response.json();
+        return json.data;
+    }
+
+    async createSubtask(parentId, name) {
+        return this.request(`/tasks/${parentId}/subtasks`, {
+            method: 'POST',
+            body: JSON.stringify({ data: { name } }),
+        });
+    }
+}

package/src/commands/comment.js

@@ -0,0 +1,51 @@
+import { existsSync } from 'fs';
+import { formatSuccess, formatError } from '../formatter.js';
+
+export async function commentCommand(taskId, options, client) {
+    const message = options.message;
+    const attachments = options.attachment || [];
+
+    if (!message && attachments.length === 0) {
+        console.error(formatError('Provide --message and/or --attachment'));
+        process.exit(1);
+    }
+
+    // Validate files exist
+    for (const filePath of attachments) {
+        if (!existsSync(filePath)) {
+            console.error(formatError(`File not found: ${filePath}`));
+            process.exit(1);
+        }
+    }
+
+    // Upload attachments and collect GIDs
+    const uploaded = [];
+    for (const filePath of attachments) {
+        const result = await client.uploadAttachment(taskId, filePath);
+        uploaded.push({ name: result.name, gid: result.gid });
+    }
+
+    // Build comment
+    if (uploaded.length > 0) {
+        // Use html_text with inline images via data-asana-gid
+        const textPart = message
+            ? message.replace(/\\n/g, '\n')
+            : '';
+        const imgTags = uploaded
+            .map((att) => `<img data-asana-gid="${att.gid}"/>`)
+            .join('\n');
+        const htmlBody = textPart
+            ? `<body>${textPart}\n${imgTags}</body>`
+            : `<body>${imgTags}</body>`;
+        await client.addHtmlComment(taskId, htmlBody);
+    } else if (message) {
+        await client.addComment(taskId, message);
+    }
+
+    const task = await client.getTask(taskId);
+    const parts = [];
+    if (message) parts.push(`Comment: "${message}"`);
+    if (uploaded.length > 0) parts.push(`Inline attachments: ${uploaded.map((u) => u.name).join(', ')}`);
+
+    console.log(formatSuccess(`Task "${task.name}" updated\n   ${parts.join('\n   ')}`));
+}

package/src/commands/complete.js

@@ -0,0 +1,43 @@
+import { formatSuccess } from '../formatter.js';
+
+export async function completeCommand(taskId, options, client) {
+    const message = options.message;
+    if (!message) {
+        console.error('Error: --message is required');
+        process.exit(1);
+    }
+
+    await client.addComment(taskId, message);
+
+    // When a progress custom field is configured, set it instead of the
+    // completed checkbox (useful for boards driven by an enum field).
+    const progressField = process.env.ASANA_PROGRESS_FIELD;
+    const progressValue = process.env.ASANA_PROGRESS_VALUE;
+    const useProgressField = Boolean(progressField && progressValue);
+
+    if (useProgressField) {
+        await client.setCustomFieldEnum(taskId, progressField, progressValue);
+    }
+
+    if (options.close || !useProgressField) {
+        await client.completeTask(taskId);
+    }
+
+    if (options.close) {
+        const subtasks = await client.getSubtasks(taskId);
+        const pending = subtasks.filter((s) => !s.completed);
+        for (const sub of pending) {
+            await client.completeTask(sub.gid);
+        }
+
+        if (pending.length > 0) {
+            console.log(formatSuccess(`${pending.length} pending subtask(s) also marked as completed`));
+        }
+    }
+
+    const task = await client.getTask(taskId);
+    const actions = [];
+    if (useProgressField) actions.push(`progress set to "${progressValue}"`);
+    if (options.close || !useProgressField) actions.push('marked as completed');
+    console.log(formatSuccess(`Task "${task.name}" - ${actions.join(' + ')}\n   Comment added: "${message}"`));
+}

package/src/commands/create-subtask.js

@@ -0,0 +1,14 @@
+import { formatSuccess } from '../formatter.js';
+
+export async function createSubtaskCommand(parentId, options, client) {
+    const name = options.name;
+    if (!name) {
+        console.error('Error: --name is required');
+        process.exit(1);
+    }
+
+    const subtask = await client.createSubtask(parentId, name);
+    const parent = await client.getTask(parentId);
+
+    console.log(formatSuccess(`Subtask created: "${name}" (id: ${subtask.gid})\n   Parent: ${parent.name}`));
+}

package/src/commands/init.js

@@ -0,0 +1,42 @@
+import { writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { createInterface } from 'readline';
+import { formatSuccess, formatError } from '../formatter.js';
+
+const CONFIG_DIR = join(homedir(), '.asana-cli');
+const ENV_PATH = join(CONFIG_DIR, '.env');
+
+function prompt(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+
+export async function initCommand() {
+    console.log('\nAsana CLI setup\n');
+
+    if (existsSync(ENV_PATH)) {
+        const overwrite = await prompt('   A configuration already exists. Overwrite? (y/N): ');
+        if (overwrite.toLowerCase() !== 'y') {
+            console.log(formatSuccess('Existing configuration kept.'));
+            return;
+        }
+    }
+
+    const token = await prompt('   Paste your Asana Personal Access Token: ');
+
+    if (!token) {
+        console.log(formatError('Token cannot be empty.'));
+        process.exit(1);
+    }
+
+    mkdirSync(CONFIG_DIR, { recursive: true });
+    writeFileSync(ENV_PATH, `ASANA_TOKEN=${token}\n`, { mode: 0o600 });
+
+    console.log(formatSuccess(`Token saved to ${ENV_PATH}`));
+}

package/src/commands/subtasks.js

@@ -0,0 +1,8 @@
+import { parseTaskId } from '../utils.js';
+import { formatSubtasks } from '../formatter.js';
+
+export async function subtasksCommand(urlOrId, client) {
+    const taskId = parseTaskId(urlOrId);
+    const subtasks = await client.getSubtasks(taskId);
+    console.log(formatSubtasks(subtasks));
+}

package/src/commands/task.js

@@ -0,0 +1,12 @@
+import { parseTaskId } from '../utils.js';
+import { formatTask } from '../formatter.js';
+
+export async function taskCommand(urlOrId, client) {
+    const taskId = parseTaskId(urlOrId);
+    const [task, subtasks] = await Promise.all([
+        client.getTask(taskId),
+        client.getSubtasks(taskId),
+    ]);
+
+    console.log(formatTask(task, subtasks));
+}

package/src/formatter.js

@@ -0,0 +1,71 @@
+import chalk from 'chalk';
+
+export function formatTask(task, subtasks) {
+    const lines = [];
+
+    lines.push('');
+    lines.push(chalk.bold(`Task: ${task.name}`));
+    lines.push(`   Status: ${task.completed ? chalk.green('Completed') : chalk.yellow('In progress')}`);
+
+    const project = task.memberships?.[0]?.project?.name;
+    if (project) {
+        lines.push(`   Project: ${project}`);
+    }
+
+    if (task.assignee?.name) {
+        lines.push(`   Assignee: ${task.assignee.name}`);
+    }
+
+    lines.push(`   ID: ${task.gid}`);
+
+    if (task.notes) {
+        lines.push('');
+        lines.push('   Description:');
+        const noteLines = task.notes.split('\n');
+        for (const line of noteLines) {
+            lines.push(`   ${line}`);
+        }
+    }
+
+    if (subtasks && subtasks.length > 0) {
+        lines.push('');
+        lines.push(`   Subtasks (${subtasks.length}):`);
+        for (const sub of subtasks) {
+            const check = sub.completed ? chalk.green('x') : ' ';
+            const name = sub.completed ? chalk.dim(sub.name) : sub.name;
+            lines.push(`   [${check}] ${name} (id: ${sub.gid})`);
+        }
+    }
+
+    lines.push('');
+    return lines.join('\n');
+}
+
+export function formatSubtasks(subtasks) {
+    const lines = [];
+    lines.push('');
+
+    if (subtasks.length === 0) {
+        lines.push(chalk.dim('   No subtasks found.'));
+        lines.push('');
+        return lines.join('\n');
+    }
+
+    lines.push(`   Subtasks (${subtasks.length}):`);
+    for (const sub of subtasks) {
+        const check = sub.completed ? chalk.green('x') : ' ';
+        const name = sub.completed ? chalk.dim(sub.name) : sub.name;
+        lines.push(`   [${check}] ${name} (id: ${sub.gid})`);
+    }
+
+    lines.push('');
+    return lines.join('\n');
+}
+
+export function formatSuccess(message) {
+    return `\n${chalk.green('OK')} ${message}\n`;
+}
+
+export function formatError(message) {
+    return `\n${chalk.red('Error:')} ${message}\n`;
+}

package/src/utils.js

@@ -0,0 +1,41 @@
+/**
+ * Extracts the task ID from an Asana URL, or returns the ID as-is.
+ *
+ * Supported formats:
+ * - https://app.asana.com/0/<project-id>/<task-id>
+ * - https://app.asana.com/0/<project-id>/<task-id>/f
+ * - https://app.asana.com/1/<workspace-id>/project/<project-id>/task/<task-id>
+ * - Plain numeric ID
+ */
+export function parseTaskId(input) {
+    if (/^\d+$/.test(input)) {
+        return input;
+    }
+
+    try {
+        const url = new URL(input);
+        if (!url.hostname.includes('asana.com')) {
+            throw new Error(`URL is not an Asana URL: ${input}`);
+        }
+
+        const parts = url.pathname.split('/').filter(Boolean);
+
+        // Format: /1/<workspace>/project/<project>/task/<task-id>
+        const taskIndex = parts.indexOf('task');
+        if (taskIndex !== -1 && parts[taskIndex + 1]) {
+            return parts[taskIndex + 1];
+        }
+
+        // Format: /0/<project-id>/<task-id>[/f]
+        if (parts[0] === '0' && parts.length >= 3) {
+            return parts[2];
+        }
+
+        throw new Error(`Could not extract a task ID from: ${input}`);
+    } catch (err) {
+        if (err.code === 'ERR_INVALID_URL') {
+            throw new Error(`Invalid input (not a URL or numeric ID): ${input}`);
+        }
+        throw err;
+    }
+}