Todoist

Overview

Todoist is an OpenClaw skill that wraps the todoist-ts-cli command line client so you can manage tasks, projects, labels, and comments from a terminal or an automated workflow. The skill is built on the official Todoist TypeScript SDK and exposes the same operations documented in the CLI usage. It focuses on repeatable task management actions such as listing tasks with filters, creating tasks with metadata, updating or completing tasks, and administering projects and labels. The skill is designed for both manual use in a shell and scripted automation in cron jobs, CI runners, or personal workflows.

What This Skill Is Good For

Use this skill when you want a fast, text based workflow for Todoist that does not require the web UI. It is well suited for daily inbox triage, batch scheduling, recurring maintenance tasks, and small automations that add or update tasks based on other tools. Because it is a CLI wrapper, you can compose it with other scripts, pipe data through it, and integrate it with a team workflow. It also works well for users who prefer keyboard driven task management and want to avoid context switching to the browser.

Requirements and Setup

The skill requires the todoist-ts-cli package at version 0.2.0 or newer. You must authenticate with a Todoist API token, which can be created in Todoist under Settings and Integrations. The CLI supports two authentication approaches:

• Set the environment variable TODOIST_API_TOKEN with your token.
• Run the CLI auth command with your token, which stores it for future use.

After authentication, the CLI can call the Todoist REST API on your behalf. Because this uses a real account token, treat it as a secret and avoid logging it. The skill assumes you already installed the CLI, and it does not install dependencies automatically. The official CLI documentation is the reference for parameters, and the OpenClaw skill follows that interface closely.

Core Task Commands

The CLI exposes a task command group that is the center of most workflows:

• tasks list supports filters by project, label, priority, and due date. This is the main command for daily review and inbox clean up. Filters like p1 and p2 let you focus on urgent items.
• tasks add creates a new task with content and optional metadata. You can set project, labels, priority, order, parent relationships, and due dates in one command.
• tasks update modifies an existing task by ID. Typical updates include new due dates, renaming, changing priority, or changing labels.
• tasks view returns the details for a specific task ID, which is useful before making updates or for inspection.
• tasks done completes a task by ID, allowing you to close work items from a script.
• tasks reopen reopens a completed task if it was closed too early.
• tasks move changes the project of a task, keeping project structure clean.
• tasks delete removes a task. This is best reserved for cleanup of duplicates or invalid items.
• tasks search finds tasks using Todoist search syntax, which is useful for fast lookup without a full list.

These commands are designed to be composable. A common pattern is to list with filters, inspect IDs, then update or complete tasks based on the list. Because commands work with explicit IDs, a safe workflow is to view a task before changing it in automation.

Project, Label, and Comment Management

The CLI also supports project and label administration so that you can keep taxonomy consistent:

• projects list shows available projects and their IDs.
• projects create and projects update create or modify projects.
• projects delete removes a project.
• labels list, labels create, labels update, and labels delete manage labels.

Comments are supported through comment commands:

• comments list returns comments for a task.
• comments create adds a new comment to a task for context or audit notes.
• comments update edits an existing comment.
• comments delete removes a comment.

These features are useful when you want a fully CLI driven workflow. You can create a project, add tasks, tag them with labels, and attach context in comments without leaving the terminal.

Example Workflow Patterns

A morning review workflow might look like this: list high priority tasks, then add one or two follow ups with due dates. If a task no longer matters, mark it done. If a task needs more context, add a comment with links or notes. This keeps the daily review tight and repeatable.

Another pattern is project setup. Create a project, then add tasks with labels and priorities. If you are importing tasks from another system, use tasks add with consistent labels so the list is searchable later. If you reorganize, move tasks into a different project and update labels rather than creating duplicates.

A third pattern is batch maintenance. Use tasks search to find tasks with a keyword or label, then update or complete them in a loop. Because the CLI is scriptable, this works well for periodic clean up.

Data Handling and Safety Notes

The skill uses your Todoist API token to read and write data. This gives it access to your tasks, projects, labels, and comments. Use a dedicated token for automation, store it in a secret manager or environment variable, and avoid checking it into source control. If you run scripts in shared environments, ensure only trusted users can access the token.

Because destructive actions like delete are supported, confirm task IDs before removing data. Consider using tasks view to inspect a task before applying updates or deletion. For automated workflows, you can add a dry run step that logs intended changes for review.

Reliability and API Limits

Todoist enforces API limits, and the CLI makes calls through the REST API. If you run large batch jobs, add retries and spacing between requests. For frequent automation, prefer incremental updates over bulk operations to keep usage predictable. If you see rate limit responses, slow down the request cadence and scope your queries.

Troubleshooting Tips

• If commands fail, check that TODOIST_API_TOKEN is set and valid.
• If list or search returns no results, verify your filter syntax and project names.
• If update fails, confirm the task ID and verify that the task exists.
• If you have authentication issues, re run the auth command or reset the token.

Summary

This skill provides a complete CLI interface to Todoist based on todoist-ts-cli and the official SDK. It covers task management, project and label administration, and comment workflows. By combining list, add, update, and search commands with careful handling of IDs, you can build reliable automations or operate Todoist from a keyboard first workflow. This makes it a strong fit for users who value speed, scriptability, and consistent task hygiene.

API Details and Limits

The Todoist REST API uses bearer token authentication. The CLI sends requests with your token in the authorization header and exchanges JSON payloads for tasks, projects, labels, and comments. The API documentation notes rate limits, so for heavy automation you should throttle or batch requests. When you build scripts around this skill, prefer incremental updates and avoid very large bursts of requests.