Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/xwmx/nb/llms.txt

Use this file to discover all available pages before exploring further.

nb todo (shortcut: nb to) creates and manages structured todo items stored as Markdown files (.todo.md). Each todo is a single primary task with an optional due date, description, subtask list, related links, and tags. The companion commands nb todos, nb tasks, nb do, and nb undo let you list, filter, complete, and re-open todos and individual tasks.

​
Usage

nb todo add [<notebook>:][<folder-path>/][<filename>] <title>
            [--description <description>] [--due <date>]
            [-r (<url> | <selector>) | --related (<url> | <selector>)]
            [--tags <tag1>,<tag2>...] [--task <title>...]
nb todo delete ([<notebook>:][<folder-path>/][<id> | <filename> | <title>])
nb todo do   ([<notebook>:][<folder-path>/][<id> | <filename> | <description>])
             [<task-number>]
nb todo undo ([<notebook>:][<folder-path>/][<id> | <filename> | <description>])
             [<task-number>]
nb todos [<notebook>:][<folder-path>/] [open | closed] [--pager]
             [--tags <tag1>,<tag2>...]
nb todos tasks ([<notebook>:][<folder-path>/][<id> | <filename> | <description>])
               [open | closed] [--pager]
nb tasks ([<notebook>:][<folder-path>/][<id> | <filename> | <description>])
         [open | closed] [--pager]
nb do ([<notebook>:][<folder-path>/][<id> | <filename> | <title>])
      [<task-number>]
nb undo ([<notebook>:][<folder-path>/][<id> | <filename> | <title>])
        [<task-number>]

​
Todo File Format

Todos are structured Markdown documents. The title line uses an [ ] / [x] checkbox heading to indicate open/closed status: 
# [ ] Example todo title.

## Due

2100-01-01

## Description

Example description.

## Tasks

- [ ] Task one.
- [x] Task two.
- [ ] Task three.

## Related

- [[example:123]]
- <https://example.com>

## Tags

#tag1 #tag2
The # [ ] Title heading is the primary status indicator. nb updates it to # [x] Title when you run nb do. All other sections are optional.

​
Creating Todos

​
Basic Todo

# create a new todo
nb todo add "Example todo one."
# Added: [1] ✔️ [ ] Example todo one.

# view the generated file
nb show 1 --print
# # [ ] Example todo one.

​
With a Due Date

Use --due to add a ## Due section: 
nb todo add "Example todo two." --due "2100-01-01"

nb show 2 --print
# # [ ] Example todo two.
#
# ## Due
#
# 2100-01-01

​
With a Description

nb todo add "Example todo three." --description "Example description."

nb show 3 --print
# # [ ] Example todo three.
#
# ## Description
#
# Example description.

​
With Subtasks

Add one or more --task options to create a ## Tasks checklist: 
nb todo add "Example todo seven." \
  --task "Task one." \
  --task "Task two." \
  --task "Task three."

nb show 7 --print
# # [ ] Example todo seven.
#
# ## Tasks
#
# - [ ] Task one.
# - [ ] Task two.
# - [ ] Task three.
Link related nb items or external URLs using -r / --related: 
nb todo add "Example todo four." --related example:123 -r https://example.com

nb show 4 --print
# # [ ] Example todo four.
#
# ## Related
#
# - [[example:123]]
# - <https://example.com>

​
With Tags

nb todo add "Example todo five." --tags tag1,tag2

nb show 5 --print
# # [ ] Example todo five.
#
# ## Tags
#
# #tag1 #tag2

​
Options for todo add

​
<title>
string
required
The title of the todo. This becomes the # [ ] Title heading.
​
--description <description>
string
A description placed in a ## Description section.
​
--due <date>
string
A due date or time placed in a ## Due section.
​
-r, --related (<url> | <selector>)
string
A related URL or nb selector. Use multiple times to add multiple related items.
​
--tags <tag1>,<tag2>...
string
A comma-separated list of tags added as #hashtags in a ## Tags section.
​
--task <title>
string
A task title to add to the ## Tasks checklist. Use multiple times for multiple tasks.

