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.
• todo Set following task(s) to todo.
• done Set following task(s) to done.
• archive Archive following 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, bold tags, a bold task description, and [duration]. Long task descriptions are ellipsized so duration stays visible. Press Right to reveal a task's notes and Left to hide them.

State tags

Task state is represented by tags rather than a database status field: done, archived, active, and paused. A paused task also has the active tag. These state 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.

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.

When listing, smaller priority number tasks appear first (at the top of the output). Both the CLI list commands and the TUI use priority-ascending order.

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

todo

Set following task(s) to todo.

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

done

Set following task(s) to done.

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

archive

Archive following 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: 🏹