blue-lock

blue-lock is a small Windows CLI that locks your screen when a remembered Bluetooth LE device is no longer seen nearby.

It is designed for the simplest phone setup possible: users do not install a phone app. They turn on Bluetooth, run the learning command, and keep the watcher running.

Important limits

• Locking Windows is supported.
• Automatic unlock is not supported from this CLI. Windows intentionally prevents ordinary user programs from bypassing the lock screen. Use Windows Hello, Dynamic Lock, or a proper Windows credential provider for unlock behavior.
• Bluetooth proximity is approximate. Phones often randomize Bluetooth identifiers and may stop advertising when idle, so detection can vary by phone model and OS settings.
• The scanner uses Bluetooth LE advertisements. If your phone does not appear during learning, open Bluetooth settings on the phone and keep the screen awake while learning.

Install

npm install -g blue-lock

If npm fails with UNABLE_TO_VERIFY_LEAF_SIGNATURE, fix your local Node/npm certificate trust before installing. This usually means a corporate proxy or local TLS inspection certificate is not trusted by Node.

For local development:

npm install
npm link

Usage

Learn nearby Bluetooth LE devices:

blue-lock scan

Remember a device:

blue-lock pair <device-id>

Start watching:

blue-lock watch

Install auto-start for the current Windows user:

blue-lock autostart enable

Disable auto-start:

blue-lock autostart disable

Show current configuration:

blue-lock status

Configuration

The config file is stored at:

%APPDATA%\blue-lock\config.json

Useful options:

blue-lock config --away-seconds 20 --near-rssi -75 --lock-cooldown 60

• away-seconds: seconds without seeing the phone before locking.
• near-rssi: RSSI threshold. Less negative is nearer, so -65 is stricter than -85.
• lock-cooldown: minimum seconds between lock attempts.

Publish

npm login
npm publish --access public

If the package name is already taken, change name in package.json before publishing.