A local-first task manager for developers with a native CLI, optional Web UI, shell completion, and local AI assistance.

---

Preview

CLI

Web UI

CLI + optional Web UI powered by FastAPI

---

Why RazTodo

RazTodo is a local-first task manager built around a shared core engine with optional interfaces (CLI, Web UI, and shell completion).

CLI ─┐
     ├── Core Engine ─── SQLite
Web ─┘

All interfaces share a single SQLite database, enabling instant synchronization without external services or accounts.

The design follows three principles:

• Separation of concerns: core logic is interface-agnostic
• Local-first storage: all data remains on the user’s machine
• Composable interfaces: CLI, Web UI, and shell tooling are optional layers

---

Quick Start

CLI

# Add a task
rt add "Prepare weekly groceries" --priority H --due 2026-12-31

# List all tasks
rt list

# Mark as done
rt done 1

# Search
rt search "groceries"

# Get AI explanation of a task
rt explain 1 --short

# Update
rt update 1 --title "Weekly groceries: milk, vegetables, essentials"

# Delete
rt remove 1

Web UI

Start the server:

rt-web

Then open http://127.0.0.1:8000.

Note

Runs locally only (not exposed to the internet)
Single-user design with no authentication layer
CLI and Web UI share one SQLite database (real-time sync)
Local-first architecture optimized for personal use
Built with FastAPI + lightweight static frontend AI-powered task explanations (Summary / Deep Analysis / Action Plan) via Ollama

Shell Completion

# Requires raztodo[completion]
eval "$(rt completion bash)"

Supports bash, zsh, and fish. For permanent setup see the Completion Guide.

---

Installation

# Recommended (pipx)
pipx install raztodo

# No-install (uv)
uvx --from raztodo rt

# Standard install
pip install raztodo

# Web UI (optional)
pip install "raztodo[web]"

# Shell completion (optional)
pip install "raztodo[completion]"

# Everything (web + completion)
pip install "raztodo[all]"

For virtual environment and source installation, see the Installation Guide

---

Commands

Command	Description	Example
add	Create a new task	rt add "Task" --priority H
list	List tasks with filters	rt list --pending --priority H
update	Update a task	rt update 1 --title "New title"
done	Toggle task done/undone	rt done 1
remove	Delete a task	rt remove 1
search	Search tasks by keyword	rt search "keyword"
export	Export tasks to JSON	rt export backup.json
import	Import tasks from JSON	rt import backup.json
migrate	Run database migrations	rt migrate
clear	Delete all tasks	rt clear --confirm
completion	Output shell completion script	rt completion bash
explain	Get an AI explanation of a task	rt explain 1 --plan

rt --help
rt add --help

📖 See the Usage Guide for full command documentation.

---

Configuration

Variable	Description	Default
RAZTODO_DB	Database filename or path	tasks.db
LOG_LEVEL	Logging level	ERROR

export RAZTODO_DB="/path/to/custom.db"
export LOG_LEVEL="DEBUG"

Tip

📖 See the Configuration Guide

---

Docker

docker build -t raztodo:local .
docker run --rm -it -v "$HOME/raztodo-data:/data" raztodo:local add "My first task"

Note

kept CLI-only to minimize image size and dependencies

Tip

📖 See the Docker Guide

---

Documentation

Core:

• 📦 Installation Guide
• 📖 Usage Guide
• ⚙️ Configuration Guide

Advanced:

• ⌨️ Completion Guide
• 🐳 Docker Guide
• 🏗️ Architecture
• 🧪 Testing
• 📝 Changelog

---

Ecosystem

RazTodo is part of the RazBuild ecosystem of open-source developer tools.

• RazTint — Zero-dependency ANSI colors, icons, and terminal formatting utilities powering RazTodo's CLI output.

---

Contributing

git clone https://github.com/razbuild/raztodo
cd raztodo
uv sync

Quality checks

uv run pytest
uv run ruff check src/ tests/
uv run ruff format src/ tests/
uv run ty check src/

Workflow

1. Create feature branch
2. Implement changes
3. Ensure tests pass
4. Submit PR

See CONTRIBUTING guide for details.

---

License