​
Listing Todos

Use nb todos to list all todos in the current notebook: 
# list all todos
nb todos
# [6] ✔️ [ ] Example todo six.
# [5] ✅ [x] Example todo five.
# [4] ✔️ [ ] Example todo four.

# list todos in the "sample" notebook
nb todos sample:

# list open todos only
nb todos open

# list closed todos only
nb todos closed

# list todos with a specific tag
nb todos --tags tag1

​
Marking Todos Done and Undone

​
nb do / nb todo do

Mark a todo as done (closed). The heading changes from # [ ] to # [x]: 
nb todo add "Example todo six."
# Added: [6] ✔️ [ ] Example todo six.

nb do 6
# Done: [6] ✅ [x] Example todo six.

# alternative: nb todo do
nb todo do 6

​
nb undo / nb todo undo

Re-open a closed todo: 
nb undo 6
# Undone: [6] ✔️ [ ] Example todo six.

# alternative: nb todo undo
nb todo undo 6

​
Tasks

Any Markdown document can contain tasks, not just .todo.md files. Tasks are Markdown list items beginning with - [ ] (open) or - [x] (done): 
- [ ] Example open task.
- [x] Example closed task.

​
Listing Tasks with nb tasks

nb tasks (shortcut: nb t) lists both tasks and todos across notebooks, folders, and individual items: 
# list tasks in item 7
nb tasks 7
# [7] ✔️ [ ] Example todo seven.
# ------------------------------
# [7 1] [x] Task one.
# [7 2] [x] Task two.
# [7 3] [ ] Task three.

# list all tasks in the "example" notebook
nb tasks example:

# list open tasks only
nb tasks open

# list closed tasks only
nb tasks closed

# list open tasks in item 7
nb tasks open 7
Tasks are identified by the item selector followed by a space and the sequential task number, e.g. 9 2 is task 2 inside item 9.

​
Completing and Reopening Tasks

Use nb do with a task number to mark a specific task as done: 
# mark task 2 in item 9 as done
nb do 9 2
# Done: [9 2] [x] Task two.

# undo task 2 in item 9
nb undo 9 2
# Undone: [9 2] [ ] Task two.

​
nb todos tasks

List tasks specifically within the todo system: 
nb todos tasks
nb todos tasks 7
nb todos tasks open
nb todos tasks closed

​
Examples

1

Create a todo with full metadata

nb todo add "Write quarterly report" \
  --due "2024-03-31" \
  --description "Cover Q1 metrics and projections." \
  --tags work,reports \
  --task "Gather metrics." \
  --task "Draft outline." \
  --task "Review with team."
2

List open todos

nb todos open
3

Mark a todo as done

nb do 3
4

Mark a specific subtask as done

nb do 3 2
5

Re-open a completed todo

nb undo 3
6

Browse todos in the web interface

nb browse --tag work

​
Shortcut Aliases

CommandAlias / ShortcutDescription
nb todonb toManage todos
nb todo addnb todo a, nb todo +Add a new todo
nb todo deletenb todo -Delete a todo
nb todosnb todoList todos (alias)
nb tasksnb tList tasks and todos

​
Subcommand Reference

nb todo add

Create a new structured todo with optional due date, description, tasks, related links, and tags.

nb todo do / nb do

Mark a todo or a specific numbered task as done. Updates the [ ] checkbox to [x].

nb todo undo / nb undo

Re-open a done todo or task. Reverts [x] back to [ ].

nb todos

List todos. Filter with open, closed, or --tags.

nb tasks / nb t

List tasks across all items in a notebook. Also lists todos. Filter with open or closed.

nb todos tasks

List tasks within the todo system, with optional open/closed filter.

Build docs developers (and LLMs) love

Get started for freeTalk to us