meeple-cli 1.2.0

Local board game collection manager. Powered by BoardGameGeek.

meeple-cli

Local board game collection manager. Powered by BoardGameGeek.

Disclaimer: Neither meeple-cli nor its maintainers are affiliated with BoardGameGeek.

Install

Via Homebrew (Recommended on macOS/Linux)

brew tap boldandbrad/tap
brew install meeple-cli

Via pipx (Recommended on Windows):

pipx install meeple-cli

Via pip:

pip install meeple-cli

Usage

$ meeple --help
Usage: meeple [OPTIONS] COMMAND [ARGS]...

  Local board game collection manager. Powered by BoardGameGeek.

Options:
  -h, --help     Show this message and exit.
  -v, --version  Show the version and exit.

Collection Commands:
  add          Add items to a collection.
  collections  List all collections.
  delete       Delete collections.
  drop         Drop items from a collection.
  find         Search collections for items.
  list         List contents of a collection.
  move         Move an item from one collection to another.
  new          Create new collections.
  rename       Rename a collection.
  stats        View collection statistics.
  update       Update collection data.

BoardGameGeek Commands:
  hot     List current BoardGameGeek trending items.
  import  Import BoardGameGeek user collections.
  info    View item details.
  open    Open an item on BoardGameGeek.
  search  Search BoardGameGeek for items.

Other Commands:
  completions  Setup meeple shell completions.

Completions

meeple-cli supports shell completions for bash, zsh, and fish. For setup, use meeple completions <SHELL>, or the following instructions:

bash

Add the following to ~/.bashrc:

eval "$(_MEEPLE_COMPLETE=bash_source meeple)"

zsh

Add the following to ~/.zshrc:

eval "$(_MEEPLE_COMPLETE=zsh_source meeple)"

fish

Save the script to ~/.config/fish/completions/meeple.fish:

_MEEPLE_COMPLETE=fish_source meeple > ~/.config/fish/completions/meeple.fish

Changelog

See a history of implemented features/changes in the Changelog.

Roadmap

See a list of planned features and milestones here.

FAQ

Why local only collections?

Currently, the BoardGameGeek Public API provides limited read-only data about user Collections and GeekLists.

While it is technically feasible to interface with Collections and GeekLists via webscrapers or spiders, these approaches would be complex and also violate BoardGameGeek Terms of Service.

For now, it is possible to import BGG user collections into meeple-cli via meeple import.

Why does collection import take so long?

Currently, the BoardGameGeek Public API relies on queued jobs to create a snapshot of a user's collection on demand. Depending on the length of the queue or size of your BGG collection, the job may take several minutes or longer to complete. You can read more about this issue in this thread.

If your request times out, or exceeds the BGG API rate limit, please be patient and try again later.

Why do some items show a weight of NA when boardgamegeek.com has a value?

This is a known and occasionally recurring bug in the BoardGameGeek database. It usually resolves itself within a day. For more info or additional support, read this thread.

Luckily for us, game weights do not often change drastically. In most cases, we can assume that the weight from yesterday is close enough. In the future, meeple-cli will attempt to compensate for this issue automatically by displaying the last known value by default, if there is one.

Where does meeple-cli store data?

meeple-cli stores collection data in ~/.meeple and only makes network connections to retrieve data from the BoardGameGeek API.

License

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