zettel-cli.nvim

A Neovim plugin that integrates zettel-cli — a terminal Zettelkasten note manager — with Neovim-native UI and pickers.

---

Requirements

• Neovim 0.10+
• zettel-cli binary on $PATH
• (Optional) snacks.nvim or telescope.nvim for enhanced pickers with file preview

---

Installation

lazy.nvim — minimal

No options are required. This is enough to register all commands and enable wikilink navigation:

{
  'joaoluga/zettel-cli.nvim',
  config = true,
}

lazy.nvim — all options

{
  'joaoluga/zettel-cli.nvim',
  dependencies = {
    -- Pick one for enhanced pickers with file preview (both are optional).
    -- If neither is installed, a plain vim.ui.select fallback is used.
    'folke/snacks.nvim',
    -- 'nvim-telescope/telescope.nvim',
  },
  config = function()
    require('zettel-cli').setup({
      -- Register default <leader>z* keymaps (see table below). Default: false.
      keymaps = true,
      -- Enable `gf` wikilink navigation in markdown buffers. Default: true.
      wikilinks = true,
    })
  end,
}

---

Commands

Note creation

Command	Description
:ZettelCliNew [title]	Create a new note. Prompts for a title if omitted. Accepts --template and --target to override config defaults.
:ZettelCliPreset [name]	Create a note from a saved preset. Shows a selector if no name is given.
:ZettelCliPreview [title]	Render the default template in a scratch buffer without writing a file.
:ZettelCliLucky	Open a random .md note from the notes directory.

Pickers

Command	Description
:ZettelCliFindNotes	Fuzzy-search notes by filename across the notes directory.
:ZettelCliFindByTag	Browse notes by tag — scans #tag inline mentions and YAML frontmatter tags:.
:ZettelCliFindBacklinks	Find all notes that contain a [[wikilink]] pointing to the current buffer.
:ZettelCliFindLinks	List all [[wikilinks]] found in the current buffer and navigate to their targets. Unresolved links are shown with (unresolved).

---

Default keymaps

Opt in with setup({ keymaps = true }).

Key	Command
<leader>zn	:ZettelCliNew
<leader>zl	:ZettelCliLucky
<leader>zp	:ZettelCliPreset
<leader>zv	:ZettelCliPreview
<leader>zf	:ZettelCliFindNotes
<leader>zt	:ZettelCliFindByTag
<leader>zb	:ZettelCliFindBacklinks

:ZettelCliFindLinks has no default keymap. Add one manually if desired, for example:

vim.keymap.set('n', '<leader>zk', ':ZettelCliFindLinks<CR>', { desc = 'Zettel: outgoing links' })

---

Picker actions

All note pickers (FindNotes, FindByTag, FindBacklinks, FindLinks) support a secondary action to insert a wikilink at the cursor instead of opening the file.

Key	Action
<CR>	Open the selected note
<C-i>	Insert [[note-title]] at the cursor in the originating buffer

Backend behaviour:

Backend	Preview	<C-i> insert
snacks.nvim	Yes (file preview in picker)	Not available
telescope.nvim	Yes (file preview in picker)	Yes
builtin (vim.ui.select)	No	No

---

Wikilink navigation

When wikilinks = true (the default), pressing gf on a [[wikilink]] in any markdown buffer opens the referenced note in the current Neovim instance. If the cursor is not on a wikilink, gf falls back to Vim's built-in file-under-cursor behaviour.

Wikilink targets are resolved by searching notes_path for a .md file whose stem matches the link text exactly, or after slugification (lowercase, spaces to hyphens).

---

Configuration reference

zettel-cli.nvim reads ~/.config/zettel-cli/config.toml automatically (or the path in $ZETTEL_CLI_CONFIG) and uses it to locate the notes directory and available presets. See zettel_cli.md for the full config format.

The setup() function accepts the following options:

Option	Type	Default	Description
keymaps	boolean	false	Register default <leader>z* keymaps
wikilinks	boolean	true	Enable gf wikilink navigation in markdown buffers

To reload the config without restarting Neovim:

require('zettel-cli.config').reload()

---

How files open in Neovim

zettel-cli normally spawns a new editor process to open a created file. This plugin intercepts that by passing a wrapper as --file-reader:

nvim --server <v:servername> --remote <file>

This sends the file path to the already-running Neovim instance via its RPC server, so the file opens in your current session without spawning a second process. The --file-reader flag is injected automatically on every zettel-cli invocation and overrides whatever is set in the config file.