libre-cli

Fast CLI for retrieving glucose levels from Libre sensors via the LibreLinkUp API.

• Zero runtime dependencies - uses native fetch()
• Token caching - fast subsequent calls (~330ms vs ~1.1s cold start)
• AI-agent friendly - JSON output with semantic exit codes
• Bun-powered - fast startup, TypeScript native

Installation

git clone https://github.com/petermekhaeil/libre-cli.git
cd libre-cli
bun install

# Link globally
bun link

# Set credentials (add to ~/.bashrc or ~/.zshrc for persistence)
export LIBRE_EMAIL="your-email@example.com"
export LIBRE_PASSWORD='your-password'

Tip: Use single quotes for passwords with special characters (like $).

Usage

# Get current glucose (JSON)
libre current
# {"value":105,"unit":"mg/dL","mmol":"5.8","trend":"Flat","trendArrow":"->","timestamp":"2026-02-07T10:30:00.000Z","isHigh":false,"isLow":false,"color":"green"}

# Human-readable output
libre current --human
# 105 mg/dL (5.8 mmol/L) -> Flat
# Time: 10:30 AM, Feb 7
# Status: In Range

# Get history (default: last 10 readings)
libre history
libre history --limit 24

# Check authentication status
libre auth

# Clear cached token
libre logout

# Help
libre help
libre history -l 24

Options

Flag	Short	Description
--human		Human-readable output (default: JSON)
--limit	-l	Number of history readings (default: 10)
--patient		Select patient by first name
--patient-id		Select patient by exact ID
--help		Show help message

Environment Variables

Variable	Description
LIBRE_EMAIL	Your LibreLinkUp email
LIBRE_PASSWORD	Your LibreLinkUp password
LIBRE_PATIENT_ID	Specific patient ID (optional)
LIBRE_PATIENT_NAME	Patient first name (optional)

Exit Codes

For AI agents and scripts:

Code	Meaning
0	Success
1	Authentication error
2	Network/API error
3	No sensor data available
4	Invalid arguments

JSON Output Format

Current Reading

{
  "value": 105,
  "unit": "mg/dL",
  "mmol": "5.8",
  "trend": "Flat",
  "trendArrow": "->",
  "timestamp": "2026-02-07T10:30:00.000Z",
  "isHigh": false,
  "isLow": false,
  "color": "green"
}

Trend Values

Trend	Arrow	Meaning
SingleDown	down down	Falling fast
FortyFiveDown	southeast	Falling
Flat	right arrow	Stable
FortyFiveUp	northeast	Rising
SingleUp	up up	Rising fast
NotComputable	?	Unknown

Color Values

Color	Meaning
green	In range
yellow	Warning
orange	Alert
red	Critical (high/low)

Token Caching

Auth tokens are cached at ~/.config/libre-cli/cache.json with restrictive permissions (600).

Tokens are automatically refreshed when expired. To force a fresh login:

libre logout
libre current

Development

# Run directly
bun run src/index.ts current

# Run tests
bun test

# Watch mode
bun --watch src/index.ts current

# Type check
bun run typecheck

How It Works

This CLI directly interfaces with the LibreLinkUp API (the same API used by the LibreLinkUp mobile app). It:

1. Authenticates with your LibreLinkUp credentials
2. Handles regional API redirects automatically
3. Fetches glucose data from your connected sensor
4. Returns data in a format optimized for AI agents

Requirements

• Bun v1.0+
• LibreLinkUp account with a connected Freestyle Libre sensor
• Sensor must be shared via the Libre Link app