jot

Minimal opinionated Python command-line interface (CLI) to jot timestamped thoughts.

Install

Recommended:

1. Install uv.
2. Run uv tool install git+https://github.com/matt-dray/jot in a terminal.

Requires Python >=3.10. To update: uv tool update jot.

CLI

Write

Open a terminal and write a jotting:

jot "ate an apple"

The first time you run jot, you'll be prompted for a path to a text file where your jottings will be written. The file path will be stored under the JOT_PATH key in a jot-config.json file saved to the location given by pathlib's Path.home().

Each jotting is timestamped and prepended to the text file in the form [2025-08-25 11:15] ate an apple.

Options

You can append optional flags. For example:

• jot -l 5 to list the last 5 jottings
• jot -s apple to search for 'apple' in jottings
• jot -s apple -l 3 to search for 'apple' and limit to 3 jottings
• jot -s "2025-08-2([5-9]).*apple" to search with regex for 'apple' in a given work week
• jot -w to show where the config and jot files are
• jot -v to get the version number
• jot -h to show the help file

Python

jot is CLI-first, but you can also import its functions to a Python session. For example, assuming you already set up a jot file:

from jot import *
config_path = get_config_path()
jot_path = read_jot_path(config_path)
search_jottings(jot_path, "apple")

Notes

• I developed this to help me remember the tasks I've done during my day job and later reflect.
• Your kilometerage may vary; leave an issue if you find bugs or have suggestions.
• v0.1.0 developed via LLM, v0.2.0 rewritten with my brain (you can read about it).