# Todoist on boxd

> Todoist is a task management tool allowing users to create to-do lists, set deadlines, and collaborate on projects with reminders and cross-platform syncing.

- Page: https://boxd.sh/integrations/todoist/
- CLI: `run todoist` (84 commands, 53 marked common)
- SDK: `import { todoist } from "@boxd/run"`; every parameter and response type is at `@boxd/run/todoist`
- Triggers: 1
- Connect: `run auth todoist` (Sign in with Todoist), or https://app.boxd.sh/integrations/detail/todoist
- All integrations: https://boxd.sh/integrations/ (Markdown: https://boxd.sh/integrations/index.md)

## From the shell

```sh
run auth todoist      # once: prints a link to connect your account
run todoist           # list its commands
run todoist get-user
```

Parameters are flags (`--flag value`); object and array parameters take a JSON string. Output is YAML, or JSON with `--json`. Calls use your own connection; `--scope <name>` uses a connection shared with your team.

## From a script

```ts
import { todoist } from "@boxd/run";

const result = await todoist.getUser();
console.log(result);

todoist.on("new-task-created", async (event) => {
  // New Task Created: runs on this machine, once per event
  console.log(event);
});
```

Run it with `run todoist.run.ts`. A script that calls `.on()` keeps running as a job and handles each event.

## Commands

Required flags are listed; `run todoist <command> --help` lists the optional ones. "common" marks what `run todoist` shows without `--all`.

