jrnl/docs/usage.md

Basic Usage

jrnl has two modes: composing and viewing. Whenever you don't enter any arguments that start with a dash (-) or double-dash (--), you're in composing mode, meaning that you can write your entry on the command line.

We intentionally break a convention on command line arguments: all arguments starting with a single dash (-) will filter your journal before viewing it. Filter arguments can be combined arbitrarily. Arguments with a double dash (--) will control how your journal is displayed or exported. Control arguments are mutually exclusive (i.e., you can only specify one way to display or export your journal at a time).

Composing Entries

Composing mode is entered by either starting jrnl without any arguments -- which will launch an external editor -- or by just writing an entry on the command line:

jrnl today at 3am: I just met Steve Buscemi in a bar! What a nice guy.

!!! note Most shells contain a certain number of reserved characters, such as # and *. These characters, as well as unbalanced single or double quotation marks, parentheses, and others, likely will cause problems. Although reserved characters can be escaped using \, this is not ideal for long-form writing. The solution: first enter jrnl and hit return. You can then enter the text of your journal entry. Alternatively, you can use an external editor).

You can also import an entry directly from a file:

jrnl < my_entry.txt

Specifying Date and Time

If you don't specify a date and time (e.g., jrnl finished writing letter to brother), jrnl will create an entry using the current date and time. For retrospective entries, you can use a timestamp to tell jrnl where to put the entry. Timestamps can be entered using a variety of formats. Here are some that work:

• at 6am
• yesterday
• last monday
• sunday at noon
• 2 march 2012
• 7 apr
• 5/20/1998 at 23:42
• 2020-05-22T15:55-04:00

If you don't use a timestamp, jrnl will create an entry using the current time. If you use a date only (no time), jrnl will use the default time specified in your configuration file (see advanced usage). Behind the scenes, jrnl reorganizes entries in chronological order.

Using Tags

jrnl supports tags. Note that because # is a reserved character, the default tag symbol is @. You can specify your own tag symbol in the configuration file. There is no limit to how many tags you can use in an entry. To use tags, simply preface the desired tag with the symbol:

jrnl Had a wonderful day at the @beach with @Tom and @Anna.

Although you can use capitals while tagging an entry, searches by tag are case-insensitive.

Starring Entries

To mark an entry as a favorite, simply "star" it using an asterisk (*):

jrnl last sunday *: Best day of my life.

If you don't want to add a date (i.e., you want the date to be entered as now), the following options are equivalent:

• jrnl *: Best day of my life.
• jrnl *Best day of my life.
• jrnl Best day of my life.*

!!! note Make sure that the asterisk (*) is not surrounded by whitespaces. jrnl Best day of my life! * will not work because the * character has a special meaning in most shells.

Viewing Entries

jrnl can display entries in a variety of ways. Entries are filtered using commands preceded by a single dash (-). Type jrnl -h for a list of commands.

It is possible to see all entries by entering jrnl -until today. However, in most cases you will likely want to use a filter to see specific entries that meet certain criteria. jrnl provides several filtering commands, prefaced by a single dash (-), that allow you to find exactly what you're looking for. For example,

jrnl -n 10

lists the ten most recent entries. jrnl -10 is even more concise and works the same way. If you want to see all of the entries you wrote from the beginning of last year until the end of this past March, you would enter

jrnl -from "last year" -until march

Filter criteria that use more than one word require surrounding quotes ("").

Text Search

The -contains command displays all entries containing a specific string. This may be helpful when you're searching for entries and you can't remember if you tagged any words when you wrote them.

You may realize that you use a word a lot and want to turn it into a tag in all of your previous entries.

jrnl -contains "dogs" --edit

opens your external editor so that you can add a tag symbol (@ by default) to all instances of the word "dogs."

Filtering by Tag

You can filter your journal entries by tag. For example,

jrnl @pinkie @WorldDomination

displays all entries in which either @pinkie or @WorldDomination occurred. Tag filters can be combined with other filters:

jrnl -n 5 @pinkie -and @WorldDomination

displays the last five entries containing both @pinkie and @worldDomination. You can change which symbols you'd like to use for tagging in the configuration.

!!! note Entering jrnl @pinkie @WorldDomination will display entries in which both tags are present because, although no command line arguments are given, all of the input strings look like tags. jrnl will assume you want to filter by tag, rather than create a new entry that consists only of tags.

Viewing Starred Entries

To display only your favorite (starred) entries, enter

jrnl -starred

Editing Entries

You can edit entries after writing them. This is particularly useful when your journal file is encrypted. To use this feature, you need to have an external editor configured in your configuration file. You can also edit only the entries that match specific search criteria. For example,

jrnl -until 1950 @texas -and @history --edit

opens your external editor displaying all entries tagged with @texas and @history that were written before 1950. After making changes, save and close the file, and only those entries will be modified (and encrypted, if applicable).

If you are using multiple journals, it's easy to edit specific entries from specific journals. Simply prefix the filter string with the name of the journal. For example,

jrnl work -n 1 --edit

opens the most recent entry in the 'work' journal in your external editor.

Deleting Entries

The --delete command opens an interactive interface for deleting entries. The date and title of each entry in the journal are presented one at a time, and you can choose whether to keep or delete each entry.

If no filters are specified, jrnl will ask you to keep or delete each entry in the entire journal, one by one. If there are a lot of entries in the journal, it may be more efficient to filter entries before passing the --delete command.

Here's an example. Say you have a journal into which you've imported the last 12 years of blog posts. You use the @book tag a lot, and for some reason you want to delete some, but not all, of the entries in which you used that tag, but only the ones you wrote at some point in 2004 or earlier. You're not sure which entries you want to keep, and you want to look through them before deciding. This is what you might enter:

jrnl -to 2004 @book --delete

jrnl will show you only the relevant entries, and you can choose the ones you want to delete.

You may want to delete all of the entries containing @book that you wrote in 2004 or earlier. If there are dozens or hundreds, the easiest way would be to use an external editor. Open an editor with the entries you want to delete...

jrnl -to 2004 @book --edit

...select everything, delete it, save and close, and all of those entries are removed from the journal.

Listing Journals

To list all of your journals:

jrnl -ls

The journals displayed correspond to those specified in the jrnl configuration file.