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

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 🔗

Coming soon.

• 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 🦀 ✅

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

1. Add tap:

   brew tap boldandbrad/tap

2. Install formula:

   brew install mpl-cli

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 crate:

  cargo install mpl-cli

• Run script:

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

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

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

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.

Initiate an import:

mpl bgg import --user=boldandbrad

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

mpl stash list --verbose

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!

• 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

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

Manage local stashes in the active profile.

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

• 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

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

Manage configurations.

Profile level configs override global ones by default.

• -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

• 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

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

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

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/

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 ❌ - ?

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

• 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.

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