senile

A command-line todo list and time tracker.

Overview

This utility functions as a personal todo list and time tracker. You can create tasks with tags and they are saved in sqlite3 file: ~/.senile.db.

Installation

install from pypi (recommend)

python3 -m pip install senile

install from git (latest master)

python3 -m pip install -U git+https://gitlab.nul.one/mush/senile.git

senile supports Python 3.11, 3.12, and 3.13.

development installation

Create an isolated environment, then install development dependencies:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e '.[dev]'

Run the quality checks and test suite with:

python -m ruff check .
python -m ruff format --check .
python -m pytest --cov=senile

Usage

Commands:

• add Add a new task.
• modify Modify existing task.
• remove Delete following task(s).
• list List non-archived tasks.
• list-all List all tasks, including archived tasks.
• start Start a task or resume the paused task.
• stop Stop tasks.
• pause Pause the active task while keeping it in focus. Alias: p.
• done Toggle done state for task(s).
• archive Toggle archive state for task(s).
• info Show details for one task or list-style summaries and notes for multiple tasks. With no IDs, shows only active and paused tasks.
• tags List all tags and their counts.
• edit Open task notes for editing.
• focus Show the active task and its elapsed duration. Alias: f.
• normalize Remove orphaned tags and normalize task IDs.
• tui Open the interactive task list. Alias: ui.

The tui screen loads all tasks (including archived) and filters them when you press Enter. Filters support words, +tag, -tag, and %MAX_PRIORITY. Tasks are displayed in priority-ascending order (lower number = more important = shown first). Use Tab to select tasks, Enter to edit a task's description, tags, and notes, and the shortcuts below:

After a status, tag, notes, archive, or delete change, only the affected pane is updated or removed — the rest of the list is left untouched. If a changed task no longer matches the current filter (or is deleted), its pane is removed and focus moves to the next pane, or the previous one if it was last.

Task panes show a right-aligned priority, a bold task description, bold tags, and [duration]. Long task descriptions are ellipsized so tags and duration stay visible. Press Right to reveal a task's notes and Left to hide them.

State tags

Workflow state is represented by done, active, and paused tags rather than a database status field. A paused task also has the active tag. These tags are shown, editable, and filterable like every other tag. Changing them applies the associated task action: removing active also removes paused and stops timing; adding active starts timing and stops any other active task. If multiple active tasks are found at startup, senile stops all of them and displays a warning.

archived is an independent convenience tag for hiding or deprioritizing a task. It has no lifecycle or timing meaning: an archived task can be todo, active, paused, or done. The archive command only toggles this tag. To remove both done and archived, use modify -done -archived.

In display and sorting, archived takes precedence over done: the priority column shows 🗄️ if a task is archived (even if it is also done), and ✔️ only when a task is done but not archived. CLI listings sort archived tasks first, done-only tasks second, and all other tasks last.

Task priority

Use %NUMBER to set a task's priority when adding or modifying it, for example senile add "Submit report" %10. Use %MAX_PRIORITY with list or list-all to show only tasks with that priority or lower. Lower priority numbers are more important.

When adding a task without %NUMBER, senile prompts for its priority. The default is 20 when the prompt is left empty.

The TUI uses priority-ascending order. CLI listings put archived tasks first, then done tasks, and order each group by descending priority so lower-numbered, more important tasks remain visible at the bottom of long terminal output.

add

Add a new task.

• When no priority is specified, prompts for a priority before opening the notes editor. The default priority is 20.

• aliases: a

• usage: senile add Some text description +tag1 +tag2 +tag3 %PRIORITY

• example: senile add Submit the project +work +project +new %10

modify

Modify existing task.

• aliases: mod, m
• usage: senile mod ID_OR_UUID Updated text -TAG_TO_REMOVE +TAG_TO_ADD %PRIORITY
• example: senile mod 5 Re-submit the finished project -new +old %10

remove

Delete following task(s).

• aliases: rm
• usage: senile rm ID_OR_UUID_1 ID_OR_UUID_2 ID_OR_UUID_3
• example: senile rm d59de172 fcf8799e 4 5

list

List non-archived tasks.

• aliases: ls, l
• usage: senile l SOME_TEXT_TO_SEARCH +CONTAIN_TAG -DO_NOT_CONTAIN_TAG %MAX_PRIORITY
• example: senile l project +work -old %10
• use + by itself to show only tasks without tags; use - by itself to exclude tasks without tags

list-all

List all tasks, including archived tasks.

• aliases: la, ll
• usage: senile list-all SOME_TEXT_TO_SEARCH +CONTAIN_TAG -DO_NOT_CONTAIN_TAG %MAX_PRIORITY
• example: senile list-all project +work -old %10
• use + by itself to show only tasks without tags; use - by itself to exclude tasks without tags

start

Start a task or resume the paused task.

• aliases: s
• usage: senile start [TASK_ID_OR_UUID]
• example: senile start 5
• note: Without an ID, resumes the paused task. Only 1 task can be focused.

stop

Stop tasks.

• Called without arguments and stops a single task that was started.

pause

Pause the active task while keeping it in focus. Its elapsed duration stops increasing until it is started again.

• alias: p

done

Toggle done state for task(s).

• usage: senile done ID_OR_UUID_1 ID_OR_UUID_2 ID_OR_UUID_3
• example: senile done d59de172 fcf8799e 4 5

archive

Toggle archive state for task(s).

• aliases: ar, arc, arch
• usage: senile archive ID_OR_UUID_1 ID_OR_UUID_2 ID_OR_UUID_3
• example: senile archive d59de172 fcf8799e 4 5

info

Show details for one task or list-style summaries and notes for multiple tasks. With no IDs, shows only active or paused tasks.

• aliases: i
• usage: senile info [TASK_ID_OR_UUID ...]
• example: senile info d59de172 fcf8799e

tags

List all tags and their counts.

• aliases: t, tag
• Called without arguments. Lists tags of all tasks, even archived.

edit

Edit notes for a task.

• aliases: e, notes, n
• usage: senile edit TASK_ID_OR_UUID
• Opens a multiline prompt where you can edit notes. (Alt+Return to finish)
• Notes are rendered as Markdown by senile info.

Configuration

Configuration options are available as environment variables that you need to export, either on each senile command or in your environment file (e.g. .bashrc, .profile, etc.).

Data file

By default, senile creates and uses an sqlite3 database file located at ~/.senile.db. Export SENILE_DB_PATH variable to desired alternative file location.

The database is preserved across application upgrades. The first start after an upgrade from the old status-column schema creates a numbered .bak backup next to the database before migrating its data. To make your own backup:

cp ~/.senile.db ~/.senile.db.backup

TUI filter

The TUI saves a filter to ~/.senile.rc when it is applied with Enter, and restores it on the next start. Quitting does not change the saved filter. Set SENILE_RC_PATH to use a different file.

Icons

You can change default status icon theme by exporting SENILE_ICON_THEME. Possible values are:

• default - standard theme
  • archived: 🗄️
  • done: ✔️
  • todo: ⭕
  • active: 🔴
• text
  • archived: h
  • done: d
  • todo: T
  • active: A
• senile
  • archived: 👓
  • done: ⚰️
  • todo: 📰
  • active: 🧠
• love
  • archived: 💔
  • done: 💖
  • todo: ❤️
  • active: 💘
• xmas
  • archived: ☃️
  • done: 🎁
  • todo: 🎄
  • active: 🛷
• archery
  • archived: 🐺
  • done: 🏅
  • todo: 🎯
  • active: 🏹