Toodledo CLI

Every Toodledo feature from the terminal, plus an offline SQLite mirror, GTD reviews, and rate-budget-aware sync that no other Toodledo tool has.

Toodledo caps you at 100 API calls per access token, so a naive wrapper is unusable. toodledo-pp-cli mirrors your whole task universe into local SQLite, then runs GTD next-actions, weekly review, stalled-project detection, goal rollups, and full-text search entirely offline — with JSON on every command and a complete agent-native MCP surface. sync-cost tells you what a refresh will spend before you spend it.

Authentication

Toodledo uses OAuth 2.0. Register an app at toodledo.com to get a client id and secret, set TOODLEDO_CLIENT_ID and TOODLEDO_CLIENT_SECRET, then run 'toodledo-pp-cli auth login' to authorize in your browser. Access tokens last two hours and are refreshed automatically; the refresh token expires after 30 idle days, after which you re-run auth login. The token endpoint sits behind Cloudflare and occasionally returns 403 to valid requests — the CLI treats that distinctly from a real 401 auth failure.

Quick Start

# Check the binary, config, and Toodledo API reachability before anything else
toodledo-pp-cli doctor

# Authorize via OAuth in the browser; tokens are stored and auto-refreshed
toodledo-pp-cli auth login

# Mirror your whole Toodledo account into local SQLite once
toodledo-pp-cli sync --full

# Your GTD next actions for @work, answered offline from the mirror
toodledo-pp-cli next-actions --context @work

# The full weekly review (inbox, overdue, stalled, waiting, someday) with zero API calls
toodledo-pp-cli review

Unique Features

These capabilities aren't available in any other tool for this API.

GTD rituals, offline

• next-actions — Your GTD 'what should I do now?' list — incomplete Next-Action tasks, sorted by priority then due date, optionally scoped to a context or goal.

  When an agent needs the single best next action, this answers offline in one call instead of refetching and re-filtering every task.

  toodledo-pp-cli next-actions --context @work --agent
  

• review — The full GTD weekly review in one pass: inbox (untriaged), overdue, stalled projects, waiting-for, and someday/maybe.

  Hands an agent the entire weekly-review state in one offline payload so it can drive the Sunday-night ritual without rate-limit risk.

  toodledo-pp-cli review --agent
  

• stalled-projects — Folders (projects) that have open tasks but zero Next Actions — the GTD failure mode that silently stalls progress.

  Surfaces the highest-value weekly-review bucket on its own so an agent can prompt the user to define a next action.

  toodledo-pp-cli stalled-projects --json
  

• goal-progress — Per-goal counts of completed vs incomplete contributing tasks, rolled up the lifetime/long-term/short-term goal hierarchy.

  Lets an agent report whether a user's goals are actually being advanced by their day-to-day tasks.

  toodledo-pp-cli goal-progress --level short --json
  

• dashboard — A one-screen status board: incomplete task counts by status, priority, folder, and context, plus overdue, due-today, and starred totals.

  Gives an agent the whole task-system state at a glance without N separate grouped queries.

  toodledo-pp-cli dashboard --json
  

Rate-budget-aware

• sync-cost — Forecasts how many of your 100 per-token API calls an incremental sync would spend, before fetching any rows.

  Toodledo locks you out after 100 calls per token; this tells an agent whether a sync is safe to run before spending the budget.

  toodledo-pp-cli sync-cost --since 7d
  

• capture — Add many tasks from a file or stdin (one title per line), resolving folder/context names to ids, in budget-aware batches of 50.

  Turns a pile of captured ideas into Toodledo tasks in a handful of calls rather than dozens, without exhausting the token budget.

  toodledo-pp-cli capture --file ~/inbox.txt --folder Inbox
  

Recipes

Morning next actions

toodledo-pp-cli next-actions --context @work --agent

The @work next-action list as agent-shaped JSON, answered offline from the local mirror.

Weekly review, narrowed for an agent

toodledo-pp-cli review --agent --select overdue.title,overdue.duedate,stalled_projects.folder

Pull only the overdue titles/dates and stalled-project names from the five-bucket review so the agent does not ingest the full payload.

Budget-safe sync

toodledo-pp-cli sync-cost --since 7d

Preview how many of your 100 token-calls a 7-day incremental sync will spend before running it.

Bulk capture from a file

toodledo-pp-cli capture --file ~/inbox.txt --folder Inbox

Add one task per line, resolving the Inbox folder name, in batches of 50.

Find stalled projects

toodledo-pp-cli stalled-projects --json

Projects with open tasks but no Next Action — the weekly review's highest-value bucket.

Usage

Run toodledo-pp-cli --help for the full command reference and flag list.

Commands

account

Account info (subscription, sync cursors)

• toodledo-pp-cli account - Get account info, including per-resource lastedit/lastdelete sync cursors and Pro status

contexts

Contexts (GTD contexts like @home, @work)

• toodledo-pp-cli contexts add - Create a context
• toodledo-pp-cli contexts delete - Delete a context (its tasks become unassigned)
• toodledo-pp-cli contexts edit - Rename a context
• toodledo-pp-cli contexts list - List all contexts

folders

Folders (GTD projects)

• toodledo-pp-cli folders add - Create a folder
• toodledo-pp-cli folders delete - Delete a folder (its tasks become unassigned)
• toodledo-pp-cli folders edit - Edit/rename/archive a folder
• toodledo-pp-cli folders list - List all folders

