​
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.