clickup

ClickUp CLI（cup）- スキルバージョン 1.46.2

cup CLI ツールを使用する AI エージェント向けのリファレンスです。タスク管理、スプリントの追跡、コメント、時間の記録、カスタムフィールド、目標、Docs、Chat、ビュー、Webhook、ワークスペース構成、エクスポート、プロジェクトのワークフローを扱います。

バージョンの確認： cup --version を実行します。インストール済みのバージョンが 1.46.2 より古い場合は、npm install -g @krodak/clickup-cli で更新し、cup skill でこのスキルを更新してください（cup skill --path <file> は指定した場所にインストールし、cup skill --print は標準出力に書き込みます）。

インストールと設定

前提条件

Node.js 22 以降が必要です。

インストール

npm install -g @krodak/clickup-cli

または Homebrew 経由：

brew tap krodak/tap && brew install clickup-cli

API トークンの取得

ユーザーは ClickUp の個人用 API トークンが必要です。

1. https://app.clickup.com/settings/apps を開きます
2. 「API Token」の下にある「Generate」をクリックします（または既存のトークンをコピーします）
3. トークンは pk_ で始まります

設定

非対話型（エージェントに推奨）：

cup init --token pk_USER_TOKEN --team TEAM_ID

team/workspace ID を確認するには、ユーザーは ClickUp の URL を確認します：https://app.clickup.com/TEAM_ID/...

対話型（ターミナルを使う人間向け）：

cup init

環境変数（設定ファイル不要）：

export CU_API_TOKEN="pk_..."
export CU_TEAM_ID="12345678"

確認

cup auth

認証済みのユーザー名とワークスペースが表示されます。失敗する場合は、トークンまたは設定が無効です。

セットアップ

設定は ~/.config/cup/config.json に保存され、名前付きプロファイルを使用します。各プロファイルには apiToken と teamId があります。任意で sprintFolderId を指定すると、スプリントの検出対象を特定のフォルダーに固定できます。

複数のプロファイルに対応しています。cup profile add <name> で作成し、cup profile use <name> で切り替えるか、単発の上書きには -p <name> フラグを使用します。

CU_PROFILE 環境変数でプロファイルを選択します（-p フラグで上書きできます）。

保存済みフィルター（クイックショートカット）

各セッションの開始時に cup filter list を実行し、このワークスペースの保存済みショートカットを確認します。

コマンド	内容
cup filter list [--json]	保存済みのショートカットをすべて、コマンドと説明付きで一覧表示します
cup filter run <name>	保存済みのショートカットを実行します（完全なコマンドを実行するのと同じです）
cup filter save <name> <cmd> [args...] [-d desc]	コマンドのショートカットを保存します
cup filter delete <name>	ショートカットを削除します
cup filter show <name> [--json]	単一のショートカットの詳細を表示します

例：cup filter save sprint-tasks tasks --status "in progress" --list l1 -d "Current sprint tasks" 次のコマンド：cup filter run sprint-tasks は cup tasks --status "in progress" --list l1 と同じです。

出力モード

コンテキスト	デフォルトの出力	上書き
ターミナル（TTY）	対話型ピッカー UI	JSON には --json
パイプ接続時／非 TTY	Markdown テーブル	JSON には --json

• パイプ接続時のデフォルト出力は Markdown です。エージェントのコンテキストウィンドウに最適化されています。
• パイプ接続時、cup task <id> は Markdown の要約を出力します。完全な生の API オブジェクトには --json を使用します。
• CU_OUTPUT=json を設定すると、パイプ接続時は常に JSON が出力されます。
• エージェントが構造化データを jq で解析する場合を除き、通常は --json は不要です。

コマンド

すべてのコマンドで --help を指定すると、フラグの詳細を確認できます。すべてのコマンドは --json に対応しています。

読み取り

コマンド	返される内容
cup tasks [--status s] [--name q] [--type t] [--list id] [--space id] [--all] [--include-closed] [--assignee id|me] [--tag t] [--due-before d] [--due-after d] [--created-after d] [--created-before d] [--field "Name" val]	自分に割り当てられたタスク（ステータス、名前、タイプ、リスト、スペース、担当者、タグ、日付、カスタムフィールドで絞り込みます）。すべての担当者を対象にするには --all を指定します
cup assigned [--status s] [--include-closed]	自分のすべてのタスクをステータス別にグループ化して表示します
cup sprint [--status s] [--space nameOrId] [--folder id] [--include-closed]	アクティブなスプリント内のタスク（自動検出）
cup sprints [--space nameOrId]	すべてのスプリントを一覧表示します（アクティブなものには * を付けます）
cup search [query] [--status s] [--list id] [--space id] [--all] [--include-closed] [--assignee id|me] [--tag t] [--due-before d] [--due-after d] [--created-after d] [--created-before d] [--field "Name" val]	名前でタスクを検索します。クエリを指定しない場合は、フラグで絞り込んだタスクを一覧表示します。すべての担当者を対象にするには --all を指定します
cup task <id>	単一タスクの詳細（カスタムフィールド、チェックリスト、添付ファイル、依存関係、リンク）
cup subtasks <id> [--status s] [--name q] [--include-closed]	タスクのサブタスク
cup comments <id>	タスクのコメント
cup activity <id>	タスクの詳細とコメント履歴をまとめて表示します
cup inbox [--days n] [--include-closed]	過去 n 日間に更新されたタスク（デフォルトは 30 日）
cup summary [--hours n]	スタンドアップ：完了、進行中、期限超過
cup overdue [--all] [--include-closed]	期限を過ぎたタスク（期限超過日数の長い順）
cup spaces [--name partial] [--my] [--archived]	ワークスペースのスペースを一覧表示／絞り込みます
cup lists <spaceId> [--name partial] [--archived]	スペース内のリスト（フォルダー内のリストを含む）
cup folders <spaceId> [--name partial] [--archived]	スペース内のフォルダー（各フォルダー内のリストを含む）。JSON にはサブフォルダーの parent_folder が含まれます
cup time-in-status <id>	タスクが各ステータスにとどまっている時間を表示します
cup members	ワークスペースのメンバー（ユーザー名、ID、メールアドレス）
cup groups	ユーザーグループ／チーム（ハンドル、名前、UUID、メンバー数）。--group-assignee フラグで使用します
cup fields <listId>	リストのカスタムフィールド（タイプ、必須かどうか、選択肢）
cup attachments <taskId>	タスクの添付ファイルを一覧表示します（名前、サイズ、URL）
cup attach-get <taskId> [idOrTitle] [-o|--output path] [--all] [--dir d] [--force]	タスクの添付ファイルをダウンロードします。セレクターを指定せず、添付ファイルが 1 つの場合はそのファイルをダウンロードします。複数ある場合はセレクターまたは --all が必要です。デフォルトでは添付ファイルのファイル名で保存します
cup task-members <taskId>	タスクへのアクセス権を持つメンバーを一覧表示します
cup plan	ワークスペースのプランと使用状況を表示します
cup tags <spaceId>	スペースで使用可能なタグ
cup goals	ワークスペースの目標と進捗
cup key-results <goalId>	目標の主要な成果
cup docs [query]	ワークスペースのドキュメント（名前で絞り込み可能）
cup doc <docId> [pageId]	ドキュメントのメタデータとページツリー、または特定のページ
cup doc-pages <docId>	ドキュメント内のすべてのページとその内容
cup task-types	カスタムタスクタイプ（--custom-item-id 用）
cup templates	タスクテンプレート（--template 用）
cup list-templates	リストテンプレート（list-from-template 用）
cup folder-templates	フォルダーテンプレート
cup views <id> [--space|--folder|--workspace]	リスト（デフォルト）、スペース、フォルダー、またはワークスペースのビューを一覧表示します（cup views any --workspace）
cup view <viewId>	ビューの詳細を取得します
cup view-tasks <viewId> [--me]	ビュー内のタスクを一覧表示します（--me を指定すると自分のタスクに絞り込みます）
cup open <query>	ID または名前でタスクをブラウザーで開きます
cup auth	認証状態を確認します
cup list-comments <listId>	リストのコメント
cup view-comments <viewId>	ビューのコメント
cup webhook list	ワークスペースの Webhook を一覧表示します
cup shared	共有されているスペース、フォルダー、リスト
cup chat channels [--all] [--type type]	チャットチャンネルを一覧表示します
cup chat channel <id>	チャンネルの詳細を表示します
cup chat messages <channelId> [--limit n]	チャンネルのメッセージを一覧表示します
cup chat members <channelId>	チャンネルのメンバーを一覧表示します
cup chat followers <channelId>	チャンネルのフォロワーを一覧表示します
cup chat replies <messageId>	メッセージへの返信を一覧表示します
cup chat reactions <messageId>	メッセージへのリアクションを一覧表示します
cup export user|team|roadmap|initiatives|docs|all ... [--out dir] [--dry-run] [--item-id n] [--yes]	タスク／ドキュメントをローカルアーカイブにエクスポートします（損失のない JSON と Markdown）。詳しくは「エクスポート」を参照してください

Write

コマンド	説明
cup create -n name [-l listId|sprint:current] [--parent parentId] [-d desc|--description-file path] [-s status] [--priority p] [--due-date d] [--start-date d] [--time-estimate t] [--assignee id|me] [--group-assignee uuid|@handle,...] [--tags t] [--custom-item-id n] [--template id] [--field "Name" val]	タスクを作成します（--list は sprint:current を受け付けます。--field はカスタムフィールドをインラインで設定します。--description-file はファイルまたは標準入力の - から Markdown を読み込みます）
cup update <id> [-n name] [-d desc|--description-file path] [-s status] [--priority p] [--due-date d|none] [--start-date d] [--time-estimate t] [--assignee id|me] [--remove-assignee id|me] [--group-assignee uuid|@handle] [--remove-group-assignee uuid|@handle] [--parent id] [--archive] [--unarchive] [--type type] [--field "Name" val]	タスクのフィールドを更新します（--description-file はファイルまたは標準入力の - から Markdown を読み込みます）
cup comment <id> -m text|--message-file path [--notify-all] [--mention user]	コメントを投稿します（Markdown は自動的にリッチテキストに変換されます。--message-file はファイルまたは標準入力の - から読み込みます。--mention は実際の @メンション用で、複数回指定できます）
cup comment-edit <commentId> -m text|--message-file path [--resolved] [--unresolved] [--mention user]	コメントを編集します（Markdown は自動的にリッチテキストに変換されます。--mention は実際の @メンション用です）
cup comment-delete <commentId> or cup comment-delete --task <taskId> --mine [--match text]	ID でコメントを削除するか、自分のタスクコメントを削除します
cup replies <commentId>	スレッド形式の返信を一覧表示します
cup reply <commentId> -m text|--message-file path [--notify-all] [--mention user]	コメントに返信します（Markdown は自動的にリッチテキストに変換されます。--message-file はファイルまたは標準入力の - から読み込みます。--mention は実際の @メンション用です）
cup assign <id> [--to ids|me] [--remove ids|me] [--group uuid|@handle,...] [--remove-group uuid|@handle,...]	ユーザーとグループを割り当て／割り当て解除します（すべてのフラグでカンマ区切りの値を受け付けます）
cup depend <id> [--on taskId] [--blocks taskId] [--remove]	依存関係を追加／削除します
cup move <id> [--to listId|sprint:current] [--remove listId]	タスクをリストに追加／リストから削除します。--to と --remove を併用すると、タスクの ホーム リストが変更されます（自動ステータスマッピングを使用する v3 の home_list エンドポイントを使用します）。--to のみを指定すると、複数リストへの所属が追加されます。--to は sprint:current を受け付けます。
cup field <id> [--set "Name" value|--set "Name" --value-file path] [--remove "Name"]	カスタムフィールドの値を設定／削除します（--value-file はファイルまたは標準入力の - から値を読み込みます。長文や自由記述の値に使用してください）
cup field-create <name> -t <type> [-d desc] [--options "a,b,c"] [--required] [--list id] [--lists id1,id2]	カスタムフィールドを作成します。ワークスペース全体（デフォルト）、1 つのリスト（--list）、または複数のリスト（--lists、並列処理、リストごとのレポート）に作成できます
cup tag <id> [--add tags] [--remove tags]	タスクのタグを追加／削除します
cup link <taskId> <linksTo> [--remove]	タスクをリンク／リンク解除します
cup attach <taskId> <filePath>	ファイル添付をアップロードします
cup delete <id> [--confirm]	タスクを削除します（破壊的操作）
cup list-delete <listId> [--confirm]	リストを削除します（破壊的操作。非対話モードでは --confirm が必要です）
cup folder-delete <folderId> [--confirm]	フォルダーを削除します（破壊的操作。非対話モードでは --confirm が必要です）
cup space-delete <spaceId> [--confirm]	スペースを削除します（破壊的操作。非対話モードでは --confirm が必要です）
cup duplicate <taskId>	タスクを複製します
cup bulk status <status> <taskIds...>	複数のタスクのステータスを一括更新します
cup bulk assign <taskIds...> [--to userId|me] [--remove userId|me]	複数のタスクへのユーザーの割り当て／割り当て解除を一括で行います
cup bulk due-date <date|none|clear> <taskIds...>	複数のタスクの期限日を一括設定またはクリアします
cup bulk tag <tagName> <taskIds...> [--remove]	複数のタスクへのタグの追加／削除を一括で行います
cup bulk priority <taskIds...> --to <priority>	複数のタスクの優先度を一括設定します
cup bulk field <taskIds...> --set "Name" value	複数のタスクのカスタムフィールド値を一括設定します
cup bulk move <taskIds...> --to <listId>	複数のタスクを移動先のリストに一括移動します
cup checklist view <id>	タスクのチェックリストを表示します
cup checklist create <id> <name>	チェックリストを作成します
cup checklist delete <checklistId>	チェックリストを削除します
cup checklist add-item <checklistId> <name> [--parent itemId]	チェックリストに項目を追加します（--parent で親項目の下にネストします）
cup checklist edit-item <checklistId> <itemId> [--name n] [--resolved] [--unresolved] [--assignee id] [--parent itemId|null]	チェックリスト項目を編集します（--parent で親を変更し、ネストを解除するには "null" を使用します）
cup checklist delete-item <checklistId> <itemId>	チェックリスト項目を削除します
cup time start <taskId> [-d desc]	タイマーを開始します
cup time stop	実行中のタイマーを停止します
cup time status	実行中のタイマーを表示します
cup time log <taskId> <duration> [-d desc]	時間を手動で記録します（例：「2h」、「30m」）
cup time list [--days n] [--task id] [--all]	最近の自分の時間記録を一覧表示します（チーム全体を表示するには --all を指定します）
cup time update <timeEntryId> [-d desc] [--duration dur]	時間記録を更新します
cup time delete <timeEntryId>	時間記録を削除します
cup goal-create <name> [-d desc] [--color hex]	目標を作成します
cup goal-update <goalId> [-n name] [-d desc] [--color hex]	目標を更新します
cup goal-delete <goalId>	目標を削除します
cup key-result-create <goalId> <name> [--type t] [--target n]	主要な成果指標を作成します
cup key-result-update <keyResultId> [--progress n] [--note text]	主要な成果指標を更新します
cup key-result-delete <keyResultId>	主要な成果指標を削除します
cup doc-create <title> [-c content]	ドキュメントを作成します（ルートページにはタイトルと同じ名前が付けられます。-c で Markdown の内容を書き込みます）
cup doc-page-create <docId> <name> [-c content|--content-file path] [--parent-page pageId]	ドキュメントページを作成します（--content-file はファイルまたは標準入力の - から Markdown を読み込みます）
cup doc-page-edit <docId> <pageId> [--name text] [-c content|--content-file path]	ドキュメントページを編集します（--content-file はファイルまたは標準入力の - から Markdown を読み込みます）
cup doc-delete <docId>	サポートされていません — ClickUp にはドキュメント削除 API がありません（HTTP 405）。すぐに失敗します。ドキュメントは UI から削除してください。1 つのページを削除するには cup doc-page-delete を使用します
cup doc-page-delete <docId> <pageId>	ドキュメントページを削除します
cup space-create <name>	スペースを作成します
cup list-create <spaceId> <name> [--folder folderId] [--copy-statuses-from id]	スペースまたはフォルダー内にリストを作成します
cup folder-create <spaceId> <name>	スペース内にフォルダーを作成します
cup list-rename <listId> <newName>	リストの名前を変更します
cup folder-rename <folderId> <newName>	フォルダーの名前を変更します
cup space-rename <spaceId> <newName>	スペースの名前を変更します
cup tag-create <spaceId> <name> [--fg color] [--bg color]	スペースタグを作成します
cup tag-update <spaceId> <tagName> --name <newName> [--fg c] [--bg c]	スペースタグを更新します
cup tag-delete <spaceId> <name>	スペースタグを削除します
cup list-from-template <name> --template <id> [--space id] [--folder id]	テンプレートからリストを作成します
cup view-create <listId> <name> -t <type> [--group-by field]	リストにビューを作成します
cup view-update <viewId> [-n name] [--group-by field]	ビューを更新します
cup view-delete <viewId> [--confirm]	ビューを削除します（破壊的操作）
cup list-comment <listId> -m text [--notify-all] [--mention user]	リストにコメントを投稿します（--mention は実際の @メンション用です）
cup view-comment <viewId> -m text [--notify-all] [--mention user]	ビューにコメントを投稿します（--mention は実際の @メンション用です）
cup webhook create --url <url> --events <events> [--space|--folder|--list|--task <id>]	Webhook を作成します
cup webhook update <webhookId> [--url u] [--events e] [--status s]	Webhook を更新します
cup webhook delete <webhookId> [--confirm]	Webhook を削除します（破壊的操作）
cup merge <sourceTaskId> <intoTaskId> [--confirm]	タスクを別のタスクに統合します（破壊的操作。元のタスクは削除されます）
cup time estimate-by-user <taskId> <userId> <duration> [--replace]	ユーザーごとの時間見積もりを設定します
cup chat send <channelId> -m <text> [--post --title t]	チャンネルにメッセージを送信します
cup chat reply <messageId> -m <text>	メッセージに返信します
cup chat react <messageId> --emoji <name>	リアクションを追加します
cup chat unreact <messageId> --emoji <name>	リアクションを削除します
cup chat channel-create <name> [--private] [--topic t]	チャンネルを作成します
cup chat dm <userIds...>	ダイレクトメッセージを作成／開きます
cup chat channel-update <id> [--name n] [--topic t]	チャンネルを更新します
cup chat channel-delete <id> [--confirm]	チャンネルを削除します
cup chat message-update <messageId> -m <text>	メッセージを編集します
cup chat message-delete <messageId> [--confirm]	メッセージを削除します
cup favorite add <type> <id> [alias] [-n name]	ローカルのお気に入りを追加します
cup favorite remove <alias>	お気に入りを削除します
cup favorite list [--type t]	お気に入りを一覧表示します（種類による絞り込みも可能です）
cup profile list [--json]	すべてのプロファイルを一覧表示します
cup profile add <name>	新しいプロファイルを追加します（対話形式）
cup profile remove <name>	プロファイルを削除します
cup profile use <name>	デフォルトのプロファイルを設定します
cup config get <key> / set <key> <value> / path	設定を管理します
cup completion <shell>	シェル補完（bash/zsh/fish）

