WoonVeilig CLI

Command-line interface for managing a WoonVeilig (Egardia) alarm system.

This project is designed to work for both humans and AI agents (for example OpenClaw) that need scriptable alarm-system operations.

Features

• OAuth2 authentication (compatible with the mobile app flow)
• Full management commands for alarm state changes
• Alarm status, system info, devices, residents, and contacts
• Alarm log retrieval in plain JSON output
• Debug mode for diagnostic output when needed

Installation

pip install -r requirements.txt

Quick Start for AI Agents

Use this flow when an agent (for example OpenClaw) needs to install and operate the CLI with minimal ambiguity.

1) Install

pip install -r requirements.txt

2) Configure credentials

Set environment variables before running commands:

WOONVEILIG_USERNAME=your_screen_name_username
WOONVEILIG_PASSWORD=your_password

Notes:

• Username must be the screen name (not email).
• Keep credentials out of source control.

3) Authenticate and verify access

python woonveilig.py login
python woonveilig.py status

Expected behavior:

• Commands return plain JSON.
• On success, status returns alarm account fields.

4) Core control commands

python woonveilig.py arm --mode away
python woonveilig.py arm --mode home
python woonveilig.py disarm

5) Read data for automations

python woonveilig.py logs
python woonveilig.py devices
python woonveilig.py residents
python woonveilig.py contacts
python woonveilig.py info

6) Non-interactive health check

python woonveilig.py status

If auth is missing/expired, output is:

{
	"ok": false,
	"error": "Not authenticated. Run 'login' first."
}

For Humans

Copy this instruction to your AI agent:

Install and configure this WoonVeilig CLI from README instructions, set WOONVEILIG_USERNAME and WOONVEILIG_PASSWORD, run python woonveilig.py login, verify with python woonveilig.py status, then use arm --mode away|home and disarm for control. Keep output in JSON and report any auth/control errors clearly.

Configuration

Use environment variables (recommended for automation) or interactive login.

WOONVEILIG_USERNAME=your_screen_name_username
WOONVEILIG_PASSWORD=your_password

You can also copy .env.example to .env for local development.

Command Reference

# Authentication
python woonveilig.py login
python woonveilig.py logout
python woonveilig.py token-info

# Alarm management
python woonveilig.py arm --mode away
python woonveilig.py arm --mode home
python woonveilig.py disarm

# Monitoring and data
python woonveilig.py status
python woonveilig.py info
python woonveilig.py devices
python woonveilig.py residents
python woonveilig.py contacts
python woonveilig.py logs
python woonveilig.py logs --start 0 --amount 50
python woonveilig.py logs --all --output logs.json

AI Agent Usage Notes

• Prefer non-interactive authentication with environment variables.
• All command output is plain JSON for machine processing.
• Sensitive token details are hidden by default and only shown with --debug.

Security Notes

• Stored tokens are local user-session credentials. Treat them as secrets.
• Do not share debug output publicly.
• Keep .env out of source control (covered by .gitignore).

How It Works

This CLI uses reverse-engineered WoonVeilig/Egardia mobile API behavior:

• Base URL: https://my.egardia.com/
• OAuth2 password/refresh token flow
• Bearer token authorization for secure endpoints

AI-Assisted Development Disclosure

Parts of this project were developed with AI assistance.

Disclaimer

This is an unofficial project and is not affiliated with WoonVeilig or Egardia. Use at your own risk and only on systems/accounts you own or are authorized to manage.