| Command | SDK method | Required flags | Optional | Description |
|---|---|---|---|---|
| `add-workspace` ·common | `todoist.addWorkspace()` | `--name` | 4 | Create a new workspace in Todoist |
| `archive-project2` ·common | `todoist.archiveProject2()` | `--project-id` | 0 | Archive a project using Todoist API v1 |
| `bulk-create-tasks` ·common | `todoist.bulkCreateTasks()` | `--tasks` | 0 | Create many tasks in one request using Todoist's Sync batching |
| `close-task` ·common ·deprecated | `todoist.closeTask()` | `--task-id` | 0 | Use close-task-v1 instead |
| `close-task-v1` ·common | `todoist.closeTaskV1()` | `--task-id` | 0 | Close (complete) a task in Todoist using API v1 |
| `create-comment-v1` ·common | `todoist.createCommentV1()` | `--content` | 4 | Create a new comment on a project or task using Todoist API v1 |
| `create-label` ·common ·deprecated | `todoist.createLabel()` | `--name` | 3 | Use create-label-v1 instead |
| `create-label-v1` ·common | `todoist.createLabelV1()` | `--name` | 3 | Create a new personal label using API v1 |
| `create-project` ·common ·deprecated | `todoist.createProject()` | `--name` | 4 | Use TODOIST_TODOIST_CREATE_PROJECT2 instead |
| `create-project2` ·common | `todoist.createProject2()` | `--name` | 6 | Create a new project in Todoist using the unified API v1 |
| `create-section` ·common ·deprecated | `todoist.createSection()` | `--name` `--project-id` | 1 | Use create-section-v1 instead |
| `create-section-v1` ·common | `todoist.createSectionV1()` | `--name` `--project-id` | 1 | Create a new section within a project using API v1 |
| `create-task` ·common | `todoist.createTask()` | `--content` | 14 | Create a new task in Todoist using the unified API v1 |
| `delete-comment` ·common | `todoist.deleteComment()` | `--comment-id` | 0 | Delete a specific comment from Todoist by its ID |
| `delete-label-v1` ·common | `todoist.deleteLabelV1()` | `--label-id` | 0 | Delete a personal label using API v1 |
| `delete-project2` ·common | `todoist.deleteProject2()` | `--project-id` | 0 | Delete a project and all of its sections and tasks using Todoist API v1 |
| `delete-section2` ·common | `todoist.deleteSection2()` | `--section-id` | 0 | Delete a section and all tasks within it |
| `delete-task` ·common | `todoist.deleteTask()` | `--task-id` | 0 | Delete a specific task from Todoist |
| `delete-task-v1` ·common ·deprecated | `todoist.deleteTaskV1()` | `--task-id` | 0 | Use delete-task instead |
| `delete-upload` ·common | `todoist.deleteUpload()` | `--file-url` | 0 | Delete an uploaded file from Todoist |
| `export-template-as-file` | `todoist.exportTemplateAsFile()` | `--project-id` | 1 | Export a Todoist project as a CSV template file |
| `export-template-as-url` ·common | `todoist.exportTemplateAsUrl()` | `--project-id` | 1 | Export a Todoist project as a shareable template URL |
| `filter-tasks` ·common | `todoist.filterTasks()` | `--query` | 3 | Get all tasks matching the filter |
| `get-all-comments` ·common | `todoist.getAllComments()` | — | 2 | This tool retrieves all comments associated with a specific task or project in Todoist |
| `get-all-projects` ·common | `todoist.getAllProjects()` | — | 2 | Get all projects from a user's Todoist account |
| `get-all-tasks` ·common | `todoist.getAllTasks()` | — | 5 | Fetches all INCOMPLETE tasks from Todoist and returns their details |
| `get-backups` ·common | `todoist.getBackups()` | — | 0 | List all available backup archives for the user |
| `get-comment-v1` | `todoist.getCommentV1()` | `--comment-id` | 0 | Retrieve a single comment by ID using the v1 API |
| `get-completed-tasks-by-completion-date` ·common | `todoist.getCompletedTasksByCompletionDate()` | `--since` `--until` | 8 | Retrieve completed tasks within a specified completion date window |
| `get-id-mappings` | `todoist.getIdMappings()` | `--obj-ids` `--obj-name` | 0 | Translate IDs between Todoist API v1 and v2 |
| `get-personal-label` ·common | `todoist.getPersonalLabel()` | `--label-id` | 0 | Retrieve a personal label by its ID |
| `get-productivity-stats` ·common | `todoist.getProductivityStats()` | — | 0 | Retrieve comprehensive productivity statistics for the authenticated user |
| `get-project` ·common | `todoist.getProject()` | `--project-id` | 0 | Retrieve a specific project by its ID using Todoist API v1 |
| `get-project-full` ·common | `todoist.getProjectFull()` | `--project-id` | 0 | Retrieve full project data including all sections, tasks, and collaborators |
| `get-project-permissions` | `todoist.getProjectPermissions()` | — | 0 | Retrieve all available roles and their associated actions in Todoist projects |
| `get-section-v1` | `todoist.getSectionV1()` | `--section-id` | 1 | Retrieve a specific section by its ID using Todoist v1 API |
| `get-special-backups` ·common | `todoist.getSpecialBackups()` | — | 0 | List special backup archives for the authenticated user's projects |
| `get-task` ·common ·deprecated | `todoist.getTask()` | `--task-id` | 0 | Use get-task2 instead |
| `get-task2` | `todoist.getTask2()` | `--task-id` | 1 | Retrieve a single active (non-completed) task by ID using API v1 |
| `get-user` ·common | `todoist.getUser()` | — | 0 | Retrieve information about the currently authenticated user |
| `get-workspace-plan-details` | `todoist.getWorkspacePlanDetails()` | `--workspace-id` | 0 | Retrieve details about a workspace's current plan and usage |
| `import-template-into-project-by-id` | `todoist.importTemplateIntoProjectById()` | `--project-id` `--template-id` | 1 | Import a template from Todoist's template gallery into an existing project |
| `import-template-into-project-from-file` | `todoist.importTemplateIntoProjectFromFile()` | `--file` `--project-id` | 0 | Import a CSV template into an existing Todoist project from a file |
| `invite-project-collaborator` ·common | `todoist.inviteProjectCollaborator()` | `--email` `--project-id` | 1 | Invite a collaborator to a Todoist project by email |
| `list-activities` | `todoist.listActivities()` | — | 18 | Get activity logs from Todoist |
| `list-all-invitations-workspaces` | `todoist.listAllInvitationsWorkspaces()` | `--workspace-id` | 0 | Return a list containing details of all pending invitations to a workspace |
| `list-archived-projects` | `todoist.listArchivedProjects()` | — | 2 | Get all archived projects from Todoist |
| `list-archived-sections` | `todoist.listArchivedSections()` | `--project-id` | 0 | Retrieve all archived sections for a specific project in Todoist |
| `list-archived-workspace-projects` ·common | `todoist.listArchivedWorkspaceProjects()` | — | 5 | List all archived projects in a workspace |
| `list-completed-tasks` ·common | `todoist.listCompletedTasks()` | — | 3 | Retrieve all completed tasks with optional project filtering |
| `list-completed-tasks-by-due-date` | `todoist.listCompletedTasksByDueDate()` | `--since` `--until` | 8 | Retrieve completed tasks within a specified due date range (up to 6 weeks) |
| `list-filters` ·common | `todoist.listFilters()` | — | 1 | List all filters for the authenticated user |
| `list-joinable-workspaces` | `todoist.listJoinableWorkspaces()` | — | 0 | Get workspaces the user can join |
| `list-labels` ·common | `todoist.listLabels()` | — | 2 | Get all user labels with pagination support |
| `list-pending-workspace-invitations` | `todoist.listPendingWorkspaceInvitations()` | `--workspace-id` | 0 | List pending invitation emails in a workspace |
| `list-project-collaborators` ·common | `todoist.listProjectCollaborators()` | `--project-id` | 3 | Get all collaborators for a given project with cursor-based pagination |
| `list-sections` ·common | `todoist.listSections()` | — | 3 | Get all active sections for the user, with optional filtering by project |
| `list-shared-labels` | `todoist.listSharedLabels()` | — | 3 | Retrieve shared label names from active tasks with pagination support |
| `list-workspace-active-projects` ·common | `todoist.listWorkspaceActiveProjects()` | — | 3 | List all active workspace projects |
| `list-workspace-archived-projects` | `todoist.listWorkspaceArchivedProjects()` | — | 3 | Get archived projects in a workspace |
| `list-workspace-invitations` | `todoist.listWorkspaceInvitations()` | `--workspace-id` | 0 | List user emails with pending invitations to a workspace |
| `list-workspace-users` | `todoist.listWorkspaceUsers()` | — | 3 | List users in workspace(s) |
| `move-task` ·common | `todoist.moveTask()` | `--task-id` | 3 | Move a task to another project, section, or parent task while preserving task identity and metadata |
| `move-task-rest-api` | `todoist.moveTaskRestApi()` | `--task-id` | 3 | Move a task to another project, section, or parent task using the REST API |
| `quick-add-task` ·common | `todoist.quickAddTask()` | `--text` | 4 | Add tasks using natural language parsing similar to the official Todoist clients |
| `remove-shared-label-v1` | `todoist.removeSharedLabelV1()` | `--name` | 0 | Remove a shared label from all active tasks using API v1 |
| `rename-shared-labels-v1` | `todoist.renameSharedLabelsV1()` | `--name` `--new-name` | 0 | Rename a shared label across all active tasks using API v1 |
| `reopen-task2` ·common | `todoist.reopenTask2()` | `--task-id` | 0 | Reopen a completed task in Todoist using API v1 |
| `reorder-tasks` ·common | `todoist.reorderTasks()` | `--items` | 0 | Reorder tasks deterministically by updating child_order in bulk via the Sync API item_reorder command |
| `search-labels` | `todoist.searchLabels()` | `--query` | 2 | Search user labels by name with case-insensitive matching |
| `search-projects` ·common | `todoist.searchProjects()` | `--query` | 2 | Search active user projects by name with support for wildcards and pagination |
| `search-sections` ·common | `todoist.searchSections()` | `--query` | 3 | Search active sections by name, optionally filtered by project |
| `sync` | `todoist.sync()` | `--sync-token` | 2 | Sync data with Todoist server, supporting both read and write operations |
| `unarchive-project2` ·common | `todoist.unarchiveProject2()` | `--project-id` | 0 | Unarchive a previously archived Todoist project using API v1 |
| `update-comment2` | `todoist.updateComment2()` | `--comment-id` `--content` | 0 | Update a comment by ID and return its content via v1 API |
| `update-label-v1-second` | `todoist.updateLabelV1Second()` | `--label-id` | 4 | Update an existing label using API v1 |
| `update-notification-setting` | `todoist.updateNotificationSetting()` | `--dont-notify` `--notification-type` `--service` | 1 | Update notification settings for the current user |
| `update-project` ·common ·deprecated | `todoist.updateProject()` | `--project-id` | 4 | Use TODOIST_TODOIST_UPDATE_PROJECT2 instead |
| `update-project2` ·common | `todoist.updateProject2()` | `--project-id` | 5 | Update a project's properties using Todoist API v1 |
| `update-section` ·deprecated | `todoist.updateSection()` | `--section-id` | 1 | Use TODOIST_TODOIST_UPDATE_SECTION2 instead |
| `update-section2` | `todoist.updateSection2()` | `--section-id` | 1 | Update an existing section by its ID using Todoist v1 API |
| `update-task` ·common | `todoist.updateTask()` | `--task-id` | 12 | Update an existing task's properties |
| `update-workspace-logo` | `todoist.updateWorkspaceLogo()` | `--workspace-id` | 2 | Upload an image as the workspace logo or delete the existing logo |
| `upload-file` ·common | `todoist.uploadFile()` | `--file` | 1 | Upload a file to Todoist |

## Triggers

`todoist.on("<event>", handler)` in a script; required config goes before the handler as an object.

| Event | Name | Required config | Description |
|---|---|---|---|
| `"new-task-created"` | New Task Created | — | Trigger when a new task is added to Todoist |

## Docs

- [run CLI](https://docs.boxd.sh/cli/run): Call connected integrations from the shell, connect new ones, and run automations.
- [Quickstart](https://docs.boxd.sh/guides/integrations/quickstart): Connect an integration, call it from the shell, and turn a script into an automation.
- [Connections](https://docs.boxd.sh/guides/integrations/connections): Connect an account once, for yourself or for your whole organization.
- [Scripts](https://docs.boxd.sh/guides/automations/scripts): Typed integrations, triggers, schedules and state in a .run.ts file.
- [Jobs](https://docs.boxd.sh/guides/automations/jobs): How a script becomes a background job: states, retries, sleep and wake.
- [Beyond the catalog](https://docs.boxd.sh/guides/automations/beyond-the-catalog): Reach your own APIs, databases and cloud accounts from a script.