Homepage Source Code Docs

jrnl

About the Project

A simple tool to maintain a journal/diary completely in CLI!

Source Code

The github repository, which houses the source code for both the tool and this page.

Docs

Some roughly made documentation for the code. Not great/reliable. Mainly made for my own needs later on.

Video Demo

A sample video showing most of the functionalities of this tool with a dummy input

Features

Arranges entries of each day such that a month of entries is stored in a file. File structure(tree):


    Template           |   Example
                       |
    jrnl_folder        |   jrnl_folder
    '- YYYY            |   '- 2025
    |  '- YYYY_MM.md   |   |  '- 2025_01.md
    |  '- YYYY_MM.md   |   |  '- 2025_02.md
    '- YYYY            |   '- 2026
    |  '- YYYY_MM.md   |   |  '- 2026_01.md
    |  '- YYYY_MM.md   |   |  '- 2026_02.md

Just by running jrnl with no flags opens the current day's entry in your text editor. Automatically fills in the date - weekday and time is configurable.

General entry format:


    Template                |   Example
                            |
    ### WEEKDAY (HH:MM:SS)  |   ### FRI (13:05:28)
    # YYYY-MM-DD            |   # 2025-03-28
    - [tag] entry           |   - [milestone] [game] Played and won 200th game of chess.
    - entry                 |   - Cleaned up room.
    - [tag1] [tag2] entry   |   - [fees] Paid electricity bill.

All entries are in standard markdown, for ease of reading
Entries of any date can be fetched and pretty-printed to the terminal.
Any given entry can be opened with the text editor at that date, in case of any editing required.

Tags are implemented; one can search for all occurances of a tag in a given month or year. When searched for, a table is printed, with the dates and respective entries that contain the given tag. The tag is highlighted. Further, a calendar of the current month(or months - if in a year) is printed, with the dates of the tags used being highlighted.


    ╭───────────────┬──────────────────────────────────────────╮
    │ Date of Entry ┆ Record                                   │
    ╞═══════════════╪══════════════════════════════════════════╡
    │ 2025-03-31    ┆ [tag_1] Stuff                            │
    ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
    │ 2025-03-29    ┆ [tag_1] Some more                        │ 
    ├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
    │ 2025-03-28    ┆ [tag_1] Other things                     │
    ╰───────────────┴──────────────────────────────────────────╯
         March 2025
    Mo Tu We Th Fr Sa Su
                    1  2
     3  4  5  6  7  8  9
    10 11 12 13 14 15 16
    17 18 19 20 21 22 23
    24 25 26 27 28 29 30
    31

