{"id":"8be6ad61-d5f1-42cb-ad9b-9d12ed065e9b","slug":"remote-ble-tools","kind":"skill","name":"remote-ble-tools","summary":"Tools to work with RemoteBLE: CLI and agentic AI","owner":"Yahia-Mohammad","repoUrl":"https://github.com/Yahia-Mohammad/remote-ble-tools","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":8,"match":null,"fewStars":false,"format":"skill","createdAt":"2026-08-10T19:49:58.000Z","addedAt":"2026-10-22T01:38:05.517Z","logoUrl":"https://avatars.githubusercontent.com/u/4076677?u=c172b4fdcbce8bd9555336cd5b62c8eb10c76c2a&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["writing"],"tags":[],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T16:14:11.199Z","sample":false,"url":"https://conduits.dev/tools/remote-ble-tools","language":"Kotlin","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# RemoteBLE Tools\n\nA command-line client and companion Agent Skill for\n[RemoteBLE](https://github.com/Yahia-Mohammad/remote-ble).\n\nPrimary executable: `remoteble` (optional short alias `rble`).\n\n> Control and debug BLE devices anywhere using commands, pipes, and AI coding agents.\n\n## Demo\n\nTerminal recording of a RemoteBLE read-only treadmill check:\n\nhttps://github.com/user-attachments/assets/f7126056-8b77-4926-bb57-1b28b7b92982\n\nThe recording shows agent preflight, device discovery, GATT inspection, Battery Level and Heart\nRate reads, a short Treadmill Data observation, and lease release—without sending a device write.\n\n## What this is\n\nA CLI that turns the RemoteBLE SDK into a general-purpose developer tool, exposing the remote BLE\ncontrol plane independently of Kable application code, in any environment able to run a command.\n\n```text\nHuman / script / CI / coding agent\n              │ commands\n        remoteble CLI          parsing · output · advisory policy\n              │\n      slim protocol client\n              │ WebSocket + CBOR\n       RemoteBLE agent         auth · leases · reconciliation · radio\n              │\n          BLE device\n```\n\nThe defining property is that the command may run anywhere while the radio runs beside the\nphysical device:\n\n```text\nLocal BLE CLI:      command → local adapter → device\nRemoteBLE CLI:      command → network → chosen RemoteBLE agent → device\n```\n\nThat enables remote labs, phones as radio nodes, CI access from radio-less runners, shared-device\nleasing, and simulation.\n\nA companion Agent Skill adds procedural knowledge for coding agents without making AI part of the\ncore product. The CLI is independently useful, testable, and scriptable.\n\n## Build and run\n\nBuild a self-contained native executable on Apple Silicon:\n\n```sh\n./gradlew :cli:macosArm64ReleaseArtifacts\ncli/build/native-release-stage/macosArm64/dist/bin/remoteble --help\n```\n\nThat stages the same layout a release archive ships, so the binary is named `remoteble` rather\nthan carrying Kotlin/Native's `.kexe` linker suffix. `:cli:linkRemotebleReleaseExecutableMacosArm64`\nlinks the executable alone, under `cli/build/bin/`, if that is all you need.\n\nThe same Kotlin Multiplatform source also links Linux x64 and ARM64 executables with\n`:cli:linkRemotebleReleaseExecutableLinuxX64` and\n`:cli:linkRemotebleReleaseExecutableLinuxArm64`. `:cli:fatJar` provides a JVM compatibility\nartifact; the native executable is the primary distribution and requires no installed JRE.\n\nRelease archives include a manual page in `dist/man/remoteble.1` and Bash, Fish, and Zsh completion\nassets in `dist/completions/`.\n\nEvery archive also includes the human-readable Agent Skill at `dist/skills/remoteble`. Install the\nembedded copy without MCP or credentials with `remoteble skills install`; use\n`remoteble skills doctor` to verify installed copies.\n\nThe distribution also includes `rble`, a short launcher alias. Use [examples/config.yaml](examples/config.yaml)\nas a starting configuration and set the agent token in its configured environment variable.\nConfiguration precedence is command-line options, selected profile, configuration file, then built-in defaults.\n\n## Install a release\n\nStable releases publish native packages for Linux and a macOS Apple Silicon Homebrew formula. Replace\n`X.Y.Z` with the release version when downloading a package directly from the GitHub Release.\n\n```sh\nbrew install Yahia-Mohammad/tap/remoteble\nsudo apt install ./remoteble_X.Y.Z_amd64.deb\nsudo dnf install ./remoteble-X.Y.Z-1.x86_64.rpm\n```\n\nEach GitHub Release includes ZIP distributions, the standalone Agent Skill, Linux packages, per-file\nchecksums in `checksums.txt`, and SBOMs within the distributions. Verify the checksum file before\ninstalling a downloaded artifact. Every archive and package also carries a build provenance\nattestation, so a download can be checked against the workflow that produced it:\n\n```sh\ngh attestation verify remoteble-macos-arm64-X.Y.Z.zip --repo Yahia-Mohammad/remote-ble-tools\n```\n\n### Install an agent\n\nThe CLI drives a [RemoteBLE agent](https://github.com/Yahia-Mohammad/remote-ble); it does nothing\non its own. The agent usually runs beside the device rather than beside the CLI, but on macOS the\nsame tap installs one locally:\n\n```sh\nbrew trust --cask Yahia-Mohammad/tap/remoteble-agent\nbrew install --cask remoteble-agent\nopen -a RemoteBleAgentRs --args --port 8080\n```\n\nIt installs as a cask, not a formula, because macOS grants Bluetooth to an application bundle and\nhonors the grant only for an app LaunchServices started — `open` is what satisfies that, and the\nfirst launch prompts once for Bluetooth access. Homebrew also refuses casks from a third-party tap\nuntil it is trusted, which is what the `brew trust` line is for; formulae need no such step. The\nbuild is ad-hoc signed, so the prompt returns after an upgrade.\n\nAn agent reached over the network serves `wss://` behind its own self-signed identity (RemoteBLE\n0.14+). Pin it with `agent.fingerprint` or `--fingerprint`, using the `fp=` value the agent prints\nwith `--print-pairing`; see [Encrypted agents](docs/cli-reference.md#encrypted-agents).\n\n## Release automation\n\nPushing a stable `vX.Y.Z` tag builds and publishes the GitHub Release, the Linux packages, signed\nbuild provenance/SBOM attestations, and the Homebrew formula. A valid prerelease tag such as\n`vX.Y.Z-rc.1` publishes only the existing ZIP assets as a GitHub prerelease.\n\nThe formula is published to [`Yahia-Mohammad/homebrew-tap`](https://github.com/Yahia-Mohammad/homebrew-tap),\nusing the `HOMEBREW_TAP_REPOSITORY` repository variable and a `HOMEBREW_TAP_TOKEN` secret held in the\n`release` environment. The workflow validates packages and the formula on pull requests and `main`,\nbut does not publish from those events. Deferred packaging work is recorded in\n[`docs/distribution-roadmap.md`](docs/distribution-roadmap.md).\n\nStructured output uses the versioned [result envelope schema](schemas/result-envelope-v1.json) and the\n[persistent session schemas](schemas/session-input-v1.json). Use `remoteble session --jsonl` for coding\nagents; use `remoteble shell` for a human REPL. The shell supports foreground/background streams and\nprocess-level pipes, but is not an OS shell and does not execute child processes. Human-readable data\ngoes to stdout; diagnostics go to stderr.\n\n## Documents\n\n| Document | What it covers |\n|---|---|\n| [`docs/state-model.md`](docs/state-model.md) | **Read first.** How connections and leases survive between CLI invocations |\n| [`docs/cli-reference.md`](docs/cli-reference.md) | Command surface, output contract, exit codes, configuration |\n| [`docs/safety-model.md`](docs/safety-model.md) | Write policy, where enforcement actually lives, untrusted device data, audit |\n| [`CONTRIBUTING.md`](CONTRIBUTING.md) / [`SECURITY.md`](SECURITY.md) | Contribution checks and vulnerability reporting policy |\n| [`docs/slim-client.md`](docs/slim-client.md) | Embedded protocol/WebSocket/CBOR client boundary and update rules |\n| [`docs/session-protocol.md`](docs/session-protocol.md) | Persistent machine session and human shell protocol |\n| [`docs/logging-audit.md`](docs/logging-audit.md) | Redacted audit/debug logging, retention, and failure policy |\n| [`docs/releasing.md`](docs/releasing.md) | How to cut a release: version files that must agree, tag patterns, and what to check afterwards |\n| [`docs/distribution-roadmap.md`](docs/distribution-roadmap.md) | Deferred packaging work: cask automation, apt/yum hosting, Developer ID signing |\n\n## Repository layout\n\n```text\nremoteble-tools/\n├── core/        high-level, interface-independent operations\n├── cli/         commands, formatting, configuration\n├── skills/      portable Agent Skills\n├── schemas/     versioned output and recipe schemas\n├── examples/    configuration examples\n├── docs/\n└── integration-tests/\n```\n\n`core` implements the shared operation layer for the CLI, including BLE lifecycle behavior.\n"}