Fern

Go Reference Go Report Card fern fern

Made with VHS

Fern aims to be everything you love about note-taking tools like Obsidian or Notion with out the bloated GUI overhead, cloud data storage, or proprietary lock-ins. A beautiful Terminal UI (TUI) that is local first, privacy respecting, light-weight, yet powerful enough to manage your personal knowledge Vault of notes and journal entries with ease.

Features

• Notes, Journals & Templates: daily, weekly, monthly, and yearly journal entries; templates to keep new notes consistent and simple to setup. Don't lose your flow!
• Full-text search: regex-compatible search across your entire vault (/)
• Command palette: fuzzy-searchable palette for quick access to all commands (ctrl+p)
• Collapsible sidebar tree: tree directory over Notes, Journals, Assets and Templates subfolders (ctrl+b)
• Tabs & split panes: open multiple notes side-by-side panes or in tabs within a panes. Change tab order and move tabs between panes easily.
• Wikilinks & Markdown links: links are automatically rewritten when notes are renamed. No more dead links!
• Bookmarks: save and re-open important tabs quickly
• Themes: comes with a set of popular themes, pride flag themes, & support for your own custom JSON themes. Add them in a PR for others to enjoy too!
• Multiple vaults: create and switch between vaults on the fly
• UI Supports Multiple Languages: Use Fern in the language you're most comfortable with. Don't see your language of choise? Help out with adding translations or open a ticket.
• Local-first: no telemetry, no cloud sync service; runs well on resource-constrained systems
• Modal editing: Normal, Insert, Replace, and Visual modes with a mode indicator in the status bar; View mode for read-only rendered markdown
• Keybinding presets: choose from vim, emacs, helix, or arrows presets; auto-detected on the first run
• Configurable keybindings: remap any individual action on top of your chosen preset

Installation

Binary Releases

For Windows, Mac OS(10.12+) or Linux, you can download a pre-built binary release here.

Homebrew (macOS and Linux)

brew tap InodeLabs/tap https://codeberg.org/InodeLabs/homebrew-tap
brew install --cask fern

Scoop (Windows)

scoop bucket add InodeLabs https://codeberg.org/InodeLabs/scoop-bucket
scoop install fern

Linux packages (DEB / RPM)

Pre-built .deb and .rpm packages are available on the releases page.

# Debian / Ubuntu
sudo dpkg -i fern_*.deb
# Fedora / RHEL / openSUSE
sudo rpm -i fern_*.rpm
# or with dnf:
sudo dnf install fern_*.rpm

Snap

Get it from the Snap Store

snapcraft pack
sudo snap install fern_*.snap --dangerous

NOTE: Fern stores its config, indexes, and state inside the snap's common per-user data area so they persist across snap revisions. Vaults in your home directory work through the home interface. If you keep vaults on USB drives or other external media, connect removable-media after install:

sudo snap connect fern:removable-media

Go

go install codeberg.org/InodeLabs/fern@latest

NOTE: If you get an error that fern cannot be found or that it is not defined, you may need to add ~/go/bin to your $PATH (for macOS/Linux). On Windows, add %HOME%\go\bin, not to be confused with C:\Go\bin, which is for Go's own binaries, not apps like fern.

Nix

With Nix flakes enabled:

# run without installing
nix run codeberg:InodeLabs/fern
# install into your profile
nix profile install codeberg:InodeLabs/fern

Manual (from Source Code)

You will need to have Go installed first.

git clone https://codeberg.org/InodeLabs/fern
cd fern
go install

Using Fern

Run fern in your terminal to launch the TUI. On first run you will be prompted to set up a new vault or point Fern at an existing one.

Try the Demo Vault!

