1 unstable release
0.1.0-alpha.1 | Nov 20, 2023 |
---|
#318 in Games
26KB
397 lines
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) โ
-
Add tap:
brew tap boldandbrad/tap
-
Install formula:
brew install mpl-cli
Install via Scoop ๐ฆ (Windows) โ
-
Add bucket:
scoop bucket add boldandbrad_scoop-bucket https://github.com/boldandbrad/scoop-bucket
-
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 โฌ๏ธ ๐ง
- Download the latest GitHub Release for your platform
- Extract contents and install to a location in your
$PATH
Manual install from source ๐ฉโ๐ป ๐ง
- Install Rust
- Run
git clone https://github.com/boldandbrad/mpl-cli
andcd mpl-cli
- Run
cargo install --path .
- 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 withmpl --help
.
Root ๐ง
mpl add
๐ง - add titles to a stashmpl drop
๐ง - drop titles from a stashmpl titles
๐ง - list titles in stashesmpl move
โ - move titles to another stashmpl 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 stashesmpl stash delete
๐ง - delete existing stashesmpl stash list
๐ง - list existing stashes-v
/--verbose
โ - list stats for stashes
mpl stash rename
โ - rename an existing stashmpl stash info
โ - view details of a stashmpl stash move
โ - move stashes to another profile
BoardGameGeek ๐ง
BoardGameGeek specific actions.
mpl bgg search
๐ง - search boardgamegeek for titles- Flag
--market
โ - search geek market listings
- Flag
mpl bgg info
๐ง - view title detailsmpl 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
- Option
mpl bgg import
โ - import bgg collectionsmpl bgg hotness
โ - view bgg hotness listmpl bgg campaigns
โ - list active crowdfunding campaignsmpl bgg releases
โ - list recent releases
Profiles ๐ง
Manage user profiles.
mpl profile active
๐ง - display current profilempl profile create
โ - create new profilempl profile delete
โ - delete existing profilempl profile list
๐ง - list existing profilesmpl profile rename
โ - rename existing profilempl 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 configurationmpl config options
โ - show available config optionsmpl config set
โ - set option valuempl config unset
โ - revert option value to defaultmpl config complete
๐ง - setup shell tab completions
Ratings โ
Needs more thought and design.
Manage personal title ratings.
mpl rating rate
โ - rate a titlempl rating unrate
โ - unrate a titlempl 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 plaympl play delete
โ - delete an existing plaympl 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. Defaultfalse
default_stash
- the default stash to perform add/drop operations on. Defaultcollection
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.
Dependencies
~8โ23MB
~291K SLoC