npm package: @gasolin/todomd-cli
Description: A command-line tool for managing todomd format files with MCP support
Author: Fred Lin
Latest version: 1.0.0

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

<img width="439" height="316" alt="Image" src="https://github.com/user-attachments/assets/e19b4488-95ff-41a4-97cb-0a8cae0d7559" />

(origin markdown from [todo_sample.md](https://github.com/gasolin/todomd/blob/main/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
- [x] `serve` - Run as MCP (Model Context Protocol) server
- [x] `--json` - Output raw JSON for machine readability

## Installation

```bash
npm install -g @gasolin/todomd-cli
```

Or clone and build locally:

```bash
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:

```bash
# 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`:

```sh
#!/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](./tools/append_journal.sh) in tools folder:

```sh
#!/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:

```bash
todomd init
```

2. Add some tasks:

```bash
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):

```bash
todomd list
```

4. Mark tasks as complete:

```bash
todomd done 1
```

### Direct File/Directory Usage

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

```bash
# 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).
- `todomd --json` - Output raw JSON (can be used with any command).

### Setup

- `todomd init` - Initialize todomd directory with sample files

## Task Syntax

TodoMD uses standard Markdown task lists with additional metadata:

```markdown
- [ ] (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

```bash
# 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

# Get JSON output for automation
todomd list --json
```

## 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

## MCP (Model Context Protocol) support

You can act `todomd-cli` as an MCP server to integrate with AI tools like Claude Desktop.

Add the following to your MCP configuration (e.g., `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "todomd": {
      "command": "todomd",
      "args": ["serve"],
      "env": {
        "TODOMD_DIR": "/path/to/your/todos",
        "TODOMD_WHEN_DONE": "/path/to/your/tools/append_journal.sh",
        "TODOMD_JOURNAL_PATH": "/path/to/your/logseq/journals",
        "TODOMD_NEAR_DAYS": "3"
      }
    }
  }
}
```

Alternatively, you can use `npx` to run it without global installation:

```json
{
  "mcpServers": {
    "todomd": {
      "command": "npx",
      "args": ["-y", "@gasolin/todomd-cli", "serve"],
      "env": {
        "TODOMD_DIR": "/path/to/your/todos"
      }
    }
  }
}
```

Only `TODOMD_DIR` is required (if you don't want to use the default `~/.todomd`). The other environment variables (`TODOMD_WHEN_DONE`, `TODOMD_JOURNAL_PATH`, `TODOMD_NEAR_DAYS`) are **optional** and provide additional features.

## Development

```bash
# 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](https://github.com/gasolin/todomd) - The specification this tool implements
- [todo.txt](https://github.com/todotxt/todo.txt) - The inspiration for the metadata format
- [GitHub Flavored Markdown](https://github.github.com/gfm/) - The base Markdown specification