FENNEL-LS(1)

🎀 fennel-ls 🎀 (General Commands Manual)

okay so bestie, welcome to fennel-ls 💖 this is the page that tells you how to configure and use it after you already installed it. iykyk.

---

🌸 NAME

fennel-ls — intelligent editing features for fennel files ✨

---

💜 SYNOPSIS

fennel-ls [--lint filename] | [--fix filename] | [--help]

---

🦋 DESCRIPTION

hiii so this document has all the info on how to configure and use fennel-ls once it's already installed on your machine. no cap, that's the whole vibe of this page 🫶

---

💅 OPTIONS

• --lint filename [...filename] — prints diagnostics for the files you give it. a successful exit code means no problems were found, slay 💅
• --fix [-y] [filename] [...] — runs the suggested fixes from linters on your files 🔧

Also written out as its own line:

fennel-ls --fix [-y] [filename] [...]

• --help — displays the usage summary 😌

And here's the iconic detail: with no arguments, it just sits there waiting for Language Server Protocol messages on stdin. main character energy, honestly 👑

fennel-ls works with zero configuration beyond connecting it to your text editor, but if you're using external libraries, you're gonna need to add them to the config to get completions, documentation, and correct diagnostics. periodt.

If a docset is available for the library you're using:

1. download it and place it in ~/.local/share/fennel-ls/docsets/
2. create a flsproject.fnl in the root directory of your project
3. add the docset to it — it must match the name of the file you downloaded, without the .lua extension:

{:libraries {:library-name true}}

If a docset is not available, add the globals created by the library to the extra-globals field, separated by spaces, so they aren't reported as errors:

{:extra-globals "module1 module2 function1 function2"}

The rest of this document provides additional details on the configuration and usage of fennel-ls 🧚

---

🎀 CONFIGURATION

You configure fennel-ls by creating a file named flsproject.fnl in the root of your project 🌱

The defaults are below — you only need to provide the settings you actually want to change, no need to copy the whole thing. An empty table {} is a perfectly valid configuration and serves as a marker to indicate where the project root is located 📍

{:fennel-path "./?.fnl;./?/init.fnl;src/?.fnl;src/?/init.fnl"
 :macro-path "./?.fnlm;./?/init.fnlm;./?.fnl;./?/init-macros.fnl;./?/init.fnl;src/?.fnlm;src/?/init.fnlm;src/?.fnl;src/?/init-macros.fnl;src/?/init.fnl"
 :lua-version "lua5.4"
 :libraries {}
 :extra-globals ""
 :lints {:unused-definition true
         :unknown-module-field true
         :unnecessary-method true
         :unnecessary-tset true
         :unnecessary-do true
         :redundant-do true
         :match-should-case true
         :bad-unpack true
         :var-never-set true
         :op-with-no-arguments true
         :multival-in-middle-of-call true
         :no-decreasing-comparison false}}

• extra-globals — a space separated list of allowed global identifiers that get added to a set of predefined lua globals 🌈 these identifiers and any of their fields are considered valid and won't produce diagnostics. use this when you're importing a library that has no documentation available for it.
• version — one of lua5.1, lua5.2, lua5.3, lua5.4, intersection, or union.
  • intersection represents the APIs that are available in every supported Lua version.
  • union represents APIs available in any version.
• libraries — this setting controls which extra documentation fennel-ls will load in your environment. each entry in the table is the name of the library and a boolean, true to enable the library 📚
  • the name of the library is the name of a file that will be loaded from ~/.local/share/fennel-ls/docsets/ after appending the .lua extension.
  • for example, if the table contains {:love2d true} the file love2d.lua will be loaded from ~/.local/share/fennel-ls/docsets/. obsessed 💖
  • the available docsets are listed on the Fennel wiki.
  • see the full docsets documentation for more information on how to find, install, or create docsets.

fennel-ls respects the XDG convention, so if you changed $XDG_DATA_HOME the files will be loaded from the location you specified 🫶

---

🔥 USAGE

okay so here's a thing: fennel-ls cannot tell the difference between a regular file and a macro file 💀 but you can ask it to treat your file as a macro file if the first line exactly matches:

;; fennel-ls: macro-file

expect this to change at some point in the future when I come up with a better way to specify which files are meant to be macro files 🙈

---

👑 FEATURES

here's the whole support grid, translated out of table form so your terminal can breathe 🌸

• Completions — Locals ✅, Fields ✅, Builtin Globals ✅, Across Files ✅, Builtins ✅, Macros ✅, User globals ⬜
• Hover — Locals ✅, Fields ✅, Builtin Globals ✅, Across Files ✅, Builtins ✅, Macros ✅, User globals ⬜
• Goto Definition — Locals ✅, Fields ✅, Builtin Globals N/A, Across Files ✅, Builtins N/A, Macros ⬜, User globals ⬜
• Rename — Locals ✅, Fields ⬜, Builtin Globals N/A, Across Files ⬜, Builtins N/A, Macros ⬜, User globals ⬜
• Goto Reference — Locals ✅, Fields ⬜, Builtin Globals ⬜, Across Files ⬜, Builtins ⬜, Macros ⬜, User globals ⬜

fennel-ls can report all fennel compiler errors, plus a few custom lints 🔍

Unused locals get flagged unless they begin or end with an underscore. so if you've got a local that's unused in your code but necessary for pattern matching purposes, it's recommended to put an underscore at the end. for example:

(case [1 1 2 3 5 8]
  [a_ a_] (print "First two elements are equal"))

---

🧚 LICENSE

Copyright © 2023-2025, Released under the MIT/X11 license 📜

---

and that's the whole page bestie!! 💖 as for the official sign-off — the footer on this one is literally just () with no source, version, or date filled in, so like… the vibes are the metadata 🫶 go forth and slay your fennel files 💅✨