Getting Started

What is md-todo?

SideDraft md-todo is a powerful, markdown-based todo list manager that lives in your terminal. It stores todos in plain markdown files, making them easy to read, edit, and version control.

Key Features

  • Plain markdown storage (.md files)
  • Lightning-fast CLI interface
  • Beautiful TUI (Terminal UI) mode
  • Category support (folder mode)
  • Search and filter
  • Starship prompt integration
  • Global configuration
  • Keyboard-first design

Quick Start

# Install
cargo install --path .

# Set global location
sd-todo config move ~/todos

# Add your first todo
sd-todo + Buy milk

# List todos
sd-todo l

# Complete a todo
sd-todo co 1

# Launch TUI
sd-todo tui

Prerequisites

  • Rust and Cargo (install from rustup.rs)
  • Terminal with color support

Basic Concepts

Modes

Single File Mode

  • One markdown file (e.g., todos.md)
  • All todos in one place
  • Simple and straightforward

Folder Mode (Categories)

  • Multiple markdown files in a folder
  • Each file is a category
  • Organize by project, context, etc.

Todo Format

Todos are stored as markdown checkboxes with metadata:

- [ ] Pending todo
<!-- created: 2026-02-02T10:30:00Z -->
- [x] Completed todo
<!-- created: 2026-02-02T10:30:00Z, completed: 2026-02-02T15:45:00Z -->

Metadata is stored as HTML comments, invisible in markdown viewers but preserved in version control. Timestamps are displayed in the TUI details pane.

Global Configuration

Your todo location is stored in:

~/.config/sidedraft-md-todo/config.json

This means sd-todo works from any directory.

Configuration Priority

  1. Command-line argument: sd-todo ~/other-todos list
  2. SD_TODO_PATH environment variable
  3. Global config file
  4. Default: todos.md in current directory

Common Workflows

Daily Review

# Morning
sd-todo p                        # What's pending?

# Throughout day
sd-todo + New task               # Quick capture
sd-todo co 1                     # Mark complete

# Evening
sd-todo d                        # What did I complete?
sd-todo archive                  # Archive completed

Quick Capture

# From anywhere
sd-todo + Random idea
sd-todo + Call dentist
sd-todo + Review PR #123

# Review later in TUI
sd-todo tui

Next Steps