jot

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

Install

jot is available as jot-cli from PyPI.

Recommended:

1. Install uv.
2. Run uv tool install jot-cli in a terminal.
3. Update with uv tool upgrade jot-cli when there's a new release.

To install the current development version: uv tool install git+https://github.com/matt-dray/jot.

Alternatively you can use pipx: pipx install jot-cli.

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 (.txt or .md) 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

You can quote your text input to preserve special characters. Note that line breaks will be replaced with a space.

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 list 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)

You can back up your jottings to a GitHub gist using GitHub's CLI. To do this:

1. Download the gh CLI.
2. Login with gh auth login.
3. Create a new GitHub gist.
4. Write some jottings with e.g. jot ate an apple.
5. Run jot -u to upload the contents of your jot file to the gist.

You'll be asked for a gist ID when you first run jot -u. This is the 32-character string found in the gist's URL or with gh gist list.

There are also flags to get meta-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

Notes

• I developed this tool to help me remember and reflect on the tasks I've done during my day job.
• Your kilometerage may vary; leave an issue if you find bugs or have suggestions.
• You can read more about the development of the tool in a series of blog posts.