pp-clickup

ClickUp — Printing Press CLI

前提条件：CLI をインストールする

このスキルは clickup-pp-cli バイナリを使用します。このスキルのコマンドを実行する前に、CLI がインストールされていることを必ず確認してください。 インストールされていない場合は、先にインストールしてください。

1. Printing Press インストーラーを使用してインストールします。バイナリの既定の保存先は、macOS/Linux では $HOME/.local/bin、Windows では %LOCALAPPDATA%\Programs\PrintingPress\bin です。

   npx -y @mvanhorn/printing-press-library install clickup --cli-only
   

2. 確認します：clickup-pp-cli --version
3. このスキルを実行するエージェント／ランタイムの $PATH に、表示されたインストールディレクトリが含まれていることを確認します。

npx によるインストールに失敗した場合（Node がない、オフラインなど）は、Go を直接インストールする方法に切り替えてください（Go 1.26.6 以降が必要です）。この方法では $GOPATH/bin（既定では $HOME/go/bin）にインストールされるため、代わりにこのディレクトリを $PATH に追加してください。

go install github.com/mvanhorn/printing-press-library/library/project-management/clickup/cmd/clickup-pp-cli@latest

インストール後に --version が「command not found」と表示される場合、ランタイムから $PATH 上のバイナリディレクトリが見えていません。確認に成功するまで、スキルのコマンドを実行しないでください。

v2 リファレンス（Tasks、Spaces、Folders、Lists、Goals、Time Tracking、Webhooks、Comments、Custom Fields、Members、Templates、Views）全体で172個のエンドポイントと、v3 パブリック API（Chat、Docs、Audit Logs、ACLs）を利用できます。階層同期では、ワークスペースのツリー全体をローカルの SQLite に取り込み、オフライン検索や分析に利用できます。最上位の docs コマンドと chat コマンドを使えば、workspaces/<verb>-public の spec パスを覚えなくても、用途に合った動詞で操作できます。

この CLI を使用する場面

ClickUp の v2 および v3 の API 全体を対象にスクリプトを実行する場合、ワークスペース全体の階層を対象としたオフライン分析用にローカルの SQLite ストアを構築する場合、またはエージェントに MCP サーバーとして ClickUp を公開する場合は、clickup-pp-cli を使用してください。特に、時間追跡の集計、スプリントレポート、ウェブ UI ではできないタスクの一括操作に便利です。

独自の機能

これらの機能は、この API を扱うほかのツールでは利用できません。

積み重ねて活用できるローカル状態

• sync — ClickUp の階層全体を依存関係の順序（teams → spaces → folders → lists → tasks、teams → docs、teams → channels）に沿ってたどり、すべてのレコードをローカルの SQLite ストアに保存します。API 内のすべての親子関係を自動的にたどります。

  オフライン検索や分析、または ClickUp ワークスペースの全構造を対象とした複合クエリを実行する場合に使用してください。1つのコマンドでツリー全体を取り込めます。

  clickup-pp-cli sync --json --profile default
  

• sync — 「空の配列を含む認識済みのエンベロープ」と「認識できないレスポンス形式」を区別します。これにより、ある種類のリソースのレコードがゼロのテナントでも、クラッシュせずに同期できます。スペースのないワークスペースでは ClickUp が {"spaces":[]} を返しますが、元のフレームワークはこれを単一のレスポンスとして扱い、ラッパーを単一のレコードとして upsert しようとして、「missing id for space」というエラーで失敗していました。

  この機能がなければ、リソースコレクションが空のワークスペースでは同期がひそかに失敗し、ローカルストアが一部しか作成されません。

  clickup-pp-cli sync --resources space --profile default --json
  

エージェント向けのネイティブな機能

• docs — 仕様から派生した workspaces/docs/-public および workspaces/chat/get-channels のパスに代わり、慣用的な動詞（search、get、pages、page、listing、create、edit、send、react、reply、members、followers、messages）を使う、トップレベルの docs コマンドと chat コマンドです。エイリアスは合計約22個です。後方互換性のため、元の動詞は Cobra のエイリアスとして残しています。

  深くネストした workspaces ツリーを覚える代わりに、docs search、chat list、chat send を直接使えます。v3 エンドポイントに対するスクリプト作成で特に便利です。

  clickup-pp-cli docs search 9017321407 --json --profile default
  

