### Development Setup for todoist-ts-cli

Source: https://github.com/mjrussell/todoist-ts-cli/blob/main/README.md

Instructions for cloning the repository, installing dependencies, building the project, and running the CLI locally.

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

--------------------------------

### Install todoist-ts-cli

Source: https://github.com/mjrussell/todoist-ts-cli/blob/main/README.md

Installs the todoist-ts-cli globally using npm or allows direct execution with npx.

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

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

--------------------------------

### Example: Scripting with todoist-ts-cli

Source: https://github.com/mjrussell/todoist-ts-cli/blob/main/README.md

Provides examples of using the CLI in scripts, such as adding a task and capturing its ID for further operations, or completing a task.

```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
```

--------------------------------

### Install and Authenticate Todoist CLI

Source: https://context7.com/mjrussell/todoist-ts-cli/llms.txt

Instructions for installing the CLI globally or running it via npx, and setting up authentication using an API token via environment variables or the auth command.

```bash
npm install -g todoist-ts-cli
npx todoist-ts-cli --help
todoist auth YOUR_API_TOKEN
export TODOIST_API_TOKEN=YOUR_API_TOKEN
todoist auth
```

--------------------------------

### Example: Add task with all options

Source: https://github.com/mjrussell/todoist-ts-cli/blob/main/README.md

Demonstrates adding a task with numerous options including due date, deadline, priority, project, label, assignee, and description.

```bash
todoist add "Review PR" \
  --due "tomorrow 10am" \
  --deadline "2026-03-05" \
  --priority 2 \
  --project "Work" \
  --label "dev" \
  --assign "user-id" \
  --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

# Assign task in a shared project
todoist add "Review PR" -a "123456789"  # Use collaborator ID
```

--------------------------------

### Example: Move task to a section

Source: https://github.com/mjrussell/todoist-ts-cli/blob/main/README.md

Illustrates moving a task to a specific section within a project.

```bash
todoist move <id> -p "Work" -s "Section A"
```

--------------------------------

### Example: Export tasks to JSON

Source: https://github.com/mjrussell/todoist-ts-cli/blob/main/README.md

Demonstrates exporting all tasks to a JSON file using the --json flag and shell redirection.

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

--------------------------------

### Example: Update task deadlines

Source: https://github.com/mjrussell/todoist-ts-cli/blob/main/README.md

Demonstrates setting a specific deadline for a task and clearing an existing deadline.

```bash
todoist update <id> --deadline "2026-03-05"
todoist update <id> --deadline none  # clear
```

--------------------------------

### Example: Filter tasks by priority

Source: https://github.com/mjrussell/todoist-ts-cli/blob/main/README.md

Shows how to filter tasks based on priority, labels, or status like 'overdue'.

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

--------------------------------

### Example: Update task labels

Source: https://github.com/mjrussell/todoist-ts-cli/blob/main/README.md

Shows how to replace all existing labels on a task or apply incremental changes by adding and removing labels.

```bash
# Replace all labels
todoist update <id> --labels "next,waiting"

# Or apply incremental changes
todoist update <id> --add-label next --remove-label waiting
```

--------------------------------

### Process Tasks with jq

Source: https://context7.com/mjrussell/todoist-ts-cli/llms.txt

Processes all Todoist tasks exported as JSON using `jq`. This example filters tasks to select those with a priority of 4 and then extracts their content. It demonstrates piping the JSON output to `jq` for advanced filtering and manipulation.

```bash
todoist tasks --all --json | jq '.[] | select(.priority == 4) | .content'
```

--------------------------------

### Search Tasks by Keyword

Source: https://context7.com/mjrussell/todoist-ts-cli/llms.txt

Find tasks across all projects by specifying keywords. The `--json` flag can be used to get results in JSON format for easier parsing in scripts.

```bash
# Search tasks
todoist search "bug fix"
todoist search "meeting notes"

# JSON output for processing
todoist search "project alpha" --json

# Example output:
# 8590123456  Fix login bug (today)
# 8590123457  Bug triage meeting (tomorrow)
```

--------------------------------

### Manage Todoist Projects

Source: https://github.com/mjrussell/todoist-ts-cli/blob/main/README.md

Commands for listing all projects and adding new projects with optional color customization.

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

--------------------------------

### Manage Projects (List and Create)

Source: https://context7.com/mjrussell/todoist-ts-cli/llms.txt

View a list of all your Todoist projects or create new ones. New projects can be created with an optional color. JSON output is available for scripting.

