This project has the primary purpose of giving me a CLI tool to create incident reports and store working configurations for my homelab. As my projects have grown larger, I have had a greater need to refer back to old fixes or working configs. Often, when faced with a new install or issue, I have either not recorded my past fixes or configs at all or the code or settings I need are stored in a random folder on my server or, worse yet, on some note I scrawled on an old envelope and shoved into a pile on my desk.
I have been reading The Phoenix Project by Gene Kim, George Spafford, and Kevin Behr and the principle that stood out most to me was logging my knowledge. I shouldn't need to fight through the same problem more than once just because I don't remember how I had fixed it in the past. Since I was refreshing myself on Python, learning Neovim, and looking for a project this baby was born.
The program operates entirely in the CLI. Since I am usually working in the CLI anyway, I thought this would make the process easier to access and therefore more likely that I would use it. I have created an alias so I can call the program quickly, again because the more accessible it is the more likely I am to keep up with it.
Currently, the program allows users to create two kinds of files. All the functions are available from the main menu. To write a config or incident report, the program walks the user through a series of questions, formats the data, allows the user to approve, then both writes the entry as a .txt file and lists the entry in the json database. Below is an example of the list of questions for recording an incident response.
- Title: Enter a title for this incident report
- Host: Which machine(s) did the incident impact?
- OS/Distro: What operating system(s) did the incident occur on?
- Tags: Enter tags for future searching, separated with a space
- Symptoms: What symptoms alerted you to the incident?
- Root Cause: What did the symptoms indicate was the root cause of the incident?
- Steps Taken: Write out the exact steps you have taken while addressing the incident
- Status: Do you consider this incident resolved, worked around, or still open?
- References: What references did you use to address the issue?
Doom Eternal VRAM Exhaustion on Second Monitor
2026-04-29 14:32:01
Status: Resolved
Host: garuda-desktop
OS or Distro: Garuda Linux (KDE Plasma/Wayland)
Symptoms: Game crashes immediately on launch with VRAM exhaustion error
Root Cause: Second monitor keeping VRAM allocated, leaving insufficient memory for game
Steps Taken: Disabled second monitor before launching, confirmed VRAM available, launched game successfully
References: https://github.com/doitsujin/dxvk/issues/1234
There are two options for reading the files. From the main menu, you can choose to search by tag or to view a full list of all the entries. If you choose to search by tag, it will ask for tag(s) and return all filenames with any of the searched tags. If you choose to view all the files, it just returns all the filenames. The program then moves to another function that lists all the filenames in a numbered list. You can choose a file, which it will print for you to read.
Besides logging errors and configurations, I decided that I need to be able to track devices on my local network. Some devices don't display much information on my router and I wanted a way to store information that I figured out about them as I map my network topology. The information added about devices is stored in an SQLite database.
The main menu allows users to create an entry for a new device, walking them through a series of prompts much like the journal entries above.
- Hostname: The device's hostname
- MAC: MAC address
- Vendor: Hardware vendor
- IP: Static IP or "dynamic"
- VLAN: Associated VLAN
- OS: Operating system
- Location: Physical location or "mobile"
- Notes: Anything useful
- Confidence: How confident you are in the identification, 0-10
The device explorer lists simplified entries for 5 devices at a time and uses pagination to move through the rest. Users can examine a specific device and see all of its information. Each field for the device can also be edited from the examine view. The database is one SQLite file in the project directory that syncs to Gitea with my other files.
The program now asks for the user to login to a self-hosted Gitea instance at start. If a connection is made the program automatically pulls and can then push after every write. If Gitea is unreachable, the program will attempt to connect to Tailscale before trying again. If that fails, it logs the errors and displays that it is not connected on the main screen.
-
SQL Migration for Journal Entries - This will probably be my next step. I appreciate the flexibility and power of SQLite and would like to move the reports and configs from being stored in a JSON file to a table in the SQLite database.
-
Connect Incidents and Configs with Devices - I would like to be able to connect the devices from the device list to the incidents so the information is connected and searchable. I don't know how I will do that yet, but I have been considering it.
-
Search Other Files? - I had the idea before to let the program view other files in a config folder inside the main project folder. I am seeing less need for this as I continue working, so I've commented out the config file path. I'm keeping it in to remind myself that it was an idea until I decide to try it or bin it.