Task syntax

Every task in Terra is one line of Markdown in a note. This page lists exactly what Terra reads on that line and what it writes back when you change a task in the app. A task line has three parts:

- [ ] Title of the task ::: key=value key=value

A list marker and a status in brackets, then the title, then, optionally, a space, three colons and a space (:::) followed by the task's properties.

How a line is read

• It must be a bulleted list item. The line starts with -, * or +, then at least one space, then the brackets. Indent it as much as you like.
• Indented under another task, it's a subtask. Nest as deep as you need.
• The space after ] is optional. - [ ]Call Ana is a task.
• Everything before the last ::: is the title, colons and all.
• The properties are key=value pairs separated by spaces, after the last :::.
• One bad pair spoils the list. If any pair has no =, no value, or a value with a space in it, Terra reads the whole tail as part of the title and the task has no properties. There's no error message.
• Indented lines straight under a task (not tasks themselves, no blank line between) are its description, which Edit task shows.

These are never tasks:

Status markers

A custom marker uses plain keyboard characters (letters, digits, punctuation), with no spaces, tabs or brackets. A marker you haven't set up in Task statuses still makes a task; it just goes by the marker itself until you name it.

Properties

Keys are lowercase and spelled exactly as below. Any other key becomes a custom property of that name, so Due= is not a due date.

A value is everything after the first = up to the next space.

Dates

due, start and until take the same forms:

Use a four-digit year and two-digit months, days and hours. Terra doesn't understand 20/10/2026, Oct 20, today, next friday, 2:30pm or a space instead of the T. A due date it can't read is kept on the line, but the task has no due date.

Repeating tasks

Add repeat= to a task with a due date. When you finish it on the board, in Edit task, on the Calendar or in the Tasks drawer, Terra adds the next copy. Ticking the checkbox in the note doesn't.

When a task repeats, Terra changes its status, then inserts a new open line directly under it with the same title and properties, the next due= and one less count=. The new due date is a day without a time, even if the old one had a time. Subtasks aren't copied, and because the new line goes in above them, the old subtasks end up under the new copy. repeat-on=completion takes "the day you finish" from the UTC calendar, so late in the evening in the Americas it can count from tomorrow.

What Terra writes when you edit a task

Changing a task anywhere in the app rewrites only its line, or the lines next to it, in its note.

Examples

A meeting's action items:

## Action items

- [ ] Send Ines the cover brief ::: due=2026-10-16
- [ ] Book the copy editor ::: due=2026-10-20 priority=high assignee=Sam

Everything at once, as in the screenshot at the top:

- [/] Draft the launch email ::: start=2026-10-19 due=2026-10-23T17:00 priority=high project=field-guide assignee=Ines tags=launch
  - [x] Write the subject line
  - [ ] Add the pre-order link

Chores that come back:

- [ ] Weekly review ::: due=2026-10-16 repeat=weekly
- [ ] Pay the studio rent ::: due=2026-11-01 repeat=monthly:1 count=12
- [ ] Water the plants ::: repeat=every:3d repeat-on=completion

A custom status and a custom property:

- [?] Check the print proofs ::: assignee=Ines effort=2

Lines that don't do what they look like:

1. [ ] Order the flowers
- [ ] Book the venue ::: assignee=Sam Lee due=2026-10-20
- [ ] Call the printer due:2026-10-20

The first isn't a task. The second is, but Sam Lee has a space, so its whole property list is read as title. The third has no :::, so due:2026-10-20 is just words.

Coming from Obsidian

Terra's four markers are the ones the Obsidian Tasks plugin uses, but Terra only reads properties after :::. It doesn't read the Tasks plugin's emoji dates (📅 2026-10-20, 🔁 every week) or Dataview fields ([due:: 2026-10-20]); they stay as text in the title. Rewrite them as ::: due=2026-10-20 repeat=weekly.

Not supported

• Relative dates such as today or tomorrow, and 12-hour times.
• Spaces inside a value.
• Tasks in numbered lists.
• Showing blocks and blocked-by anywhere in the app.
• Setting a repeat rule from a menu. Type it on the line.

Related

• Tasks — the board, Edit task and the Tasks drawer.
• Calendar — where due= puts a task.
• Search syntax — the other little language in Terra.
• Glossary — the Terra words used on this page.