グローバルフラグ

フラグ	説明
-p, --profile <n>	このコマンドで特定のプロファイルを使用します
--json	JSON 出力を強制します（すべてのコマンドで使用できます）

-p は常に --profile であり、--parent ではありません。 グローバルの短縮フラグはサブコマンドの短縮フラグより優先されるため、cup create -p <taskId> は Profile "<taskId>" not found エラーになります。cup create --parent <taskId> を使用してください。

フラグと規約

トピック	詳細
タスク ID	ネイティブ（abc123def）またはカスタム（PROJ-123）。カスタム ID は PREFIX-DIGITS 形式で自動検出されます
タスク URL	タスク ID を受け付けるすべてのコマンドでは、ClickUp の完全な URL（https://app.clickup.com/t/<id> または https://app.clickup.com/t/<workspace>/<id>）も使用できます。ID は自動抽出されます
ビュー URL	ビュー ID を受け付けるすべてのコマンドでは、ClickUp ビューの完全な URL（https://app.clickup.com/<workspace>/v/<type>/<viewId>）も使用できます。ID は自動抽出されます
--status	あいまい一致：完全一致 > 前方一致 > 部分一致。一致結果は stderr に出力されます
--priority	名前（urgent、high、normal、low）または数値（1-4）
--due-date	YYYY-MM-DD（日付のみ）、YYYY-MM-DDTHH:MM（時刻付き）、またはオフセット付きの完全な ISO 8601。時刻を含む形式では、ClickUp の due_date_time: true が設定されます
--assignee	ユーザー ID または me
--tags	カンマ区切り（例：--tags "bug,frontend"）
--time-estimate	期間："2h"、"30m"、"1h30m"、またはミリ秒の数値
--type	task（通常）またはカスタムタイプ名／ID（例：initiative、Bug）
--custom-item-id	cup create 用のカスタムタスクタイプ ID（cup task-types で確認できます）
--space	名前の部分一致または完全一致する ID
--name	大文字と小文字を区別しない部分一致
--all	自分に割り当てられたタスクだけでなく、ワークスペース内のすべてのタスクを表示します。tasks、search、overdue で使用できます。デフォルトでは自分のタスクのみです（エージェントのコンテキストウィンドウ向けに出力を小さくします）
--include-closed	クローズ済み／完了済みのタスクを含めます
作成時の --list	--parent が指定されている場合は省略可能です（自動検出されます）。疑似 ID sprint:current を受け付けます
cup field --set	対応する値：テキスト、数値、チェックボックス（true/false）、ドロップダウン（オプション名）、ラベル（カンマ区切りの名前）、日付（YYYY-MM-DD）、URL、メール、絵文字／評価（0-5）、手動進捗（0-100）、タスク／リレーションシップ（カンマ区切りのタスク ID）、ユーザー／メンバー（カンマ区切りのユーザー ID）。名前は大文字と小文字を区別せずに解決されます。エラー時には、利用可能なフィールド／オプションが一覧表示されます
cup field-create	drop_down 型と labels 型では --options "a,b,c" を使用します（必須）。その他の型では --options は不要です
--field フィルター	tasks と search で --field "Name" value を使用するには、フィールド名を ID に解決するために --list が必要です
--due-before/after	期限範囲の日付フィルター（YYYY-MM-DD）
--created-before/after	作成日範囲の日付フィルター（YYYY-MM-DD）
cup sprint	フォルダー名（sprint/iteration/cycle/scrum）からアクティブなスプリントを自動検出し、複数の日付形式を解析します。--folder <id>、cup config set sprintFolderId <id>、またはスプリントフォルダーのお気に入り登録で上書きできます
cup favorite	ローカルのみのお気に入りです（ClickUp とは同期されません）。タイプ：sprint-folder、space、list、folder、view、task。お気に入り登録した sprint-folder はスプリントコマンドで自動的に使用されます
cup link	両方の ID は同じタイプ（両方ともカスタム、または両方ともネイティブ）である必要があります
cup delete	破壊的な操作です。非対話モードでは --confirm が必要です。元に戻すことはできません
エラー	エラー時の終了コードは 1 です。cup auth --json（および CU_OUTPUT=json）では認証エラーが JSON として stdout に出力され、その他のエラーは stderr に出力されます。厳密な解析により、余分な引数や不明な引数は拒否されます
レート制限	クライアントは Retry-After に応じたバックオフで HTTP 429 を再試行します（最大 3 回）。一時的な 502/503/504 の再試行は GET/HEAD の読み取りに限定されます。ゲートウェイエラーまたは通信障害の後、変更操作は再実行されません。再試行する前にリモートの状態を確認してください。警告は stderr に出力されます
複数行の Markdown（-d / -m / フィールド値）	エージェントに最適： --description-file <path>／--message-file <path>／--value-file <path>（または標準入力の場合は -）を使用すると、シェルのクォートを完全に回避できます。下記の複数行の例を参照してください。インラインで複数行を指定する場合は、クォート付きヒアドキュメント "$(cat <<'EOF' … EOF)" を使用してください。バッククォート、改行、アポストロフィがそのまま保持されます。注意点： アポストロフィを含む $'...' 文字列を '\'' で分割しないでください。後続部分は通常のシングルクォートに戻り、\n が文字どおりのテキストになります（例：$'…team'\''s…\n## Goals' は正しく動作しません）。通常のダブルクォートではバッククォート内の文字列がコマンドとして実行されます。
--mention <user>	ClickUp の実際の @メンション（ユーザーに通知します）。ID、メールアドレス、ユーザー名、または me を指定できます。複数指定可能です。また、文中でメンションする場合は -m 内で <@userId> のインライントークンを使用できます。@Name のみの形式は（曖昧なため）解析されません。comment、reply、comment-edit、list-comment、view-comment で使用できます
コメント内のリンク	コメントのメッセージでは、URL（https://...）をそのまま記述した場合も、Markdown リンク（[text](url)）も、クリック可能なリンクとして表示されます。展開プレビューカードには対応していません（Web UI のみ対応）

