todo — CLI Reference

Getting Started

init

todo init [--force] [--yaml] [--both]

Create a new TODO file in the current directory. Supports Markdown (TODO.md), YAML (TODO.yaml), or both. Fails if a valid file already exists unless --force is used. When no flag is provided, prompts interactively.

Flag	Default	Description
--force	false	Overwrite existing TODO file
--yaml	false	Create TODO.yaml instead of TODO.md
--both	false	Create both TODO.md and TODO.yaml

$ todo init

$ todo init --yaml

Creating Items

add --task

todo add --task <description> [--actors <ids>] [--tags <tags>] [--priority <level>] [--due <date>] [--position <url>]

Add a new task with an auto-generated 4-character ID. Optionally assign actors, tags, priority, due date, and a code position URL.

Flag	Default	Description
--task	—	Task description (required)
--actors	—	Comma-separated actor IDs to assign
--tags	—	Comma-separated tags
--priority	—	Priority level (low, medium, high)
--due	—	Due date in YYYY-MM-DD HH:MM format
--position	—	Code position URL (e.g. file:///path/to/file#L42:10)

$ todo add --task "Build login" --actors u0v1 --priority high

$ todo add --task "Fix bug" --position "file:///C:/project/src/main.rs#L23:5"

add --actor

todo add --actor <pseudo> [--pic <url>]

Add a new actor (team member) with an auto-generated ID.

Flag	Default	Description
--actor	—	Actor pseudo (required)
--pic	—	URL or path to avatar image

$ todo add --actor "Alice" --pic https://example.com/avatar.png

add --comment

todo add --comment <text> --task-id <id>

Add a comment to an existing task.

Flag	Default	Description
--comment	—	Comment text (required)
--task-id	—	ID of the task to attach the comment to (required)

$ todo add --comment "Started on this" --task-id a1b2

Reading Items

list

todo list [--tasks] [--actors] [--comments] [--status <status>] [--search <query>]

Display items. With no flags, shows all tasks grouped by status. Supports filtering by status and text search.

Flag	Default	Description
--tasks	false	Show only tasks
--actors	false	Show only actors
--comments	false	Show only comments
--status	—	Filter tasks by status
--search	—	Search tasks by text or tags

$ todo list --status en-cours

Modifying Items

update

todo update <id> [--description <text>] [--due <date>] [--priority <level>] [--actors <ids>] [--tags <tags>] [--blocked-reason <text>] [--position <url>]

Update any item by its ID. Available flags depend on the item type (task, actor, or comment).

Flag	Target	Description
--description	task	New task description
--due	task	New due date
--priority	task	New priority (low, medium, high)
--actors	task	Replace assigned actor IDs (comma-separated)
--tags	task	Replace tags (comma-separated)
--blocked-reason	task	Reason when task is blocked
--position	task	Code position URL
--name	actor	New pseudo
--pic	actor	New picture URL/path
--text	comment	New comment text

$ todo update a1b2 --description "Updated task" --priority high

$ todo update a1b2 --position "file:///C:/project/src/main.rs#L23:5"

update (actor)

todo update <id> --name <pseudo> [--pic <url>] [--actor-type <type>]

Update an actor's pseudo, picture, or type (Human / AgentIa).

$ todo update u0v1 --name "Bob" --actor-type AgentIa

update (comment)

todo update <id> --text <new-text>

Update a comment's text.

$ todo update c1d2 --text "Updated comment"

Scan Source Code

scan

todo scan

Recursively scans all source files in the current directory for TODO: comments and automatically adds them as tasks with their code position. Skips TODO.md, TODO.yaml, .todo/, .git/, node_modules/, and target/. Each detected comment becomes a task with its position column set to the exact file and line number.

$ todo scan

# Scanned 47 files, found 3 TODO: comments

# file://C:/project/src/main.rs#L15:10: "Refactor auth logic"

Switch Format

cwi

todo cwi [md|yaml]

Switch the current working file between Markdown (TODO.md) and YAML (TODO.yaml). With no argument, displays the current format. The format persists in .todo/config and affects all subsequent commands. Both files can coexist — switch freely between them.

$ todo cwi yaml

# Switched to TODO.yaml

$ todo cwi md

# Switched to TODO.md

Utilities

install

todo install

Copy the binary to the user PATH. Windows only. Runs automatically on first launch if not already installed.

$ todo install

Status & Deletion

status

todo status <id> --set <status> [--reason <text>]

Change a task's status. Status values: todo, en-cours, done, bloqued. Provide a reason when setting to bloqued.

Flag	Default	Description
--set	—	New status (todo \| en-cours \| done \| bloqued)
--reason	—	Required when status is bloqued

$ todo status a1b2 --set done

delete

todo delete <id>

Delete a task, actor, or comment by ID. Cascade removes the ID from all references.

$ todo delete a1b2

Dashboard

dashboard

todo dashboard

Start the web dashboard server. Automatically finds an available port starting at 8383. Open http://127.0.0.1:8383 in your browser.

$ todo dashboard

The dashboard features three view modes:
List view — tasks grouped by status with inline detail, comments, and CRUD modals. Displays the Position column linking to source code.
Kanban view — drag-and-drop columns by status with quick-add buttons and position links.
Format switcher — toggle between TODO.md and TODO.yaml directly from the header when both files exist.

Shell Completion

completion

todo completion {bash|zsh|powershell|fish|elvish}

Generate shell completion scripts for tab-completion of all commands and flags. Pipe the output to your shell's completions directory.

Shell	Install command
bash	todo completion bash > /etc/bash_completion.d/todo
zsh	todo completion zsh > "${fpath[1]}/_todo"
powershell	todo completion powershell > "$PROFILE"
fish	todo completion fish > ~/.config/fish/completions/todo.fish

# Source directly without installing

$ . <(todo completion bash)

File Format

TODO.md

A plain Markdown document with three sections: Tasks, Actors, and Comments. When a task has a code position, it includes a Position field.

# Tasks - [ ] a1b2 **Build login** - **Actors**: u0v1 - **Priority**: high - **Created**: 2026-07-07 12:00 - **Position**: "file:///C:/project/src/main.rs#L15:10" - [x] x9k2 **Deploy to prod** - **Due**: 2026-07-15 18:00 # Actors - u0v1 - **Pseudo**: Alice - **Pic**: https://example.com/alice.png - **Type**: Human # Comments - c1d2 - **Text**: This is a comment - **Task**: a1b2 - **Actors**: u0v1

TODO.yaml

An alternative YAML format for the same data model. Switch between formats with todo cwi.

tasks: - id: a1b2 status: Todo description: Build login actors: - u0v1 priority: High created: 2026-07-07 12:00 position: "file:///C:/project/src/main.rs#L15:10" actors: - id: u0v1 pseudo: Alice actor_type: Human comments: - id: c1d2 text: This is a comment task_id: a1b2

AI Agent Skill

SKILL.md

A structured SKILL.md is available to teach AI coding agents how to use todo. Includes all CLI commands (including scan, cwi), the Markdown and YAML data model, the position field, and the HTTP API route table.

npx skills add rayanbo/todo/skills

# Or copy the file manually

$ curl -LO https://raw.githubusercontent.com/RayanBO/todo/main/skills/SKILL.md

CLI Reference