Meet Fern(she/her). She's a transfem 🏳️‍⚧️, tech worker 👩🏽‍💻 who is just trying to keep her head above water and get organised in today's crazy world. Good thing she has Fern! Her vault* contains some example notes (cross-linked), along with sample journals, templates, and bookmarks. This demo vault can be found in the demo folder (I'm not so creative in names, sorry). For an orientation to the Vault and a tour of some of Fern's main features, open the start-here.md in the sidebar, under the Notes section! Have fun and explore all of Fern's features without needing to set up a new vault or touch any of your existing notes.

After installing Fern, you can load it:

• From the CLI: by running fern open ./demo
• From inside Fern: by running the vaultLoad command: :vaultLoad ./demo

*All notes, journals, etc are purely fictional. McBoatface is not a real politician, to my knowledge!

Command Bar

Press : from Normal or View mode to jump to the command bar. Commands support tab-completion on both the command name and their arguments. Don't worry if you can't remember them all!

Some commonly used commands:

For the complete command reference, see the Command Bar docs.

Templates

Templates are markdown files stored in the templates/ folder of your vault. When you create a note from a template, Fern substitutes built-in variables before opening the file.

Some commonly used template variables:

A custom format can be appended to any date variable with a colon: {{DATE:DD MMM YYYY}}. Unknown variables like {{AUTHOR}} prompt for a value when the template is applied.

For the full template reference, see the Templates docs.

Configuration

Fern is configured through TOML files: a global file at ~/.config/fern/config.toml that applies to all vaults, and an optional per-vault file at {vault}/.fern/config.toml that overrides global settings for that vault only. Both are created automatically on first run with all options commented out.

For the full configuration reference including all keys, defaults, and keybinding remapping, see the Configuration docs.

Keybindings

Fern has four editing modes: Normal, Insert, Replace, and Visual, plus a View mode for read-only rendered markdown. The active mode is always shown in the status bar. Press ? at any time to open the in-app keybinding reference.

Some key shortcuts (pun intended) to know are:

Keybinding Presets

Fern ships four presets that work as a base layer for the viewer and editor keybindings. The default is arrows, which uses arrow keys and standard clipboard shortcuts that should be familiar for most users and those familiar with editors like Visual Studio Code, SublimeText, etc.

Auto-detection: on first run or whenever a starting preset is not configured, Fern attempts to read environment variables to pick the closest preset automatically that resembled that of your prefered editor. If none of the env vars are set or match a known editor can't be determined, Fern defaults to arrows.

Changing the preset in the Settings Editor: run :settings from the command bar to open the in-app Settings Editor. The preset selector is at the top of the Keybindings section. Change it and then save. No file editing required! :)

Setting it manually in your config file (~/.config/fern/config.toml): If you love poking around in config files, you can manually set it too. The appropriate stanza is show below:

[keybindings]
preset = "vim" # options: vim | emacs | helix | arrows

Per-key overrides layered on top of the preset, custom keybinds in the config file still work exactly as before. Any key you set under [keybindings.viewer] wins over the preset for that action.

For the complete keybinding reference, covering all modes, see the Fern User Documentation pages: Interface docs & Editing modes.

Project Roadmap

Here's a near-term list of features I'm hoping to work on adding to Fern along with a very-rough release plan:

In v1.5.X

• Technical Debt Paydown: Review the codebase and paydown/cleanout any technical cruft that has accumulated

v1.6

• Intelligent Indenting: All sub-items change indentation as well in the same direction as the parent item/bullet (opt-in setting)
• Startup Layout: Replace the start_journals with a more flexible, powerful Layout system (like TMUX predefined layouts) wherein users can define pane splits and the journals/notes to have occupying each of them on startup (or swtiching to a vault)
• Plugins Engine: Create a few hooks that 3rd party Lua plugins could utilize to safely extend Fern's capabilities whilst allowing the core program to stay smaller and focused. Opt-in feature. Users would define a list of plugins they want.

v1.7

• Visualize your Vault's Graph: Have a way to export your vault's notes/journals connections graph.
• Right sidebar: could hold note/vault stats, outbound and inbound links for the active note, etc. I'm all ears if you have ideas for what could/should live in this space!

And mor! 😻 Open an issue for any features you want to see!

To Contributors

Nix Development Environment

If you have Nix, with flakes enabled, you can skip manual tool installation and use provided dev shell:

git clone https://codeberg.org/InodeLabs/fern
cd fern
nix develop # enter a shell with env & tools all setup
nix build # build the binary at: ./result/bin/fern

Linting and Formatting

We use golangci-lint and gocyclo as part of our Git pre-commit hook and the CI workflows for formatting, linting and overall code quality checks.

Please ensure you have both installed:

# golanci-lint Docs: https://golangci-lint.run/docs/welcome/install/local/
curl -sSfL https://golangci-lint.run/install.sh | sh -s -- -b $(go env GOPATH)/bin latest
# gocyclo Docs: https://github.com/fzipp/gocyclo
go install github.com/fzipp/gocyclo/cmd/gocyclo@latest

Found a bug? Got an idea for a new feature?

Please open a ticket at https://codeberg.org/InodeLabs/fern/issues/new/choose.