Getting started

Prerequisites

Perennial is intended to work with Python 3.9 or higher.

Installing

Use pip like usual:

pip install -U perennial

Development

If you’d like to explore the repo or experiment with your own changes and potentially contribute to development:

git clone https://almonds.dev/git/perennial
cd perennial
pip install -e ."[dev]"

Basic concepts

This section describes how to use the command-line options for creating journals, adding entries, and tracking goals. See the Perennial reference for information on how to interface with your journals more directly.

Run python -m perennial -h for help.

init

Initialize a journal in the current working directory:

python -m perennial init 'Journal full of examples'

Specify a journal elsewhere with the -d (--database) flag:

python -m perennial -d ~/journals/test/ init 'Journal full of examples'

This flag is settable for all subcommands. The default is the current working directory.

Each journal entry can optionally be associated with a file. The init command can take a template file with the -t (--template) flag:

python -m perennial init 'Journal full of examples' -t ~/journals/test/template.md

When recording a new entry with an associated file, this template file will be copied over if the file does not already exist.

The journal’s streak-tracking mode can be set with the -s (--streak-mode) flag:

python -m perennial init 'Journal full of examples' -s daily

Currently, the supported streak-tracking modes are: daily, weekly, monthly, and yearly. The default journal streak-tracking mode is weekly.

record

Record an entry with:

python -m perennial record 'This is an example entry.'

Specify a mood for the entry with -m (--mood). Mood values are integers.

Associate a file with the new entry using -f (--file):

python -m perennial record 'This is an example entry.' -f example-entry.md

goal

Update the status of a goal with the goal subcommand by specifying the name of the goal followed by the goal state:

python -m perennial goal 'Example goal' DONE

Use whichever goal-tracking system you like. I prefer sticking with these goal states: TODO, DOING, DONE, CANCELED.

check

Finally, check up on your journals with the check command:

python -m perennial check