odot

A minimalist, interactive command-line task manager built with Python.

Features

• Interactive prompts — arrow-key navigable menus when you omit an argument
• Rich output — clean, formatted tables via the rich library
• Filtering & sorting — slice your task list by status, category, priority, or date
• Import / export — move tasks between machines with JSON
• Reports — generate Markdown or HTML reports with one command
• Scripting-friendly — machine-readable JSON output via a global --json flag
• Local first — SQLite-backed, zero-configuration, works offline

Installation

# uv (recommended)
uv tool install odot

# pipx
pipx install odot

# pip
pip install odot

Quick Start

odot add "Buy groceries" -p 2 -c home # add a task (database created automatically)
odot list                             # view all tasks
odot list --todo --sort priority      # open tasks, sorted by priority

The database defaults to ~/.odot/db.sqlite. Override with the ODOT_DB_PATH environment variable.

Usage

Managing Tasks

odot add "Submit quarterly report" -p 3 -c work   # add
odot show                                          # interactive detail view
odot done 1                                        # mark task 1 as done
odot undo 1                                        # re-open task 1
odot update                                        # interactive update
odot update 1 --content "Revised name" --done      # explicit update
odot rm                                            # interactive delete
odot rm 1 --force                                  # skip confirmation

Searching & Filtering

odot search "groceries"
odot list --done                       # completed tasks only
odot list -c work --todo               # open work tasks
odot list --sort priority --reverse    # descending priority
odot count --todo -c work              # count matches without a table

Scripting

Add --json to emit machine-readable JSON instead of a table, ready to pipe into tools like jq:

odot list --json | jq '.[] | .content'   # list open task titles
odot count --json                         # {"total": N, "pending": N, "done": N}

--json applies to list, show, add, update, done, undo, search, count, rm, clean, purge, and import. It is ignored by export and report, which already produce their own artifacts.

Import, Export & Reports

odot export backup.json --todo         # export open tasks
odot import backup.json                # append from file
odot import backup.json --clear        # replace all tasks
odot report tasks.md --sort priority   # Markdown report
odot report work.html --todo -c work   # filtered HTML report

Bulk Operations

odot clean          # remove completed tasks (prompts for confirmation)
odot clean --force  # skip confirmation
odot purge          # remove all tasks (prompts for confirmation)
odot purge --force  # skip confirmation

Development

Prerequisites: uv, just, gh

git clone https://github.com/jkomalley/odot.git && cd odot
uv sync

just test          # run pytest
just test-cov      # enforce 100% coverage
just check         # ruff + ty + tests

Contributing

Contributions are welcome. See CONTRIBUTING.md for development setup, project layout, and the conventions this repo follows.

License

Released under the MIT License.