todomd-cli

A command-line tool for managing todomd format files, inspired by todo.txt-cli but designed specifically for the todomd specification that combines Markdown with todo.txt features.

(origin markdown from todo_sample.md )

Features

• 📝 Markdown Native: Uses standard Markdown task list syntax
• 🏷️ Rich Metadata: Supports priorities, projects, contexts, due dates, and custom attributes
• 🌳 Hierarchical Tasks: Native support for subtasks and tree-like display
• 🤖 LLM-Friendly: Structured format optimized for AI parsing and automation
• 🔧 Configurable: Environment variable support for custom directories
• 🎨 Beautiful CLI: Built with Ink for a modern terminal experience

Feature Status

• [x] init - Initialize the todo directory
• [x] add, a <task> - Add a new task
• [x] list, ls - List all tasks (including completed and cancelled)
• [x] listcon, lsc <context> - List tasks by context, or list all contexts
• [x] listpri, lsp <priority> - List tasks by priority
• [x] listproj, lsproj <project> - List tasks by project, or list all projects
• [x] done, do <id> - Mark a task as completed
• [x] undone, ud <id> - Mark task as incomplete
• [x] delete, rm, del <id> - Delete a task
• [x] cancel <id> - Cancel a task
• [x] inprogress <id> - Set a task as in progress
• [x] edit <id> <new description> - Edit a task's description
• [x] priority, pri <id> <priority> - Set task priority
• [x] project, proj <id> <project> - Add a project to a task
• [x] context, ctx <id> <context> - Add a context to a task
• [x] due <id> <date> - Set a due date for a task
• [x] archive - Move completed tasks to done.md

Installation

npm install -g @gasolin/todomd-cli

Or clone and build locally:

git clone https://github.com/gasolin/todomd-cli.git
cd todomd-cli
npm install
npm run build
npm link

Configuration

Set your todo directory and other options using environment variables:

# In your shell profile (~/.bashrc, ~/.zshrc, etc.)
export TODOMD_DIR="$HOME/Documents/todos"
export TODOMD_NEAR_DAYS=3 # Highlight tasks due in the next 3 days (default is 2)

# Or create a .env file in your project directory
echo "TODOMD_DIR=/path/to/your/todos" > .env
echo "TODOMD_NEAR_DAYS=3" >> .env
echo "TODOMD_WHEN_DONE=~/bin/task_done_notify" >> .env

TODOMD_WHEN_DONE

You can specify a command to be executed whenever a task is marked as done. The description of the completed task will be passed to the command via the TASK_DESCRIPTION environment variable.

Example script ~/bin/task_done_notify:

#!/bin/bash
echo "Task completed: $TASK_DESCRIPTION" >> ~/task_log.txt
# Or send a notification, etc.

Another example is to append the completed task to your daily note in Logseq, using a script like append_journal.sh in tools folder:

#!/bin/bash
# tools/append_journal.sh
# This script appends the content of TASK_DESCRIPTION to today's Logseq journal.
LOGSEQ_DIR="~/Documents/Logseq"
JOURNAL_FILE="$LOGSEQ_DIR/journals/$(date +'%Y_%m_%d').md"
echo "- DONE $TASK_DESCRIPTION" >> "$JOURNAL_FILE"

You would then set TODOMD_WHEN_DONE in your .env file: TODOMD_WHEN_DONE=~/tools/append_journal.sh

Quick Start

1. Initialize a new todomd directory:

todomd init

2. Add some tasks:

todomd add "Buy groceries @home +personal due:2025-08-10"
todomd add "(A) Important meeting preparation @office +work"
todomd add "Call dentist for appointment"

3. List your tasks (subtasks will be displayed in a tree structure):

todomd list

4. Mark tasks as complete:

todomd done 1

Direct File/Directory Usage

You can also work with specific todo.md files directly by providing a path:

# List tasks from a specific file
todomd path/to/another/todo.md

# List tasks from todo.md in a specific directory
todomd path/to/a/project/

Commands

Basic Operations

• todomd list, ls [search terms] - List all tasks, or filter by search terms.
• todomd add, a <task> - Add a new task
• todomd done, do <id> - Mark task as completed
• todomd undone, ud <id> - Mark task as incomplete
• todomd delete, rm, del <id> - Delete a task

Task Management

• todomd edit, e, replace <id> <new description> - Edit a task's description
• todomd priority, pri <id> <priority> - Set task priority (A-Z)
• todomd project, proj <id> <project> - Add project to task
• todomd context, ctx <id> <context> - Add context to task
• todomd due <id> <date> - Set due date. Accepts YYYY-MM-DD and natural language like today, tomorrow, friday (next upcoming), this friday (within this week), next friday (in the following week), or in 2 weeks (English only).

Setup

• todomd init - Initialize todomd directory with sample files

Task Syntax

TodoMD uses standard Markdown task lists with additional metadata:

- [ ] (A) Task description @context +project due:2025-08-10 rec:w
  - [ ] Subtask 1
  - [ ] Subtask 2
- [x] Completed task cm:2025-08-01
- [-] Cancelled task

Metadata Format

• Priority: (A) to (Z) - Higher priority tasks
• Projects: +project-name - Group related tasks
• Contexts: @context-name - Where/when to do tasks
• Due Date: due:YYYY-MM-DD - Task deadline
• Creation Date: cr:YYYY-MM-DD - When task was created
• Completion Date: cm:YYYY-MM-DD - When task was completed
• Recurrence: rec:d/w/m/y - Recurring tasks (daily/weekly/monthly/yearly)
• Custom Attributes: key:value - Any additional metadata
• Tags: #tag-name - Categorize tasks

Examples

# Add a high-priority work task with due date
todomd add "(A) Prepare quarterly report @office +work due:2025-08-15"

# Add a recurring personal task
todomd add "Exercise for 30 minutes @gym +health rec:d"

# Add a task with subtasks (note: subtasks must be added manually to the file)
todomd add "Plan vacation +personal"
# Then edit todo.md to add:
#   - [ ] Plan vacation +personal
#     - [ ] Research destinations
#     - [ ] Book flights
#     - [ ] Reserve hotel

# Search for tasks
todomd list "report"

# Set priority for existing task
todomd pri 1 A

# Set a due date using natural language
todomd due 1 "next tuesday"

# Mark task as done
todomd done 1

# Add context to existing task
todomd context 2 home

File Structure

When you run todomd init, it creates:

~/.todomd/          # Default directory (or your TODOMD_DIR)
├── todo.md         # Main task file
├── done.md         # Completed tasks archive
└── .env.example    # Configuration example

Integration with Other Tools

Since TodoMD files are standard Markdown, they work with:

• Any Markdown editor (VS Code, Obsidian, Typora, etc.)
• Git for version control and collaboration
• Static site generators for publishing
• LLMs and AI tools for intelligent task management
• CI/CD pipelines for automated task processing

Development

# Clone the repository
git clone https://github.com/gasolin/todomd-cli.git
cd todomd-cli

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode
npm run dev

# Link for global usage
npm link

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

MIT License - see LICENSE file for details.

Related Projects

• todomd specification - The specification this tool implements
• todo.txt - The inspiration for the metadata format
• GitHub Flavored Markdown - The base Markdown specification