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 | Getting Started | Command Reference | 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 📦 ✅

Note

In order to install pre-releases (alpha/beta/pre) you must run cargo install with --version=<VERSION>.

• 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 or $CARGO_HOME/bin is in your $PATH

🚀 Getting Started

Using mpl is as easy as:

mpl

To get you started, on first run mpl creates a default profile with the same name as your user $HOME directory containing a stash called collection.

Tip

If you prefer, you can rename these later with mpl profile rename and mpl stash rename respectively.

Import BGG user collections 🚢

Initiate an import:

Tip

Try it with --dry-run to simulate the import without actually making changes.

mpl bgg import --user=boldandbrad

mpl will guide you through the import process. When done, see your imported stash(es):

mpl stash list --verbose

Start fresh 🧼

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

mpl bgg search "wingspan"

Copy a title 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 stash:

mpl list -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
  • -s/--stash [Opt] ❌ - stash to add titles to
  • -v/--verbose [Flg] ❌ - include additional output
• mpl drop ✳️ - drop titles from a stash
  • -s/--stash [Opt] ❌ - stash to drop titles from
  • -f/--force [Flg] ❌ - drop titles without confirmation
  • -v/--verbose [Flg] ❌ - include additional output
• mpl list 🚧 - list stashed titles
  • --sort [Opt] ❌ - sort titles by provided value. values: [rank, rating, weight, year, name, id, time]. default: rating
  • -g/--games-only [Flg] ❌ - list only games
  • -e/--expansions-only [Flg] ❌ - list only expansions
  • --group [Opt] ❌ - group expansions below their parent game. default: true
  • --players [Opt] ❌ - list only games that support the given player count
  • --max-time [Opt] ❌ - list only games that fit the given play time (Min.)
  • --weight [Opt] ❌ - list only games that match the given weight class. options: [1,2,3,4]. ex: 2 -> 2.00-2.99
  • -v/--verbose [Flg] ❌ - include additional columns in output
• mpl move ❌ - move titles to another stash
  • -s/--from-stash [Opt] ❌ - source stash
  • -d/--to-stash [Opt] ❌ - destination stash
  • -v/--verbose [Flg] ❌ - include additional output

Profiles 🚧

Manage user profiles.

• mpl profile list ✳️ - list all existing profiles
  • -v/--verbose [Flg] ❌ - include additional columns in output
• mpl profile active ✅ - show the current active profile
  • -v/--verbose [Flg] ❌ - include additional columns in output
• mpl profile switch ✳️ - switch the active profile
• mpl profile create ✳️ - create a new profile
  • --active [Flg] ✳️ - make the new profile the active profile
• mpl profile delete ✳️ - delete an existing profile
  • -f/--force [Flg] ❌ - delete profile without confirmation
• mpl profile rename ❌ - rename an existing profile

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
  • -f/--force [Flg] ❌ - delete stash without confirmation
• mpl stash list ✳️ - list existing stashes
  • -v/--verbose [Flg] ❌ - 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 🚧

Perform BoardGameGeek related actions.

• mpl bgg search ✳️ - search boardgamegeek for titles
  • --market [Flg] ❌ - search geek market listings
  • -v/--verbose [Flg] ❌ - include additional columns in output
• mpl bgg info ✳️ - view title details
• mpl bgg open ❌ - open links in the web browser
  • --page [Opt] - open a title's boardgamegeek page(s)
  • --campaign [Opt] - open a title's crowdfunding campaign page
  • --listing [Opt] - open a geek market listing
• mpl bgg import ❌ - import bgg user collections
  • -u/--user [Opt] ❌ - bgg user to import collections from
  • --dry-run [Flg] ❌ - simulate import without persisting changes
• mpl bgg hotness ✳️ - view bgg hotness list
  • -v/--verbose [Flg] ❌ - include additional columns in output
• mpl bgg campaigns ❌ - list active crowdfunding campaigns
• mpl bgg releases ❌ - list recent title releases
  • -v/--verbose [Flg] ❌ - include additional columns in output

Config 🚧

Manage configurations.

Profile level configs override global ones by default.

Flags/Options

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

Commands

• mpl config list ❌ - list all config options and their current values
  • --name-only ❌ - output only config option names
• mpl config get ❌ - get the current value of the given config option
  • --default ❌ - get the default value of the given config option
  • --all-values ❌ - get all valid values of the given config option
• mpl config set ❌ - set the value of the given config option
• mpl config unset ❌ - revert the value of the given option to its default
  • -a/--all ❌ - revert all option values to their default
• mpl config complete 🚧 - setup tab-completions for the given shell

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 to modify default behavior. In cases where multiple variables control the same behavior, mpl obeys the left-most present variable.

• MPL_CONFIG_HOME/XDG_CONFIG_HOME ❌ - change where mpl configs are stored. Default: ~/.config/mpl/
• MPL_STATE_HOME/XDG_STATE_HOME ❌ - change where mpl state is stored. Default: ~/.local/state/mpl/

Config options

Needs more thought and design.

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

• quiet_success ❌ - force --quiet on all supported commands on success [Default false]
• pretty_format ❌ - format outputs with table borders and emojis [Default true]
• default_stash_name ❌ - the default name to use when creating new stashes [Default collection]
• abbreviated_format ❌ - ?

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.