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.
3. Update with uv tool update jot.

Requires Python >=3.10.

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 config.json file, which is saved to the OS-dependent location resolved by platformdirs.user_config_path("jot").

Each jotting is timestamped and prepended to your text file:

[2025-08-28 11:15] ate an apple
[2025-08-27 10:58] ate a kiwi
[2025-08-26 11:09] ate a pineapple
[2025-08-25 10:40] ate an apple and a pear

Options

You can review your jottings using the provided options. For example:

• jot -l 3 to list the last three
• jot -s apple -l 1 to search for 'apple' and limit to the most recent one
• jot -s "[^pine]apple" to search for 'apple' with a regular expression that excludes 'pineapple'
• jot -f 20250825 -t 20250828 to return jottings from 25 Aug 2025 (inclusive) and to 28 Aug 2025 (exclusive)

And for information:

• 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, which includes possible option combinations

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 tool 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).