Skip to main content

easydone

Your terminal-based task manager — simple, fast, and safe.

easydone is a lightweight CLI tool to keep your to‑do list in check.
Create, update, mark done, delete, and filter tasks with a few keystrokes.
All your data is stored as plain JSON, with atomic writes, automatic backups, and corruption quarantine so you never lose a task.

pip install easydone

📚 About this Project

This project was built as a solution to the Task Tracker project on roadmap.sh.

The goal was to practice building a real-world CLI tool with:

  • A clean, user-friendly interface
  • Robust data storage with atomic writes and automatic backups
  • A well-tested, maintainable codebase

✨ Why you'll like it

  • Instant workflow – no mouse, no distractions.
  • Smart statuses: not-done, in-progress, done.
  • Priority levels: low, normal, high, urgent.
  • Customizable task lists – include or exclude tasks by status, priority, tags, and due state; sort the results and hide date columns when you want a compact view.
  • Human‑readable JSON – inspect your data anytime.
  • Bulletproof storage – atomic writes, .bak backups, and quarantined corrupt files.
  • Beautiful output with Rich – optional, falls back to plain text if not installed.
  • Consistent tag colors – the same tag gets a stable color in Rich output. The palette has ten styles, so different tags can still share a color when their hash values map to the same style.
  • Clean architecture – business logic separated from CLI, making the core testable and reusable.

📦 Installation

Basic install (no extras)

pip install easydone

This installs the core tool with plain‑text output. Works perfectly for everyday use.

With Rich (pretty output)

pip install easydone[pretty]

This installs Rich for colored tables, styled text, and a more polished terminal experience.

💡 Note: Rich is completely optional. If you install the basic version, easydone automatically falls back to clean plain‑text output. No functionality is lost – it just looks different.


🚀 Quick Start

# Create a task
easydone new "Read a book"

# Add details
easydone new "Finish report" --status in-progress --priority high

# List everything
easydone list

# Focus on urgent, unfinished tasks
easydone list --status not-done --priority urgent

# Show overdue tasks, but leave out tasks already in progress
easydone list --overdue --not-status in-progress

# Exclude completed and low-priority tasks, then sort the rest by due date
easydone list --not-status done --not-priority low --sort due

# Use a compact view without date columns and sort descendently by priority
easydone list --no-dates --sort priority --reverse

# View all tasks with the term `easydone` in their description
easydone search "easydone"

# Mark complete
easydone mark 123 done

# Delete (with confirmation)
easydone delete 123

# Delete without confirmation
easydone delete 123 -f

# Delete multiple tasks
easydone delete 123 456 789 -f

# Archive tasks without deleting them
easydone archive 123 456

# Restore an archived task
easydone restore 123

# Review archived tasks
easydone list --archived

📋 Command Reference

Command Description
easydone new DESCRIPTION [--status STATUS] [--priority PRIORITY] [--due-date DATE] Create a task. Due dates accept YYYY-MM-DD, Tomorrow, +N, or -N.
easydone update TASK_ID [--description NEW] [--priority NEW] [--due-date DATE] [--add-tag TAG ...] [--remove-tag TAG ...] Change task fields and add or remove tags. Use Clear to remove a due date.
easydone mark TASK_ID [TASK_ID ...] new-status Set status to not-done, in-progress, or done for one or more tasks.
easydone delete TASK_ID [TASK_ID ...] [-f] Delete one or more tasks. Use -f to skip confirmation.
easydone search TERM [TERM ...] [--no-dates] Show tasks matching one or multiple terms in their description.
easydone archive TASK_ID [TASK_ID ...] Archive one or more tasks without deleting them.
easydone restore TASK_ID [TASK_ID ...] Restore one or more archived tasks.
easydone list [filters] [--sort FIELD] [--reverse] [--no-dates] [--archived | --with-archived] Show tasks matching optional filters; archived tasks are hidden unless explicitly included.
easydone stats Show counts for active and archived tasks separately.

💡 Pro tip: Delete multiple IDs at once: easydone delete 123 456 789. All IDs are validated before anything is removed – no partial deletions. Press Ctrl+C at any prompt to cancel the entire operation.

Fully customizing the task list

The list command lets you fully tailor which tasks appear, their order, and whether date details are shown:

Option Effect
--status STATUS / --priority PRIORITY Include tasks with the selected status and/or priority.
--tag TAG [TAG ...] Include tasks that have all specified tags.
--not-status STATUS / --not-priority PRIORITY Exclude tasks with the selected status and/or priority.
--not-tag TAG [TAG ...] Exclude tasks that have all specified tags.
--overdue / --not-overdue Include only overdue tasks, or exclude overdue tasks.
--sort FIELD Sort by priority, status, due, created, or updated.
--reverse Reverse the selected sort order.
--no-dates Hide due, created, and updated date columns for a more compact list.
--archived Show only archived tasks.
--with-archived Include archived tasks alongside active tasks.

