# todoist-ts-cli

> **⚠️ Unofficial CLI for Todoist**  
> Not affiliated with or endorsed by Doist.

A command-line interface for [Todoist](https://todoist.com) built on the official [@doist/todoist-api-typescript](https://www.npmjs.com/package/@doist/todoist-api-typescript) SDK.

## Installation

```bash
npm install -g todoist-ts-cli
```

Or run directly with npx:

```bash
npx todoist-ts-cli --help
```

## Quick Start

```bash
# Authenticate with your API token
todoist auth <your-api-token>

# View today's tasks (default command)
todoist

# Add a task
todoist add "Buy groceries" --due tomorrow --priority 1

# Complete a task
todoist done <task-id>
```

Get your API token at: https://todoist.com/app/settings/integrations/developer

## Commands

### Authentication

```bash
todoist auth <token>     # Save API token
todoist auth             # Check auth status
todoist logout           # Clear stored token
```

### Tasks

```bash
todoist                  # Show today's tasks (default)
todoist today            # Same as above
todoist tasks            # List tasks (today + overdue)
todoist tasks --all      # All tasks
todoist tasks -p "Work"  # Tasks in project
todoist tasks -f "p1"    # Filter query (priority 1)

todoist add "Task" -d "tomorrow" -P 1 -p "Work" -l "urgent"
todoist add "Task at top" -p "Work" --top
todoist add "Task at position 3" -p "Work" --order 3
todoist view <id>        # View task details
todoist update <id> --due "next week"
todoist done <id>        # Complete task
todoist reopen <id>      # Reopen completed task
todoist move <id> -p "Personal"  # Move to project
todoist delete <id>      # Delete task
todoist search "keyword" # Search tasks
```

### Projects

```bash
todoist projects         # List all projects
todoist project-add "New Project" --color blue
```

### Sections

```bash
todoist sections                    # List all sections
todoist sections -p "Work"          # Sections in project
todoist section-add "Q1" -p "Work"  # Create section
```

### Labels

```bash
todoist labels           # List all labels
todoist label-add "urgent" --color red
```

### Comments

```bash
todoist comments <taskId>              # List comments
todoist comment <taskId> "Note text"   # Add comment
```

## Options

Global flags available on all commands:

| Flag | Description |
|------|-------------|
| `-h, --help` | Show help |
| `-V, --version` | Show version number |
| `--no-color` | Disable colored output |
| `--json` | Output as JSON (where applicable) |

## Environment Variables

| Variable | Description |
|----------|-------------|
| `TODOIST_API_TOKEN` | API token for authentication |
| `NO_COLOR` | Disable colored output (any value) |

## Exit Codes

| Code | Meaning |
|------|---------|
| `0` | Success |
| `1` | Generic failure |
| `2` | Invalid usage (bad arguments) |
| `3` | Authentication failure |

## Examples

### Add task with all options

```bash
todoist add "Review PR" \
  --due "tomorrow 10am" \
  --priority 2 \
  --project "Work" \
  --label "dev" \
  --description "Check the new feature branch"

# Add task to a specific position in a project/section
todoist add "Triage inbox" --order top
todoist add "Triage inbox" --order 2
```

### Filter tasks by priority

```bash
todoist tasks -f "p1 | p2"  # Priority 1 or 2
todoist tasks -f "overdue"  # Overdue tasks
todoist tasks -f "@urgent"  # Tasks with label
```

### Export tasks to JSON

```bash
todoist tasks --all --json > tasks.json
```

### Scripting

```bash
# Add task and get ID
TASK_ID=$(todoist add "Test" --json | jq -r '.id')
echo "Created task: $TASK_ID"

# Complete it
todoist done $TASK_ID
```

## Development

```bash
git clone https://github.com/mjrussell/todoist-ts-cli
cd todoist-ts-cli
npm install
npm run build
node dist/cli.js --help
```

## License

MIT © [Matt Russell](https://github.com/mjrussell)

## Disclaimer

This is an unofficial tool created by the community. Todoist is a trademark of Doist Inc. This project is not affiliated with, endorsed by, or connected to Doist in any way.

This CLI uses the official Todoist TypeScript SDK but is not an official Doist product.