goals

Goals (lifetime / long-term / short-term)

• toodledo-pp-cli goals add - Create a goal
• toodledo-pp-cli goals delete - Delete a goal
• toodledo-pp-cli goals edit - Edit a goal
• toodledo-pp-cli goals list - List all goals

lists

Custom lists (user-defined tabular lists)

• toodledo-pp-cli lists add - Create custom list(s). Pass a JSON array of list objects.
• toodledo-pp-cli lists delete - Delete custom list(s). Pass a JSON array of list ids.
• toodledo-pp-cli lists deleted - List custom-list ids deleted after a timestamp
• toodledo-pp-cli lists edit - Edit custom list(s). Pass a JSON array of list objects including id.
• toodledo-pp-cli lists list - List custom lists. Feeds the local mirror via sync.

locations

Locations (named places with coordinates)

• toodledo-pp-cli locations add - Create a location
• toodledo-pp-cli locations delete - Delete a location
• toodledo-pp-cli locations edit - Edit a location
• toodledo-pp-cli locations list - List all locations

notes

Notes (standalone notes, optionally filed in folders)

• toodledo-pp-cli notes add - Create note(s). Pass a JSON array of note objects.
• toodledo-pp-cli notes delete - Delete note(s). Pass a JSON array of note ids.
• toodledo-pp-cli notes deleted - List note ids deleted after a timestamp
• toodledo-pp-cli notes edit - Edit note(s). Pass a JSON array of note objects including id.
• toodledo-pp-cli notes list - List notes. Feeds the local mirror via sync.

outlines

Outlines (hierarchical outline documents)

• toodledo-pp-cli outlines add - Create outline(s). Pass a JSON array of outline objects.
• toodledo-pp-cli outlines delete - Delete outline(s). Pass a JSON array of outline ids.
• toodledo-pp-cli outlines deleted - List outline ids deleted after a timestamp
• toodledo-pp-cli outlines edit - Edit outline(s). Pass a JSON array of outline objects including id.
• toodledo-pp-cli outlines list - List outlines. Feeds the local mirror via sync.

tasks

Tasks (the GTD hub). Writes (add/edit/complete/delete) are hand-built ergonomic commands; list/deleted feed the local mirror.

• toodledo-pp-cli tasks deleted - List task ids deleted after a timestamp (for mirror reconciliation)
• toodledo-pp-cli tasks list - List tasks (incomplete by default). Feeds the local mirror via sync.

Output Formats

# Human-readable table (default in terminal, JSON when piped)
toodledo-pp-cli account

# JSON for scripting and agents
toodledo-pp-cli account --json

# Filter to specific fields
toodledo-pp-cli account --json --select id,name,status

# Dry run — show the request without sending
toodledo-pp-cli account --dry-run

# Agent mode — JSON + compact + no prompts in one flag
toodledo-pp-cli account --agent

Agent Usage

This CLI is designed for AI agent consumption:

• Non-interactive - never prompts, every input is a flag
• Pipeable - --json output to stdout, errors to stderr
• Filterable - --select id,name returns only fields you need
• Previewable - --dry-run shows the request without sending
• Explicit retries - add --idempotent to create retries when a no-op success is acceptable
• Confirmable - --yes for explicit confirmation of destructive actions
• Piped input - write commands can accept structured input when their help lists --stdin
• Offline-friendly - sync/search commands can use the local SQLite store when available
• Agent-safe by default - no colors or formatting unless --human-friendly is set

Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.

Health Check

toodledo-pp-cli doctor

Verifies configuration, credentials, and connectivity to the API.

Configuration

Config file: ~/.config/toodledo-pp-cli/config.toml

Static request headers can be configured under headers; per-command header overrides take precedence.

Environment variables:

Name	Kind	Required	Description
TOODLEDO_CLIENT_ID	per_call	Yes	Set to your API credential.
TOODLEDO_CLIENT_SECRET	per_call	Yes	Set to your API credential.

agentcookie (optional)

If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, toodledo-pp-cli doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.

Troubleshooting

Authentication errors (exit code 4)

• Run toodledo-pp-cli doctor to check credentials
• Verify the environment variable is set: echo $TOODLEDO_CLIENT_ID Not found errors (exit code 3)
• Check the resource ID is correct
• Run the list command to see available items

API-specific

• 403 Forbidden during auth login or sync — Toodledo sits behind Cloudflare, which intermittently WAF-blocks valid API traffic. Wait a minute and retry; the CLI sends a real User-Agent and reports 403 distinctly from a 401 auth failure.
• 401 / token_rejected after a couple of hours — Access tokens expire after 2 hours and refresh automatically. If the refresh token expired (30 days idle), run 'toodledo-pp-cli auth login' again.
• Subtasks set with --parent are silently dropped — parent/child links require a Toodledo Pro subscription; non-Pro accounts sync the task without the link. Confirm your plan with 'toodledo-pp-cli account get'.
• Locked out after a burst of commands — Toodledo allows 100 calls per access token. Run 'toodledo-pp-cli sync-cost' to preview a sync's cost and prefer 'sync --since 7d' over '--full' for routine refreshes.

Sources & Inspiration

This CLI was built by studying these projects and resources:

• poodledo — Python (29 stars)
• toodledo-python — Python (8 stars)
• tdcli — Go (2 stars)
• toodledo-mcp — TypeScript (1 stars)
• org-toodledo — Emacs Lisp

Generated by CLI Printing Press