# Project pack: Spoolman @ 488eb74

Facts about **Spoolman** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v4.md). Pinned to one version; never changes after publication.

> Spoolman is a self-hosted inventory for 3D-printing filament. You record each spool with its material, colour, weight and price, and it keeps track of how much is left as you print. It connects to printer software such as Klipper and OctoPrint, and can print spool labels.

## Setup path (checked 2026-11-03)
- **Start here, no Docker:** Install it with its language package manager. No Docker.
- Offer Docker only if the person asks or this path fails. The commands further down may use Docker; they are not the starting point.
- Verdict source: https://github.com/Donkie/Spoolman/wiki
- You may be unable to download source archives or run commands in this session. The person downloads and runs things; if you cannot fetch something, give any changed file in full in chat with its path.

## Version and source
- Repository: https://github.com/Donkie/Spoolman
- Pinned commit: `488eb7455bead9b2968ff9466ba2f59091a6c23b`. Use exactly this version.
- Zip the person can download in a browser: https://github.com/Donkie/Spoolman/archive/488eb7455bead9b2968ff9466ba2f59091a6c23b.zip
- Fresh checkout (only if you have a shell and git): use the commands below in an empty folder. If this exact source is already checked out, keep your branch and use the development command; do not clone again or reset local changes.
- Official docs: https://github.com/Donkie/Spoolman/wiki
- Licence: **MIT**. Free to use, change and share, even commercially. Keep the original copyright notice.

## Commands from the pinned source
- Developer commands (they may use Docker):

  ```sh
  git clone https://github.com/Donkie/Spoolman bespoke-spoolman
  cd bespoke-spoolman
  git checkout --detach 488eb7455bead9b2968ff9466ba2f59091a6c23b
  # Prepare development requirements and local configuration first.
  pip install uv
  uv sync
  uv run uvicorn spoolman.main:app --reload
  ```

- Separate trial of the current upstream release (not your changes; sample data and a separate data directory only):

  ```sh
  Follow the install guide at https://github.com/Donkie/Spoolman/wiki/Installation, which provides a docker-compose.yml using ghcr.io/donkie/spoolman.
  ```
- Tools these commands use: Docker for a trial, Python 3.11 and Node 22 for development
- Develop: `uv run uvicorn spoolman.main:app --reload`
- Test: `uv run pytest`
- Stack: python, typescript (FastAPI, SQLAlchemy, React, Ant Design, Refine). Difficulty for a non-developer with an AI: **easy**. A small FastAPI server with a React front end. The data model is a few tables (vendors, filaments, spools), so new fields and reports are simple.
Personal data: **no**. Stored in: A SQLite database in the data folder (a Docker volume). Secrets are entered by the person, never in chat.

---
Later, only when a step needs it: [reference.md](https://handoff.bespokeai.software/p/spoolman/488eb74/r3/reference.md) (customisation points, must-keep-working, data and costs, coding conventions) · [hosting.md](https://handoff.bespokeai.software/p/spoolman/488eb74/r3/hosting.md) (long-term hosting; hosts are paid third parties) · [bespoke.yaml](https://handoff.bespokeai.software/p/spoolman/488eb74/r3/bespoke.yaml) · [SKILL.md](https://handoff.bespokeai.software/p/spoolman/488eb74/r3/SKILL.md)