Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/boldandbrad/mpl-cli

🎲 Manage local board game stashes and interact with BoardGameGeek from your terminal.
https://github.com/boldandbrad/mpl-cli
board-game boardgamegeek cli collections meeple rust
Last synced: 7 days ago
JSON representation
🎲 Manage local board game stashes and interact with BoardGameGeek from your terminal.
Host: GitHub
URL: https://github.com/boldandbrad/mpl-cli
Owner: boldandbrad
License: mit
Created: 2023-08-22T22:40:33.000Z (over 1 year ago)
Default Branch: main
Last Pushed: 2024-02-04T21:57:27.000Z (almost 1 year ago)
Last Synced: 2025-01-20T10:16:06.106Z (15 days ago)
Topics: board-game, boardgamegeek, cli, collections, meeple, rust
Language: Rust
Homepage:
Size: 124 KB
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 1
Metadata Files:
- Readme: README.md
- Contributing: docs/CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project

README

        *This is a reimagination and reimplementation of my other project

[meeple-cli](https://github.com/boldandbrad/meeple-cli).*

---

# mpl

[![Crates.io](https://img.shields.io/crates/v/mpl-cli)](https://crates.io/crates/mpl-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](https://boardgamegeek.com) (BGG) public APIs.

**Jump to:**

[Features](#features) |

[Installation](#install) |

[Getting Started](#getting-started) |

[Command Reference](#cmd-ref) |

[Configuration](#config) |

[Resources](#resources) |

[Legal](#legal) |

[Documentation](https://boldandbrad.github.io/mpl/) 🔗

> [!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](https://boldandbrad.github.io/mpl/) for more info. Then run

`mpl --version` to verify installation.

**Jump to:** [Homebrew](#install-homebrew) | [Scoop](#install-scoop) |

[Cargo](#install-cargo) | [Remote](#install-remote) |

[GitHub Release](#install-release) | [Source](#install-source)

### Install via [Homebrew](https://brew.sh) 🍺 (macOS/Linux) ❌ 

1. Add tap:

    ```sh

    brew tap boldandbrad/tap

    ```

1. Install formula:

    ```sh

    brew install mpl-cli

    ```

### Install via [Scoop](https://scoop.sh) 🍦 (Windows) ❌ 

1. Add bucket:

    ```sh

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

    ```

1. Install manifest:

    ```sh

    scoop install boldandbrad_scoop-bucket/mpl-cli

    ```

### Install via [Cargo](https://crates.io) 📦 ✅ 

> [!NOTE]

> In order to install pre-releases (alpha/beta/pre) you must run `cargo install`

> with `--version=`.

- Install crate:

  ```sh

  cargo install mpl-cli

  ```

### Install via remote install script 📜 ❌ 

> [!NOTE]

> The [remote install script](scripts/install.sh) explains what it will do and

> prompts before doing so.

- Run script:

  ```sh

  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](https://github.com/boldandbrad/mpl-cli/releases)

   for your platform

2. Extract contents and install to a location in your `$PATH`

### Manual install from source 👩‍💻 ✅ 

1. Install [Rust](https://www.rust-lang.org/tools/install)

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:

```sh

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.

```sh

mpl bgg import --user=boldandbrad

```

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

stash(es):

```sh

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:

```sh

mpl bgg search "wingspan"

```

Copy a title ID from the output and use it in another command:

```sh

mpl add -s=collection 266192

```

You've added Wingspan 🦜 to the `collection` stash!

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

```sh

mpl list -s=collection

```

Run `mpl --help` or read the [docs](https://boldandbrad.github.io/mpl/) 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//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 `.

## 📚 Resources 

- [Changelog](docs/CHANGELOG.md) - See a history of implemented

  features/changes.

- [Roadmap](https://github.com/boldandbrad/mpl-cli/milestones) - See a list of

  planned features and milestones.

- [FAQ](docs/faq.md) - Find answers to common questions.

- [Contributor Guide](docs/CONTRIBUTING.md) ❌ - Find out how to get involved.

## ⚖️ Legal 

> [!NOTE]


> Neither **mpl** nor its maintainers are affiliated with

> [BoardGameGeek](https://boardgamegeek.com).

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

[LICENSE](LICENSE) for details.