---
name: "todo-txt"
section: "1"
platform: "linux"
package: "todotxt-cli"
version: "2.11.0-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/todo-txt"
---

# todo-txt(1)

simple and extensible shell script for managing todo.txt file

## NAME

todo-txt - simple and extensible shell script for managing todo.txt file

## SYNOPSIS

**todo-txt** \[*-fhpantvV*\] \[*-d todo\_config*\] *action* \[*task\_number*\] \[*task\_description*\]

## OPTIONS

- **-@**

  Hide context names in list output. Use twice to show context names (default).

- **-+**

  Hide project names in list output. Use twice to show project names (default).

- **-c**

  Color mode

- **-d** *CONFIG\_FILE*

  Use a configuration file other than the default ~/.todo-txt/config

- **-f**

  Forces actions without confirmation or interactive input

- **-h**

  Display a short help message; same as action "shorthelp"

- **-p**

  Plain mode turns off colors

- **-P**

  Hide priority labels in list output. Use twice to show priority labels (default).

- **-a**

  Don't auto-archive tasks automatically on completion

- **-A**

  Auto-archive tasks automatically on completion

- **-n**

  Don't preserve line numbers; automatically remove blank lines on task deletion

- **-N**

  Preserve line numbers

- **-t**

  Prepend the current date to a task automatically when it's added.

- **-T**

  Do not prepend the current date to a task automatically when it's added.

- **-v**

  Verbose mode turns on confirmation messages

- **-vv**

  Extra verbose mode prints some debugging information and additional help text

- **-V**

  Displays version, license and credits

- **-x**

  Disables TODOTXT\_FINAL\_FILTER

## ACTIONS

- **add**, **a** *"THING I NEED TO DO +project @context"*

  Adds *THING I NEED TO DO* to your todo.txt file on its own line. Project and context notation optional. Quotes optional.

- **addm** *"FIRST THING I NEED TO DO +project1 @context\<break\>SECOND THING I NEED TO DO +project2 @context"*

  Adds *FIRST THING I NEED TO DO* to your todo.txt on its own line and Adds *SECOND THING I NEED TO DO* to you todo.txt on its own line. Project and context notation optional.

- **addto** *DEST* *"TEXT TO ADD"*

  Adds a line of text to any file located in the todo.txt directory. For example, addto inbox.txt "decide about vacation"

- **append**, **app** *ITEM#* *"TEXT TO APPEND"*

  Adds *TEXT TO APPEND* to the end of the task on line *ITEM#*. Quotes optional.

- **archive**

  Moves all done tasks from todo.txt to done.txt and removes blank lines.

- **command** *\[ACTIONS\]*

  Runs the remaining arguments using only todo.sh builtins. Will not call any .todo.actions.d scripts.

- **deduplicate**

  Removes duplicate lines from todo.txt.

- **del**, **rm** *ITEM#* \[*TERM*\]

  Deletes the task on line *ITEM#* in todo.txt. If *TERM* specified, deletes only *TERM* from the task.

- **depri**, **dp** *ITEM#* \[*ITEM#* ...\]

  Deprioritizes (removes the priority) from the task(s) on line *ITEM#* in todo.txt.

- **do** *ITEM#* \[*ITEM#* ...\]

  Marks task(s) on line ITEM# as done in todo.txt.

- **help \[*ACTION* ...\]**

  Display help about usage, options, built-in and add-on actions, or just the usage help for the passed *ACTION(s)*.

- **list**, **ls** \[*TERM* ...\]

  Displays all tasks that contain *TERM(s)* sorted by priority with line numbers. Each task must match all *TERM(s)* (logical AND); to display tasks that contain any *TERM* (logical OR), use "TERM1TERM2..." (with quotes), or TERM1\\\|TERM2 (unquoted). Hides all tasks that contain *TERM(s)* preceded by a minus sign (i.e. *-TERM*). If no *TERM* specified, lists entire todo.txt.

- **listall**, **lsa** \[*TERM* ...\]

  Displays all the lines in todo.txt AND done.txt that contain *TERM(s)* sorted by priority with line numbers. Hides all tasks that contain *TERM(s)* preceded by a minus sign (i.e. *-TERM*). If no *TERM* specified, lists entire todo.txt AND done.txt concatenated and sorted.

- **listaddons**

  Lists all added and overridden actions in the actions directory.

- **listcon**, **lsc** \[*TERM* ...\]

  Lists all the task contexts that start with the @ sign in todo.txt. If *TERM* specified, considers only tasks that contain *TERM(s)*.

- **listfile**, **lf** \[*SRC* \[*TERM* ...\]\]

  Displays all the lines in *SRC* file located in the todo.txt directory, sorted by priority with line  numbers. If *TERM* specified, lists all lines that contain *TERM(s)* in *SRC* file. Hides all tasks that contain *TERM(s)* preceded by a minus sign (i.e. *-TERM*). Without any arguments, the names of all text files in the todo.txt directory are listed.

- **listpri**, **lsp** \[*PRIORITIES*\] \[*TERM* ...\]

  Displays all tasks prioritized *PRIORITIES*. *PRIORITIES* can be a single one (A) or a range (A-C). If no *PRIORITIES* specified, lists all prioritized tasks. If *TERM* specified, lists only prioritized tasks that contain *TERM(s)*. Hides all tasks that contain *TERM(s)* preceded by a minus sign (i.e. *-TERM*).

- **listproj**, **lsprj** \[*TERM* ...\]

  Lists all the projects (terms that start with a + sign) in todo.txt. If *TERM* specified, considers only tasks that contain *TERM(s)*.

- **move**, **mv** *ITEM#* *DEST* \[*SRC*\]

  Moves a line from source text file (*SRC*) to destination text file (*DEST*). Both source and destination file must be located in the directory defined in the configuration directory. When *SRC* is not defined it's by default todo.txt.

- **prepend**, **prep** *ITEM#* *"TEXT TO PREPEND"*

  Adds *TEXT TO PREPEND* to the beginning of the task on line *ITEM#*. Quotes optional.

- **pri**, **p** *ITEM#* *PRIORITY*

  Adds *PRIORITY* to task on line *ITEM#*.  If the task is already prioritized, replaces current priority with new *PRIORITY*. *PRIORITY* must be a letter between A and Z.

- **replace *ITEM#* *"UPDATED TODO"***

  Replaces task on line *ITEM#* with *UPDATED TODO*.

- **report**

  Adds the number of open tasks and done tasks to report.txt.

- **shorthelp**

  List the one-line usage of all built-in and add-on actions.