iTag CLI

A small, extensible command-line toolkit for interacting with iTag-style BLE trackers. Includes a plugin-based action system, vendor profile support, and a clean CLI for scanning, alerting, reading battery levels, and listening for button presses.

Features

• BLE device discovery (itag_cli.discovery.find_device)
• Plugin-based actions (alert, stop-alert, battery, listen-button, etc.)
• Vendor profile system with capability validation
• Async BLE operations powered by bleak
• Unit-tested with pytest and pytest-asyncio, run in CI on every push with no hardware attached
• Installed as a real CLI command: itag-cli
• Extensible: add your own actions or vendor profiles without modifying the core

Installation & Setup

1. Create and activate a virtual environment:

   python3 -m venv venv
   source venv/bin/activate

2. Install dependencies:

   pip install -r requirements.txt

3. Install the project in editable mode (enables the itag-cli command):

   pip install -e .

Dependencies include:

• bleak
• pytest
• pytest-asyncio

Running Tests

All tests live in the tests/ directory.

Run the full suite:

pytest -q

Async tests require the plugin to be loaded. This is handled automatically via pytest.ini:

[pytest]
pythonpath = itag_cli
addopts = -p pytest_asyncio

Device Discovery

The CLI can automatically find an iTag-like device using:

from itag_cli.discovery import find_device

Discovery logic matches devices whose names contain "itag" or "tag" (case-insensitive).

You can also explicitly scan for a device from the CLI:

itag-cli --discover

Using the CLI

After installation, the CLI is available as the itag-cli command.

View help:

itag-cli --help

Examples

Alert the device:

itag-cli alert --mac AA:BB:CC:DD:EE:FF

Stop alerting:

itag-cli stop-alert --mac AA:BB:CC:DD:EE:FF

Read battery level:

itag-cli battery --mac AA:BB:CC:DD:EE:FF

Listen for button presses:

itag-cli listen-button --mac AA:BB:CC:DD:EE:FF

Auto-discover device (no --mac needed):

itag-cli alert

Explicit discovery:

itag-cli --discover

Vendor Profiles

Vendor profiles define the BLE characteristics required by actions.

Example default profile (itag_cli/gatt_uuids/itag.py):

class iTag:
    ALERT_CHAR = "00002a06-0000-1000-8000-00805f9b34fb"
    BUTTON_CHAR = "0000ffe1-0000-1000-8000-00805f9b34fb"
    BATTERY_CHAR = "00002a19-0000-1000-8000-00805f9b34fb"

Using a custom vendor file:

itag-cli alert --vendor-file my_vendor.py --profile MyVendor

Adding New Actions

Actions live in itag_cli/actions/ and follow a simple pattern:

• declare required vendor capabilities
• implement an async run() method
• register via load_actions()

This makes the system easy to extend without modifying the core.

Development Notes

• All imports inside the package use absolute imports:

  from itag_cli.actions import load_actions
  from itag_cli.discovery import find_device
  from itag_cli.gatt_uuids import itag as builtin_itag

• Tests rely on pytest.ini to treat itag_cli/ as the import root.

• The CLI entry point is defined in pyproject.toml:

  [project.scripts]
  itag-cli = "itag_cli.cli:main"