asana-cli

Codex から Asana REST API を直接呼ぶためのバックアップ CLI です。MCP が接続できない場合でも、Node.js だけでタスク、サブタスク、コメントを操作できます。

前提

• Node.js 18 以上
• Asana Personal Access Token または OAuth access token
• 環境変数 ASANA_ACCESS_TOKEN

export ASANA_ACCESS_TOKEN="your-token"

Asana API token は Authorization: Bearer <token> として送信します。token はログやコードに残さないでください。

インストール

グローバルにインストールすると、asana-cli コマンドを利用できます。

npm install --global @chikin14niwa/asana-cli
asana-cli --help

インストールせず一度だけ実行する場合:

npx @chikin14niwa/asana-cli --help

使い方

依存パッケージはありません。

asana-cli --help

Codex からは dry-run でリクエストを確認してから実行すると安全です。

asana-cli tasks get 1200000000000000 --dry-run

タスク

タスク検索は Asana の workspace search endpoint を使います。

asana-cli tasks search --workspace 123456789 --text "release" --limit 20
asana-cli tasks search --workspace 123456789 --project 987654321 --assignee me

タスク取得、作成、変更:

asana-cli tasks get 1200000000000000
asana-cli tasks create --workspace 123456789 --name "調査する" --notes "Codex から作成"
asana-cli tasks create --project 987654321 --name "実装する"
asana-cli tasks update 1200000000000000 --completed true
asana-cli tasks update 1200000000000000 --data-json '{"name":"名称変更","notes":"本文"}'
asana-cli tasks create --workspace 123456789 --name "資料確認" --attach ./仕様書.pdf --attach ./画面.png
asana-cli tasks update 1200000000000000 --attach ./調査結果.txt

任意フィールドは --set key=value または --data-json で指定できます。 --attach <path> は複数指定できます。全ファイルが通常ファイル・読み取り可能・各 100MB 以下であることを確認してからタスクを作成または更新し、続けて添付します。tasks update は --attach だけでも実行でき、その場合はタスクへの空更新を行いません。

タスクの作成・更新と添付は別の API request であり、原子的ではありません。添付中に通信結果が不明になった場合は自動再試行せず、出力された task GID とファイル名を Asana 上で確認してから不足分だけ再実行してください。

asana-cli tasks update 1200000000000000 --set custom_fields.12345="value"

サブタスク

Asana の subtask は task と同じ resource です。変更は task update endpoint に送られます。

asana-cli subtasks list 1200000000000000
asana-cli subtasks create 1200000000000000 --name "サブタスク"
asana-cli subtasks update 1200000000000001 --completed true
asana-cli subtasks set-parent 1200000000000001 --parent 1200000000000000 --insert-before 1200000000000002
asana-cli subtasks set-parent 1200000000000001 --parent 1200000000000000 --insert-after 1200000000000003
asana-cli subtasks set-parent 1200000000000001 --parent null

subtasks set-parent は親の設定と同時に、--insert-before または --insert-after で新しい親のサブタスク内における位置を指定できます。両方は同時に指定できません。位置の基準にする GID は、新しい親の既存サブタスクである必要があります。--insert-before null は末尾、--insert-after null は先頭へ移動します。--parent null は親を解除します。

コメント

Asana API ではコメントは task story として扱われます。この CLI の comments list は既定で comment story だけを返します。system story も含めたい場合は --include-system を指定します。

asana-cli comments list 1200000000000000
asana-cli comments create 1200000000000000 --text "対応しました"
asana-cli comments update 1200000000000002 --text "コメントを修正しました"

補助コマンド

asana-cli me
asana-cli workspaces list

共通オプション

• --dry-run: Asana に送信せず、method、URL、body を JSON で出力
• --base-url <url>: API base URL を変更
• --token <token>: ASANA_ACCESS_TOKEN の代わりに token を指定
• --opt-fields <fields>: opt_fields をカンマ区切りで指定
• --query key=value: 任意の query parameter を追加
• --data-json '<json>': Asana の data object を JSON で指定
• --data-file <path>: JSON ファイルから data object を読み込み
• --stdin-json: stdin から data object を読み込み
• --set key=value: data object に任意フィールドを追加
• --attach <path>: tasks create/update のタスクにローカルファイルを添付（複数可、各 100MB 以下）
• --compact: JSON を 1 行で出力

--data-json は {"name":"x"} と {"data":{"name":"x"}} の両方を受け付けます。

Asana API 対応

• tasks search: GET /workspaces/{workspace_gid}/tasks/search
• tasks list: GET /tasks
• tasks get: GET /tasks/{task_gid}
• tasks create: POST /tasks
• tasks update: PUT /tasks/{task_gid}
• task attachment: POST /attachments (multipart/form-data の parent、file)
• subtasks list: GET /tasks/{task_gid}/subtasks
• subtasks create: POST /tasks/{task_gid}/subtasks
• subtasks update: PUT /tasks/{subtask_gid}
• subtasks set-parent: POST /tasks/{subtask_gid}/setParent
• comments list: GET /tasks/{task_gid}/stories
• comments create: POST /tasks/{task_gid}/stories
• comments update: PUT /stories/{story_gid}

タスク検索 endpoint は Asana 側で Premium access が必要な場合があり、検索 index の eventual consistency により作成直後の変更がすぐ反映されないことがあります。書き込み直後の確認には tasks get または tasks list を使ってください。

参照:

• Asana API reference
• Search tasks in a workspace
• Create a task
• Update a task
• Create an attachment
• Get subtasks from a task
• Create a subtask
• Set the parent of a task
• Get stories from a task
• Create a story on a task
• Update a story
• Personal access token

テスト

npm test

リポジトリを直接利用する開発者向けの zsh command function は、./scripts/setup-zsh-alias.sh で設定できます。npm からインストールする場合、この設定は不要です。

公開手順と公開前チェックリストは docs/npm-publishing.md を参照してください。