MoniCard CLI

CLI for discovering and controlling a MoniCard over BLE.

Setup

From a fresh clone, create a virtual environment and install the CLI in editable mode:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

Then run the console script:

monicard --help

Discover the card identifiers

Scan for the card and save the identifiers:

monicard discover --timeout 10 --out monicard-discover.json

Use target[0].address from the JSON as --address for later commands. On macOS this is usually a CoreBluetooth UUID, not a public Bluetooth MAC.

Show protocol identifiers, known UUIDs, supported commands, and current limits:

monicard info

Most commands can also find the default card by name (MoniCard-0103) if --address is omitted.

Common commands

Read and update this device's business card:

monicard card read --address "$ADDR"
monicard card write --address "$ADDR" --text $'Name\nemail@example.com' --yes

Manage received cards:

monicard card count --address "$ADDR"
monicard card list --address "$ADDR"
monicard card delete 1 --address "$ADDR" --yes

Read and update settings:

monicard settings read --address "$ADDR"
monicard settings write --address "$ADDR" --buzzer off --vibration on --yes

Read or set the media carousel interval; 0 disables it:

monicard carousel read --address "$ADDR"
monicard carousel write 10 --address "$ADDR" --yes

Upload images, GIFs, videos, or files. Display media should be prepared as 240x320; the CLI warns for detected PNG/JPEG/GIF dimensions that do not match.

monicard files upload image.png --address "$ADDR" --yes
monicard files upload animation.gif --address "$ADDR" --remote-name animation.gif --yes
monicard files upload image.png --address "$ADDR" --strict-media-size --yes

Diagnostics and low-level tools

monicard ble gatt-dump --address "$ADDR"
monicard ble monitor --address "$ADDR" --seconds 10
monicard serial decode "1f 00 04 00 70 69 6e 67"
monicard uuid decode 00000000-0000-0070-7061-5f696c666973

Raw writes and serial probes are available but intentionally require --yes.

Safety and limits

• Every mutating command requires --yes.
• Add --out result.json to save any JSON response.
• Media/file upload and transfer abort are supported. PNG/JPEG/GIF uploads are checked against 240x320 by default; use --strict-media-size to refuse mismatches or --no-media-check to bypass the check.
• Generic media/file listing and deletion are not known in the discovered BLE protocol.
• Received business-card records can be deleted with monicard card delete; uploaded media/files cannot currently be deleted by a known safe command.