Feather — CLI Debugging, Inspection, and Builds for LÖVE

Important

This is the dev version of Feather, for stable releases go to the release page.

Feather is a CLI for debugging, inspecting, and manage packages for LÖVE games.

It gives you a live window into your running game (logs, variables, errors, performance) without touching your game's release build. Inspired by LoveBird and Flipper.

The goal is to make the day-to-day loop of writing and testing a LÖVE game faster: less time adding print statements and restarting, more time actually building.

✨ Demo · 📖 Documentation · Releases · Changelog · Contributing

---

What it does

• Live log viewer — See print() output in real time without a terminal window.
• Variable inspection — Watch values update as the game runs.
• Error capturing — Errors are caught and shown with a full stack trace.
• Step debugger — Breakpoints, step over/into/out, call stack, local variable inspection.
• Session Replay — Record inputs plus game-defined state checkpoints so playthroughs can be replayed, exported, and debugged later.
• Console / REPL — Execute Lua in the running game (opt-in, requires an apiKey).
• Plugin system — 18+ built-in plugins (collision debug, animation inspector, audio debug, particle editor, and more). Plugins define their UI in Lua; the desktop app renders it automatically.
• Multi-session — Connect multiple games at the same time.
• Mobile and platform builds — CLI-managed web, Android, iOS, Windows, macOS, Linux, and SteamOS workflows.
• Screenshots & GIF capture — Built-in capture plugin.
• Log file viewer — Open .featherlog files for offline inspection.
• CLI — No Lua changes needed to run, debug, build, or clean up love2d games.
  • Package Manager — Install packages from a curated list of popular love2D packages.

---

---

Quick Start

Install the Feather desktop app and CLI:

1. Download the desktop app from Releases.
2. Install the CLI:

npm install -g @kyonru/feather

Initialize your project, open the Feather app, then run the game:

feather init path/to/my-game
feather run path/to/my-game

Feather is injected by the CLI for dev runs and debug builds, so your game code does not need a manual require for any target.

Optional vendor setup for web, mobile, and packaged desktop workflows:

feather build vendor add web --dir path/to/my-game
feather run path/to/my-game --target web

feather build vendor add android --dir path/to/my-game
feather run path/to/my-game --target android

feather build vendor add ios --dir path/to/my-game
feather run path/to/my-game --target ios

For all build vendors, including desktop packaging runtimes:

feather build vendor add all --dir path/to/my-game

Build release artifacts from the same CLI flow:

feather build love --dir path/to/my-game
feather build android --dir path/to/my-game --release
feather build ios --dir path/to/my-game --release
feather build windows --dir path/to/my-game
feather build macos --dir path/to/my-game
feather build linux --dir path/to/my-game
feather build steamos --dir path/to/my-game

For more commands and options:

feather --help
feather run --help

See the CLI docs for feather run, feather doctor, feather build, and feather upload.

---

Package manager

Feather includes a curated installer for common LÖVE libraries. It is not a general package manager — it is a hand-picked catalog of known-good libraries with verified SHA-256 checksums and a lockfile you can commit.

feather package install anim8       # install a library
feather package install             # restore everything in feather.lock.json
feather package audit               # verify checksums of installed files
feather package list                # browse the catalog

Available libraries include anim8, bump, hump, lume, flux, inspect, middleclass, classic, push, sti, and windfield. See packages/README.md for the full list and command reference.

---

Documentation

• Installation
• CLI
• Configuration
• Usage — observers, logging, console, step debugger
• Session Replay
• Plugins
• Packages
• Recommendations — security, performance, release builds

---

Built-in Lua dependencies

• Hump Class
• Inspect
• json.lua
• log.lua
• ws.lua

---

Credits

• LoveBird by rxi — original inspiration
• Love-Dialogue by Miisan-png — plugin system reference
• HUMP, anim8, flux, bump.lua, lua-state-machine
• love2d-community/awesome-love2d - Inspiration for package helpers

---

License

The license applies to products that directly replicate the logic or purpose of this tool. It does not apply to games built using it as a development tool.

See LICENSE.md.

AI usage

The architecture and planning of this tool is my own work. The main goal of this tool is to improve developer experience, meaning providing utilities to save time for my own developer experience and hopefully others. AI autocompletion is used for the creation of some of the features in this tool. This is not an AI driven tool nor a product designed by AI. This is a devtool made by an indie dev for indie devs nothing else. All generated code is reviewed by me. But I understand some people are not comfortable with AI involvement in any form. I respect that.