Recurring task created via `due_string` with a `starting` clause never advances on completion

[aheckler]

Summary

A task created with a due_string that contains a starting clause has the entire string stored verbatim as its recurrence rule. Completing the task then never advances it — every completion re-pins the same date. The identical recurrence without starting advances correctly.

Todoist's quick-add parser (the app's "Add task" box, and td task quickadd) handles the same text correctly: it consumes starting <date> into the due date and stores a clean recurrence rule (every! 2 weeks). So Todoist has two natural-language date parsers — the due_string field parser and the quick-add parser — and they disagree on starting.

This is server-side — it reproduces with raw REST, no td involved (see below). Filing it here because td task add --due is likely a common way to hit it. td task quickadd is not affected.

Impact

Silent. A recurring task created via the API looks completely normal; the breakage only surfaces the first time you complete it — the task doesn't move, and never will. Anything that creates recurring tasks programmatically — td task add --due, the SDK, direct REST, bulk imports/migrations — is exposed.

Reproduce — td CLI (v1.63.0)

$ td task add "repro-cli" --due "every! 2 weeks starting 2026-05-17"
$ td task view "repro-cli" --json | jq -c .due
{"isRecurring":true,"string":"every! 2 weeks starting 2026-05-17","date":"2026-05-17","timezone":null,"lang":"en"}

$ td task complete "repro-cli"
$ td task view "repro-cli" --json | jq -c .due
{"isRecurring":true,"string":"every! 2 weeks starting 2026-05-17","date":"2026-05-17","timezone":null,"lang":"en"}
#                                                                  ^^^^^^^^^^^^^^^^^^ date UNCHANGED — did not advance

Control — td task quickadd parses the identical text correctly:

$ td task quickadd "repro-qa every! 2 weeks starting 2026-05-17"
$ td task view "repro-qa" --json | jq -c .due
{"isRecurring":true,"string":"every! 2 weeks","date":"2026-05-17","timezone":null,"lang":"en"}
#                            ^^^^^^^^^^^^^^^^ "starting" consumed into the date; clean recurrence rule stored

That task advances correctly on completion.

Reproduce — raw REST (no td; isolates it to the API)

TOKEN=...            # a Todoist API token
TODAY=$(date +%F)