注記： cup search、cup tasks、cup overdue、cup assigned は、デフォルトで現在のユーザーに割り当てられたタスクを対象とします。他のユーザーに割り当てられたタスクも含めるには、--all を使用してください。親イニシアチブやチーム全体の項目を検索する場合は、この点が重要です。

インタラクティブモード（TTY）

ターミナルで実行すると（パイプ経由ではない場合）、タスク一覧表示コマンド（cup tasks、cup search、cup sprint、cup overdue、cup assigned、cup inbox、cup summary）では、インタラクティブなタスクピッカーが表示されます。

• ↑/↓ または j/k でリストを移動します
• Space でタスクの選択を切り替えます
• Enter で確定し、選択したタスクの詳細を表示します
• 詳細を表示した後、ブラウザーでタスクを開くかどうかを尋ねられます

その他のインタラクティブなプロンプト：スプリントの選択（一致するものが複数ある場合）、ワークスペースの選択（cup init）、エージェントの選択（cup skill）、破壊的な操作の確認（cup delete、cup list-delete、cup folder-delete、cup space-delete、cup archive、cup view-delete、cup merge、cup webhook delete）。

パイプ経由で実行する場合、または --json を指定して呼び出す場合、すべてのコマンドはインタラクティブではない Markdown または JSON を出力します。エージェントは、構造化データには常に --json を使用し、Markdown にはパイプを使用してください。

