Aveine CLI

Local command-line control and wine-setting recommendations for the Aveine smart wine aerator.

aveine-cli lets you:

• scan for an Aveine AER over Bluetooth LE;
• read and change the equivalent-aeration hour setting;
• ask a local codex exec session for a wine-specific recommendation;
• inspect BLE services safely before experimenting with lower-level writes.

The project is intentionally conservative: it only has a first-class shortcut for the hour setting we observed on an Aveine AER device, and raw BLE writes require explicit confirmation.

Status

Tested locally on macOS with:

• Aveine AER device advertising as AVEINE-AER-*;
• firmware 1.14.2;
• Python 3.14.3;
• Bleak 3.0.2;
• Codex CLI 0.132.0.

The known hour setting is a single-byte value from 1..24 on characteristic:

cccdbeef-f631-4720-822b-9b304df77dd6

On the tested device, writes must use BLE write-with-response to persist.

Install

git clone https://github.com/fabianbaier/aveine-cli.git
cd aveine-cli
make setup

This creates .venv, installs dependencies, and installs the CLI in editable mode.

Check your setup:

make doctor
make test

Run commands through Make:

make scan
make recommend WINE="2021 Barolo Nebbiolo high tannin" ARGS="--ai codex"

Or activate the virtualenv:

source .venv/bin/activate
aveine --help

Discover Your Aerator

Turn on the Aveine and keep it near your Mac:

make scan

Example output:

AVEINE-AER-123456789  6FE55F79-12A2-21C2-243C-3475474AC771  RSSI=-70

Use the address in later commands:

export AVEINE_ADDRESS="6FE55F79-12A2-21C2-243C-3475474AC771"

Inspect BLE services:

aveine inspect --address "$AVEINE_ADDRESS" --read

Read Or Change Aeration Hours

Read the current setting:

aveine hours --address "$AVEINE_ADDRESS"

Set the equivalent aeration to 4h:

aveine set-hours --address "$AVEINE_ADDRESS" 4 --confirm-write --with-response

With Make:

make hours ADDRESS="$AVEINE_ADDRESS"
make set-hours ADDRESS="$AVEINE_ADDRESS" HOURS=4 ARGS="--confirm-write --with-response"

Without --confirm-write, set-hours is a dry run and only prints the payload.

Recommend A Setting

Local heuristic:

aveine recommend "2020 Rioja Reserva, Tempranillo, medium body, oak"

Codex-backed recommendation:

aveine recommend "Beckmen Vineyards 2017 Grenache Ballard Canyon" --ai codex

JSON output:

aveine recommend "2018 left bank Bordeaux, Cabernet blend" --json

Recommend and write in one step:

aveine serve \
  "Beckmen Vineyards 2017 Grenache Ballard Canyon" \
  --ai codex \
  --address "$AVEINE_ADDRESS" \
  --with-response \
  --confirm-write

Raw BLE Tools

These are useful when validating another firmware version or another Aveine model.

Scan all BLE devices:

aveine scan --all

Find readable value changes after manually changing the setting on the device:

aveine diff --address "$AVEINE_ADDRESS"

Monitor notifications while interacting with the device:

aveine monitor --address "$AVEINE_ADDRESS" --seconds 30

Raw write to a known characteristic:

aveine write \
  --address "$AVEINE_ADDRESS" \
  --char cccdbeef-f631-4720-822b-9b304df77dd6 \
  --hours 4 \
  --encoding uint8_hours \
  --with-response \
  --confirm-write

Supported encodings:

• uint8_hours: one byte, 1..24;
• uint8_zero_based: one byte, 0..23;
• utf8_hours: ASCII integer, e.g. 8;
• json_hours: JSON payload, e.g. {"hours":8};
• hex_template: custom hex template such as aa {hh:02x} 00.

Safety

This project does not modify firmware and does not require opening the device. Still:

• only control devices you own;
• do not use unknown BLE writes on bottles you care about;
• do not block air inlets/outlets;
• do not immerse the device;
• do not run anything except wine or water through food-contact paths;
• taste mature or fragile bottles before increasing aeration.

Documentation

• BLE protocol notes
• Development guide
• Troubleshooting

License

MIT. See LICENSE.