Skip to content

Managing Plugins

Enabling the plugin system

Plugins are disabled by default. To turn them on, add the following to your global config (~/.config/fern/config.toml):

[plugins]
enabled = true

Once enabled, Fern loads every subdirectory inside the plugins directory that contains a main.lua file. The default plugins directory is ~/.config/fern/plugins/. You can point it somewhere else with the dir key:

[plugins]
enabled = true
dir = "~/dotfiles/fern-plugins"

The Plugin Manager

Open the plugin manager from the command palette (ctrl+p) by searching for "Plugins: Manage Plugins". You can also open it from the command bar with :Plugin.

Plugin Manager
----------------------------------------------------------------------
  [x] tasks                 Manage tasks inside your notes
  [x] word-count            Show word count in the status line
  [ ] habit-tracker         Log daily habits
  [ ] diary-prompts         Daily writing prompts
----------------------------------------------------------------------
[f]etch  [i]nstall  [u]pdate  [d]elete  [a]pprove  [r]evoke  [esc] close

Status indicators

Symbol Meaning
[x] Installed from the Fern-Terranium registry
[~] Installed as a local plugin (no registry entry)
[?] Present on disk but blocked pending your approval
[ ] Available in the registry but not yet installed

Keyboard shortcuts

Key Action
down Move selection down
up Move selection up
f Fetch the Fern-Terranium registry
i Install the selected plugin
u Update the selected plugin
d Delete the selected plugin
a Approve the selected plugin
r Revoke approval from the selected plugin
esc / q Close the manager

Installing from the registry

  1. Press f to fetch the registry. Fern downloads the plugin list from Fern-Terranium and merges it with any plugins you already have installed.
  2. Navigate to the plugin you want with j/k.
  3. Press i to install it.

After installation the status bar shows a confirmation message. Restart Fern to activate the newly installed plugin.

Updating a plugin

Select an installed plugin and press u. Fern downloads the latest version from the registry (or directly from its Codeberg repository if the registry has not been fetched) and overwrites the existing main.lua. Restart Fern to apply the update.

Removing a plugin

Select an installed plugin and press d. Fern deletes the plugin's directory. The plugin is immediately removed from disk; restart Fern to fully unload it.

Plugin approval

Fern will not execute a plugin it has not seen before without your explicit approval. This applies to any plugin that was not installed through the :Plugin manager -- for example, a plugin you cloned manually or copied into the plugins directory.

When Fern starts and finds an unapproved plugin on disk it blocks it from loading and shows a status-bar warning:

1 plugin(s) blocked (not approved) - open :Plugin to review

Blocked plugins appear in the manager with a [?] indicator. To approve one:

  1. Open the plugin manager (command palette ctrl+p -> "Plugins: Manage Plugins", or :Plugin from the command bar).
  2. Navigate to the [?] entry with j/k.
  3. Press a. Fern approves the plugin, loads it immediately, and records the approval so it runs automatically on every subsequent startup.

Approval is stored per plugin name in your global state file (~/.local/share/fern/state.json). Plugins installed through the plugin manager are approved automatically.

Revoking approval

If you no longer trust a local or third-party plugin you can revoke its approval from the same manager:

  1. Open the plugin manager (:Plugin).
  2. Navigate to the approved [~] or [x] entry.
  3. Press r. The entry immediately changes to [?] and a confirmation is shown in the status bar.

The plugin continues to run for the rest of the current session because the Lua runtime cannot unload an already-executed script. On the next startup Fern will block the plugin and it will appear as [?] again. The revoked approval is removed from ~/.local/share/fern/state.json.

Declaring plugins in config

The install list in the config serves as a manifest: Fern warns you at startup if any declared plugin is not present on disk.

[plugins]
enabled = true
install = ["tasks", "word-count"]

Entries can be bare registry names ("tasks") or Codeberg author/repo paths ("InodeLabs/fern-tasks"). A repo-style entry is installed by fetching main.lua from the default branch of that repository.

Writing a local plugin

Create a subdirectory inside your plugins directory with a main.lua file:

~/.config/fern/plugins/
  my-plugin/
    main.lua

The first time Fern starts after you add the directory it will block the plugin and show a [?] entry in the manager. Press a to approve it. See Writing Plugins for the full Lua API.