# CASE 1 — due_string WITH a "starting" clause
ID=$(curl -s -X POST https://api.todoist.com/api/v1/tasks \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"content\":\"repro-A\",\"due_string\":\"every! 2 weeks starting $TODAY\"}" | jq -r .id)
curl -s -X POST "https://api.todoist.com/api/v1/tasks/$ID/close" -H "Authorization: Bearer $TOKEN"
curl -s "https://api.todoist.com/api/v1/tasks/$ID" -H "Authorization: Bearer $TOKEN" | jq -c .due
#   => due date is UNCHANGED after completion
curl -s -X DELETE "https://api.todoist.com/api/v1/tasks/$ID" -H "Authorization: Bearer $TOKEN"

# CASE 2 — identical recurrence WITHOUT "starting" (control)
ID=$(curl -s -X POST https://api.todoist.com/api/v1/tasks \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"content":"repro-B","due_string":"every! 2 weeks"}' | jq -r .id)
curl -s -X POST "https://api.todoist.com/api/v1/tasks/$ID/close" -H "Authorization: Bearer $TOKEN"
curl -s "https://api.todoist.com/api/v1/tasks/$ID" -H "Authorization: Bearer $TOKEN" | jq -c .due
#   => due date advanced by 2 weeks
curl -s -X DELETE "https://api.todoist.com/api/v1/tasks/$ID" -H "Authorization: Bearer $TOKEN"

Observed (run 2026-05-17):

CASE 1  due_string sent: "every! 2 weeks starting 2026-05-17"
  POST /tasks       -> stored due.string = "every! 2 weeks starting 2026-05-17"   due.date = 2026-05-17
  POST .../close    -> HTTP 204
  GET  /tasks/{id}  -> due.string = "every! 2 weeks starting 2026-05-17"   due.date = 2026-05-17   << UNCHANGED

CASE 2  due_string sent: "every! 2 weeks"
  POST /tasks       -> stored due.string = "every! 2 weeks"                due.date = 2026-05-17
  POST .../close    -> HTTP 204
  GET  /tasks/{id}  -> due.string = "every! 2 weeks"                       due.date = 2026-05-31   << advanced +2 weeks

Same endpoint, same auth, same completion call — the only variable is the starting clause.

Where the fault is

• td task add --due "X" sends X verbatim as the task's due_string. Confirmed: the created task's due.string comes back byte-identical to the input — the CLI and SDK do not transform it.
• The raw-REST repro reproduces the bug with td entirely out of the loop, so the fault is server-side: the due_string parser on POST /api/v1/tasks stores a starting clause inside the recurrence rule instead of resolving it into the due date.
• The quick-add parser (the app's Add-task box, td task quickadd) resolves starting correctly. The two parsers should agree.

Expected

POST /api/v1/tasks with due_string: "every! 2 weeks starting <date>" should behave like quick-add: set the first due date to <date>, store the recurrence rule as every! 2 weeks, and advance normally on completion.

Workaround

Create the task with a bare recurrence, then position the first occurrence separately:

td task add "task" --due "every! 2 weeks"    # created due today
td task reschedule "task" 2026-06-20          # moves the first occurrence; recurrence preserved

td task reschedule keeps the recurrence rule intact, and the task advances correctly on completion thereafter.

Versions

• td 1.63.0 (@doist/todoist-cli)
• Endpoint: POST https://api.todoist.com/api/v1/tasks
• Reproduces equally via direct REST with no td in the path (above)
• macOS 26.5

[engfragui]

@aheckler 👋 This is an interesting topic and I happily looked into it.

After reviewing this, I don't think it's a reasonable expectation for POST /api/v1/tasks (the Backend API endpoint) to massage the input. At the same time, I also don't think we'd want td task add to compensate for the input and massage it before feeding it to the Backend API endpoint.

@aheckler I think the best course of action here would for you to rely on the existing td task quickadd command, which already embeds the capability to handle "starting " (and similar) correctly and reliably.
I've gone ahead and opened a PR to clarify this in our documentation, since I agree that it wasn't necessarily clear.

Cc. @scottlovegrove @gnapse to double-check my understanding and/or recommendation (and chime in if necessary) 🙏

[engfragui]

After reviewing this, I don't think it's a reasonable expectation for POST /api/v1/tasks (the Backend API endpoint) to massage the input. At the same time, I also don't think we'd want td task add to compensate for the input and massage it before feeding it to the Backend API endpoint.

@Doist/backend-hero Please let us know your thoughts on this.

💭 For reference, what happens in todoist-web (but doesn't happen in todoist-cli in the regular td task add command) is that the "starting " clause is handled by Dateist client-side, which parses the start anchor into the resolved date field and then sends it to the Backend API via /sync.

[aheckler]

rely on the existing td task quickadd command

For context, this issue came up when I was mass-importing my to-dos from Things 3 into Todoist. I decided to use td task add instead of td task quickadd for three reasons:

1. td task add avoids any parsing trickiness

Consider the following quickadd examples:

• td task quickadd "Call James about the quarterly report"
• td task quickadd "Cancel Sunday newspaper delivery"

In the first case, the quickadd parser sees "quarterly", uses that as the task recurrence schedule, and you wind up with just "Call James about the report" in your task title. In the second case, "Sunday" is stripped from the task title in a similar manner and used as the due date. Likely not what you wanted for either task!

That's why it seemed safer (at least when doing an import, where you can't hand-check every task) to use td task add: you can set a title without worrying about the quickadd parsing.

But of course, that means you also have to use --due and maybe a starting string. 🙁

2. I already had task metadata in a structured format.

Things 3 keeps its data in SQLite: due date, recurrence, and so on. Using quickadd would mean I'd need to take all that and "re-encode" it back into a natural language sentence so it could be parsed correctly. Oof.

task add came to the rescue (it seemed!) since it has its own flags that my import can pipe data directly into: --project, --labels, --due, etc.

3. Your SKILL.md itself directs me to

From SKILL.md:

Use td task add [...] when the text is being composed programmatically

Given I was mass-importing, using task add seemed to be the right move. The PR proposed here doesn't change that language either.

So yeah... it seems like anyone else who does this might be stuck for the same reasons:

• task add is safe for arbitrary titles and structured data / mass imports, but doesn't handle starting.
• quickadd handles starting but isn't ideal for importing + might mess up task data, you can't be sure.

The workaround I referenced in the original report above is the best way to go as it stands right now, but it's two commands instead of one, and it might not necessarily be obvious.