(Note: Here, the colors cannot be shown, so you'll have to trust this.)

A special tag - food is pre-defined. Input your daily food intake as:


    - [food] Breakfast | Lunch | Dinner | Other
    
    - [food] some breakfast item | A lunch item - course 1 A lunch item - course 2 A lunch item - course 3 | A filling dinner. A tasty dinner. | Snack - Chips Fruit - Mango

When fetching the tag through `--tag food`, you get a nice ascii table(along with a calendar - not shown here):


    ╭───────────────┬─────────────────────┬─────────────────────────┬───────────────────┬────────────────╮
    │ Date of Entry ┆ Breakfast           ┆ Lunch                   ┆ Dinner            ┆ Other          │
    ╞═══════════════╪═════════════════════╪═════════════════════════╪═══════════════════╪════════════════╡
    │ 2025-03-27    ┆ some breakfast item ┆ A lunch item - course 1 ┆ A filling dinner. ┆ Snack - Chips  │
    │               ┆                     ┆ A lunch item - course 2 ┆ A tasty dinner.   ┆ Fruit - Mango  │
    │               ┆                     ┆ A lunch item - course 3 ┆                   ┆                │
    ╰───────────────┴─────────────────────┴─────────────────────────┴───────────────────┴────────────────╯

If there are too many entries for a tag or for the food tag(specifically), it will automatically open a pager with the contents(configurable).
To fetch entries(or open them), a date is required. You can either pass this through the flag --entry YYYY-MM-DD (-e YYYY-MM-DD), or if you just pass an empty flag(-e), an interactive calendar will prompt for the date(Using [inquire](https://github.com/mikaelmello/inquire)). The calendar will also open if there is any problem with reading the date.
When fetching tags, the default file to search for is the current month's file. However, you can specify any other file using --year YYYY(-y YYYY) or --month MM(-m MM). If only provided with a year, and no month, all files of that year will be searched through and printed chronologically.(The pager comes in use here)
A feature of "generating reports" is implemented. Currently, it goes through a file, and prints the number of entries of that month, and the most used tags. Similar to tags, you can specify the month and/or year to get a specific month's report.
All tables are automatically wrapped around if its width exceeds 90% of the terminal width.
Calendars are printed in tags and generating reports, with highlighting. The calendars of each month will be printed in a grid-like form, extending rightwards depending on your terminal's width.

Usage

This is a quite detailed explanation of what I made this tool for and how to use it to get the most out of it

Once installed, run jrnl -V. You should get the version printed out.

The next step is to add the configuration file. Copy the config.toml file into ~/.config/jrnl/config.toml, and read it. It contains all the currently possible configuration options. All their details are given in comments. Make suitable changes. Then run jrnl -h. If no errors appear, great! You are set to go. If some error appears(most likely configuration errors), then read the error message and make appropriate corrections.

jrnl doesn't make any folder for you. This is to avoid accidental creations of a lot of directories. Hence, you will have to create the folders yourself. The files, however, are generated by the code. Say your default_path is set to ~. Go to this directory(~), and make a folder named jrnl_folder. All of your main journal or diary entries will live here. Go into this folder(you should now be at ~/jrnl_folder). Make a folder whose name is the current year as YYYY , for instance, at the moment of writing this, it is April 2025, so the folder name would be 2025. Now go back to ~, and run jrnl. A new file ~/jrnl_folder/2025/2025_04.md will have been created, and that file will be opened in your specified editor, with the date(and weekday and time if configured). You can now directly enter your entry.

Each entry is preferably supposed to be in this format:

- [tag1] [tag2] [tag3] Your entry here.

Some points to note from this:

Each entry item starts with -, which indicates(in markdown) that it is an unordered list.
All tags must be at the start of the entry, before any other text. Preferably it must be in snake_case, for easier use.
An entry can have more than one tag, or no tags as well.

A special tag: `food`

You can create any name for the tags, except for food, because it has pre-defined behaviour. The `food` tag is to be entered as follows:

- [food] Breakfast | Lunch | Dinner | Other
// Example
- [food] some breakfast item | A lunch item  | A filling dinner. A tasty dinner. | Snacks

This is so that, later, when you use the --tag flag to fetch all instances of that tag, if you use food, you'll get a nice table as can be seen here.

Events

Make a file called events.md in your jrnl_folder. Here, you can store all your events in a specific format, and when you run --gen-report, it shows you the upcoming events, and the recently completed ones, with highlighting.

The format to be followed is:

- [MM-DD] Information about the event
// Example
- [04-25] Person A's birthday.

Any lines not starting with - will be ignored, so this can be used to add comments if required. If any error occurs in parsing the date, an Error with the line number will be shown so you can correct it. You can also open the events file from anywhere using jrnl --open e. Here, e is hardcoded to mean the events.md file. This means you cannot create a file named e, but can create a file named e.txt. This is simply for ease of input.

Positional argument: date

You can open any given entry by providing an optional positional argument as such:

jrnl YYYY-MM-DD #OR
jrnl #Opens today's entry

By default, if you just run jrnl, then the current date(today's date) will be considered. If you want the interactive calendar to show, then you can use

jrnl c

This will open an interactive calendar, from which you can select the date.

`--entry` or `-e`

This flag is used to fetch any given day's entry if it exists. General usage:

jrnl --entry YYYY-MM-DD

where YYYY-MM-DD is the date of the entry which you are trying to fetch.
If it exists, a nice formatted output will be presented, with colors. If it does not exist, you will get an error message saying so. Since it is unnecessary to type out the 10 character string(YYYY-MM-DD) everytime, if you just pass an empty flag, i.e.

jrnl --entry

you will get an interactive calendar from which you can select the date required.
If, for whatever reason, the date provided is deemed to be invalid(the date does not exist - 2025-02-29, invalid format - 02-13-2025, etc) you will get an error message saying so, and the interactive calendar will be presented again.

`--tag` or `-t`

This flag allows you to fetch the entries for a given month(or year). General usage:

jrnl --tag "tag_name" --year YYYY --month MM # OR
jrnl -t "tag_name" -y YYYY -m MM

Here, "tag_name" is the name of the tag you are searching for. If it doesn't exist, you will get a message saying so. You can also provide the year/month to specify which date range to search from.

By default, the current month's file is considered. If you pass only --year or -y flag, you will get all the results from the provided year. If you just pass the flag with no YYYY, then the current year's files will be searched.

Example:

jrnl -t tag_1 -m 3 # The current year is 2025, and current month is April

This will result(provided the entries exist) in this.

`--search` or `-s`

This flag searches for a given string in a given month's file. By default, the file is the current month's file. You can also provide a --approx or -a flag along with this, to search for similar words. General usage:

jrnl --search "word" --year YYYY --month MM --approx *sensitivity*

Here, the "word" can be any string to be searched for. The provision of year and month works the same as it did for the tags.

You can provide the --approx or -a flag, which also searches for words similar to the one provided. You can pass a number which denotes the sensitivity of the search. 1 corresponds to allowing 1 character difference, 2 allows two characters differnce, and so on. If you pass just the flag -a, the default sensitivity which you have provided in the config.toml file will be used.

`--gen-report`

This generates a report for a given month or year, and prints it out to the terminal(STDOUT). General usage:

jrnl --gen-report --year YYYY --month MM

By default(i.e. if you provide no -y or -m flags), the current month's file is considered. It will print out(in a nice format), the number of entries in the provided month, and a table of n of the most used tags and their frequencies, along with a calendar(or a couple of them) representing which all days you wrote the entries. Here, n is the corresponding number provided in the config.toml file. If a year is passed, without any month, then the report is generated for the provided year(if not provided, then it defaults to the current year).

This also prints the upcoming and recently completed events. (Refer this)

`--open-config`

This does exactly what is says it does. It opens the config file - ~/.config/jrnl/config.toml in your provided text editor.

`--path` or `-p`

This allows you to maintain multiple different jrnls. If you run jrnl from any directory, the default jrnl_folder will be opened(which is configured). To use another jrnl_folder(as is done in the video demo), you can use this flag. General usage:

jrnl --path "path" *any other flags here*

Here, if you provide the "path", it will use that. If you don't, it will search for jrnl_folder in the current directory.

`--print-config`

This prints the current configuration in a nice table format. Sample output, for the default config:(Colors can't be shown)

CONFIGURATION
╭──────────────────────────────┬─────────╮
│ Quantities                   ┆ Value   │
╞══════════════════════════════╪═════════╡
│ Add Weekday                  ┆ true    │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ Add Food Column              ┆ true    │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ Add timestamp                ┆ true    │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ Default Editor               ┆ hx      │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ Default Pager                ┆ bat     │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ Max rows to display for tags ┆ 5       │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ When to use pager            ┆ default │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ Default path                 ┆ ~       │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┤
│ Approximation sensitivity    ┆ 1       │
╰──────────────────────────────┴─────────╯

`--open`

This is a flag that will open any filename(makes the file if not present) in your jrnl_folder. This is so that you can add some notes or whatever. Usage:

jrnl --open "filename"
# Example
jrnl --open events.md

To use the events functionality, refer this.

Dependencies

chrono: For date and time purposes.
clap: For CLI arguments.
colored: For colored messages.
inquire: To interactively get the date(of entry to be fetched) from the user.
pager: To page long outputs.
comfy-table: To print tables.
toml: To parse the configuration file.
serde: For use in toml and clap.
term_size: To get the terminal width, to be able to wrap tables and calendars accordingly.
stringmetrics: For approximate word searching.
shellexpand: To expand the ~(tilde) in paths.
parse_datetime: To convert human-readable time to exact dates.

Any other doubts/questions?

Feel free to open an issue.

Last Edited:

About the Project

Source Code

Docs

Video Demo

Features

Usage

A special tag: food

Events

Positional argument: date

--entry or -e

--tag or -t

Example:

--search or -s

--gen-report

--open-config

--path or -p

--print-config

--open