```bash
# List all projects
todoist projects
# Output:
# 2334567890  Inbox (Inbox)
# 2334567891  Work
# 2334567892  Personal

# JSON output
todoist projects --json

# Create new project
todoist project-add "Q1 Goals"

# Create project with color
todoist project-add "Side Project" --color blue

# JSON output for new project
todoist project-add "New Initiative" --json

# Example output:
# ✓ Created project: Q1 Goals
#   ID: 2334567893
```

--------------------------------

### Todoist CLI Global Options

Source: https://github.com/mjrussell/todoist-ts-cli/blob/main/README.md

Global flags available on all commands, including help, version, color control, and JSON output.

```bash
# Show help
-h, --help

# Show version number
-V, --version

# Disable colored output
--no-color

# Output as JSON (where applicable)
--json
```

--------------------------------

### Manage Todoist Sections

Source: https://github.com/mjrussell/todoist-ts-cli/blob/main/README.md

Commands for listing sections within a project and creating new sections.

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

--------------------------------

### Manage Todoist Labels

Source: https://github.com/mjrussell/todoist-ts-cli/blob/main/README.md

Commands for listing all labels and adding new labels with optional color customization.

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

--------------------------------

### Configure Global Options (CLI)

Source: https://context7.com/mjrussell/todoist-ts-cli/llms.txt

Demonstrates configuring global options for the Todoist CLI, such as disabling colored output via a flag or environment variable, and showing the version or help information. These options affect all subsequent commands.

```bash
# Disable colored output
todoist --no-color tasks
todoist tasks --no-color

# Via environment variable
NO_COLOR=1 todoist tasks

# Show version
todoist --version
todoist -V

# Show help
todoist --help
todoist -h
todoist add --help
```

--------------------------------

### Manage Sections (List and Create)

Source: https://context7.com/mjrussell/todoist-ts-cli/llms.txt

List sections within projects or create new ones to organize tasks. Sections must be associated with a project. JSON output is available.

```bash
# List all sections
todoist sections
# Output:
# 123456789  To Do
# 123456790  In Progress
# 123456791  Done

# Filter sections by project
todoist sections --project "Work"
todoist sections -p "Work"

# JSON output
todoist sections --json

# Create section in project (project is required)
todoist section-add "Backlog" --project "Work"
todoist section-add "Blocked" -p "Work"

# JSON output
todoist section-add "Review" -p "Work" --json

# Example output:
# ✓ Created section: Backlog
#   ID: 123456792
```

--------------------------------

### Manage Labels (List and Create)

Source: https://context7.com/mjrussell/todoist-ts-cli/llms.txt

View all existing labels or create new ones for categorizing tasks. Labels can also be created with a specific color. JSON output is supported.

```bash
# List all labels
todoist labels
# Output:
# 4567890123  urgent
# 4567890124  waiting
# 4567890125  next

# JSON output
todoist labels --json

# Create new label
todoist label-add "research"

# Create label with color
todoist label-add "blocker" --color red

# JSON output
todoist label-add "review" --json

# Example output:
# ✓ Created label: research
#   ID: 4567890126
```

--------------------------------

### Manage Todoist Tasks

Source: https://github.com/mjrussell/todoist-ts-cli/blob/main/README.md

Provides commands for viewing, adding, completing, updating, and deleting tasks. Supports various options for due dates, priorities, projects, labels, assignments, and ordering.

```bash
# View today's tasks (default command)
todoist

# View today's tasks (explicit)
todoist today

# List tasks (today + overdue)
todoist tasks

# List all tasks
todoist tasks --all

# List tasks in a specific project
todoist tasks -p "Work"

# Filter tasks by query (e.g., priority 1)
todoist tasks -f "p1"

# Add a task with various options
todoist add "Buy groceries" --due tomorrow --priority 1
todoist add "Task" -d "tomorrow" -P 1 -p "Work" -l "urgent"
todoist add "Task" -p "Work" --deadline "2026-03-05"
todoist add "Task at top" -p "Work" --top
todoist add "Task at position 3" -p "Work" --order 3
todoist add "Assigned task" -a "user-id"

# View task details
todoist view <id>

# Update task properties
todoist update <id> --due "next week"
todoist update <id> --deadline "2026-03-05"
todoist update <id> --deadline none          # Clear deadline
todoist update <id> --labels "next,waiting" # Replace labels
todoist update <id> --add-label next --remove-label waiting
todoist update <id> -a "user-id"        # Assign task
todoist update <id> -a "null"           # Unassign task

# Complete a task
todoist done <task-id>

# Reopen a completed task
todoist reopen <id>

# Move a task to a different project or section
todoist move <id> -p "Personal"

# Move task to a specific section within a project
todoist move <id> -p "Work" -s "Section A"

# Delete a task
todoist delete <id>

# Search for tasks
todoist search "keyword"
```