エージェントのワークフロー例

タスクを調査する

cup task abc123def                   # markdown summary
cup subtasks abc123def               # child tasks (open only)
cup subtasks abc123def --include-closed  # all child tasks
cup comments abc123def               # discussion
cup activity abc123def               # task + comments combined

タスクを検索する

cup tasks --status "in progress"     # by status
cup tasks --name "login"             # by partial name
cup tasks --type initiative          # initiatives only
cup tasks --list 12345 --all         # all tasks in list, not just mine
cup tasks --tag "bug" --status "to do"  # by tag and status
cup tasks --list 123 --field "Sprint" "Week 1"  # by custom field
cup tasks --due-before 2026-04-01    # due before a date
cup tasks --assignee me --created-after 2026-03-01  # my tasks created recently
cup search "payment flow"            # multi-word search
cup search auth --status "prog"      # fuzzy status match
cup search "auth" --list 123 --space 456  # search within list and space
cup search --assignee me             # no query — all my tasks
cup search --assignee me --status "in progress"  # filter without query
cup sprint                           # current sprint
cup assigned                         # all my tasks by status
cup overdue                          # past due date
cup inbox --days 7                   # recently updated

変更を加える

cup update abc123def -s "done"
cup update abc123def --priority high --due-date 2025-03-15
cup update abc123def --due-date 2025-03-15T14:30     # date + time (user's timezone)
cup update abc123def --due-date 2025-03-15T14:30:00Z # UTC
cup create -n "Fix the thing" --parent abc123def   # -p is the global --profile, not --parent
cup create -n "Fix bug" -l <listId> --priority urgent --tags "bug,frontend"
cup create -n "Bug fix" -l sprint:current         # create in active sprint
cup create -n "Q3 Roadmap" -l <listId> --custom-item-id 1
cup create -n "New story" -l <listId> --field "Story Points" 5 --field "Stage" "In Review"
cup comment abc123def -m "Completed in PR #42"
cup comment abc123def -m "## Results\n\n**Passed**: 15/15\n- Unit tests\n- Integration"
cup assign abc123def --to me
cup assign abc123def --to 12345,67890        # assign multiple users at once
cup assign abc123def --group @mobile-team    # assign a user group (find handles with `cup groups`)
cup assign abc123def --to me --group @backend  # assign self and a group together
cup update abc123def --group-assignee @mobile-team   # group assignment via update
cup update abc123def --remove-group-assignee @backend
cup depend task3 --on task2            # task3 waits for task2
cup move task1 --to list2                        # add task1 to list2 (multi-list membership)
cup move task1 --to list2 --remove list1         # change home list from list1 to list2 (v3 home_list)
cup move task1 --to sprint:current --remove list1 # move home list to active sprint
cup field abc123def --set "Story Points" 5
cup tag abc123def --add "bug,frontend"
cup checklist create abc123def "QA Steps"
cup checklist add-item <clId> "Run unit tests"
cup checklist add-item <clId> "Sub step" --parent <itemId>           # nest under parent
cup checklist edit-item <clId> <itemId> --resolved
cup checklist edit-item <clId> <itemId> --parent <newParent>         # reparent (use "null" to unnest)
cup link abc123 def456
cup attach abc123def ./screenshot.png
cup time start abc123def -d "Working on feature"
cup time stop
cup time log abc123def 2h -d "Code review"
cup delete abc123def --confirm          # irreversible!