• task attach — ローカルファイルを1つ以上、実際の multipart/form-data としてタスクにアップロードします（ファイルごとに1回 POST し、パートのフィールド名は attachment、MIME タイプはファイルごとに設定）。--custom-task-ids --team-id でカスタムタスク ID を指定でき、送信前にすべてのファイルを検証します。また、--dry-run を使うと送信せずにアップロード内容をプレビューできます。

  エージェントがローカルファイル（レポート、スクリーンショット、エクスポートデータ）を ClickUp タスクに追加する必要があるときに使います。

  clickup-pp-cli task attach abc123xyz ./report.pdf --dry-run --json
  

• task attachments — GET /v2/task/{id} からタスクの添付ファイルを行形式（id、title、extension、size、url、total_comments、resolved_comments、open_comments）で一覧表示します。カスタムタスク ID にも対応しています。

  未解決のレビューコメントが残っている添付ドキュメントを確認するときに使います。

  clickup-pp-cli task attachments abc123xyz --json
  

コマンドリファレンス

checklist — チェックリストを管理

• clickup-pp-cli checklist delete — タスクからチェックリストを削除します。
• clickup-pp-cli checklist edit — タスクのチェックリストの名前を変更するか、タスク上の他のチェックリストの上または下に表示されるように並べ替えます。

comment — コメントを管理

• clickup-pp-cli comment delete — タスクのコメントを削除します。
• clickup-pp-cli comment update — タスクのコメントの内容を置き換え、コメントを割り当て、コメントを解決済みとしてマークします。

folder — フォルダーを管理

• clickup-pp-cli folder delete — ワークスペースからフォルダーを削除します。
• clickup-pp-cli folder get — フォルダー内のリストを表示します。
• clickup-pp-cli folder update — フォルダーの名前を変更します。

goal — 目標を管理

• clickup-pp-cli goal delete — ワークスペースから目標を削除します。
• clickup-pp-cli goal get — ターゲットを含む目標の詳細を表示します。
• clickup-pp-cli goal update — 目標の名前を変更し、期限を設定し、説明を置き換え、オーナーを追加または削除して、目標の色を設定します。

group — グループを管理