Filters combine: inclusion filters narrow the results, then exclusion filters remove matching tasks. For example, easydone list --overdue --not-status in-progress shows overdue tasks except those in progress. Tag filters use AND semantics, so --tag work planning requires both tags; --not-tag work planning excludes tasks carrying both.

The available output customization is filtering, sorting, and showing or hiding date columns; the table's other columns are fixed.

Archived tasks are excluded from list and search by default. Use easydone list --archived to review them or easydone list --with-archived to show them with active tasks. Archiving preserves the task; use restore to return it to the active list. stats reports archived tasks separately from active task totals.


🛡️ Safety first

easydone takes care of your data:

  • Atomic writes – a crash mid‑save never corrupts your file.
  • Automatic backups – each save creates a tasks.json.bak in the same directory.
  • Corruption quarantine – if a file is unreadable, it's copied to tasks.corrupted-<timestamp>.json instead of being discarded.

Your tasks live in a user‑specific folder:

Platform Location
Windows %APPDATA%\easydone\tasks.json
macOS ~/Library/Application Support/easydone/tasks.json
Linux ~/.local/share/easydone/tasks.json

You can override the storage path by setting the EASYDONE_DATA_FILE environment variable.


📁 Project Structure

easydone/
├── easydone/
│   ├── __init__.py   # Package metadata
│   ├── __main__.py   # Application entry point
│   ├── cli.py        # CLI interface (argparse, handlers, user prompts)
│   ├── logic.py      # Pure business logic (CRUD, validation, filtering)
│   ├── storage.py    # JSON persistence with atomic writes, backup & quarantine
│   └── format.py     # Output formatting (Rich / plain text)
├── tests/
│   ├── conftest.py        # Shared task fixtures
│   ├── test_logic.py      # Task-manager unit tests
│   ├── test_archiving.py  # Archive and restore tests across logic and CLI
│   ├── test_integration.py # CLI parsing, handlers, and output integration
│   ├── test_storage.py    # Persistence, backups, and corruption handling
│   └── test_format.py     # Rich/plain rendering and messages
├── LICENSE
├── pyproject.toml
└── README.md

Architecture Overview

  • logic.py – Core business logic. Knows nothing about the CLI. Accepts only plain Python types (str, list, bool, etc.).
  • cli.py – CLI interface. Parses arguments, extracts values, calls the manager, handles user prompts.
  • storage.py – Persistence layer. Handles loading, saving, atomic writes, backups, and quarantine.
  • format.py – Presentation layer. Renders tables and messages with Rich or plain‑text fallback.

This design makes the core reusable in other contexts (API, TUI, GUI) and easy to test.


🔧 Development

Install in editable mode with dev dependencies:

git clone https://github.com/prares-dev/easydone.git
cd easydone
python -m venv .venv
source .venv/bin/activate   # or .venv\Scripts\activate on Windows
pip install -e ".[dev]"

Run the complete test suite:

py -m pytest

Run a specific test file:

py -m pytest tests/test_logic.py
py -m pytest tests/test_archiving.py
py -m pytest tests/test_integration.py
py -m pytest tests/test_storage.py
py -m pytest tests/test_format.py

Test Structure

Test File What It Tests
conftest.py Shared fixtures for active, legacy, and empty task managers
test_logic.py Task creation, due dates, tags, filtering, bulk operations, sorting, and stats
test_archiving.py Archive/restore logic, CLI behavior, list visibility, and persistence integration
test_integration.py CLI parsing, handlers, user interaction, and command output
test_storage.py Loading, saving, atomic writes, backups, and corruption handling
test_format.py Rich/plain task rendering, archive markers, stats output, and prompts

📄 License

MIT – see LICENSE.


Made with ❤️ by Pedro Rosquete — feedback and contributions are always welcome!

Metadata

Release files for easydone 1.6.0

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

Source distribution (sdist)

Source distribution for easydone 1.6.0
File Size Uploaded Provenance Actions
easydone-1.6.0.tar.gz 35.3 kB Without provenance Details for easydone-1.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for easydone 1.6.0
File Interpreter ABI Platform Actions
easydone-1.6.0-py3-none-any.whl Python 3 none any Details for easydone-1.6.0-py3-none-any.whl

Total release size: 57.1 kB

Release files / easydone-1.6.0.tar.gz

Download URL easydone-1.6.0.tar.gz
Size 35.3 kB
Tags Source
SHA-256 checksum
How to use checksums
1228f7d91caacf77e88e58344095c8d0b2210db6b2c8a4adcf3b503ca3ec5955
BLAKE2b-256 checksum
How to use checksums
fa2ecb61ab881eab436bf1f9e93b7786e9793c811f43d33ffae04749348ecd31
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.3

Release files / easydone-1.6.0-py3-none-any.whl

Download URL easydone-1.6.0-py3-none-any.whl
Size 21.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
62d8ec64a14ef0f381101ef8c015e5da47c29d290d0428cc9739c7e5b1bcb05d
BLAKE2b-256 checksum
How to use checksums
9ef404072bfa132eff5a17a89f12b8d72259eb3cdc8234a51457355c3e70120e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.3

Security for easydone 1.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page