timestampr(CLI)

A bare-bones note-taker. Dead simple to use. Helps keep you on track.

---

0 - Prologue

Imagine:

Your notebook was laying open while you worked. You were multi-tasking. You were sporadically jotting down notes. You were working late to meet a deadline. Repeat ad nauseam. Now skip ahead a year or more. You need to write a grad thesis based on those notes.

If you were using pen and paper:

• your notes are probably a mess;
• you will waste a month of Sundays trying to decipher them;
• you might need to defer your graduation.

If you were using timestampr(CLI):

• your notes were timestamped and filed (by date or topic);
• your notes are now searchable, sortable, and exportable;
• you might have time to go camping this weekend.

---

1 - What it does

timestampr(CLI) lets you jot ultra-quick notes from any terminal.
Each notebook is just a folder on your laptop;
Each page is a .csv file inside that folder;
Each line is:

N,YYYY-MM-DD,HH:MM:SS,Your note text…

Since it is plain text, you can easily grep, sync to the cloud, or open in Excel.

---

2 - Quick start

bash
# 1. pick or create a folder for your notebook
stamp notebook              # will ask for the path

# 2. pick or create a page
stamp page                  # name it or press <Enter> for an auto-dated page

# 3. write notes
stamp - fixed issues 42-43
stamp - inoculated flask `#16

---

3 - Commands available

Command & arguments	Action
stamp - <note text>	New note
stamp active	Display active notebook & page
stamp page	Change page
stamp notebook	Change notebook
stamp show ... (head / foot / all / first / last)	Show notes (first/last 10, all, or very first/last)
stamp show N (e.g. stamp show 27)	Show notes at index N (or range N to M)
stamp times query (e.g. stamp times from 08:00 to 13:00)	Show notes in range (by dates and/or times)
stamp clock ... (12h / 24h)	Convert timestamps on active page to 12h or 24h format
stamp search keyword	Search notes containing keyword (case-insensitive)

For peace of mind, a message like this appears every time a note is added successfully:

stamp success: wetlab_log 2025-07-30 15:42:01 inoculated all flasks for overnight culture…

---

3.1 Special characters: escaping

Basic use: backticks (tested in PowerShell)

The following characters are accepted without any fuss: . ! ? / \ - _ = + : [ ] % ^ * ~.
Other characters can be used if preceded by a backtick ` including , ; ' ( ) { } | @ # $ & < >.
Use single ' quotes when needed. Double quotation marks are not escaped with backticks.

---

3.2 Special characters: alternative approaches

Some characters like &, |, (, ), {, }, [, ], and others are interpreted by your shell before stamp sees them. Use one of the approaches below:

Easiest: interactive entry

stamp -
note> fix @mentions & quotes 'single', hash #, pipe |, braces { } [ ] ( ) , commas

Pipe the note via stdin

printf '%s' 'ALL SPECIALS: # & @ ( { [ | , } ] ) ^ ~ ! $ % * +' | stamp -

PowerShell

Use single quotes for literal text and double a single quote inside:

stamp - 'fix @mentions & quotes single, hash #, pipe |, braces { } [ ] ( ) , commas'
stamp - 'Don''t break single quotes'

Windows CMD

Prefer interactive mode (stamp -) or escape operators with ^ when using quotes:

stamp - "fix @mentions & quotes single, hash #, pipe ^|, braces { } [ ] ( ) , commas"

Bash / Zsh

Use single quotes for literal text; escape a single quote by closing and reopening:

stamp - 'fix @mentions & quotes single, hash #, pipe |, braces { } [ ] ( ) , commas'
stamp - 'Don'\''t break single quotes'

CSV safety: Notes are saved with csv.writer, so commas and quotes are handled correctly.

---

4 - Installation

4.1 Windows

Using pip

py -m pip install git+https://github.com/Donnie-McFarlane/timestampr.git

From source

git clone https://github.com/Donnie-McFarlane/timestampr.git
cd timestampr
py -m pip install .

4.2 Mac / Linux

Using pip

bash
pip install git+https://github.com/Donnie-McFarlane/timestampr.git

From source

bash
git clone https://github.com/Donnie-McFarlane/timestampr.git
cd timestampr
pip install .

---

5 - Dependencies

Runtime: Python ≥ 3.8 and the standard library – no external packages required.
Packaging-time: setuptools (installed automatically by pip). The CLI works on Linux, macOS and Windows when a compatible Python interpreter is available.

---

6 - File locations

Item	Location
User config	~/.timestampr/config.json (on Windows: C:\Users\<you>\.timestampr\config.json)
Notebook folder	path provided by stamp notebook
Page files	<notebook>/<page>.csv

---

7 - Back-ups & syncing

Because everything is plain text, simply back-up or sync your notebook folder (e.g. with Git, Dropbox, OneDrive, etc.).

---

8 - Uninstall

8.1 Windows

py -m pip  uninstall timestampr        # removes the CLI tool
rm -rf ~/.timestampr                   # removes stored config

8.2 Mac / Linux

bash
pip uninstall timestampr        # removes the CLI tool
rm -rf ~/.timestampr            # removes stored config

---

Thanks for reading! I hope my little side-quest here helps you to stay organized and save a bit of time for yourself.