Add a `td watch` command for live Todoist changes

Summary

Add a td watch command that keeps running and reports relevant Todoist changes as they happen. It should support compact human-readable output and stable NDJSON output for agents, scripts, and local integrations.

The problem

Most Todoist CLI commands answer a question or perform an action at one point in time. That works well when a person or agent already knows it is time to act, but it does not help workflows that need to react when Todoist changes in the future.

Today, those workflows must poll repeatedly, compare snapshots themselves, or use a separately hosted webhook integration. Polling adds delay and unnecessary requests. Comparing snapshots pushes subtle state-management work into every consumer. Webhooks are a good fit for permanent integrations, but they require a reachable service and are too heavy for many local, temporary, or agent-driven workflows.

A live CLI stream would provide a simple middle ground: start a process, select the changes that matter, and react when they arrive.

Proposed experience

The command would establish a current-state baseline, wait for live Todoist notifications, and then use incremental Sync to retrieve the complete changed resources. The live connection would be a wake-up signal; Sync data would remain the authoritative event data.

Examples:

# Follow changes as a person
td watch --project "Launch"

# Consume task and comment changes from an agent or script
td watch --resource task,comment --project "Launch" --ndjson

# Wait until one matching event is available, then exit
td watch --resource task,comment --project "Launch" --one-event --ndjson

Useful filters would include resource type, project, workspace, and task label. Repeating or comma-separating resource names would make it possible to watch related Todoist data through one stream.

What this enables

The following are a few examples rather than an exhaustive list of possible workflows.

1. Let an agent wait for a human handoff

A user can ask an agent to prepare work, then wait for a task update or a clarifying comment before continuing.

td watch --resource task,comment --project "Launch" --one-event --ndjson

For the user, this means they do not have to return to the agent and manually say “check Todoist again.” An active agent host can block on the command, inspect the event when it arrives, read the latest Todoist state, and continue the delegated work. The command does not wake a stopped agent by itself; it gives an active agent process a reliable event source to wait on.

2. Keep a local view current

A terminal UI, menu-bar tool, dashboard, or development utility can use the stream as a signal to refresh a Todoist view only when relevant data changes.

td watch --project "Launch" --ndjson | your-view-refresher

This avoids a fixed refresh interval. It also lets the consumer reread the current project state instead of trying to reconstruct an entire view from individual events.

3. Create focused personal alerts and small automations

A user can route only selected changes into a local notifier or automation.

td watch --resource task --workspace "Doist" --label blocked --ndjson | your-notifier

The consumer can group bursts, respect quiet hours, or apply conditions that do not belong in the CLI. This makes small reactive workflows possible without deploying a webhook service.

Why this belongs in a CLI

A long-running stream fits normal shell composition. People can read it directly, while programs can consume one JSON object per line, pipe it to another process, capture it in development tooling, or stop it with normal process signals.

It also reuses the CLI's existing authentication and resource references. A user should be able to select a project by the same name or identifier they use with other td commands, without creating separate credentials or configuring an externally reachable endpoint.

This is an established CLI pattern

Several widely used service CLIs expose a long-running watch, listen, tail, or wait command:

• Kubernetes supports long-running resource and event watches with structured output and resource filters through kubectl get --watch and kubectl events --watch.
• Consul can watch changing keys, services, health checks, and events, then write the resulting view or invoke a handler through consul watch.
• Stripe can listen for selected account events and optionally forward them to a local service through stripe listen.
• GitHub and CircleCI provide bounded commands that wait for a remote run and report state changes, showing the value of predictable completion and machine-usable exit behavior (gh run watch, circleci run watch).

These commands differ because their backends differ, but they share useful product principles: make scope and filters explicit, distinguish human and structured output, support bounded waiting where useful, and document delivery semantics honestly.

Suggested initial scope

• Watch common Todoist resources, including tasks, projects, sections, comments, labels, filters, reminders, notifications, workspaces, and workspace members.
• Filter by resource type, project, workspace, and task label.
• Offer compact human-readable output and NDJSON output.
• Optionally exit after one future event for agent and script workflows.
• Continue watching after temporary connection interruptions without requiring a manual restart.
• Build the shared parts with reuse in mind, so they can later move into CLI Core and make it easier to add similar watch commands to other Doist CLIs, such as Comms and Automations. The first version does not need to include that extraction.