kkga / tdx

CLI todo manager for iCalendar files.

tdx

tdx is a todo manager for iCalendar files.

It is designed to work with vdirsyncer and expects to operate in its storage format.

iCalendar-compatibility means it can be used as a CLI companion to any CalDAV-enabled todo program, such as iOS Reminders or Tasks.org. See more on how to set up calendars and synchronization in vdirsyncer documentation.

Features

• adding todos
  • automatic date and priority parsing
• listing todos
  • sorting and filtering by fields
  • automatic hashtag parsing and output organized by tags
• completing todos
• editing todos in a $VISUAL/$EDITOR program
• deleting todos
• purging completed/cancelled todos

Usage

General usage

tdx -- todo manager for vdir (iCalendar) files.

Usage:
  tdx [flags]
  tdx [command]

Available Commands:
  add         Add todo
  list        List todos
  done        Complete todos
  edit        Edit todo
  show        Show todos
  delete      Delete todos
  purge       Delete done todos
  help        Help about any command
  completion  generate the autocompletion script for the specified shell

Flags:
  -h, --help          help for tdx
  -p, --path string   path to vdir folder
  -v, --version       version for tdx

Use "tdx [command] --help" for more information about a command.

List command usage

List todos, optionally filtered by query.

Usage:
  tdx list [query] [flags]

Aliases:
  list, ls, l

Examples:
$ tdx list --sort prio --due 2

Flags:
  -l, --lists LISTS     filter by LISTS, comma-separated (e.g. 'tasks,other')
  -g, --group string    group listed todos, valid options: list, tag, none  (default "list")
  -a, --all             show todos from all lists (overrides -l)
  -d, --due N           filter by due date in next N days
  -S, --status STATUS   filter by STATUS: needs-action, completed, cancelled, any (default "needs-action")
  -t, --tag TAGS        filter todos by given TAGS
  -T, --no-tag TAGS     exclude todos with given TAGS
  -s, --sort FIELD      sort by FIELD: prio, due, status, created (default "prio")
      --description     show description in output
      --two-line        use 2-line output for dates and description
  -h, --help            help for list

Global Flags:
  -p, --path string   path to vdir folder

Installation

From release binaries

Download the compiled binary for your system from Releases page and put it somewhere in $PATH.

From source

Requires Go installed on your system.

Clone the repository and run go build, then copy the compiled binary somewhere in $PATH.

If Go is configured to install packages in $PATH, it's also possible to install without cloning the repository:

go install github.com/kkga/tdx@latest

Configuration

tdx is configured through environment variables.

variable	function
TDX_PATH	Path to vdir directory1
TDX_LIST_OPTS	Default options for <list> command, see tdx list -h2
TDX_ADD_OPTS	Default options for <add> command, see tdx add -h3
NO_COLOR	Disable color in output

Footnotes

1. Either root path containing multiple collections or path to specific collection containing *.ics files. ↩

2. For example, to show todos due in the next 2 days, from 'myList', grouped by tag: TDX_LIST_OPTS='-d 2 -l myList -g tag' ↩

3. For example, to use a default list for new todos: TDX_ADD_OPTS='-l myList' ↩

tdx's Issues

ical: malformed param value: illegal double-quote

I'm seeing ical: malformed param value: illegal double-quote for this entry:

It seems to have some funky quotes in the X-APPLE-STRUCTURED-LOCATION attribute. I think it's standards-complaint, since other tools / libs don't complain about it.

Here's a sample:

BEGIN:VCALENDAR
CALSCALE:GREGORIAN
PRODID:-//Apple Inc.//iOS 10.2.1//EN
VERSION:2.0
BEGIN:VTIMEZONE
TZID:America/Argentina/Buenos_Aires
BEGIN:DAYLIGHT
DTSTART:20071230T000000
RDATE:20071230T000000
RDATE:20081019T000000
TZNAME:GMT-3
TZOFFSETFROM:-0300
TZOFFSETTO:-0200
END:DAYLIGHT
BEGIN:STANDARD
DTSTART:20080316T000000
RRULE:FREQ=YEARLY;UNTIL=20090315T020000Z;BYDAY=3SU;BYMONTH=3
TZNAME:GMT-3
TZOFFSETFROM:-0200
TZOFFSETTO:-0300
END:STANDARD
END:VTIMEZONE
BEGIN:VEVENT
CREATED:20170308T193554Z
DTEND;TZID=America/Argentina/Buenos_Aires:20170308T220000
DTSTAMP:20170308T193557Z
DTSTART;TZID=America/Argentina/Buenos_Aires:20170308T190000
LAST-MODIFIED:20170308T193554Z
LOCATION:Home\nSome street 123\nApt "A"\nXXXX 
 CABA\nArgentina\nArgentina
SEQUENCE:0
SUMMARY:Broken entry lala
TRANSP:OPAQUE
UID:2F7602ED-B76E-468D-8A36-CBB45988613E
X-APPLE-STRUCTURED-LOCATION;VALUE=URI;X-ADDRESS=Some street 123\\nApt 
 \"A\"\\nXXXX CABA\\nArgentina\\nArgentina;X-APPLE-ABUID="ab://Home";
 X-APPLE-RADIUS=0;X-APPLE-REFERENCEFRAME=1;X-TITLE=Home:geo:
 -34.123455,-58.123456
END:VEVENT
END:VCALENDAR

Don't exit on corrupted ical data

Currently the program exits if there's a corrupted file in vdir collections.
It would be better to skip and report the file, while continue working on the rest of data.

Prevent existing IDs from changing when adding new todos

More details: #9 (comment)

A new empty list prevents tasks to be created

Thanks for this awesome CLI tool! Was looking for something like this for a while.

As the title says, it's currently impossible to create a task in a directory that doesn't contain a file with an *.ics extension (or any other extension configured).

This method https://github.com/kkga/tdx/blob/main/vdir/vdir.go#L131-L139 seems to prevent it. Do we need to check the existence of a file?