todoist-tui

A Todoist client for the terminal, built on Textual.

Built because the available terminal clients were low-traffic and several predate Todoist's migration to API v1 — the old REST v2 endpoint now returns 410 Gone.

  Today                │  Today  (10 tasks)  by date (g to switch)
  Upcoming             │        task                      due       pri   project
  ---                  │        OVERDUE
  Inbox                │  ○     Rotate API keys           20 Aug    p1    Ops
  Work                 │  ○     Chase vendor invoice      20 Aug    p3    Finance

Features

• Today / Upcoming views, grouped by date or project
• Complete, add, edit, reschedule, set priority and due dates, delete and undo
• Task detail with comments
• Activity log, with restore of completed tasks
• Filter, and a project sidebar you can toggle away
• Links in tasks, descriptions and comments are live -- O opens them

Links

A url typed into a task is clickable, and a markdown [label](url) shows as its label rather than as the whole address.

O opens the link on the highlighted task -- straight away if there is one, or via a numbered menu if there are several. In the detail view O also reaches links in the description and in the comments.

The text is a real terminal hyperlink too, so a terminal that supports OSC 8 (ghostty, foot, kitty, alacritty >= 0.11) can open it on click, usually with ctrl or shift held, since the app itself is using the mouse. Inside the detail view a plain click works on its own; the task list is a table, where a click picks the row, so O is the way in there.

Install

Requires Python 3.11+.

mkdir -p ~/.local/share/todoist-tui/app
cp *.py ~/.local/share/todoist-tui/app/
cp bin/todoist ~/.local/bin/
python3 -m venv ~/.local/share/todoist-tui/venv
~/.local/share/todoist-tui/venv/bin/pip install -r requirements.txt
todoist --set-token <your API token>
todoist --check

Get a token from Todoist: Settings → Integrations → Developer → API token.

Where the token is stored

The system keyring via secret-tool, falling back to a 0600 file at ~/.config/todoist-tui/token only if no keyring is available. TODOIST_API_TOKEN overrides both. No token is ever written to this repository.

Theming

Colours come from theming.py, which reads the live Omarchy desktop theme when present and falls back to a built-in light/dark palette otherwise, so the app follows the desktop rather than assuming a dark terminal. TODOIST_TUI_THEME=light|dark forces the choice.

Licence

MIT.