GitHub - LatentDream/merlion: 🌊 A better TUI for Obsidian

3 min read Original article ↗

Obsidian-inspired terminal note-taking app
merlion.dev

What is it?

Merlion is a TUI, Markdown-based note-taking application, inspired by Obsidian but built for command-line workflows

  • Uses $EDITOR (nvim, nano, ...) to edit notes
  • Uses Markdown Format
  • Compatible with Obsidian vaults (any .md files)

Merlion works fully offline by default, no account needed, all files are on your computer in a SqliteDB or directly as .md files.

Installation

Option 1: Download Pre-built Binaries (Recommended)

Download the latest release for your platform from GitHub Releases:

macOS:

  • ARM (M1/M2/M3): merlion-darwin-arm64.tar.gz
  • Intel (x86): merlion-darwin-amd64.tar.gz

Linux:

  • ARM: merlion-linux-arm64.tar.gz
  • x86: merlion-linux-amd64.tar.gz

Windows:

  • ARM: merlion-windows-arm64.zip
  • x86: merlion-windows-amd64.zip

After downloading, extract and move the binary to your PATH:

# macOS/Linux example
tar -xzf merlion-*.tar.gz
sudo mv merlion /usr/local/bin/

Option 2: Homebrew (macOS/Linux)

Install from source using the Homebrew formula:

# In the root of the repo
brew install --build-from-source merlion.rb

Option 3: Build from Source

Requirements: Go 1.21 or higher

# Clone the repository
git clone https://github.com/latentdream/merlion.git
cd merlion

# Build using just
just build

# Or build directly with go
go build -o merlion ./cmd/merlion

# Move to your PATH
sudo mv merlion /usr/local/bin/

Features

  • Keyboard (only) navigation
  • Local-first note storage
  • Optional cloud storage to sync notes across devices
    • Lightweight web UI (this will be removed in favor of a sync feature)
  • Built-in themes: Gruvbox and NeoTokyo
    • Feel free to submit a PR to add more themes.
    • Or to ask for a new theme to be added
    • Toggle themes with ctrl+t
  • Naviguate between note base on note title
  • Markdown support
  • Use your $EDITOR as note editor

Keymap

Key(s) Action Description
↑ or k Up Move selection up
↓ or j Down Move selection down
← or h Left Go back to list view
→ or l Right View selected note
delete Delete Delete selected item
tab Next Tab Switch to next tab
shift+tab Previous Tab Switch to previous tab
pgup or ctrl+u Page Up Scroll up one page
pgdn or ctrl+d Page Down Scroll down one page
enter Select Confirm selection
e Edit Edit the current note
m Manage Manage note information
esc Clear Filter/Back Clear current filter or go back
q or ctrl+c Quit Exit the application
ctrl+t Toggle Theme Switch between light/dark theme
i Toggle Info Show/hide note information panel
ctrl+p Toggle Info Position Change note info panel position
ctrl+f Toggle Compact View Toggle compact view (large screens only)
c Create Create a new note
( or ) Toggle Vault Toggle between Vault

Getting Started

Once installed (see Installation section above), run:

Or with compact mode for smaller terminals:

Tmux Integration

Add the following to your .tmux.conf to launch Merlion in a popup window:

bind C-m display-popup \
  -d "#{pane_current_path}" \
  -w 90% \
  -h 90% \
  -E "merlion --compact"

Then launch it with <tmux-leader> + m.

Cloud Storage

Merlion supports cloud storage, you can create an account at note.Merlion.dev to get your notes across devices.

  • This is still a WIP and subject to change / removal in favor of a sync feature

  • The notes are not encrypted on the server (yet), it's still a work in progress

    • DON'T use this for sensitive data

  • To have online note for sharing note across computer, you can create an account at note.Merlion.dev

    • Your notes will then be local, or online, switch between the two workplace with ( or )
    • Sync capability between online & offline note will soon be added

This software is provided "as is", the code ain't perfect, the app ain't perfect and I'm having fun