Pen Tracker

A simple fountain pen collection tracker.

Installation

pip install .

Data Storage

Data is stored in a SQLite database by default at ~/.local/share/pen-tracker/pen_tracker.db, following the XDG Base Directory specification. The directory is created automatically if it doesn't exist.

You can override the location by setting the PEN_TRACKER_DB environment variable or using --db when running the CLI.

Usage

CLI

Interactive mode:

pen-tracker

Command-line mode:

pen-tracker add --maker "Pilot" --model "Metropolitan" --nib "F"
pen-tracker list
pen-tracker export --output my_pens.json
pen-tracker export --output my_pens.csv --format csv
pen-tracker dashboard
pen-tracker version
pen-tracker --version

Generate Bash completion commands:

pen-tracker completion --shell bash > ~/.local/share/bash-completion/completions/pen-tracker
source ~/.local/share/bash-completion/completions/pen-tracker

Add a new ink:

pen-tracker add-ink --maker "Iroshizuku" --name "Kon-peki" --vendor "Goulet"

List saved inks:

pen-tracker list-inks

View the collection dashboards:

pen-tracker dashboard
pen-tracker unused-dashboard

The standard dashboard shows collection totals, currently inked pens, pen and ink leaderboards by maker and vendor, the five most-used inks including historical ink assignments, and the five longest-inked pens. The least-used dashboard is a separate view that lists the ten pens and ten inks not used the longest. Sampler-sized inks are excluded from ink leaderboards. In interactive mode, choose Dashboard from the main menu, then choose the pen dashboard, ink dashboard, or least-used dashboard.

Display the installed package version with pen-tracker version or pen-tracker --version. Generate Bash completion with pen-tracker completion --shell bash; source or install the generated output in your Bash completion directory.

Add a pen with explicit maker/vendor:

pen-tracker add --maker "Pilot" --model "Custom 92" --vendor "VendorX" --current-ink "Kon-peki"

Features

• Track fountain pens with details like maker, model, nib, ink, and notes
• CLI interface with interactive and command-line modes
• Data stored in SQLite with normalized makers and vendors lookup tables
• Add and list inks via add-ink / list-inks
• View collection statistics with dashboard
• See pen and ink leaderboards by maker and vendor
• See the five most-used inks based on historical pen ink assignments
• See the ten pens and ten inks not used the longest in the dedicated unused-dashboard
• Display version information with version or --version
• Generate Bash completion commands with completion --shell bash
• See the five longest-inked pens; sampler-sized inks are excluded from ink leaderboards
• Export collection to JSON or CSV
• CSV export includes the current ink maker, ink name, and ink date when available
• Empty Notes values stay blank when adding a pen
• Input validation for dates
• Configurable database path via PEN_TRACKER_DB or --db