複数行の Markdown による説明とコメント

エージェントは、見出し、箇条書き、コード、アポストロフィを含む構造化された Markdown を生成します。主な失敗要因はシェルでの引用符の扱いです。堅牢な方法は次の 2 つです。

# 1. Best for agents: write markdown to a file, then reference it (no shell quoting at all)
cup create -n "Improve onboarding" -l <listId> --description-file /tmp/desc.md
cup update <taskId> --description-file /tmp/desc.md
cup comment <taskId> --message-file /tmp/comment.md
cup field <taskId> --set "Standup 4 - 6/25" --value-file /tmp/note.md
# "-" reads stdin:
printf '## Notes\n\nTeam'\''s update with `code`.' | cup update <taskId> --description-file -

# 2. Inline multiline: quoted heredoc preserves backticks, newlines, AND apostrophes
cup create -n "Improve onboarding" -l <listId> -d "$(cat <<'EOF'
## Overview

Refresh the team's onboarding docs. Use `init()` first.

## Goals

- Goal one
- Goal two
EOF
)"

$'…team'\''s…\n\n## Goals' は使用しないでください。'\'' でアポストロフィを挿入した後は、通常のシングルクォートに戻るため、\n が文字どおり渡され、見出しや箇条書きが ClickUp で \n\n というテキストとして表示されます。