--------------------------------

### Todoist CLI Environment Variables

Source: https://github.com/mjrussell/todoist-ts-cli/blob/main/README.md

Environment variables that can be used to configure the todoist-ts-cli, such as the API token and color output.

```bash
# API token for authentication
TODOIST_API_TOKEN

# Disable colored output (any value)
NO_COLOR
```

--------------------------------

### Programmatic API Usage (TypeScript)

Source: https://context7.com/mjrussell/todoist-ts-cli/llms.txt

Shows how to use the Todoist API programmatically within a Node.js application using TypeScript. It covers retrieving a token, initializing the API, fetching tasks, adding a new task, and closing a task, along with comments on exit codes.

```typescript
import { TodoistApi, getToken, saveToken, clearToken, requireToken, ExitCode } from 'todoist-ts-cli';

// Use saved token or environment variable
const token = getToken();
if (token) {
  const api = new TodoistApi(token);

  // Get today's tasks
  const response = await api.getTasksByFilter({ query: 'today | overdue' });
  console.log(`You have ${response.results.length} tasks today`);

  // Add a task
  const task = await api.addTask({
    content: 'New task from script',
    dueString: 'tomorrow',
    priority: 2,
  });
  console.log(`Created task: ${task.id}`);

  // Complete the task
  await api.closeTask(task.id);
}

// Exit codes for CLI integration
// ExitCode.Success = 0
// ExitCode.Failure = 1
// ExitCode.InvalidUsage = 2
// ExitCode.AuthFailure = 3
```

--------------------------------

### Add New Tasks

Source: https://context7.com/mjrussell/todoist-ts-cli/llms.txt

Create tasks with various attributes such as due dates, priorities, labels, project assignments, and descriptions. Supports natural language dates and parent-child relationships.

```bash
todoist add "Buy groceries"
todoist add "Review PR" --due "tomorrow" --priority 1 --project "Work"
todoist add "Write tests" --parent "8590123456"
```

--------------------------------

### List Todoist Collaborators

Source: https://github.com/mjrussell/todoist-ts-cli/blob/main/README.md

Lists collaborators for a given project, useful for task assignment.

```bash
todoist collaborators <project-id>     # List collaborators (for assignment)
```

--------------------------------

### Manage Todoist Comments

Source: https://github.com/mjrussell/todoist-ts-cli/blob/main/README.md

Commands for listing comments on a task and adding new comments.

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

--------------------------------

### Complete and Reopen Tasks

Source: https://context7.com/mjrussell/todoist-ts-cli/llms.txt

Mark tasks as completed or reopen previously completed tasks using the 'done', 'complete', or 'reopen' commands. Provides immediate feedback on the operation's success.

```bash
# Complete a task
todoist done 8590123456
# Output: ✓ Task completed

# Alternative alias
todoist complete 8590123456

# Reopen a completed task
todoist reopen 8590123456
# Output: ✓ Task reopened
```

--------------------------------

### View and Filter Tasks

Source: https://context7.com/mjrussell/todoist-ts-cli/llms.txt

Commands to display tasks due today, list all tasks, or apply custom filters using Todoist's query language. Supports JSON output for automation.

```bash
todoist
todoist today --json
todoist tasks --all
todoist tasks --project "Work"
todoist tasks -f "p1 | p2"
```

--------------------------------

### Export All Tasks to JSON

Source: https://context7.com/mjrussell/todoist-ts-cli/llms.txt

Exports all Todoist tasks to a JSON file for backup purposes. This command utilizes the `--all` flag to include all tasks and the `--json` flag to format the output as JSON, redirecting it to `backup.json`.

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

--------------------------------

### Authenticate with Todoist API

Source: https://github.com/mjrussell/todoist-ts-cli/blob/main/README.md

Saves, checks, or clears the Todoist API token for authentication. The token can also be set via the TODOIST_API_TOKEN environment variable.

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

--------------------------------

### Task Creation with Exit Code Handling

Source: https://context7.com/mjrussell/todoist-ts-cli/llms.txt

Adds a new task and checks the exit code to handle potential errors. The script provides specific messages for success (0), invalid arguments (2), and authentication failure (3), showcasing robust error handling for CLI integrations.

