tellme/README.md

# TellMe

A server and client notifications system written in Python that alerts you of events via SimpleX chat or Matrix.

## Overview

TellMe monitors for events (completed processes, server uptime, etc.) and sends notifications through a built-in server to SimpleX chat or Matrix over websockets. Starting from version 2.2, TellMe supports [GoAlert](https://goalert.io) messages natively.

## Client Features

- **Send messages**: `-m "Your message"` - Send custom notifications
- **Monitor processes**: `-p <pid>` - Wait for a process to exit, then notify
- **Watch commands**: `-w "command"` - Run a command periodically and notify on output
- **Ping hosts**: `-P <host>` - Monitor host availability until it's reachable

## Server Setup

### Installation

```bash
cd server/src
pip install -r requirements.txt
```

### Configuration

1. Configure hooks in `/etc/tellme/hooks.yml`:
```yaml
2345555XE:
  transport: "simplex"
  target: "#Bottest"
```

Supported transports: `simplex`, `matrix`

2. (Optional) Configure Matrix credentials in `/etc/tellme/config.yml`:
```yaml
matrix_homeserver: "https://matrix.org"
matrix_access_token: "syt_your_token_here"
matrix_user_id: "@yourbot:matrix.org"
```

#### Obtaining a Matrix Access Token

**Via Element Web (easiest):**
1. Log into Element (https://app.element.io or your homeserver's Element instance)
2. Go to **Settings** (gear icon) → **Help & About**
3. Scroll to **Access Token** → click "Reveal Access Token" → copy it

**Via Matrix API (curl):**
```bash
curl -X POST "https://your-homeserver.url/_matrix/client/v3/login" \
  -H "Content-Type: application/json" \
  -d '{"type":"m.login.password","user":"@youruser:homeserver","password":"yourpassword"}'
```
The response includes `access_token`.

**Important:**
- Use a dedicated bot account, not your personal one
- Keep the token secure (don't commit to git)
- Revoke it in Element settings if compromised

3. Run the SimpleX CLI chat as a daemon (for SimpleX transport).

4. Start the server:
```bash
python tellmesrv.py
```

## Ansible

An example Ansible role is included in `Ansible/tellme_notification` for integrating TellMe notifications into Ansible playbooks.

Created by Taurix IT (https://www.taurix.net) | Licensed under AGPLv3+