Emeraldian reads your Obsidian vault in place, with no import step

It reads the same folder Obsidian already does

The central design choice is that Emeraldian is pointed at a vault you already have rather than asked to create one. There is no import step, no database and no lock-in. It reads the same plain folder of Markdown files that Obsidian reads, which means two things follow. You can leave Obsidian open on that folder for the whole session without a conflict, and closing Emeraldian leaves your notes exactly as the files they were.

The interface reproduces the layout people already know: three panes, live preview markdown, backlinks, a force-directed graph, and eighteen themes.

An assistant panel is included, and the stated design goal for it is auditability rather than convenience. It works on your notes through the very same commands you use, so you can watch what it did instead of taking its word for it. Whatever the assistant changes arrives through the same actions you could have performed, which makes the diff inspectable.

Running it takes a path, nothing, or a query. With no argument it opens whichever vault Obsidian last had open, and a flag lists what Obsidian knows about. It also accepts the URI scheme the desktop app registers, so a link that opens Obsidian opens this instead.

Four install routes, with npm deliberately left out

The one-liner picks the right build for your machine, downloads it, and checks it against its published checksum before anything moves:

curl -fsSL https://emeraldian-tui.github.io/install.sh | sh

It works on macOS and Linux, takes an environment variable to choose the install directory and another to pin a release. Piping a script into a shell is worth reading first, and the documentation is candid that you should: the script is about 150 readable lines.

Homebrew is a single tap install. Cargo needs Rust 1.90 or newer and installs the crate directly.

The npm route is the interesting omission. It is marked as coming, and the command is not listed at all. The reasoning given is that a command which looks right and then fails is worse than one that is plainly missing, so an option that does not exist yet is documented as absent rather than as aspirational.

A manual route remains for anyone who prefers to unpack an archive themselves, and the release archives ship with a checksum file.

Intel Macs build from source because no binary exists for them

Prebuilt archives cover four targets: Apple silicon on macOS, two Linux architectures covering both x86-64 and aarch64, and Windows on x86-64. The manual route is a checksum verification, a move into the binary directory, and on macOS a step that clears the quarantine attribute so the freshly moved binary will launch.

Intel Macs are absent from that list. The documented consequence is that they build from source with cargo, which means installing a Rust toolchain rather than downloading a file. A second consequence follows from the minimum version: the cargo route needs 1.90 or newer.

Building from a clone is the same requirement seen from another angle, with one useful flag. Installing from the workspace path with the locked flag installs to the cargo binary directory and refuses to move dependency versions, while a plain release build skips installation entirely.

So there are really three shapes here: a script that decides for you, a package manager you already trust, and a source build. The middle option is the one with the fewest surprises, since Homebrew and Cargo both handle the toolchain question for you.

Emeraldian is the interface, obsidian is a remote control

Obsidian ships an official command line tool, enabled under a general settings toggle, and the documentation goes out of its way to distinguish it from Emeraldian rather than treating them as rivals.

The Obsidian binary is a remote control for the desktop application. It talks to a running instance, and it launches one if none is running, so it needs the app. On a machine with no display it also needs a headless ozone platform flag or a virtual framebuffer.

Emeraldian is the interface itself. It talks to the vault files, needs no Obsidian instance, and runs as it is on a machine with no display at all.

They are used together for exactly one operation, the thing only the application can do: handing a note to the GUI. When the Obsidian binary is on the path, Emeraldian uses it. A command in the assistant panel reports the binary's status and the vaults the application knows about, and another opens the current note in the desktop app.

If the binary is not enabled, or the application is not running, Emeraldian says so and carries on. Nothing else depends on it, which is the important part: the GUI bridge is an optional convenience rather than a dependency.

q types a letter in text fields and quits everywhere else

Key bindings follow Obsidian where Obsidian has them and fall back on the conventions other terminal interfaces use. Question mark shows the full list, a command palette and a quick switcher exist, and there are bindings for searching all notes, toggling reading and editing, creating a note, opening today's daily note, switching between the graph and local graph, and opening the assistant panel. Tab moves between panes, the home key cluster moves within one, and enter opens or follows a link. F3 closes a tab and F4 toggles vim mode.

Two details are defensive in a way that matters. First, q never quits from a context where you might be typing: in the editor, the chat box or a search field it types the letter, and Ctrl+Q is the way out. Quit otherwise asks first. Second, a context-sensitive hint bar above the status bar shows only the keys that apply where you currently are, and the palette has a toggle to turn it off.

The editor itself follows what is on screen rather than what is stored, so a wrapped paragraph moves through a line at a time as it looks. List handling is list-aware: enter carries a marker onto the next line and ends the list on an empty item, and tab still inserts a tab in prose.

Clipboard support borrows tools you already have

Copy, cut and paste go through the system clipboard rather than an internal buffer, which is what lets text move between a note and any other application.

The terminal's own paste behaves differently from the application's paste, and the difference is deliberate. A paste from the terminal arrives as a single block: into a note with its line breaks intact, but into the chat box, a search field or a name prompt as one line, so a pasted newline cannot send a message before you meant to.

Reaching the clipboard is done with whatever the machine already provides, which is why there is no clipboard dependency of its own. macOS uses the built-in copy and paste commands, Linux uses whichever of the Wayland or X11 tools are installed, and Windows uses PowerShell.

Where none of those can copy, as over SSH, it asks the terminal to do it with an escape sequence that Ghostty, kitty, WezTerm, iTerm2, Alacritty and Windows Terminal all understand. Inside tmux that path needs one setting enabled first. Copy and paste within the app itself works either way, so the fallback is only about reaching other applications.

Rust 1.90 is imposed by an image crate, not by this code

The workspace declares Rust 1.90 as its minimum, and the comment next to that line is more interesting than the number. The requirement is not a choice by the project. The image rendering crate pulls in a sixixel crate, which pins a colour quantisation crate at a specific version, and that version is what needs 1.90. Raise the floor and the project loses image support; lower it and the build fails.

The workspace holds four crates: a core, a theme crate, an agent crate, and the binary itself. The terminal stack is ratatui on crossterm, both current major versions.

The image crate is configured with its default features switched off and a small feature list selected instead. The comment explains why: the defaults would pull in optional C bindings for two image protocols, and turning them off keeps the binary pure Rust so it cross-compiles. What remains is support for the terminal graphics protocols the major terminals implement, with a fallback that renders images as coloured blocks when the terminal cannot do better.

The image format list covers PNG, JPEG, GIF, WebP and BMP. Licenced under GPL-3.0-or-later, version 0.6.0, edition 2024, and published to crates.io under five keywords.

Editorial conclusion

Emeraldian suits someone who already keeps notes in Obsidian and wants the same folder readable over SSH or on a machine with no display, since it reads plain Markdown in place and leaves the desktop app free to stay open on the same directory. It is the wrong choice if you rely on Obsidian plugins or sync features, because those live in the app and not in the files. Before switching, check that your target platform has a prebuilt binary or that you have a Rust 1.90 toolchain, since Intel Macs build from source, and decide whether you want the assistant panel at all, given that it acts through the same commands you can audit. Confirm that the official Obsidian CLI is enabled if you want notes to open in the GUI.

Frequently asked questions

Official sources

1. iamrohithrnair/emeraldian on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases