Notewell - Command Line Notetaker

Basic Syntax

usage: notes [notebook]
usage: notes [notebook] [-ilmnr]
usage: notes —list
 help: notes —help

if no notebook is specified the default is used (see below)

Examples

notes [notebook]

• to enter a note, just type normally
• type Enter then Control-D to record your note
• type Control-C to discard the note

notes [notebook] < mynotes.txt

• you may also redirect/pipe text from a file or process (STDIN)

notes [notebook] -m

• same as above except input will be divided at blank lines into multiple notes
• this is a good way to load many notes from a text file
• note that multiple blank lines will generate empty notes

notes http[s]://somewhere.com/some/page.html

• fetch the title and first 1Kb of content from a web page

notes [notebook] -r

• reads entire notebook to standard output (STDOUT)

notes [notebook] > out.txt
notes [notebook] | more

• you may redirect this to a file or pipe

notes [notebook] -e

• open notebook file with external editor

notes -flag
notes —command

• -n or —new
  • create new notebook
  • follow prompts for notebook name and title
• -l or —list
  • list all notebooks
  • quick list if when you need to check
• -i or —index
  • reindex all notebooks
  • generally only needed after editing notes with external editor

Searching

Each notebook has an index based on fuzzy search codes (modified soundex). These codes lump word variations and similar sounding words together (eg, star, stars, and story all have the same code). This tends to broaden most searches a bit. However, searches use AND logic by default. This means that each note returned contains ALL if the search terms. You may override this behavior with the (+/-) modifiers discussed below. In addition, you should try synonyms if you are not finding what you expect (eg, cold instead of freezing).

notes [notebook] ? stars stripes

• query notebook for words stars AND stripes in the same note
• this is the default, but can be overridden with the modifiers shown below

notes [notebook] ? stars +stripes

• query specific notebook for words stars OR stripes in any note

notes [notebook] ? stars -stripes

• query specific notebook for words stars but NOT stripes in the same note

notes ?? stars stripes

• query all notebooks

Basic Setup

First, setup a directory to receive your notes (something like ~/Notes). Place the notes.pl script there and make it executable. To make it broadly available, create an alias in your preferred shell (nb, nw, notes, notewell, or something similar).

Then edit these global varibles to fit your system…

my $Root = '/home/userid/Notes';

• full path to the notes directory

my $Default = 'notes';

• the name of your default notebook (when none is specified)

my $Editor  = 'edit';

• the name of your preferred text editor

my $Delim    = '=====';

• note delimiter, change only if you need to

You can also add or delete words from the %Skip hash…

my %Skip = (

• a => 1,
• after => 1,
• also => 1,
• and => 1,
• …

To prime the system, issue the command to create the default notebook discussed above…

"notes —new"

Give it a name and title.

File Format

Notebooks are plain text files with the extension .notes. They each have a corresponding index file ending in .index. The first line should be a brief description of the notebook (eg, Default Notebook).

The actual notes are delimited by timestamp lines similar to this…

 ===== z7UnO Oct 20, 2025 20:11:05 userid ==========

Where z7UnO is the unique identifier for the note. This is generated randomly and should not repeat. The userid is the login name of the person who created the note. This leaves open the possibility of notebooks shared by several users. Notes may be complex and span several lines.

The modified soundex index has the format <code> <noteid>,<noteid>,…

…

9000 O7I1q
9900 iqRJX,z7UnO
A000 iqRJX,ue557,O7I1q
A160 iqRJX,O7I1q,uE476
A170 dISTL
A178 L6T7b,0moK0
A293 J53j8
…

The four letter code summarises the first four to ten characters of the word (vowels are ignored). Common plural forms are also ignored (eg, star and stars have the same code). The first letter must be a direct match so it is worth trying both C and K, etc. The first four digits of numbers are also indexed. This allows you to search for dates like 1917 directly. Shorter numbers will overlap: 9, 90, 900, 9000 are all coded the same.