This is a reimagination and reimplementation of my other project meeple-cli.

mpl

mpl; short for meeple [/mipel/] noun - a board game player token. (E.g., )

mpl is a local board game collection management CLI tool built in rust and powered by BoardGameGeek (BGG) public APIs.

Jump to: Features | Installation | Usage | Configuration | Resources | Legal | Documentation 🔗

[!WARNING]
mpl is currently in ALPHA. This means it is generally unstable and may be missing key features. Please track the progress of features throughout this README with the following symbols:

Symbol	Status
✅	Implemented - stable
✳️	Implemented - unstable
🚧	Work in Progress
❌	Not Started

🎥 Demo

Coming soon.

✨ Features

• Get started quickly with BGG user collection import
• Discover new titles via BGG Hotness, new releases, active crowdfunding campaigns, and BGG search
• Grow your collection by searching and opening Geek Market listings
• Flexible local stash maintainance and customization
• Powerful cross-stash search to find the best title for game night
• Create and manage personal ratings
• Log and view game playthroughs
• Multiple user support with profiles
• Written in Rust 🦀

📦 Installation

Install mpl with your favorite of the methods below, or read the docs for more info. Then run mpl --version to verify installation.

Jump to: Homebrew | Scoop | Cargo | Remote | GitHub Release | Source

Install via Homebrew 🍺 (macOS/Linux) ❌

1. Add tap:

   brew tap boldandbrad/tap
   

2. Install formula:

   brew install mpl-cli
   

Install via Scoop 🍦 (Windows) ❌

1. Add bucket:

   scoop bucket add boldandbrad_scoop-bucket https://github.com/boldandbrad/scoop-bucket
   

2. Install manifest:

   scoop install boldandbrad_scoop-bucket/mpl-cli
   

Install via Cargo 📦 🚧

• Install crate:

  cargo install mpl-cli
  

Install via remote install script 📜 ❌

[!NOTE] The remote install script explains what it will do and prompts before doing so.

• Run script:

  curl -LSfs https://raw.githubusercontent.com/boldandbrad/mpl-cli/main/ci/install.sh | sh -s -- --git boldandbrad/mpl-cli
  

Manual install from GitHub Release ⬇️ 🚧

1. Download the latest GitHub Release for your platform
2. Extract contents and install to a location in your $PATH

Manual install from source 👩‍💻 🚧

1. Install Rust
2. Run git clone https://github.com/boldandbrad/mpl-cli and cd mpl-cli
3. Run cargo install --path .
4. Ensure ~/.cargo/bin is in your $PATH

🚀 Usage

mpl

To get you started, on first run mpl creates a default profile with the same name as your user home directory (you can rename it later if you prefer with mpl profile rename), containing a stash called collection.

Import BGG user collections 🚢

mpl bgg import --user=boldandbrad

mpl will guide you through the import process. When done, see your imported collections:

mpl stash list --verbose

Start fresh 🧼

mpl relies on BoardGameGeek item IDs to manage the titles you add to your stashes. The easiest way to get these is by searching BoardGameGeek:

mpl bgg search "wingspan"

Copy an item ID from the output and use it in another command:

mpl add -s=collection 266192

You've added Wingspan 🦜 to the collection stash!

Now let's see what's in your collection:

mpl titles -s=collection

Run mpl --help or read the docs to discover what to do next!

Command Reference 📖

[!TIP]
You can discover mpl commands and options with mpl --help.

Root 🚧

• mpl add 🚧 - add titles to a stash
• mpl drop 🚧 - drop titles from a stash
• mpl titles 🚧 - list titles in stashes
• mpl move ❌ - move titles to another stash
• mpl update ❌ - update local stash data

Stashes 🚧

Manage local stashes in the active profile.

Flags/Options

• -p/--profile - the profile to perform actions in (default: active profile)

Commands

• mpl stash create 🚧 - create new stashes
• mpl stash delete 🚧 - delete existing stashes
• mpl stash list 🚧 - list existing stashes
  • -v/--verbose ❌ - list stats for stashes
• mpl stash rename ❌ - rename an existing stash
• mpl stash info ❌ - view details of a stash
• mpl stash move ❌ - move stashes to another profile

BoardGameGeek 🚧

BoardGameGeek specific actions.

• mpl bgg search 🚧 - search boardgamegeek for titles
  • Flag --market ❌ - search geek market listings
• mpl bgg info 🚧 - view title details
• mpl bgg open ❌ - open boardgamegeek.com
  • Option --title - open a title's boardgamegeek page(s)
  • Option --campaign - open a title's crowdfunding campaign page
  • Option --listing - open a geek market listing
• mpl bgg import ❌ - import bgg collections
• mpl bgg hotness ❌ - view bgg hotness list
• mpl bgg campaigns ❌ - list active crowdfunding campaigns
• mpl bgg releases ❌ - list recent releases

Profiles 🚧

Manage user profiles.

• mpl profile active 🚧 - display current profile
• mpl profile create ❌ - create new profile
• mpl profile delete ❌ - delete existing profile
• mpl profile list 🚧 - list existing profiles
• mpl profile rename ❌ - rename existing profile
• mpl profile switch ❌ - switch active profile

Config 🚧

Manage configurations.

Profile level configs override global ones by default.

Flags/Options

• -g/--global ❌ - action applies to global options. When not present, the action applies to the active profile options.
• -F/--force ❌ - used in combination with -g, changes default config value for all profiles with overwrite of profile values

Commands

• mpl config active ❌ - display current configuration
• mpl config options ❌ - show available config options
• mpl config set ❌ - set option value
• mpl config unset ❌ - revert option value to default
• mpl config complete 🚧 - setup shell tab completions

Ratings ❌

Needs more thought and design.

Manage personal title ratings.

• mpl rating rate ❌ - rate a title
• mpl rating unrate ❌ - unrate a title
• mpl rating tiers ❌ - list rated titles in tiers

Plays ❌

Needs more thought and design.

Log and manage title plays.

• mpl play log/create ❌ - log a new play
• mpl play delete ❌ - delete an existing play
• mpl play list ❌ - list all logged plays
  • Arg BGG_ID ❌ - list title logged plays
• mpl play stats ❌ - view title play stats

⚙️ Configuration

Environment Variables

mpl respects the following env variables:

• MPL_HOME/XDG_CONFIG_HOME - change where .mpl/ is stored. Default: ~/.mpl/

Config options

These options can be managed with mpl config.

Global configs are stored in .mpl/config.toml. Profile level configs are stored in .mpl/<PROFILE>/config.toml

• update_on_change - automatically pass --update to add/drop operations. Default false
• default_stash - the default stash to perform add/drop operations on. Default collection

Completions

mpl supports tab completions for bash, zsh, and fish. For setup, run mpl config completions <SHELL>.

📚 Resources

• Changelog - See a history of implemented features/changes.
• Roadmap - See a list of planned features and milestones.
• FAQ - Find answers to common questions.
• Contributor Guide ❌ - Find out how to get involved.

⚖️ Legal

[!NOTE]
Neither mpl nor its maintainers are affiliated with BoardGameGeek.

Copyright (c) 2023 Bradley Wojcik. Released under the MIT License. See LICENSE for details.