Skip to content

User Guide

Jump to bottom
Ammar Abou Zor edited this page Jan 16, 2024 · 2 revisions

User Guide

Command Line Arguments and Commands

The TUI Journal app provides the following command line arguments and commands:

Command Line Arguments

  • -j, --json-file-path <FILE PATH>: Sets the entries JSON file path and starts using it.
  • -s, --sqlite-file-path <FILE PATH>: Sets the entries SQLite file path and starts using it.
  • -b, --backend-type <BACKEND_TYPE>: Sets the backend type and starts using it. Possible values are "json" or "sqlite". Note that to set the backend type, you need to have the corresponding backend feature installed.
  • -w, --write-config: Writes the current settings to the configuration file. This will overwrite the entire configuration file.
  • -v, --verbose...: Increases logging verbosity each time it's used, up to 3 times.
  • -l, --log <FILE PATH>: Specifies a file to use for logging. The default log file is <cache_dir>/tui-journal/tui-journal.log.
  • -h, --help: Prints help information.
  • -V, --version: Prints the version of the app.

Commands

  • print-config (aliases: pc): Prints the current settings, including the paths for the backend files.
  • import-journals (aliases: imj): Imports journals from the given transfer JSON file to the current backend file.
  • assign-priority (aliases: ap): Assign priority for all the entires with empty priority field.
  • help: Prints the help message or the help of the given subcommand(s).

General Usages

The TUI Journal app has a main view consisting of two parts: the Journals List and the Built-in Editor. Each part has its own set of commands available via keybindings. You can refer to the Keymap for a complete list of available keybindings.

Journals List

The Journals List displays a list of your journal entries. You can navigate through the list using the provided keybindings. Here are some common commands available in the Journals List:

  • Select Journal: Use the arrow keys or j/k to navigate and select a journal entry.
  • Create Journal: Press n to create a new journal entry.
  • Delete Journal: Press d to delete the selected journal entry.
  • Filter Journals: Press f to activate the filter and enter keywords to search for specific journals.
  • Sort Journals: Press o open sort options for the journals. Available options are: Date, Priority and Title.

Built-in Editor

The Built-in Editor allows you to view and edit the content of a selected journal entry. It supports two modes inspired by VIM and Emacs:

  • Normal Mode: In this mode, you can use VIM keybindings to navigate through the text and enter Edit Mode. Press i, I, a, A, o, or O to enter Edit Mode at different positions within the text.
  • Edit Mode: In this mode, you can use Emacs keybindings to edit and navigate the text.

Prompts/Popups

The app displays prompts/popups for creating and editing journals, filtering the journal list, and accessing keymaps.

External Editor

The TUI Journal app allows you to use an external terminal-based text editor for editing journal entries. The external editor must be a terminal editor.

To set the external editor, open the TUI Journal configuration file (config/config.toml) and update the external_editor option with the desired terminal text editor command. Save the configuration file.

Make sure that the terminal editor you specify is installed on your system and is accessible from the command line. If the external_editor value is not set in the configuration file, the TUI Journal app will try to retrieve the editor from git global configurations. If not found, it will then try to use the environment variables VISUAL and EDITOR. If none of these options are available, the app will fallback to the vi editor.

Filter

The TUI Journal app allows you to filter your journals based on specific criteria. The available filter criteria are as follows:

  • Title Contains: Filter journals whose titles contain a specific search pattern.
  • Content Contains: Filter journals whose content contains a specific search pattern.
  • Tags: Filter journals that have the given tags.

You can specify whether all the filter criteria should be met or if any of them should be met. Here's how you can apply the filter:

  1. Press f to activate the filter mode.
  2. Enter the search pattern for the title, content, or tags as prompted by the app.
  3. Specify whether all the filter criteria should be met (AND logic) or if any of them should be met (OR logic).

The app will display the filtered journals based on your specified criteria. You can navigate through the filtered journals using the arrow keys.

Sort Options

The TUI Journal app allows you to sort your journals based on specific criteria. The available sort criteria are as follows:

  • Date: Sort journals according to their date.
  • Priority: Sort journals according to their priority.
  • Title: Sort journals alphabetically according to their title.

You can specify whether sorting should be done in ascending or descending order. You can choose multi sort criteria which will be applied in the given order.

Export and Import

The TUI Journal app provides functionality for exporting and importing journals. Here are the available commands:

  • Export Journals: To export multiple journals, enter the Multi-Selection Mode by pressing m. Use the arrow keys to navigate and select multiple journals. Then, press e to export the selected journals' content. You can specify a default export path in the configuration file. Alternatively, the app will export to the current directory by default. If you are in Normal Mode, the export command will export the content of the currently selected journal.
  • Import Journals: Use the import-journals command (alias: imj) to import journals from a transfer JSON file to the current backend file. You can run tjournal import-journals --help to see the usage details.

Multi-Selection Mode

The TUI Journal app supports multi-selection mode, which allows you to perform actions on multiple journals simultaneously. Here are the available commands for multi-selection mode:

  • Enter Multi-Selection Mode: Press m to enter multi-selection mode. Use the arrow keys to navigate and select multiple journals.
  • Perform Actions on Selected Journals: Once you have selected the desired journals, you can perform actions such as deletion or export on the selected journals.

Full-Screen Mode

Full-Screen mode let one control only to take the whole view. In Full-Screen mode you still can switch between the active control with the normal keybindings. To Toggle Full-Screen mode use the keybinding Ctrl-f

Clone this wiki locally