• clickup-pp-cli group delete-team — このエンドポイントは、[ユーザーグループ](https://docs.clickup.com/en/articles/4010016-teams-how-to-create-user-... を削除するために使用します。
• clickup-pp-cli group get-teams1 — このエンドポイントは、[ユーザーグループ](https://docs.clickup.com/en/articles/4010016-teams-how-to-create-user-gro... を表示するために使用します。
• clickup-pp-cli group update-team — このエンドポイントは、[ユーザーグループ](https://docs.clickup.com/en/articles/4010016-teams-how-to-create-user-g... を管理するために使用します。

key-result — 主要な結果を管理

• clickup-pp-cli key-result delete — 目標からターゲットを削除します。
• clickup-pp-cli key-result edit — ターゲットを更新します。

list — リストを管理

• clickup-pp-cli list delete — ワークスペースからリストを削除します。
• clickup-pp-cli list get — リストに関する情報を表示します。
• clickup-pp-cli list update — リストの名前を変更し、リスト情報の説明を更新し、期限日時を設定し、リストの優先度を設定し、担当者を設定します。設定...

oauth — OAuthを管理

• clickup-pp-cli oauth — これらは、APIの認証とOAuthフローの実行に使用するルートです。アプリケーション...

space — スペースを管理

• clickup-pp-cli space delete — ワークスペースからスペースを削除します。
• clickup-pp-cli space get — ワークスペースで利用可能なスペースを表示します。
• clickup-pp-cli space update — スペースの名前と色を設定し、スペースのClickAppsを有効にします。

task — タスクを管理

• clickup-pp-cli task attach — 1つ以上のローカルファイルを添付ファイルとしてタスクにアップロードします（multipart/form-data）
• clickup-pp-cli task attachments — タスクの添付ファイルを、サイズ、URL、コメント数（合計／解決済み／未解決）とともに一覧表示します。
• clickup-pp-cli task delete — ワークスペースからタスクを削除します。
• clickup-pp-cli task get — タスクに関する情報を表示します。アクセスできるタスクの情報のみ表示できます。添付ファイルのあるタスク...
• clickup-pp-cli task get-bulk-timein-status — 2つ以上のタスクが各ステータスにどれくらいの期間あったかを表示します。最初に「Total time in Status」ClickAppを有効にする必要があります...
• clickup-pp-cli task update — リクエスト本文に1つ以上のフィールドを含めてタスクを更新します。

team — チームを管理

• clickup-pp-cli team — 認証済みユーザーが利用できるワークスペースを表示します。

user — ユーザーを管理

• clickup-pp-cli user — 認証済みユーザーのClickUpアカウントの詳細を表示します。

view — ビューを管理

• clickup-pp-cli view delete — ビューを削除します。
• clickup-pp-cli view get — 特定のタスクビューまたはページビューに関する情報を表示します。返されるビュー情報は、ビューの種類によって異なります。
• clickup-pp-cli view update — ビューの名前を変更し、グループ化、並べ替え、フィルター、列、設定を更新します。

webhook — Webhookを管理

• clickup-pp-cli webhook delete — Webhookのイベントと場所の監視を停止するため、Webhookを削除します。
• clickup-pp-cli webhook update — 監視対象のイベントを変更するため、Webhookを更新します。

workspaces — ワークスペースを管理

適切なコマンドを見つける

やりたいことは分かっていても、それを実行するコマンドが分からない場合は、CLI に直接尋ねてください。

clickup-pp-cli which "<capability in your own words>"

which は、自然言語による機能の問い合わせを、この CLI の厳選された機能インデックスから最も一致するコマンドに解決します。終了コード 0 は少なくとも 1 件一致したことを、終了コード 2 は確度の高い一致がなかったことを示します。その場合は --help に切り替えるか、より絞り込んだ問い合わせを使用してください。

レシピ

ワークスペースからタスクまで掘り下げる

clickup-pp-cli team space get <team_id> --json --profile default

ワークスペース内のすべてのスペース ID を取得します。さらに掘り下げるには、space folder get または space list get-folderless にパイプで渡します。

エージェントのコンテキスト向けコンパクト JSON

clickup-pp-cli task get <task_id> --select id,name,status.status,assignees --profile default --agent

--agent は、--json --compact --no-input --no-color --yes を 1 つのフラグで有効にします。--select は重要度の高いフィールドに絞り込むため、情報量の多いタスクでも応答を 1 KB 未満に抑えられます。

v3 エイリアス経由でチャットメッセージを送信する

clickup-pp-cli workspaces chat create-message <team_id> <channel_id> --type message --content "shipped: rate-limit fix" --json --profile default

曖昧さのない完全なパスです。短い chat send エイリアスも同じエンドポイントに対応しています。ClickUp は新しいメッセージ ID を .data.id に返します。これは chat react／chat reply で使用できます。

同期済みタスクのローカル分析

clickup-pp-cli analytics --type task --json --profile default

ローカルの SQLite ストアを対象に集計します。同期後は API 呼び出しは不要です。件数の取得と基本的なグループ化には対応していますが、ネストされたパスによるグループ化（status.status）は既知のフレームワークの制限です。

カスタム ID でローカルファイルをタスクに添付する

clickup-pp-cli task attach PROJ-123 ./report.pdf --custom-task-ids --team-id 1234567 --agent

report.pdf を multipart/form-data としてアップロードします。送信せずに URL、MIME タイプ、サイズを確認するには、最初に --dry-run を追加してください。

未解決のレビューコメントがある添付ファイルを見つける

clickup-pp-cli task attachments PROJ-123 --custom-task-ids --team-id 1234567 --json --select title,total_comments,resolved_comments,open_comments

open_comments = total - resolved です。コメントの本文は公開 API では公開されず、件数のみ取得できます。

認証の設定

ClickUp は、個人用 API トークン（pk_...）と OAuth ベアラートークンの両方を Authorization ヘッダー経由で受け付けます。シェルまたは ~/.config/clickup-pp-cli/config.toml で CLICKUP_AUTHORIZATION_TOKEN を設定してください。clickup-pp-cli doctor を実行すると、認証と API への接続を確認できます。

エージェントモード

任意のコマンドに --agent を追加してください。次のオプションが有効になります：--json --compact --no-input --no-color --yes。

• パイプで渡せます — JSON は stdout に、エラーは stderr に出力されます

• フィルタリングできます — --select でフィールドを絞り込めます。ドット区切りのパスはネストされた構造をたどり、配列では各要素をたどります。応答が冗長な API でコンテキストを小さく保つうえで重要です。

  clickup-pp-cli folder get mock-value --agent --select id,name,status
  

• プレビューできます — --dry-run は送信せずにリクエストを表示します

• オフラインでも使いやすいです — 同期／検索コマンドは、利用可能な場合にローカルの SQLite ストアを使用できます

• 非対話型です — プロンプトは表示されず、すべての入力はフラグで指定します

• 再試行の動作を明示できます — すでに存在する項目の作成を成功として扱う場合にのみ --idempotent を、削除対象が見つからない場合に成功として扱う場合にのみ --ignore-missing を使用してください

応答エンベロープ

ローカルストアまたは API から読み取るコマンドは、出力を出所情報のエンベロープでラップします。

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

データの解析には .results を、ライブデータかローカルデータかの確認には .meta.source を使用してください。人が読める N results (live) という概要は、stdout がターミナルの場合にのみ stderr に出力されます。パイプ／エージェントの利用者には、stdout に純粋な JSON が出力されます。

エージェントからのフィードバック

あなた（またはエージェント）がこの CLI の問題に気付いたら、記録してください。

clickup-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
clickup-pp-cli feedback --stdin < notes.txt
clickup-pp-cli feedback list --json --limit 10

記録はローカルの ~/.clickup-pp-cli/feedback.jsonl に保存されます。CLICKUP_FEEDBACK_ENDPOINT が設定され、さらに --send が渡されるか CLICKUP_FEEDBACK_AUTO_SEND=true の場合を除き、POST されることはありません。デフォルトではローカルにのみ保存されます。

バグ報告ではなく、意外だったことを書いてください。短く、具体的に、1 行で。それが積み重なっていきます。

出力の配信

すべてのコマンドで --deliver <sink> を指定できます。出力は標準出力に加えて、または標準出力の代わりに指定したシンクへ送られるため、エージェントはコマンド結果を手作業でパイプに渡さずにルーティングできます。次の3つのシンクに対応しています。

シンク	動作
stdout	デフォルト。標準出力にのみ書き込みます
file:<path>	出力を <path> にアトミックに書き込みます（一時ファイルを作成してから名前を変更）
webhook:<url>	出力本文を URL に POST します（--compact を指定した場合は application/json または application/x-ndjson）

不明なスキームは、対応しているスキームの一覧を示す構造化エラーを返して拒否されます。Webhook に失敗すると、ゼロ以外の終了コードを返し、URL と HTTP ステータスを標準エラー出力に記録します。

名前付きプロファイル

プロファイルは、呼び出しのたびに再利用できるフラグ値の保存セットです。スケジュールされたエージェントが毎回同じ設定で同じコマンドを呼び出す場合に使用します。これは HeyGen の「Beacon」パターンです。

clickup-pp-cli profile save briefing --json
clickup-pp-cli --profile briefing folder get mock-value
clickup-pp-cli profile list --json
clickup-pp-cli profile show briefing
clickup-pp-cli profile delete briefing --yes

明示的に指定したフラグは常にプロファイルの値より優先され、プロファイルの値はデフォルト値より優先されます。agent-context は、実行時にエージェントが利用可能なプロファイルを確認できるよう、available_profiles の下にすべてのプロファイルを一覧表示します。

終了コード

コード	意味
0	成功
2	使用方法のエラー（引数が正しくありません）
3	リソースが見つかりません
4	認証が必要です
5	API エラー（上流の問題）
7	レート制限中（待機して再試行してください）
10	設定エラー

引数の解析

$ARGUMENTS を解析します。

1. 空、help、または --help → clickup-pp-cli --help の出力を表示します
2. install で始まる → mcp で終わる場合は MCP をインストールします。それ以外の場合は、上記の前提条件を参照してください
3. その他すべて → 直接使用（--agent を付けて CLI コマンドを実行します）

MCP サーバーのインストール

この CLI の公開済みパブリックライブラリエントリまたはビルド済みリリースから MCP バイナリをインストールし、登録します。

claude mcp add clickup-pp-mcp -- clickup-pp-mcp

確認：claude mcp list

直接使用

1. インストール済みか確認します：which clickup-pp-cli 見つからない場合は、インストールを提案します（このスキルの最初にある前提条件を参照してください）。
2. ユーザーのクエリに最適なコマンドを、上記の独自機能とコマンドリファレンスから選びます。
3. --agent フラグを付けて実行します。

   clickup-pp-cli <command> [subcommand] [args] --agent
   

4. あいまいな場合は、サブコマンドのヘルプを確認します：clickup-pp-cli <command> --help。