CLI Tool

The cgd1 command-line tool provides access to all device operations through subcommands. It uses clap for argument parsing and miette for rich error diagnostics.

Installation

cargo install --path cgd1-rs-cli

Global Options

Options:
  -v, --verbose...  Verbosity level (-v, -vv, -vvv)
      --backend <BACKEND>  BLE backend: `btleplug` (real hardware) or `virtual` (in-memory) [default: btleplug]
  -h, --help         Print help
  -V, --version      Print version

The --backend virtual flag uses an in-memory simulation instead of real BLE hardware. This is useful for testing and demos without a device.

Subcommands

scan

Scan for nearby CGD1 devices.

cgd1 scan --duration 10

Output includes MAC address, temperature, humidity, and battery from passive advertisements.

sync-time

Synchronize the device clock to the current system time. This is the recommended first command after connecting, as it confirms the authentication token is accepted.

cgd1 sync-time AA:BB:CC:DD:EE:FF

alarm-list

Read all 16 alarm slots from the device.

cgd1 alarm-list AA:BB:CC:DD:EE:FF

alarm-set

Set or modify an alarm at a specific slot.

cgd1 alarm-set AA:BB:CC:DD:EE:FF 3 07:30 --repeat 3e --no-snooze

alarm-delete

Delete an alarm at a specific slot.

cgd1 alarm-delete AA:BB:CC:DD:EE:FF 3

settings-read

Read all device settings.

cgd1 settings-read AA:BB:CC:DD:EE:FF

settings-write

Write device settings. Only specified fields are updated; unspecified fields are preserved from the device.

cgd1 settings-write AA:BB:CC:DD:EE:FF \
    --volume 3 \
    --brightness 80 \
    --night-brightness 30 \
    --timezone 60 \
    --time-format 24 \
    --temp-unit C \
    --language en

brightness

Set immediate brightness (preview, not persisted).

cgd1 brightness AA:BB:CC:DD:EE:FF 80

ringtone-preview

Play a preview beep sound on the device.

cgd1 ringtone-preview AA:BB:CC:DD:EE:FF --volume 3

ringtone-upload

Upload a custom ringtone from a PCM file.

cgd1 ringtone-upload AA:BB:CC:DD:EE:FF audio.pcm --signature CustomSlotA

firmware

Read the device firmware version.

cgd1 firmware AA:BB:CC:DD:EE:FF

battery

Read the device battery level.

cgd1 battery AA:BB:CC:DD:EE:FF

monitor

Monitor sensor data (temperature, humidity) in real-time.

cgd1 monitor AA:BB:CC:DD:EE:FF --duration 60

repl

Start an interactive REPL session with a persistent connection. State changes (e.g., settings-write) are visible in subsequent commands (e.g., settings-read).

cgd1 repl --address AA:BB:CC:DD:EE:FF

If --address is omitted, use connect <mac> inside the REPL.

Available REPL commands mirror the CLI subcommands (without the cgd1 prefix):

cgd1> help
Available commands:
  scan, sync-time, alarm-list, alarm-set, alarm-delete,
  settings-read, settings-write, brightness, ringtone-preview,
  ringtone-upload, firmware, battery, monitor, connect, disconnect, exit

Token Management

The CLI automatically manages authentication tokens via FileTokenStore. Tokens are stored per MAC address in the platform’s data directory:

• Linux: ~/.local/share/cgd1-rs/tokens/
• macOS: ~/Library/Application Support/cgd1-rs/tokens/

A new token is generated on first connection and persisted only after sync-time succeeds. Subsequent connections reuse the stored token.

If a token becomes invalid (e.g., the device was paired with a different app), delete the token file and run sync-time again to generate a new one.

Error Handling

The CLI uses miette for rich error diagnostics. Errors include context, source spans, and suggestions:

Error: Authentication failed
  → The device rejected the authentication token.
  help: This may happen if the device was paired with a different app.
        Delete the token file and try again:
        rm ~/.local/share/cgd1-rs/tokens/AA_BB_CC_DD_EE_FF.bin

Verbosity

The -v flag controls log output: