Metalhead 🤘

Metalhead is a Go CLI application for tracking your favorite metal bands and monitoring their releases over time.

The app uses Metal Archives (Encyclopaedia Metallum) as its primary data source, including band discovery via search and retrieval of structured band information such as country of origin, status, lineup, and discography.

Build Instructions

The project ships with a Taskfile so build metadata is injected consistently.

• Binary name variable: APP_NAME
• Version variable: git short hash from git rev-parse --short HEAD
• Linker flags:
  • -s -w strips symbol/debug information
  • -X mh/internal/app.BinaryName={{.APP_NAME}} injects binary name
  • -X mh/internal/app.Version={{.VERSION}} injects version string
• Build flag:
  • -trimpath removes absolute source paths from the compiled binary

Build

task build

Override the binary name:

task build APP_NAME=mh-custom

Other Tasks

task fmt
task test
task lint
task clean

Git Hooks

The project uses a local pre-commit hook in .git/hooks/pre-commit that runs golangci-lint without reusing cache.

Install or refresh the hook:

git config --unset core.hooksPath
chmod +x .git/hooks/pre-commit

Usage

Build the binary first:

task build

Run commands with:

./bin/mh <command>

Typical Flow

1. Add one or more favorite bands.
2. List saved favorites.
3. Check latest releases for all favorites.
4. Inspect detailed info for one favorite.
5. Remove a favorite when no longer needed.

Commands

Add a band

./bin/mh add nightwish
./bin/mh add "caladan brood"

Notes:

• If multiple homonymous bands exist, the app shows a numbered list and asks you to choose.
• If the band is already in favorites, the app reports it instead of duplicating it.

List favorites

./bin/mh list

Shows an aligned table with band name and band ID.

Check latest release for each favorite

./bin/mh check

Shows an aligned table with:

• band
• album name
• year
• release type

Show detailed band info

./bin/mh info

The command is interactive:

• shows saved favorites
• asks you to choose one band
• prints country, status, current lineup, and full discography

Remove a favorite

./bin/mh remove

The command is interactive and safer than name-based deletion:

• shows saved favorites
• asks you to choose one band to remove
• supports cancellation with option 0

Help and version

./bin/mh help
./bin/mh help check
./bin/mh version

Completion scripts

./bin/mh completion bash
./bin/mh completion zsh
./bin/mh completion fish
./bin/mh completion powershell

Data and Configuration

• Default favorites file: ~/.config/metalhead/preferences.json
• Optional config file: ~/.config/metalhead/config.yaml
• Environment variables: prefix MH_ (loaded through Viper)