Metadata-Version: 2.4
Name: woonveilig-cli
Version: 0.1.0
Summary: Command-line interface for WoonVeilig/Egardia alarm systems (cloud API)
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/stefanstranger/woonveilig-cli
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click
Requires-Dist: requests
Dynamic: license-file

# 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

```bash
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

```bash
pip install -r requirements.txt
```

### 2) Configure credentials

Set environment variables before running commands:

```bash
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

```bash
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

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

### 5) Read data for automations

```bash
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

```bash
python woonveilig.py status
```

If auth is missing/expired, output is:

```json
{
	"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.

```bash
WOONVEILIG_USERNAME=your_screen_name_username
WOONVEILIG_PASSWORD=your_password
```

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

## Command Reference

```bash
# 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.
