todoist-api

Todoist のワークフロー

日常的な操作には公式 CLI を使用してください。公開 API は、特定の連携や、インストール済み CLI のヘルプで確認した不足を補う場合にのみ使用してください。別の完全なクライアントを維持したり、ユーザーのアカウントや接続をひそかに切り替えたりしないでください。

利用できる機能を確認する

1. 要求された操作に対応する、すでに認証済みの Todoist コネクターがある場合は、そちらを優先してください。それ以外の場合は、td --version、td --help、td auth status を確認してください。
2. 公式パッケージは @doist/todoist-cli、実行ファイルは td です。インストールと認証はホストやアカウントの状態を変更するため、許可された場合にのみ実施してください。
3. コマンド引数、レポート、リポジトリにトークンを記載せず、OS の資格情報ストレージを使用してください。TODOIST_API_TOKEN は保存済みの資格情報より優先されます。表示されているアカウントや権限が想定と異なる場合は、値を表示せずに設定の有無を確認してください。
4. 読み取り専用の作業では、読み取り専用 OAuth を優先してください。CLI の認証メタデータは、外部から提供されたトークンが特定のスコープを持つ証明にはなりません。
5. 使用するサブコマンドのヘルプを事前に確認してください。構造化出力を優先し、人間向けに整形された表を解析したり、コマンド間でフラグが共通だと想定したりしないでください。

Doist は独自の CLI スキルを提供しています（td skill install universal、または該当するエージェント向けのターゲット）。利用できる場合は、網羅的なコマンド構文の確認に使用してください。インストールは任意であり、必須要件でも、エージェントの設定を変更する許可でもありません。このスキルでは、以下の解決、まとめての変更、照合のワークフローを追加します。

解決、実行、検証

td project list --json
td task list --project "Work" --json
td task view TASK_ID --json

名前は、アカウント／ワークスペース、プロジェクト、セクション、個人用か共有かのラベルといったコンテキスト内で解決してください。不透明な文字列の ID はそのまま保持してください。同じ名前が複数ある場合は候補を提示し、最初の候補を選ばないでください。tmp- のクライアント用プレースホルダーをサーバーエンドポイントに渡さないでください。

許可されたキャプチャ操作の簡単な例：

td add "Email Chris tomorrow at 09:00 #Work @follow-up p2"

作成されたタスクを読み取り、プロジェクト、ラベル、解析された日付／時刻、タイムゾーン、繰り返し設定を確認してください。自然言語の解析結果だけでは、意図した日付が保存された証明になりません。API の優先度番号と、ユーザー向けの p1 表記は異なります。番号をそのまま別の画面に転記せず、対応関係を確認してください。

編集する場合は、現在の状態を読み取り、インストール済みヘルプに従って要求された変更を適用し、影響を受けたフィールドを読み返してください。要求に合致する場合は、恒久的な削除ではなく完了にしてください。繰り返しタスクの1回分を完了する操作と、シリーズを終了する操作は異なります。返された次回の期限を確認してください。

まとめての編集と復旧

一括での完了、移動、コメント追加、削除を行う前に、API と一括操作を読んでください。明示的な ID のセットと予定する変更を固定し、事前に確認してから、変化するフィルターを再実行せず、そのセットに対して適用してください。既存のユーザー許可が計画をカバーする場合があります。CLI のフラグや計画ファイルによって、追加の許可が付与されることはありません。

成功を確認した操作、失敗を確認した操作、結果が不明な操作を記録した台帳を維持してください。書き込み後のタイムアウトは「不明」であり、何も起きなかった証拠ではありません。再試行する前に照合してください。部分的に完了したバッチ全体を最初からやり直したり、復旧時に重複排除 ID を再生成したりしないでください。

レポートと連携作業

完了した作業をレポートする場合は、タイムゾーンと期間を定義し、完了時刻と期限を区別してください。要求を満たすために必要な、返されたカーソルをすべてたどるか、結果が一部のみであることを明記してください。ページサイズを総件数と取り違えないでください。

Sync API、添付ファイル、テンプレート、アーカイブ済みリソース、移行作業では、現在のエンドポイント／SDK の仕様を確認してから、参考資料を使用してください。以前のカスタム Python CLI とそのフラグは削除されており、互換性を保つためのシムはありません。

見つけた内容や変更した内容、安定した ID またはプロバイダーから返されたリンク、実施した検証、未解決の結果、ページネーションの境界を報告してください。コマンド例だけを根拠に、接続、書き込み、レポートの成功を主張しないでください。

情報源と確認項目

2026-09-13 に、Todoist API v1 および公式 CLIに照らして確認しました。正確な構文については、インストール済みのヘルプと最新のエンドポイントドキュメントを引き続き正とします。

メンテナーの方へ：evals/scenarios.jsonのシナリオをエージェントのトレースに対して実行してください。これらは評価ケースであり、ライブテストを実施したという主張ではありません。