todo.sh

List every item

$ todo.sh ls

$ todo.sh add '[description] +[project] @[context]'

$ todo.sh do [item_no]

$ todo.sh rm [item_no]

$ todo.sh pri [item_no] [priority]

$ todo.sh replace [item_no] '[new_description]'

todo.sh [GLOBAL_OPTIONS] ACTION [ARGUMENTS]

Examples:
todo.sh add "Buy milk +groceries @shop"
todo.sh ls
todo.sh do 1
todo.sh mv 1 2

-a
    Act on all todo.txt files across configured directories.

-d DIR
    Specify an alternative directory for todo.txt files.

-f FILE
    Specify an alternative todo.txt file.

-p
    Print the path to the current todo.txt file.

-v
    Display the script version.

add TEXT
    Adds a new task to the todo list. Supports contexts (@context) and projects (+project).

addm TEXT1 TEXT2 ...
    Adds multiple tasks at once.

ls [TERMS]
    Lists tasks. Can filter by keywords, contexts, or projects.

do ITEM# [TEXT]
    Marks a task as done and moves it to done.txt. Optional text is appended to the completed task.

rm ITEM#
    Removes a task from the todo list (typically moves it to done.txt).

prio ITEM# PRIORITY
    Sets or changes a task's priority (e.g., A, B, C).

dp ITEM#
    Removes a task's priority.

app ITEM# TEXT
    Appends text to an existing task.

prep ITEM# TEXT
    Prepends text to an existing task.

replace ITEM# TEXT
    Replaces an existing task with new text.

archive
    Moves all completed tasks from todo.txt to done.txt.

listall
    Lists all tasks in both todo.txt and done.txt.

report
    Shows a summary of tasks by project and context.

help [ACTION]
    Displays general help or specific help for an action.

todo.sh is a minimalist, command-line interface (CLI) todo list manager that operates directly on plain text files. It adheres to the todo.txt philosophy, where tasks are stored in a simple, human-readable text file (typically todo.txt and done.txt). This approach emphasizes flexibility, portability, and independence from complex database systems or proprietary formats.

Users can quickly add, list, prioritize, complete, and archive tasks using a straightforward set of commands. Its strength lies in its simplicity and reliance on standard Unix tools, making it highly scriptable and easy to integrate with other command-line workflows. It's often favored by developers, system administrators, and anyone who prefers a lightweight, keyboard-driven productivity tool. Its plain text format also ensures future compatibility and easy syncing across devices.

todo.sh is a shell script, typically depending on standard Unix utilities (e.g., grep, sed, awk).

It manages tasks in a plain text file, which means it doesn't offer advanced features like reminders, recurring tasks, or complex sorting beyond what can be scripted or manually managed. Its lack of a graphical user interface (GUI) might be a limitation for some users. While highly portable, ensuring consistent setup across different systems requires manual configuration of the script and its environment variables.

The behavior of todo.sh can be customized via a configuration file, typically located at $HOME/.todo/config or /etc/todo/config. This file allows setting default directories, custom actions, and various display options.

Tasks are stored one per line in todo.txt. Completed tasks are moved to done.txt. Priorities are indicated by (A), (B), etc. at the beginning of a line. Projects start with +project and contexts with @context. This simple, human-readable format is central to its portability and extensibility.

The todo.sh script is the command-line interface implementation of the todo.txt philosophy, which was conceived by Gina Trapani around 2006. The core idea was to create a simple, portable, and future-proof way to manage tasks using nothing more than a plain text file.

The project gained popularity in the GTD (Getting Things Done) community for its minimalist approach. While there isn't a single 'official' historical development for the todo.sh script itself (as it's often a community-maintained or self-adapted tool), its continuous development and widespread usage are rooted in the open-source spirit and the enduring appeal of the todo.txt format. It has been refined over the years by various contributors, adhering to the original principles of simplicity and plain text.

grep(1): For searching text patterns, similar to how todo.sh filters tasks., sed(1): Stream editor, often used for text manipulation, which todo.sh might use internally., awk(1): Pattern scanning and processing language, another common internal tool., vim(1) / nano(1) / emacs(1): Text editors, directly usable for managing todo.txt files., Other CLI todo managers (e.g., taskwarrior, pal): Offer similar or more advanced task management from the command line.