ドキュメント

cup docs "design"                              # search docs
cup doc <docId> <pageId>                       # view page
cup doc-create "Architecture Notes" -c "# Draft"
cup doc-page-create <docId> "Section" --parent-page <pageId>
cup doc-page-edit <docId> <pageId> -c "# Updated"

エクスポート（ナレッジの引き継ぎ／退職時の移管）

各タスクは一度だけ保存され（tasks/<id>/task.json ＋ task.md ＋ コメント ＋ 添付ファイル）、スコープごとにインデックスが追加されます。複数のスライスを 1 つの --out ディレクトリにまとめられ、共有タスクは一度だけ取得されます。再実行時には、すでに存在する項目はスキップされます。

cup export user me --out ./archive                    # my tasks, incl. closed + archived
cup export team "Atlas" --out ./archive             # every list in a space
cup export roadmap <listId> --item-id 1004 --out ./archive   # initiatives grouped with subtask trees
cup export docs --out ./archive                       # every doc as markdown page trees
cup export all --dry-run                              # plan: counts, estimated time
cup export all --yes --out ./archive                  # whole workspace (long-running; confirms)

• --item-id はイニシアチブの custom_item_id です（チーム内の規約。cup task-types で一覧を確認できます）。
• all は、--yes を指定せずに非インタラクティブで実行することを拒否します。見積もりを確認するため、必ず最初に --dry-run を実行してください。
• ホワイトボード、ダッシュボード、自動化には API がありません。これらは UI から手動でエクスポートしてください。

ワークスペースの構成

cup spaces --name "Engineering"      # find space ID
cup folders <spaceId>                # folders with their lists
cup lists <spaceId>                  # lists in a space
cup space-create "New Space"         # create a space
cup folder-create <spaceId> "Q2"     # create a folder
cup list-create <spaceId> "Backlog"  # create a list
cup list-create <spaceId> "Sprint" --folder <folderId>
cup space-rename <spaceId> "Platform"   # rename a space
cup folder-rename <folderId> "Q3"       # rename a folder
cup list-rename <listId> "Sprint 12"    # rename a list
cup members                          # workspace members
cup groups                           # user groups/teams (for --group-assignee)
cup fields <listId>                  # custom fields on a list
cup task-types                       # custom task types
cup templates                        # task templates

目標

cup goals
cup goal-create "Ship v2" -d "Release version 2"
cup key-results g123
cup key-result-create g123 "API coverage" --type percentage --target 80
cup key-result-update kr456 --progress 60 --note "On track"

プロファイル

cup profile add personal             # add a profile (interactive)
cup profile list                     # list all profiles
cup profile use personal             # switch default
cup tasks -p work                    # use specific profile for one command

お気に入り

cup favorite add sprint-folder 12345 --name "Team Sprint"  # favorite a sprint folder
cup favorite add space 67890 eng                           # favorite a space with alias
cup favorite list                                          # list all favorites
cup favorite list --type sprint-folder                     # list only sprint folders
cup favorite remove eng                                    # remove by alias
cup sprint                                                 # auto-uses favorited sprint folder

スタンドアップ

cup summary                          # completed / in progress / overdue
cup summary --hours 48               # wider window

削除の安全性

重要：cup delete、cup list-delete、cup folder-delete、cup space-delete、cup merge、cup webhook delete を実行する前に、必ずユーザーに確認してください。これらは破壊的で、取り消せない操作です。--confirm フラグを使用する場合も、まず ID が正しいことをユーザーに確認してください。