```bash
todoist add "Test task"
if [ $? -eq 0 ]; then
  echo "Task created successfully"
elif [ $? -eq 2 ]; then
  echo "Invalid arguments"
elif [ $? -eq 3 ]; then
  echo "Authentication required"
fi
```

--------------------------------

### View and Update Task Details

Source: https://context7.com/mjrussell/todoist-ts-cli/llms.txt

Commands to retrieve detailed information about a specific task by ID and modify existing task attributes like content, due dates, or deadlines.

```bash
todoist view 8590123456 --json
todoist update 8590123456 --content "Updated task title"
todoist update 8590123456 --due "next week"
```

--------------------------------

### Scripting with JSON Output and Exit Codes

Source: https://context7.com/mjrussell/todoist-ts-cli/llms.txt

Utilize the JSON output and exit codes provided by the Todoist CLI to integrate with shell scripts and automation workflows. This allows for dynamic task creation and management.

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

# Complete the task
todoist done "$TASK_ID"
```

--------------------------------

### List Project Collaborators

Source: https://context7.com/mjrussell/todoist-ts-cli/llms.txt

Retrieve a list of collaborators within a shared project, including their user IDs. This is useful for assigning tasks. JSON output is available for programmatic use.

```bash
# List collaborators in a project
todoist collaborators 2334567891
# Output:
# Collaborators:
# 123456789  John Doe (john@example.com)
# 123456790  Jane Smith (jane@example.com)

# JSON output for scripting
todoist collaborators 2334567891 --json
```

--------------------------------

### Move Tasks Between Locations

Source: https://context7.com/mjrussell/todoist-ts-cli/llms.txt

Relocate tasks to different projects, sections within projects, or designate them as sub-tasks of other tasks. Supports various flags for specifying the destination.

```bash
# Move to different project
todoist move 8590123456 --project "Personal"
todoist move 8590123456 -p "Work"

# Move to section within project
todoist move 8590123456 --project "Work" --section "In Progress"
todoist move 8590123456 -p "Work" -s "Done"

# Make sub-task of another task
todoist move 8590123456 --parent "8590123400"

# Output: ✓ Moved: Review PR
```

--------------------------------

### Manage Task Comments

Source: https://context7.com/mjrussell/todoist-ts-cli/llms.txt

View comments on a specific task or add new comments for notes and collaboration. Supports JSON output for retrieving comment data.

```bash
# List comments on a task
todoist comments 8590123456
# Output:
# 7890123456  This needs review by Friday
# 7890123457  Updated the implementation

# JSON output
todoist comments 8590123456 --json

# Add comment to task
todoist comment 8590123456 "Please review the test coverage"
todoist comment 8590123456 "Waiting for design team feedback"

# JSON output
todoist comment 8590123456 "Ready for QA" --json

# Example output:
# ✓ Comment added
```

--------------------------------

### Todoist CLI Exit Codes

Source: https://github.com/mjrussell/todoist-ts-cli/blob/main/README.md

Standard exit codes returned by the todoist-ts-cli, indicating success or different types of failures.

```bash
# Success
0

# Generic failure
1

# Invalid usage (bad arguments)
2

# Authentication failure
3
```

--------------------------------

### Update Task Properties

Source: https://context7.com/mjrussell/todoist-ts-cli/llms.txt

Modify various properties of a Todoist task, including deadline, priority, description, labels, and assignee. Supports JSON output for scripting.

```bash
# Clear deadline
todoist update 8590123456 --deadline none

# Change priority
todoist update 8590123456 --priority 1
todoist update 8590123456 -P 3

# Update description
todoist update 8590123456 --description "New detailed description"

# Replace all labels (comma-separated)
todoist update 8590123456 --labels "next,waiting,review"

# Add/remove labels incrementally
todoist update 8590123456 --add-label "urgent" --add-label "blocker"
todoist update 8590123456 --remove-label "waiting"
todoist update 8590123456 --add-label "in-progress" --remove-label "next"

# Assign to user
todoist update 8590123456 --assign "123456789"

# Unassign task
todoist update 8590123456 --assign "null"

# JSON output
todoist update 8590123456 --due "monday" --json
```

--------------------------------

### Delete Tasks Permanently

Source: https://context7.com/mjrussell/todoist-ts-cli/llms.txt

Remove tasks from Todoist permanently. The `--force` or `-f` flag can be used to bypass the confirmation prompt for immediate deletion.

```bash
# Delete with confirmation shown
todoist delete 8590123456
# Output: Deleting: Review PR
# Output: ✓ Deleted

# Force delete without showing task name
todoist delete 8590123456 --force
todoist delete 8590123456 -f
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.