jrnl-org · micahellison · Feb 5, 2022 · Aug 28, 2021 · Aug 28, 2021 · Sep 18, 2021
diff --git a/docs/advanced.md b/docs/advanced.md
@@ -5,109 +5,15 @@
 
 ## Configuration File
 
-You can configure the way jrnl behaves in a configuration file. By
-default, this is `~/.config/jrnl/jrnl.yaml`. If you have the `XDG_CONFIG_HOME`
-variable set, the configuration file will be saved as
-`$XDG_CONFIG_HOME/jrnl/jrnl.yaml`.
-
-!!! note
-    On Windows, the configuration file is typically found at `%USERPROFILE%\.config\jrnl\jrnl.yaml`.
-
-The configuration file is a YAML file with the following options
-and can be edited with a plain text editor.
-
-!!! note
-    Backup your journal and config file before editing. Changes to the config file
-    can have destructive effects on your journal!
-
-- `journals`
-    paths to your journal files
-- `editor`
-    if set, executes this command to launch an external editor for
-    writing your entries, e.g. `vim`. Some editors require special
-    options to work properly, see `FAQ <recipes>` for details.
-- `encrypt`
-    if `true`, encrypts your journal using AES.
-- `tagsymbols`
-    Symbols to be interpreted as tags. (See note below)
-- `default_hour` and `default_minute`
-    if you supply a date, such as `last thursday`, but no specific
-    time, the entry will be created at this time
-- `timeformat`
-    how to format the timestamps in your journal, see the [python docs](http://docs.python.org/library/time.html#time.strftime) for reference
-- `highlight`
-    if `true`, tags will be highlighted in cyan.
-- `linewrap`
-    controls the width of the output. Set to `false` if you don't want to wrap long lines.
-- `colors`
-    dictionary that controls the colors used to display journal entries. It has four subkeys, which are: `body`, `date`, `tags`, and `title`. Current valid values are: `BLACK`, `RED`, `GREEN`, `YELLOW`, `BLUE`, `MAGENTA`, `CYAN`, `WHITE`, and `NONE`. `colorama.Fore` is used for colorization, and you can find the [docs here](https://github.com/tartley/colorama#colored-output). To disable colored output, set the value to `NONE`. If you set the value of any color subkey to an invalid color, no color will be used.
-- `display_format`
-    specifies formatter to use, formatters available are:
-    `boxed`, `fancy`, `json`, `markdown`, `md`, `tags`, `text`, `txt`, `xml`, or `yaml`.
-
-!!! note
-    Although it seems intuitive to use the `#`
-    character for tags, there's a drawback: on most shells, this is
-    interpreted as a meta-character starting a comment. This means that if
-    you type
-
-    > `jrnl Implemented endless scrolling on the #frontend of our website.`
-
-    your bash will chop off everything after the `#` before passing it to
-      `jrnl`. To avoid this, wrap your input into quotation marks like
-      this:
-
-    > `jrnl "Implemented endless scrolling on the #frontend of our website."`
-
-  Or use the built-in prompt or an external editor to compose your
-  entries.
-
-### Modifying Configurations from the Command line 
-
-You can override a configuration field for the current instance of `jrnl` using `--config-override CONFIG_KEY CONFIG_VALUE` where `CONFIG_KEY` is a valid configuration field, specified in dot-notation and `CONFIG_VALUE` is the (valid) desired override value.
-
-You can specify multiple overrides as multiple calls to `--config-override`.
-!!! note
-    These overrides allow you to modify ***any*** field of your jrnl configuration. We trust that you know what you are doing. 
-
-#### Examples: 
-
-``` sh
-#Create an entry using the `stdin` prompt, for rapid logging
-jrnl --config-override editor ""
-
-#Populate a project's log
-jrnl --config-override journals.todo "$(git rev-parse --show-toplevel)/todo.txt" todo find my towel 
-
-#Pass multiple overrides 
-jrnl --config-override display_format fancy --config-override linewrap 20 \
---config-override colors.title green
-
-```
-
-### Using an alternate config
-
-You can specify an alternate configuration file for the current instance of `jrnl` using `--config-file CONFIG_FILE_PATH` where
-`CONFIG_FILE_PATH` is a path to an alternate `jrnl` configuration file. 
-
-#### Examples:
-
-```
-# Use personalised configuration file for personal journal entries
-jrnl --config-file ~/foo/jrnl/personal-config.yaml
-
-# Use alternate configuration file for work-related entries
-jrnl --config-file ~/foo/jrnl/work-config.yaml
-
-# Use default configuration file (created on installation)
-jrnl
-```
+`jrnl` has a wide variety of options that can be customized through the config file,
+including templates, formats, multiple journals, and more. See
+the [configuration file reference](./reference-config-file.md) for details
+or read on for some common use cases.
 
-
-## Multiple journal files
+### Multiple journal files
 
 You can configure `jrnl`to use with multiple journals (eg.
-`private` and `work`) by defining more journals in your `jrnl.yaml`,
+`private` and `work`) by defining more journals in your [config file](./reference-config-file.md),
 for example:
 
 ``` yaml
@@ -167,12 +73,46 @@ journals:
 
 The `work` journal is encrypted, prints to `json` by default, and is edited using an existing window of VSCode. Similarly, the `food` journal prints to markdown by default, but uses all the other defaults.
 
+### Modifying Configurations from the Command line 
+
+You can override a configuration field for the current instance of `jrnl` using `--config-override CONFIG_KEY CONFIG_VALUE` where `CONFIG_KEY` is a valid configuration field, specified in dot-notation and `CONFIG_VALUE` is the (valid) desired override value.
+
+You can specify multiple overrides as multiple calls to `--config-override`.
 !!! note
-    Changing `encrypt` to a different value will not encrypt or decrypt your
-    journal file, it merely says whether or not your journal
-    is encrypted. Hence manually changing
-    this option will most likely result in your journal file being
-    impossible to load.
+    These overrides allow you to modify ***any*** field of your jrnl configuration. We trust that you know what you are doing. 
+
+#### Examples: 
+
+``` sh
+#Create an entry using the `stdin` prompt, for rapid logging
+jrnl --config-override editor ""
+
+#Populate a project's log
+jrnl --config-override journals.todo "$(git rev-parse --show-toplevel)/todo.txt" todo find my towel 
+
+#Pass multiple overrides 
+jrnl --config-override display_format fancy --config-override linewrap 20 \
+--config-override colors.title green
+
+```
+
+### Using an alternate config
+
+You can specify an alternate configuration file for the current instance of `jrnl` using `--config-file CONFIG_FILE_PATH` where
+`CONFIG_FILE_PATH` is a path to an alternate `jrnl` configuration file. 
+
+#### Examples:
+
+```
+# Use personalised configuration file for personal journal entries
+jrnl --config-file ~/foo/jrnl/personal-config.yaml
+
+# Use alternate configuration file for work-related entries
+jrnl --config-file ~/foo/jrnl/work-config.yaml
+
+# Use default configuration file (created on installation)
+jrnl
+```
 
 ## Known Issues
 

diff --git a/docs/encryption.md b/docs/encryption.md
@@ -35,6 +35,14 @@ replaces the encrypted journal file with a plain text file. You can also specify
 a filename, e.g., `jrnl --decrypt plain_text_copy.txt`, to leave the original
 encrypted file untouched and create a new plain text file next to it.
 
+!!! note
+    Changing `encrypt` in your [config file](./reference-config-file.md) to
+    a different value will not encrypt or decrypt your
+    journal file. It merely says whether or not your journal
+    is encrypted. Hence manually changing
+    this option will most likely result in your journal file being
+    impossible to load. This is why the above commands are necessary.
+
 ## Storing Passwords in Your Keychain
 
 Nobody can recover or reset your `jrnl` password. If you lose it,

diff --git a/docs/recipes.md b/docs/recipes.md
@@ -1,6 +1,9 @@
 <!-- Copyright (C) 2012-2021 jrnl contributors
      License: https://www.gnu.org/licenses/gpl-3.0.html -->
-# FAQ
+# Recipes
+
+This page contains tips and tricks for using `jrnl`, often in conjunction
+with other tools, including external editors.
 
 ## Recipes
 
@@ -101,8 +104,8 @@ jrnl -1 --edit          # Opens the most recent entry in the editor
 #### 2. Include the template file in `jrnl.yaml`
 
 A more efficient way to work with a template file is to declare the file
-in your config file by changing the `template` setting from `false` to the
-template file's path in double quotes:
+in your [config file](./reference-config-file.md) by changing the `template`
+setting from `false` to the template file's path in double quotes:
 
 ```sh
 ...

diff --git a/docs/reference-command-line.md b/docs/reference-command-line.md
@@ -0,0 +1,129 @@
+# Command Line Reference
+
+## Synopsis
+```
+usage: jrnl [--debug] [--help] [--version] [--list] [--encrypt] [--decrypt]
+            [--import] [-on DATE] [-today-in-history] [-month DATE]
+            [-day DATE] [-year DATE] [-from DATE] [-to DATE] [-contains TEXT]
+            [-and] [-starred] [-n [NUMBER]] [-not [TAG]] [--edit] [--delete]
+            [--format TYPE] [--tags] [--short]
+            [--config-override CONFIG_KV_PAIR CONFIG_KV_PAIR]
+            [--config-file CONFIG_FILE_PATH]
+            [[...]]
+```
+
+## Standalone Commands
+
+These commands will exit after they complete. You may only run one at a time.
+
+### --help
+Show a help message.
+
+### --version
+Print version and license information.
+
+### --list
+List the config file location, all configured journals, and their locations.
+
+### ---encrypt
+Encrypt a journal. See [encryption](encryption.md) for more information.
+
+### --decrypt
+Decrypt a journal. See [encryption](encryption.md) for more information.
+
+
+### --import
+Import entries from another journal. If any entries have the exact same content
+and timestamp, they will be deduplicated.
+
+Optional parameters:
+```sh
+--file FILENAME
+```
+Specify a file to import. If not provided, `jrnl` will use STDIN as the data source.
+
+```sh
+--format TYPE
+```
+Specify the format of the file that is being imported. Defaults to the same data
+storage method that jrnl uses. See [formats](formats.md) for more information.
+
+## Writing new entries
+See [Basic Usage](usage.md).
+
+## Searching
+
+To find entries from your journal, use any combination of the below filters.
+Only entries that match all the filters will be displayed.
+
+When specifying dates, you can use the same kinds of dates you use for new
+entries, such as `yesterday`, `today`, `Tuesday`, or `2021-08-01`.
+
+| Search Argument | Description |
+| --- | --- |
+| -on DATE | Show entries on this date |
+| -today-in-history | Show entries of today over the years |
+| -month DATE | Show entries on this month of any year |
+| -day DATE | Show entries on this day of any month |
+| -year DATE | Show entries of a specific year |
+| -from DATE | Show entries after, or on, this date |
+| -to DATE | Show entries before, or on, this date (alias: -until) |
+| -contains TEXT | Show entries containing specific text (put quotes around text with spaces) |
+| -and | Show only entries that match all conditions, like saying "x AND y" (default: OR) |
+| -starred | Show only starred entries (marked with *) |
+| -n [NUMBER] | Show a maximum of NUMBER entries (note: '-n 3' and '-3' have the same effect) |
+| -not [TAG] | Exclude entries with this tag |
+
+## Searching Options
+These help you do various tasks with the selected entries from your search.
+If used on their own (with no search), they will act on your entire journal.
+
+### --edit
+Opens the selected entries in your configured editor. It will fail if the
+`editor` key is not set in your config file.
+
+Once you begin editing, you can add multiple entries and delete entries
+by modifying the text in your editor. When your editor closes, jrnl reads
+the temporary file you were editing and makes the changes to your journal.
+
+### --delete
+Interactively deletes selected entries. You'll be asked to confirm deletion of
+each entry.
+
+### --format TYPE
+Display selected entries in an alternate format. See [formats](formats.md).
+
+#### Optional parameters
+```sh
+--file FILENAME
+```
+Write output to file instead of STDOUT. In most shells, the
+same effect can be achieved using `>`.
+
+### --tags
+
+Alias for '--format tags'. Returns a list of all tags and the number of times
+they occur within the searched entries. If there are no tags found, `jrnl` will output a message saying so.
+
+### --short
+Only shows the date and titles of the searched entries.
+
+## Configuration arguments
+
+### --config-override CONFIG_KV_PAIR CONFIG_KV_PAIR
+
+Override configured key-value pair with CONFIG_KV_PAIR for this command invocation only.
+Read [advanced usage](./advanced.md) for examples.
+
+### --config-file CONFIG_FILE_PATH
+
+Use the config file at CONFIG_FILE_PATH for this command invocation only.
+Read [advanced usage](./advanced.md) for examples.
+
+## Other Arguments
+
+### --debug
+Prints information useful for troubleshooting while `jrnl` executes.
+
+### --diagnostic
+Prints diagnostic information useful for [reporting issues](https://github.com/jrnl-org/jrnl/issues).