note.py -- Command-line notebook program with YAML persistence


note.py is written in Python3. To use note.py you need to have PyYAML on your system:

sudo pip3 install pyyaml

For convenient usage I recommend to create an alias or a symlink to note.py, for example:

alias n="/path/to/note.py"


sudo ln -s /path/to/note.py /usr/sbin/n

Adding notes

Adding a new note:

n add Do not forget about this

Adding a new note with one or more tags:

n add -t music,title Brian Bennett - Solstice
n add -t todo Fix bug in note.py

Use quotes if the text contains characters special to the terminal (*, ?, etc.):

n add "Does this work? Yes!"

You can use the -s option to read longer text from stdin (press Ctrl+D to save the note):

n add -t spam -s

When a note was successfully added the id of the note will be printed prefixed by a + sign. Please type n add --help for further information.

Listing notes

Getting a list of all notes:

n list

Getting the last note only:

n list 1

Getting 10 notes from the fifth note (paging):

n list 10 5

Display last 10 notes having the #todo tag:

n list -t todo 10

Please type n list --help for further information.

Editing notes

You can open your notes file in an editor by typing the command:

n edit

Note YAML format

The notebook file is a series of YAML documents. A single note looks like this:

date: [date in SQL format: %Y-%m-%d %H:%M:%S]
id: [an arbitrary id for the note, an UUID will be generated when empty]
author: [name of author]
text: <content of the note (required)>
- one_or
- more
- tags

As you can see only the text part is required. You can use the options of the add subcommand to specify other data, such as tags, id, etc. When omitted the metadata will have these default values:

Name Default value
date Date when note was added.
id A random UUID.
author Unix username.
tags None

The configuration file

By default, note.py looks for and reads a file called .noterc in your home directory. You can specify a different location by setting the NOTERC environment variable to a file path. The config file is a common INI file, you can set any options shown in the first section by the n info command. Put your options under the [note] section.

Here's an example .noterc file:

file = ~/Dropbox/notes.yaml
editor = vim

In the example above I set my notes file to a location under my Dropbox folder, so I can synchronise my notebook across devices pretty easily. You can also specify the tag separator, the note display template, name of the author, etc.

Note templates

There are two kinds of templates in note.py: builtin and external. You can customize both. To customize the builtin template you can either specify it using the command-line option -s or set it in your .noterc:

n list -s :it 5

(This will print only the id and the text of the last five notes.)

Or in your .noterc it would look like this:

format = :it

An external template is a text file that describes the format of a single note. To get your notes in XML for example you can set your template file and tag separator like this:

Template file (xml_template.txt):

<note id="{id}" author="{author}" date="{date}">

The .noterc file:

template_file = xml_template.txt
tagsep = </tag><tag>

Or if you want to get XML output only on occasion, you can use the command line:

n -t </tag><tag> list -f xml_template.xml 5

This will list the last five notes as XML according to the format you've specified in the template.