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"]