#board-game #collection #mpl #management #local

app mpl-cli

Manage local board game stashes and interact with BoardGameGeek from your terminal

1 unstable release

0.1.0-alpha.1 Nov 20, 2023

#241 in Games

MIT license

26KB
397 lines

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


mpl

Crates.io

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

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.

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

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

Dependencies

~7โ€“19MB
~287K SLoC