Basalt: A Terminal Interface for Obsidian Vaults

Why Basalt Exists Alongside Obsidian

Basalt addresses a specific gap between file-oriented terminal work and graphical note applications. Its documentation describes it as a TUI for managing Obsidian vaults and notes directly from the terminal on Windows, macOS, and Linux. The intended user is someone who already understands vaults and Markdown files, or wants to work with them without switching to Obsidian's graphical interface for every operation.

The project is explicit about its boundary: Basalt is not a replacement for Obsidian. That distinction matters. Basalt operates on an existing Obsidian-compatible vault and presents a minimalist terminal interface with a WYSIWYG experience. Basalt supplies a terminal client for working with the same notes.

This division makes Basalt most interesting to developers, terminal regulars, and keyboard-oriented users. It is less convincing for someone who wants every Obsidian plugin, desktop notification, graph view, or application setting reproduced in the terminal. The README links to a dedicated known-limitations page, but it does not enumerate those limitations, so the precise feature gap cannot be inferred.

Basalt's Vault Editing Model

The visible data model centers on an Obsidian vault, its notes, and its folders. Basalt renders Markdown while presenting a WYSIWYG editing experience, which means the terminal interface aims to let the user edit content without managing raw Markdown syntax continuously. The documentation also provides separate sections for editing and formatting, Markdown support and rendering, files, and folders.

Based on the repository layout, the implementation is divided into more than the application itself. The Rust workspace includes `basalt`, `basalt-core`, `basalt-widgets`, and `obsidian-to-zola`. The application is therefore separated from reusable core and interface components, although the README does not describe their internal APIs or document a complete data-processing pipeline. Claims about indexing, synchronization, or plugin execution should therefore be left to the linked project documentation.

The practical implication is narrower than an Obsidian replacement. Basalt manages the notes as Markdown content associated with a vault, while the interface supplies terminal navigation and editing. The README does not state whether Basalt loads a plugin or modifies Obsidian metadata.

Installing Basalt and Opening a Vault

For users with Cargo available, the README gives the standard package installation command. It installs the `basalt-tui` package from crates.io and builds the application locally.

cargo install basalt-tui

After installation, the executable is `basalt`. The README also documents `basalt --version`, which reports a `-nightly` suffix for a downloaded nightly binary and a commit hash for a build made from source. This provides a concrete way to confirm which build is on the path after installation.

Homebrew is the documented alternative for macOS and compatible environments:

brew install erikjuhani/tap/basalt

Users can also install through aqua:

aqua g -i erikjuhani/basalt

For the first real use, download the precompiled binary from the latest release, extract it, move the `basalt` binary to a location in `PATH`, and launch Basalt from the terminal. The getting-started documentation covers opening the first vault, but the README does not provide a vault-path command-line argument or document a modal-based vault picker. If selection behavior matters to your workflow, verify it in the linked getting-started guide before relying on it.

Stable and Nightly Basalt Builds

Basalt separates ordinary releases from a rolling nightly channel. The latest listed stable tag is `basalt/v0.13.0`, published on 2026-10-04. Another listed release, `nightly`, tracks the latest commit on `main` and was published on 2026-08-16. The README warns that nightly builds are unstable and intended for testing.

A precompiled nightly is available from the release page and is installed by downloading, extracting, and placing `basalt` in `PATH`. Source builders can install the `main` branch directly:

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

Homebrew can also build the current source branch:

brew install --HEAD erikjuhani/tap/basalt

The source and Homebrew paths can expose changes before they appear in a stable tag. That is useful when validating a recent fix, but it makes the `-nightly` label significant rather than cosmetic. The version output gives only a partial provenance check, so users who require repeatable deployments should prefer a tagged release and record that version.

Basalt Configuration Paths and Precedence

Basalt uses TOML configuration, but it does not create a configuration file by default. A user who wants different defaults must create it manually. On macOS and Linux, Basalt recognizes either `$HOME/.basalt.toml` or `$XDG_CONFIG_HOME/basalt/config.toml`. On Windows, the documented locations are `%USERPROFILE%\.basalt.toml` and `%APPDATA%\basalt\config.toml`.

If more than one file exists, Basalt uses only the first one it finds. The home directory file takes precedence over the XDG or application-data location. The documentation also warns that a future version may merge every discovered configuration instead of selecting one. That warning is a real upgrade concern for users who spread settings across both paths, because current behavior is intentionally different from a layered configuration system.

The linked configuration reference covers key mappings, custom commands, defaults, and symbols. Those keys are not included in the repository README, so this review does not invent a sample TOML file. A first configuration change should therefore be made from the published reference and checked against the `basalt --version` output after upgrading.

Basalt Licensing Across the Rust Workspace

The licensing boundary is more specific than simply labeling the repository Apache-2.0. The README states that `basalt-tui`, which is the application, is licensed under GPL-3.0-or-later. It says that distributed modifications of that component must remain open under the same terms. Contributions are accepted under a Contributor License Agreement.

The reusable `basalt-core` and `basalt-widgets` libraries use Apache-2.0. The workspace also contains `obsidian-to-zola`, but the README does not state that crate's license, so no conclusion about that component should be drawn from the two licenses named above. The repository includes both `LICENSE-APACHE` and `LICENSE-GPL`, which is consistent with a mixed-license workspace.

For adoption, the key question is whether the user wants to run or distribute the application, or only reuse its library crates. Developers embedding `basalt-core` or `basalt-widgets` can rely on the README's Apache-2.0 designation. Teams modifying and distributing `basalt-tui` need to review the GPL obligations for their exact use. This is a project-specific licensing distinction, not legal advice.

Basalt Constraints and the Obsidian Alternative

The clearest limitation is that Basalt does not claim full Obsidian parity. The README explicitly says it is not a replacement, and it links to a known-limitations page without summarizing it. Users whose workflow depends on a specific Obsidian plugin or graphical feature should verify that dependency before switching. The terminal UI also imposes the normal constraints of terminal applications, including dependence on terminal rendering and keyboard navigation, although Basalt provides key mapping configuration for its own interface.

Obsidian itself is the real alternative, not merely another Markdown viewer. Basalt instead keeps the interaction inside the terminal and offers a WYSIWYG view over the notes. A user who values remote-shell access, keyboard-driven editing, and a small terminal surface may prefer Basalt. A user who needs Obsidian-specific features should remain with Obsidian unless the Basalt documentation confirms the required behavior.

Maintenance is recent in the repository record. The last push was on 2026-10-15, and the repository is not archived. Releases also include `basalt/v0.13.0` and `basalt/v0.12.7`. This supports continued code activity, but the README says feature work is considered case by case and asks contributors to open an issue first. Upgrade planning should therefore track release notes rather than assume that every requested feature will be accepted.

Editorial conclusion

Basalt fits terminal-focused users who want direct access to Markdown files and a WYSIWYG TUI while retaining Obsidian as the vault format. It is a poor match for users seeking an Obsidian replacement, full application parity, or one uniform license across the entire workspace. Before adoption, verify the documented limitations, confirm that your required Markdown behavior is supported, and review the GPL-3.0-or-later terms for the `basalt-tui` application separately from the Apache-2.0 libraries.

Frequently asked questions

Official sources

1. erikjuhani/basalt on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases