Environment

Local development setup

Set up Todo CLI X locally to explore the source code, run the CLI in dev mode, and contribute to the project.

Project Structure

Here’s how the project Repo is organized:

todo-cli/
├── src/
│   └── todo_cli/        # Main package
│       ├── core.py      # Business logic
│       └── main.py      # CLI entry point
├── tests/               # Unit tests
│   ├── test_core.py     # Tests for core logic (add, list, complete, etc.)
│   └── test_utils.py    # Tests for utility functions (formatting, output, etc.)
├── pyproject.toml       # Project config
├── uv.lock              # Dependency lock
├── README.md            # Main doc
├── LICENSE              # MIT license
└── .python-version      # Python 3.11

Clone & Setup

Bash

git clone https://github.com/vidjinnangni/todo-cli.git
cd todo-cli
uv sync

Make sure you have Python 3.11+ and uv installed.

(Optional) Activate the virtual environment manually:

Bash

source .venv/bin/activate  # macOS/Linux

Task Storage

All tasks are stored in a local file named todo_data.json.
Automatically created when needed.
Ignored by Git (listed in .gitignore).

JSON

[
  {
    "id": 1,
    "text": "Buy milk",
    "done": false,
    "priority": "medium",
    "created": "2025-06-01T12:00:00+00:00",
    "due": "2025-06-15",
    "tags": ["shopping", "errands"]
  }
]

Running the CLI (Dev Mode)

Use uv run to run commands without activating the virtual environment:

Bash

uv run todo add "Refactor API" --priority high --due 2025-06-30 --tags dev,urgent
uv run todo list
uv run todo list --verbose
uv run todo list --tags dev
uv run todo edit 1 --text "Refactor user API" --priority medium --tags dev

Or activate the environment and run directly:

Bash

source .venv/bin/activate
todo add "Submit report" --priority high --due 2025-06-10
todo add "Refactor API" --priority high --due 2025-06-30 --tags dev,urgent
todo list --tags dev
todo edit 1 --text "Refactor user API" --priority medium --tags dev

Running Tests

Install dev dependencies:

Bash

uv sync --extra dev

Run tests using:

bash

uv run pytest

Or manually:

bash

source .venv/bin/activate
pytest

Contributing

We welcome all contributions! Whether you’re a beginner or a seasoned dev:

Report bugs
Suggest features
Improve code — refactor, clean up
Improve docs — like this one!

Check out the Roadmap for what’s ahead.

License

This project is licensed under the MIT License.

Get Started

Development

Local development setup

Project Structure

Clone & Setup

Task Storage

Running the CLI (Dev Mode)

Running Tests

Contributing

License

​Local development setup

​Project Structure

​Clone & Setup

​Task Storage

​Running the CLI (Dev Mode)

​Running Tests

​Contributing

​License

Local development setup

Project Structure

Clone & Setup

Task Storage

Running the CLI (Dev Mode)

Running Tests

Contributing

License