todoist-api

Files (3)

• SKILL.md
• completed-tasks.md · references/
• filters.md · references/

SKILL.md (first lines)

# Todoist CLI Skill

This skill provides procedural guidance for working with Todoist using the `td` CLI tool.

## Prerequisites

The `td` CLI must be installed and authenticated. Verify with:

```bash
td auth status
```

If td is not installed or not authenticated:
- **Not installed**: Tell the user to install with `npm install -g @doist/todoist-cli`
- **Not authenticated**: Tell the user to run `td auth login` to authenticate via OAuth

## Output Formats for Agents

For machine-readable output, use these flags:
- `--json` - Output as JSON array
- `--ndjson` - Output as newline-delimited JSON (one object per line)
- `--full` - Include all fields in JSON output (default shows essential fields only)

## Confirmation Requirement

**Before executing any destructive action, always ask the user for confirmation using AskUserQuestion or similar tool.** A single confirmation suffices for a logical group of related actions.

Destructive actions include:
- Deleting tasks, projects, sections, labels, or comments
- Completing tasks
- Updating existing resources
- Archiving projects

Read-only operations do not require confirmation.

## Quick Commands

| Command | Description |
|---------|-------------|
| `td add "text"` | Quick add with natural language parsing |
| `td today` | Tasks due today and overdue |
| `td upcoming [days]` | Tasks due in next N days (default: 7) |
| `td inbox` | Tasks in Inbox |
| `td completed` | Recently completed tasks |

### Quick Add Examples

```bash
td add "Buy milk tomorrow p1 #Shopping"
td add "Call dentist every monday @health"
td add "Review PR #Work /Code Review"
```

The quick add parser supports:
- Due dates: `tomorrow`, `next monday`, `Jan 15`
- Priority: `p1` (urgent) through `p4` (normal)
- Project: `#ProjectName`
- Section: `/SectionName`
- Labels: `@label1 @label2`

## Tasks

### List Tasks

```bash
td task list [options]
```

**Filters:**
- `--project <name>` - Filter by project name or id:xxx
- `--label <name>` - Filter by label (comma-separated for multiple)
- `--priority <p1-p4>` - Filter by priority
- `--due <date>` - Filter by due date (today, overdue, or YYYY-MM-DD)
- `--filter <query>` - Raw Todoist filter query
- `--assignee <ref>` - Filter by assignee (me or id:xxx)
- `--workspace <name>` - Filter to workspace
- `--personal` - Filter to personal projects only

**Output:**
```bash
td task list --json                    # JSON array
td task list --project "Work" --json   # Filtered JSON
td task list --all --json              # All tasks (no limit)
```

### View Task Details

```bash
td task view <ref>              # Human-readable
td task view <ref> --json       # JSON output
```

The ref can be a task name, partial match, or `id:xxx`.

### Create Task

**Quick add (natural language):**
```bash
td add "Task text with #Project @label tomorrow p2"
```

**Explicit flags:**
```bash
td task add --content "Task text" \
  --project "Work" \
  --due "tomorrow" \
  --priority p2 \
  --labels "urgent,review" \
  --description "Additional details"
```

**Options:**
- `--content <text>` - Task content (required)
- `--due <date>` - Due date (natural language or YYYY-MM-DD)
- `--deadline <date>` - Deadline date (YYYY-MM-DD)
- `--priority <p1-p4>` - Priority level
- `--project <name>` - Project name or id:xxx
- `--section <id>` - Section ID
- `--labels <a,b>` - Comma-separated labels

From intellectronica/agent-skills, CC0-1.0.

More from intellectronica/agent-skills