otty / apps

All apps/todo.txt-cli

todo.txt-cli

todotxt-cli

A simple and extensible shell script for managing your todo.txt file.

Runs as todo.sh|macOS, Linux|todotxt.org

Open form in Otty otty.toml

Sync rules

What travels, what stays, what never leaves

todo.txt-cli in your home directory Every rule on this page, by file

· ~/.todo/config Sync

· ~/todo.cfg Sync

· ~/.todo.cfg Sync

· ~/.config/todo/config Sync

Only what the catalog names. A directory that syncs brings everything inside it except what is listed as excluded here.

apps/todotxt-cli/otty.tomlThe file this page is generated from

id = "todotxt-cli"

name = "todo.txt-cli"

homepage = "http://todotxt.org"

description = "A simple and extensible shell script for managing your todo.txt file."

# The todo.txt mark, as the todotxt organisation's avatar — todotxt.org is

# served over plain HTTP only.

icon = "https://github.com/todotxt.png"

executables = ["todo.sh"]

platforms = ["macos", "linux"]

[dotfiles]

# todo.sh itself lists the places it looks, in order, in the

# `configFileLocations` array just above the loop that picks the first one that

# exists:

# "$HOME/.todo/config"

# "$HOME/todo.cfg"

# "$HOME/.todo.cfg"

# "${XDG_CONFIG_HOME:-$HOME/.config}/todo/config"

# "$(dirname "$0")/todo.cfg"

# "$TODOTXT_GLOBAL_CFG_FILE"

# The last two are the installed template beside the script and the system-wide

# file, neither of which is user config; the first four are, and the XDG one

# reads the variable, so it is written as [configHome].

# The README's macOS install step copies the template to the second spelling

# ("cp -n $(brew --prefix)/opt/todo-txt/todo.cfg ~/.todo.cfg"), which is why

# more than one of these is worth listing.

paths = [

"~/.todo/config",

"~/todo.cfg",

"~/.todo.cfg",

"[configHome]/todo/config",

]

exclude = []

# The config is a shell file of exported variables — TODO_DIR, the colour

# assignments, TODOTXT_DEFAULT_ACTION and friends. Nothing in it is a

# credential; the todo.txt and done.txt it points at are plain task lists.

secret = []

# No machine_lines. TODO_DIR is the obvious candidate, but the README's own

# framing of it — "relocating the todo.txt directory to a subdirectory of the

# user's home directory, or onto a cloud drive (via the TODO_DIR variable)" —

# is precisely the setting a user wants to keep on every machine, and the

# template writes it relative to $HOME rather than as an absolute path.

# todo.sh sources the config on every invocation and exits.

side_effect = false

[commands]

format = 1

label = "Run a todo.sh action"

description = "Run one todo.sh action (add, list, done, pri ...) with its arguments and the common global options. Hide/show toggles (-@, -+, -P), verbosity levels and add-on actions are left out."

quality = "ai-draft"

parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = true }

[[commands.source]]

id = "help"

kind = "help"

url = "https://raw.githubusercontent.com/todotxt/todo.txt-cli/HEAD/todo.sh"

revision = "2026-10-27"

evidence = """

Usage: todo.sh [-fhpantvV] [-d todo_config] action [task_number] [task_description]

Actions:

add|a "(B) THING I NEED TO DO +project @context"

append|app NR "TEXT TO APPEND"

archive

del|rm NR [TERM]

depri|dp NR [NR ...]

done|do NR [NR ...]

list|ls [TERM...]

listall|lsa [TERM...]

listcon|lsc [TERM...]

listpri|lsp [PRIORITIES] [TERM...]

listproj|lsprj [TERM...]

move|mv NR DEST [SRC]

prepend|prep NR "TEXT TO PREPEND"

pri|p NR PRIORITY [NR PRIORITY ...]

replace NR "UPDATED TODO"

Options:

-c

Color mode

-d CONFIG_FILE

Use a configuration file other than one of the defaults:

-f

Forces actions without confirmation or interactive input

-p

Plain mode turns off colors

-a

Don't auto-archive tasks automatically on completion

-n

Don't preserve line numbers; automatically remove blank lines

on task deletion

-t

Prepend the current date to a task automatically

when it's added.

-v

Verbose mode turns on confirmation messages

"""

[[commands.field]]

id = "action"

label = "Action"

description = "Action name or alias. Add-on actions installed in the actions directory also work."

type = "string"

position = 0

suggestions = [{ value = "add", label = "Add a task" }, { value = "list", label = "List tasks" }, { value = "listall", label = "List tasks including done.txt" }, { value = "done", label = "Mark tasks done" }, { value = "pri", label = "Set priority" }, { value = "depri", label = "Remove priority" }, { value = "append", label = "Append text" }, { value = "replace", label = "Replace a task" }, { value = "del", label = "Delete a task" }, { value = "archive", label = "Archive done tasks" }, { value = "listproj", label = "List projects" }, { value = "listcon", label = "List contexts" }]

sources = ["help"]

[[commands.field]]

id = "args"

label = "Arguments"

description = "Task numbers, text or search terms, as the action expects. Quote task text."

type = "string"

position = 1

multiple = true

sources = ["help"]

[[commands.field]]

id = "config_file"

label = "Config file"

type = "path"

option = ["-d"]

path = { kind = "file", role = "input" }

sources = ["help"]

[[commands.field]]

id = "force"

label = "Force without confirmation"

type = "boolean"

option = ["-f"]

effect = "overwrite"

sources = ["help"]

[[commands.field]]

id = "plain"

label = "Plain mode (no colors)"

type = "boolean"

option = ["-p"]

sources = ["help"]

[[commands.field]]

id = "color"

label = "Color mode"

type = "boolean"

option = ["-c"]

sources = ["help"]

[[commands.field]]

id = "no_archive"

label = "Do not auto-archive on completion"

type = "boolean"

option = ["-a"]

sources = ["help"]

[[commands.field]]

id = "no_preserve"

label = "Do not preserve line numbers"

description = "Blank lines are removed when a task is deleted."

type = "boolean"

option = ["-n"]

effect = "delete"

sources = ["help"]

[[commands.field]]

id = "date_on_add"

label = "Prepend date when adding"

type = "boolean"

option = ["-t"]

sources = ["help"]

[[commands.field]]

id = "verbose"

label = "Verbose"

type = "boolean"

option = ["-v"]

sources = ["help"]

[[commands.task]]

id = "add_task"

label = "Add a task"

fields = ["action", "args", "date_on_add", "verbose"]

required = ["args"]

set = { action = ["add"] }

[[commands.task]]

id = "list_tasks"

label = "List tasks"

fields = ["action", "args", "plain"]

set = { action = ["list"] }

[[commands.task]]

id = "complete"

label = "Mark tasks done"

fields = ["action", "args", "no_archive", "verbose"]

required = ["args"]

set = { action = ["done"] }

[[commands.group]]

id = "basic"

label = "Basic"

fields = ["action", "args", "date_on_add", "plain"]

[[commands.group]]

id = "advanced"

label = "Advanced"

fields = ["config_file", "force", "color", "no_archive", "no_preserve", "verbose"]

Use it with your dotfile manager

Same data, in the shape your tool already reads

Opens Otty and adds this tool to what it syncs

Opens otty://sync/add/todotxt-cli. Otty ships with this catalog, so the link only has to name the tool — nothing is downloaded.

Every one of these is generated from the same rules as this page.