beestat-cli

⚠️ Unofficial CLI for Beestat
Not affiliated with or endorsed by Beestat or ecobee.

A command-line interface for Beestat, providing access to ecobee thermostat analytics, sensor data, and air quality monitoring.

Installation

npm install -g beestat-cli

Quick Start

# Set your API key
export BEESTAT_API_KEY="your-api-key-here"

# Check thermostat status
beestat status

# List all sensors
beestat sensors

# Check air quality (Premium thermostats)
beestat air-quality

Getting an API Key

1. Create an account at beestat.io
2. Link your ecobee account
3. Email [email protected] with your thermostat serial number
4. Use the email address registered with your ecobee account

API keys are typically provided within 24 hours.

Commands

beestat status

Show current thermostat status including temperature, humidity, setpoints, and running equipment.

🏠 Thermostats

Upstairs
  Temperature: 66.3°F
  Humidity: 48%
  Setpoint: Heat 67.0°F / Cool 75.0°F
  Mode: home
  Status: 💨 Fan, 🔥 Heat 1
  Filter: Changed 2025-03-17 (2857h runtime)

🌤️  Weather
  38.5°F (sunny)
  High: 45.7°F / Low: 32.6°F
  Humidity: 88%

beestat sensors

List all sensors including remote room sensors with temperature and occupancy.

🌡️  Sensors

Upstairs
  ● Upstairs: 66.3°F
  ● Master Bedroom: 68.7°F
  ○ Sophies Room: 68.0°F
  ○ Lydies Room: 68.7°F

beestat air-quality (alias: aq)

Show air quality data from thermostats with air quality sensors (ecobee Smart Thermostat Premium).

• CO2 levels (ppm)
• VOC levels (ppm)
• Overall air quality score

beestat thermostats

List all thermostats with detailed information including model, property details, and HVAC system type.

beestat summary

Show runtime summary with heating/cooling usage per day.

Options:

• -d, --days <days> - Number of days to show (default: 7)

beestat sync

Force sync with ecobee to get the latest data.

Global Options

• --json - Output as JSON for scripting
• --no-color - Disable colored output
• -V, --version - Show version number
• -h, --help - Show help

Environment Variables

• BEESTAT_API_KEY - Your Beestat API key (required)
• NO_COLOR - Disable colored output

Exit Codes

• 0 - Success
• 1 - Generic failure
• 2 - Invalid usage
• 3 - Authentication failure (missing API key)

Examples

# Get thermostat status as JSON
beestat status --json

# Get sensors for scripting
beestat sensors --json | jq '.[] | {name, temperature}'

# Show last 14 days of runtime
beestat summary --days 14

# Force sync before checking status
beestat sync && beestat status

API Reference

This CLI uses the Beestat API. The API provides:

• Thermostat data (temperature, humidity, setpoints, schedules)
• Sensor data (remote sensors, occupancy)
• Air quality data (CO2, VOC - Premium thermostats only)
• Runtime history (5-minute and daily resolution)
• Weather data
• System profiles and efficiency analytics

Development

git clone https://github.com/mjrussell/beestat-cli
cd beestat-cli
pnpm install
pnpm build

# Test locally
BEESTAT_API_KEY="your-key" node dist/cli.js status

Contributing

Contributions welcome! Please open an issue or PR.

License

MIT © Matt Russell

Disclaimer

This is an unofficial tool created by the community.
Beestat is created by Jon Ziebell.
ecobee is a trademark of ecobee Inc.