todo-cli

todo-cli

A simple and efficient command-line TODO list manager written in Go.

Features

• ✨ Add, list, complete, and delete tasks
• 📁 Local JSON storage in ~/.todo-cli/
• 🎯 Filter by active or completed tasks
• 🚀 Fast and lightweight
• 💻 Cross-platform (Linux, macOS, Windows)

Prerequisites

• Go 1.21 or higher

To verify your Go installation:

go version

Installation

Install from source

go install codeberg.org/mtnr_dev/todo-cli@latest

This will install the todo-cli binary to your $GOPATH/bin directory (typically ~/go/bin or ~/.go/bin).

Make sure your Go bin directory is in your PATH:

# Add to ~/.zshrc or ~/.bashrc if not already present
export PATH=$PATH:$HOME/.go/bin

Build from source

Clone the repository and build:

git clone https://codeberg.org/mtnr_dev/todo-cli.git
cd todo-cli
go build -o todo-cli

Then move the binary to a directory in your PATH:

mv todo-cli ~/.go/bin/

Optional: Create an alias

For a shorter command, add to your ~/.zshrc or ~/.bashrc:

alias todo='todo-cli'

Usage

Add a new TODO

todo-cli add "Buy groceries"
todo-cli add "Finish project report"

List TODOs

# List active (uncompleted) todos
todo-cli list

# List all todos (active and completed)
todo-cli list --all
todo-cli list -a

# List only completed todos
todo-cli list --completed
todo-cli list -c

Complete a TODO

todo-cli complete 1

Delete a TODO

todo-cli delete 1

Get help

# General help
todo-cli --help

# Command-specific help
todo-cli add --help
todo-cli list --help

Examples

# Add some tasks
$ todo-cli add "Buy groceries"
✓ Added todo #1: Buy groceries

$ todo-cli add "Write documentation"
✓ Added todo #2: Write documentation

$ todo-cli add "Deploy application"
✓ Added todo #3: Deploy application

# List active todos
$ todo-cli list
Active TODOs:

☐ [1] Buy groceries (created: Feb 8, 2026)
☐ [2] Write documentation (created: Feb 8, 2026)
☐ [3] Deploy application (created: Feb 8, 2026)

# Complete a todo
$ todo-cli complete 2
✓ Completed todo #2: Write documentation

# List all todos
$ todo-cli list --all
All TODOs:

☐ [1] Buy groceries (created: Feb 8, 2026)
✓ [2] Write documentation (created: Feb 8, 2026)
☐ [3] Deploy application (created: Feb 8, 2026)

# Delete a todo
$ todo-cli delete 1
✗ Deleted todo #1: Buy groceries

Data Storage

All todos are stored locally in ~/.todo-cli/todos.json. This file is created automatically on first use.

To back up your todos:

cp ~/.todo-cli/todos.json ~/todos-backup.json

To restore:

cp ~/todos-backup.json ~/.todo-cli/todos.json

Project Structure

todo-cli/
├── cmd/              # Command implementations
│   ├── root.go       # Root command
│   ├── add.go        # Add command
│   ├── list.go       # List command
│   ├── complete.go   # Complete command
│   └── delete.go     # Delete command
├── internal/
│   ├── todo/         # Todo domain model
│   │   └── todo.go
│   └── storage/      # Storage layer
│       ├── storage.go
│       └── json_store.go
├── main.go           # Entry point
├── go.mod            # Go module definition
└── README.md

Development

Running tests

go test ./...

Building

go build -o todo-cli

Running locally without installing

go run main.go add "Test todo"
go run main.go list

Technologies Used

• Go - Programming language
• Cobra - CLI framework
• JSON - Data storage format

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Author

mtnr_dev

Acknowledgments

Built as a learning project to explore Go and CLI development with Cobra.