tui-journal

TUI-Journal

TUI-Journal is a terminal-based application written in Rust that allows you to write and manage your journal/notes from within the comfort of your terminal. It provides a simple and efficient interface for creating and organizing your thoughts, ideas, and reflections. TUI-Journal supports three local back-ends: plain-text JSON, SQLite, and an iCalendar VJOURNAL directory.

Before opening a PR, please read the Contribution and AI Policy.

Demo

Fuzzy Finder

Table of Contents

• Features
• Roadmap
• Installation
  • Arch Linux
  • Alpine Linux
  • FreeBSD
  • NetBSD
  • Nix
  • Homebrew
  • Build & Install via Cargo
• Usage
• Configuration
• Themes
• Documentation
• Contribution and AI Policy
• Acknowledgments
• License

Features

• Write and manage journal/notes entries from the terminal.
• Store your entries as JSON, in a SQLite database, or as iCalendar VJOURNAL files.
• Intuitive, responsive and user-friendly text-based user interface (TUI).
• Create, edit, and delete entries easily.
• Edit journal content with the built-in editor or use your favourite terminal text editor from within the app.
• Add custom colored tags to the journals and use them in the built-in filter.
• Fuzzy Finder: Locate your desired journal with lightning-fast speed using smart-case search.
• Smart search functions for journals title and content in the built-in filter.
• Sort the journals based on their date, priority and title.
• Control many journals at once via the multi-select mode
• History management with Undo and Redo actions to easily revert or reapply changes in your entries
• Keybindings is a combination of VIM and Emacs motions (VIM for navigation and Emacs for editing texts in edit-mode).
• Utilize Editor's Visual Mode for VIM-style text selection, copying, and deletion.
• Export and Import journals between different back-end files.
• Export the current journal's content to a predefined export path or the current directory
• Transfer text between the built-in editor and the system clipboard using Cut, Copy, and Paste.
• Optionally sync the clipboard between the built-in editor and the operating system, with vim and emacs keybindings.
• Sorting and full-screen preferences in the App State will be retained.
• Easily cycle through tags in the main view with a single command , applying the current filter for quick navigation.
• See the keybindings from inside the app
• Cross-platform compatibility (Windows, macOS, Linux, NetBSD).

Roadmap

Back-ends:

• Plain text JSON back-end.
• Database back-end using SQLite.
• VJOURNAL directory back-end for use with external CalDAV sync clients.

Application:

• Edit journals content with external text editor from within the app.
• Filter & Search functionalities.
• Customize themes.
• Preview mode for journals supporting Markdown highlighting and word wrapping.
• Add mouse support
• Improve app input and rending cycle using app events to support real concurrency within the app.

Installation

Grab the most recent pre-built binaries for your platform from the Releases page, or utilize the available package managers.

Arch Linux

On Arch Linux, you can install TUI-Journal by using pacman:

pacman -S tui-journal

Alpine Linux

TUI-Journal is available for Alpine Edge. It can be installed via apk after enabling the testing repository.

apk add tui-journal

FreeBSD

On FreeBSD, you can install TUI-Journal by using pkg:

pkg install -y tui-journal

NetBSD

On NetBSD a pre-compiled binary built with default features is available from the official repositories. To install it, simply run:

pkgin install tui-journal

Nix

TUI-Journal is available on the Nix package manager. You can install it using the following commands:

# On NixOS:
nix-env -iA nixos.tui-journal

# On Non NixOS:
nix-env -iA nixpkgs.tui-journal

For more information, visit the TUI-Journal package page on Nix.

Homebrew (macOS and Linux)

For macOS and Linux users, TUI-Journal can be installed via Homebrew using a direct installation method:

brew install AmmarAbouZor/homebrew-tui-journal/tui-journal

Build & Install via Cargo

Ensure you have Rust installed on your system.

Install with default features:

To install TUI-Journal with the default JSON, SQLite, and VJOURNAL back-ends, you can use cargo to install directly from crates.io:

cargo install tui-journal --locked

Install nightly version:

To use the current nightly version, you can install it directly from the GitHub repository

cargo install --git https://github.com/AmmarAbouZor/tui-journal

Install with Specific Features:

You can choose to install TUI-Journal with specific features enabled or disabled by customizing the cargo installation command. To install TUI-Journal with only the JSON back-end feature, use the following command:

cargo install tui-journal --locked --no-default-features --features json

To install TUI-Journal with only the SQLite back-end feature, use the following command:

cargo install tui-journal --locked --no-default-features --features sqlite

To install TUI-Journal with only the VJOURNAL back-end feature, use the following command:

cargo install tui-journal --locked --no-default-features --features vjournal

Usage

Once installed, you can run TUI-Journal by typing tjournal in your terminal:

$ tjournal

To view the available arguments and commands, you can use the --help or -h flag:

…

Configuration

The configuration for TUI-Journal can be found in the config.toml file located in the configuration folder within the TUI-Journal directory.

Here is a sample of the settings in the config.toml file:

…

VJOURNAL back-end

The VJOURNAL back-end stores journal entries as iCalendar .ics files in the configured directory. To use it with CalDAV, point the directory to one managed by an external synchronization client. TUI-Journal does not connect to a CalDAV server or monitor external file changes while running, so restart it after the directory is changed externally.

Themes

Please refer to the Themes Page for a detailed guide on customizing colors and styles within the app.

Documentation

For detailed information about the TUI Journal app, including usage guide, keymaps, and configuration details, please refer to the Wiki.

Acknowledgments

TUI-Journal would not have been possible without the following open-source crates:

• tui-rs and its revival ratatui: TUI-Journal utilizes the tui-rs and ratatui crates, which provide a framework for building terminal user interfaces in Rust. They offer a wide range of components and utilities to create interactive and responsive TUI applications.

• tui-texteditor: TUI-Journal leverages the tui-texteditor crate, which offers a text editor widget specifically designed for terminal-based applications. It provides functionalities such as text manipulation, cursor movement, and scrolling within the TUI environment.

• sqlx: TUI-Journal benefits from the sqlx crate, which is a Rust library for interacting with databases. It enables seamless integration with SQLite, allowing TUI-Journal to store journal entries and notes in a reliable and efficient manner.

These crates have greatly contributed to the development of TUI-Journal, and the project extends its gratitude to the maintainers and contributors of these fantastic open-source libraries.

Contribution and AI Policy

Thank you for considering contributing to TUI-Journal. Your support is highly appreciated!

In the age of powerful AI agents, we need to specify clear rules for contributions in this repository to save my time and yours:

• Always start by opening an issue before starting implementation. Please write the issue yourself. I would rather read an issue full of typos and mistakes than a wall of AI-generated text.
• I don’t mind accepting code generated by AI agents, I do that myself. But you must review the code carefully before submitting it. If I review your PR and spot code that is clearly generated by AI and not reviewed by a human developer, you will be banned from contributing to this repository. If reviewing code generated by your agents is not worth your time, do not expect me to waste my time reviewing it for you.

License

MIT