Todol - Simple cli ToDo app

Python Status Build

Demo

📚 Contents

Installation
Usage
Command Guide
FAQ
Hotkeys
Support
License

📦 Installation

pip install todol

[!IMPORTANT] todol is a terminal application. I recommend installing it with pipx.

More Info

Check out the project page on PyPi: https://pypi.org/project/todol/
and on Github: https://github.com/WattoX00/todol

🚀 Usage

Run from anywhere in your terminal

todol

Additional flags

Click to expand

View all flags (for more options):

todol --help

Check the current version:

todol --version

See where todo files are saved:

todol --path

Update todol with a single command:

⚠️ Caution

This runs pipx upgrade todol under the hood.

todol --upgrade

Modify the todo list from the terminal

Click to expand

Aliases work with the flags too

Add new task:

todol --add [TASK_NAME] [@TAGS (optional)]

Mark task as DONE by ID:

todol --done [TASK_ID]

Remove all tasks marked as DONE:

todol --clear

COMMAND GUIDE

Commands:
  add, a        Add new task
  done, d       Mark task done
  list, ls      Show todo list
  edit, e       Edit task
  clear, c      Clear done tasks
  order, o      Order Todos by IDs
  help, h       Show help
  reload, rld   Reload the app
  exit, q       Exit app

[!TIP]

Pro Tips:

You can use Tab for autocomplete.
Navigate the terminal efficiently: arrow keys, backspace, delete ...
Use custom @tags to organize tasks
You can execute multiple commands at once:
- all - apply the command to all items
- id-id – apply the command to a range of IDs
- id1 id2 id3 – apply the command to specific IDs

examples:

done all       # marks all tasks as done
done 4-7       # marks tasks with IDs 4 through 7 as done
done 3 5 8     # marks tasks 3, 5, and 8 as done

❓ FAQ

Where are the saved todo files stored?

You can simply check it by running `todol --path`

todol stores its data using platformdirs.user_data_dir, which means files are written to the standard user data directory for each operating system.

Default locations

Linux ~/.local/share/todol/todoFiles/
macOS ~/Library/Application Support/todol/todoFiles/
Windows %APPDATA%\todol\todoFiles\

Hotkeys

Click to expand

Cursor navigation

Key	Action
`Ctrl‑a`	Move cursor to beginning of line
`Ctrl‑e`	Move cursor to end of line
`Ctrl‑f`	Move cursor forward (right)
`Ctrl‑b`	Move cursor backward (left)
`Alt‑f`	Move forward one word
`Alt‑b`	Move backward one word
`Home`	Go to start of line
`End`	Go to end of line

Editing

Key	Action
`Ctrl‑d`	Delete character under cursor
`Ctrl‑h` / `Backspace`	Delete character before cursor
`Alt‑d`	Delete word forward
`Ctrl‑k`	Kill (cut) text to end of line
`Ctrl‑y`	Yank (paste) killed text
`Ctrl‑t`	Transpose characters

History

Key	Action
`Ctrl‑p`	Previous history item
`Ctrl‑n`	Next history item

Searching

Key	Action
`Ctrl‑r`	Reverse search history
`Ctrl‑s`	Forward search history (may be intercepted by terminal flow control)

Completion & Accept

Key	Action
`Tab`	Trigger completion
`Ctrl‑Space`	Start/advance completion
`Enter`	Accept input

Misc

Key	Action
`Ctrl‑c`	Cancel / raise KeyboardInterrupt
`Ctrl‑z`	Suspend (depends on shell)
`Escape`	Escape/Meta prefix for `Alt‑` combos
Arrow keys	Move cursor up/down/left/right

For the full official key binding documentation, check the prompt_toolkit docs: prompt_toolkit GITHUB

❤️ Support

If this project saved you time, taught you something, or made your day a little easier, you can support its development here:

👉 Buy me a coffee via PayPal

Your support helps keep the project:

Actively maintained
Continuously improved
Free and open source

Thanks for being part of the community 🤝

📄 License

This project is licensed under the MIT License.
See the LICENSE file for full details.

Release files for todol 0.4.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for todol 0.4.3
File	Size	Uploaded
todol-0.4.3.tar.gz	14.4 kB	Mar 26, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for todol 0.4.3
File	Interpreter	ABI	Platform	Reset
todol-0.4.3-py3-none-any.whl 15.6 kB Mar 26, 2026	Python 3	none	any	Details

Total release size:30.0 kB

Release files / todol-0.4.3.tar.gz

Download URL	todol-0.4.3.tar.gz
Size	14.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`c58117176598543be594d60fc805b37440800c52c984eafbefb57e7b2606df54`
BLAKE2b-256 checksum How to use checksums	`6416d420f71fa2e0a0fe3b07349653f75822095c7b3ca4cc92c32abca5662992`
Upload date	Mar 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.14.3`

Release files / todol-0.4.3-py3-none-any.whl

Download URL	todol-0.4.3-py3-none-any.whl
Size	15.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`43bf5df5bb8cce283694256a466fd56fdebb632c7ba6038dda4d824429a032af`
BLAKE2b-256 checksum How to use checksums	`0e8e836db3524fa2ad56d073850e8eb01dc916a3f86d793c782310133bd00af7`
Upload date	Mar 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.14.3`