README.md

Basalt  

TUI Application to manage Obsidian notes    

---

TUI Application to manage Obsidian vaults and notes directly from the terminal ✨.

Basalt is a cross-platform TUI (Terminal User Interface) for managing Obsidian vaults and notes. It runs on Windows, macOS, and Linux. Basalt is not a replacement for Obsidian. Instead, it provides a minimalist terminal interface with a WYSIWYG experience.

Installation

• Using Homebrew:

  brew install erikjuhani/tap/basalt
  

• Using Cargo:

  cargo install basalt-tui
  

• Using aqua:

  aqua g -i erikjuhani/basalt
  

Or download a pre-compiled binary from the latest release, extract it, and move the basalt binary to a location in your PATH.

Nightly builds

Nightly builds track the latest main commit. They are unstable and meant for testing. The nightly release always holds the newest build. A downloaded nightly binary reports a -nightly suffix in basalt --version. A build from source reports the commit hash instead.

• Using Homebrew (builds from source):

  brew install --HEAD erikjuhani/tap/basalt
  

• Using Cargo (builds from source):

  cargo install --git https://github.com/erikjuhani/basalt --branch main basalt-tui
  

Or download a pre-compiled binary from the nightly release.

Configuration

Basalt can be customized using a TOML configuration file. The file does not exist by default — create it manually when you want to override the defaults.

macOS and Linux:

• $HOME/.basalt.toml
• $XDG_CONFIG_HOME/basalt/config.toml

Windows:

• %USERPROFILE%\.basalt.toml
• %APPDATA%\basalt\config.toml

If configuration files exist in multiple locations, only the first one found is used. The home directory configuration takes precedence.

See the full configuration reference for key mappings, custom commands, and defaults.

Documentation

• Getting started
• User interface
• Configuration
• Editing and Formatting
• Files and Folders
• Known Limitations

Contributing

Contributions are welcome, primarily for bug fixes. Feature work is considered on a case-by-case basis — please open an issue first to discuss.

See CONTRIBUTING.md for development setup, code style, and contribution guidelines.

License

Copyright (c) Erik Kinnunen.

Basalt spans three crates under two licenses:

• basalt-tui (the application) is GPL-3.0-or-later. Distributed modifications must stay open under the same terms.
• basalt-core and basalt-widgets (the libraries) are Apache-2.0, so they stay reusable in other projects.

Contributions are accepted under a Contributor License Agreement. See CONTRIBUTING.md.