pTask has two parsers: quick-add (composing a new task in one shot)
and the filter DSL (selecting rows from tasks for pt list).
Free text with inline tokens. The non-token remainder is the title;
trailing //description becomes the description.
| Token | Effect |
|---|---|
p1..p5 |
priority, native scale: p1=low, p2=normal, p3=high, p4=urgent, p5=critical. Identical to --priority and pt priority — no Todoist inversion. |
@label |
append to pt_extensions.labels JSON. Multiple allowed. |
#project |
pt_extensions.project (last wins). |
~30m, ~2h, ~1d |
pt_extensions.duration_min. |
!HH:MM |
reminder time of day (a valid HH:MM only). Echoed by pt add; not persisted. |
//description |
everything from // to end-of-text → description. |
every monday, every weekday, every! 5 days, etc. |
recurrence — see recurrence.md. |
YYYY-MM-DD |
deadline, when it is a standalone date in the future. |
Body-text deadline inference is deliberately narrow: only a standalone
future ISO date (2026-10-02) sets the deadline. Other date prose
(tomorrow, next friday, 4/5, a past date) stays title text instead of
silently setting a wrong deadline; pass --deadline for anything else.
Recurrence phrases (every monday at 9am) set the first occurrence.
Operator timezone: Europe/London (DST-correct via jiff).
pt add 'gym @health every! monday at 8am p2 ~45m'
pt add 'buy bread 2026-10-02 @home p1 ~30m //sourdough from baker'
pt add 'investigate ceph mon quorum @ops p4 #fleet'
pt add 'review PR #42 //sync via gh pr view 42'
Boolean expressions over field tokens.
| Token | Predicate |
|---|---|
today |
deadline = today or due today |
overdue |
deadline < today, not done or dismissed |
no date |
deadline IS NULL |
recurring |
row has a pt_recurrence entry |
p1..p5 |
exact priority match |
@label |
label in pt_extensions.labels |
#project |
project match |
due:phrase |
resolves a date phrase; exact-day match |
due before:phrase |
deadline < parsed_date |
created:phrase |
created_at on that day |
search:str |
title LIKE %str% (case-insensitive) |
status:STATE |
exact status; same lexicon as -s |
kind:scout|ship |
investigation vs implementation (see pt promote) |
| Op | Form |
|---|---|
| AND | a & b or whitespace a b |
| OR | `a |
| NOT | !a |
| group | `(a |
pt list 'today & p1'
pt list '(today | overdue) & #fleet'
pt list '@waiting & no date'
pt list 'due before: next friday & !recurring'
pt list 'search: ceph & @ops'
pt list 'kind: scout & p4'
Use single quotes around the whole DSL string in shells — &, |,
! are interpreted by the shell otherwise.