▒▓█▒░
▒█▓▓░▒░
██▓█▒▒▒▒
▒▓██▓░▒▒▒░
▓▒▒█▒▒░░░░
░▒▒░░░▒░
░▒▒▒▒░
⋅𝕭𝖆𝖘𝖆𝖑𝖙⋅
TUI Application to manage Obsidian
vaults and notes directly from the terminal.
───────────────────────────────────────────────────────────────────────────────
%version-notice
DISCLAIMER
Basalt is in its early stages, with a very limited set of features, and is
therefore susceptible to changes. The experimental editor feature is disabled
by default but can be enabled in the configuration file. When enabled, it
provides a custom-built editor with limited capabilities for basic note
modification.
Quitting the application may feel a bit abrupt, as the application exits
immediately after pressing ‹q›. I have some plans to handle this differently
in the future. For example, through a series of button presses or by using
command inputs similar to Vim's ‹:quit› or ‹:q›.
VAULT SELECTION
On startup screen you can select the Vault you want to view. Any open vaults
are shown with a ◆ symbol marker.
DEFAULT KEY BINDINGS
‹q›, Quit the application
‹Ctrl+C›
‹?› Show this help
‹k› Move selection up
‹j› Move selection down
‹↩ Enter› Select and open the highlighted vault
‹Tab› Switch to next pane
‹Shift+Tab› Switch to previous pane
The vault selection can be brought up as a modal by hitting ‹Ctrl+G› after
the startup screen.
INTERFACE
The application has two main panes: the Explorer (file browser) on the left
and the Note Editor on the right. You can switch between these panes using
the Tab key. The currently active pane will be highlighted and name of the
active pane is displayed in the lower left corner of the application.
EXPLORER PANE
Browse and select notes from your vault.
The explorer shows all notes and folders in your vault. You can navigate up
and down through the list, and press Enter to select and view a note. The
explorer panel can be toggled on/off to give more space to the note editor.
Explorer panel can be expanded and hidden. The Explorer panel has a ⟹
symbol indicator when it is expanded.
DEFAULT KEY BINDINGS
‹q›, Quit the application
‹Ctrl+C›
‹?› Show this help
‹Esc› Cancel/close modals
‹k / j› Move selection up / down
‹↑ / ↓› Move selection up / down
‹s› Toggle note sorting
‹n› Create new untitled note
‹N› Create new untitled folder
‹r› Rename selected note or directory
‹t› Toggle explorer panel visibility
‹← / h› Hide explorer panel
‹→ / l› Expand explorer panel
‹↩ Enter› Select and view the highlighted note
‹Tab› Switch to next pane
‹Shift+Tab› Switch to previous pane
‹Ctrl+G› Toggle vault selector modal
‹Ctrl+B› Toggle explorer panel visibility
‹Ctrl+U› Scroll up half a page
‹Ctrl+D› Scroll down half a page
OUTLINE PANE
Browse and go to heading in a note.
The outline shows all headings in the note. You can navigate up and down
through the list, and press ‹Enter› to expand or collapse a heading. To
move the cursor to the heading in the document press ‹g›. The outline pane
can be toggled on/off to give more space to the note editor.
DEFAULT KEY BINDINGS
‹q›, Quit the application
‹Ctrl+C›
‹?› Show this help
‹Esc› Cancel/close modals
‹k / j› Move selection up / down
‹↑ / ↓› Move selection up / down
‹g› Move editor cursor to currently selected heading
‹↩ Enter› Expand or collapse heading
‹Tab› Switch to next pane
‹Shift+Tab› Switch to previous pane
‹Ctrl+O› Toggle outline pane visibility
‹Ctrl+G› Toggle vault selector modal
‹Ctrl+B› Toggle explorer pane visibility
NOTE EDITOR PANE
Read and navigate through your selected note. The note editor supports
multiple modes when experimental editor is enabled.
VIEW MODE (Default)
View mode displays the rendered markdown content with navigation support.
This is the default display mode for reading notes.
DEFAULT KEY BINDINGS
‹q› Quit the application
‹?› Show this help
‹Esc› Cancel/close modals
‹k / j› Move cursor up / down
‹↑ / ↓› Move cursor up / down
‹← / →› Move cursor left / right (one character)
‹Alt+←› Move cursor left by word
‹Alt+→› Move cursor right by word
‹t› Toggle explorer panel visibility
‹Tab› Switch to next pane
‹Shift+Tab› Switch to previous pane
‹Ctrl+G› Toggle vault selector modal
‹Ctrl+B› Toggle explorer panel visibility
‹Ctrl+U› Scroll up half a page
‹Ctrl+D› Scroll down half a page
EXPERIMENTAL EDITOR (when enabled):
‹i› Enter edit mode
‹Shift+R› Enter read mode
‹Ctrl+X› Save note
‹Esc› Exit current mode
EDIT MODE (Experimental)
Edit mode allows you to make changes to your note. The editor is built
from scratch with limited capabilities. Single block editing is supported
(navigating between blocks switches the active edit buffer).
WARNING: Edit mode key mappings cannot be modified through configuration.
SUPPORTED OPERATIONS:
• Character insertion
• Character deletion (backspace only)
• Navigation (arrow keys, word jumping)
• Newline insertion (Enter)
EDITING COMMANDS
‹Backspace› Delete character before cursor
‹Enter› Insert newline
‹Ctrl+E› Toggle to read mode
‹Esc› Exit edit mode
CURSOR MOVEMENT
‹→› Move forward one character
‹←› Move backward one character
‹↑› Move up one line
‹↓› Move down one line
‹Alt+→› Move forward by word
‹Alt+←› Move backward by word
LIMITATIONS:
• No undo/redo support
• No clipboard operations (copy/paste/cut)
• No text selection
• No multi-line deletion
• No line/word deletion commands
• No jumping to start/end of line or document
INPUT MODAL
The input modal appears when renaming notes or directories. It provides
a text input field with basic editing capabilities.
DEFAULT KEY BINDINGS
‹Esc› Cancel and close modal without saving
‹↩ Enter› Accept changes and save
‹i› Enter edit mode for typing
‹h / l› Move cursor left / right
‹← / →› Move cursor left / right
‹Alt+F› Move cursor forward by word
‹Alt+B› Move cursor backward by word
‹Backspace› Delete character before cursor
USAGE
When renaming a note or directory from the explorer:
1. Press ‹r› on the selected item
2. The input modal will appear with the current name
3. Press ‹i› to enter edit mode
4. Modify the name as needed
5. Press ‹Enter› to save or ‹Esc› to cancel
────────────────────────────────────────────────────────────────────────────
CONFIGURATION
Basalt key mappings can be modified or extended by defining key mappings in
the user configuration file. Each key mapping is associated with a specific
'pane' and becomes active when that pane has focus. The global section
applies to all panes and is evaluated first.
The experimental editor feature is disabled by default. To enable editor
functionality, set `experimental_editor = true` in your configuration file.
Available commands are organized by pane:
GLOBAL COMMANDS:
quit, vault_selector_modal_toggle, help_modal_toggle
SPLASH COMMANDS:
splash_up, splash_down, splash_open
EXPLORER COMMANDS:
explorer_up, explorer_down, explorer_open, explorer_sort, explorer_toggle,
explorer_new_untitled_note, explorer_new_untitled_folder,
explorer_toggle_input_rename, explorer_switch_pane, explorer_scroll_up_one,
explorer_scroll_down_one, explorer_scroll_up_half_page,
explorer_scroll_down_half_page
OUTLINE COMMANDS:
outline_up, outline_down, outline_toggle, outline_toggle_explorer,
outline_switch_pane_next, outline_switch_pane_previous outline_expand,
outline_select
NOTE EDITOR COMMANDS:
note_editor_cursor_up, note_editor_cursor_down, note_editor_scroll_up_one,
note_editor_scroll_down_one, note_editor_scroll_up_half_page,
note_editor_scroll_down_half_page, note_editor_toggle_explorer,
note_editor_switch_pane
EXPERIMENTAL EDITOR COMMANDS:
note_editor_experimental_set_edit_mode, note_editor_experimental_set_read_mode,
note_editor_experimental_save, note_editor_experimental_exit_mode,
note_editor_experimental_cursor_word_forward,
note_editor_experimental_cursor_word_backward
INPUT MODAL COMMANDS:
input_modal_edit_mode, input_modal_accept, input_modal_cancel,
input_modal_left, input_modal_right, input_modal_word_forward,
input_modal_word_backward
MODAL COMMANDS:
help_modal_toggle, help_modal_close, help_modal_scroll_up_one,
help_modal_scroll_down_one, help_modal_scroll_up_half_page,
help_modal_scroll_down_half_page, vault_selector_modal_up,
vault_selector_modal_down, vault_selector_modal_close,
vault_selector_modal_open, vault_selector_modal_toggle
────────────────────────────────────────────────────────────────────────────
FEATURES
• Navigate and read notes from any Obsidian Vault using terminal
• Nested folders and notes are supported
• Key bindings can be changed with configuration
• View markdown notes in a readable, custom styled format
• Toggle between focused note reading and vault exploration
• Sort notes alphabetically
• Create new notes and folders from the explorer
• Rename notes and directories from the explorer
• Input modal with text editing for interactive operations
• Experimental editor mode for note modification (when enabled)
• Multiple editor modes: View mode for reading, Edit mode for changes
• Basic text editing capabilities in Edit mode (custom implementation)
• Single block editing with character insertion and deletion
────────────────────────────────────────────────────────────────────────────
KNOWN LIMITATIONS
• Images are not rendered
• External links are not clickable
• Markdown tables are not rendered properly
• There is no syntax highlighting for code blocks
• Markdown inline text styles are not rendered
• Experimental editor is disabled by default and requires configuration
• Edit mode key mappings cannot be customized