Metadata-Version: 2.4
Name: remindrun
Version: 0.5.0
Summary: Run commands with Reminder monitoring and expose their status to the Android app.
Author: Reminder
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Reminder

Reminder is a minimal prototype for monitoring Linux command runs from an Android app.

The first version has two parts:

- `remindrun`: a Python command wrapper. Put `remindrun` before a command to record its status, output tail, exit code, and timestamps.
- Android app: a small native app that polls the `remindrun` HTTP API, lists runs, and posts a local notification when a run changes from running to finished.

## Python monitor

Install the local package in a virtual environment:

```bash
python3 -m venv .venv
.venv/bin/python -m pip install -e .
```

Or install the built wheel:

```bash
.venv/bin/python -m pip install dist/remindrun-0.5.0-py3-none-any.whl
```

Start the status server on the Linux machine:

```bash
remindrun server --host 0.0.0.0 --port 8765 --token change-this-token
```

Run commands through Reminder:

```bash
remindrun sleep 5
remindrun run -- bash -lc 'echo hello && sleep 2 && echo done'
remindrun status
```

You can use the shorter `rrun` command for the same actions:

```bash
rrun sleep 5
rrun ngrok --domain <YOUR_DEV_DOMAIN>.ngrok-free.dev
```

The server exposes:

- `GET /health`
- `GET /api/runs?limit=50`
- `GET /api/runs/{id}`
- `GET /api/events?since=<updatedAt>`

By default the SQLite database lives at `~/.reminder/reminder.db`. Set `REMINDER_HOME=/path/to/dir` to change that location.

## Public access

If you do not have a public IP, use a Cloudflare quick tunnel:

```bash
remindrun public
```

This starts the local server and runs `cloudflared tunnel --url http://127.0.0.1:8765`. It prints a public `https://*.trycloudflare.com` URL and a token. Enter both in the Android app:

```text
Server: https://example.trycloudflare.com
Token:  generated-token
```

If `cloudflared` is missing, install it first:

```bash
brew install cloudflared
```

Cloudflare quick tunnel URLs are random. If you need the same URL every time and do not own a domain, use ngrok's free Dev Domain:

```bash
brew install ngrok/ngrok/ngrok
ngrok config add-authtoken <YOUR_NGROK_AUTHTOKEN>
remindrun ngrok --domain <YOUR_DEV_DOMAIN>.ngrok-free.dev
```

In the Android app:

```text
Server: https://<YOUR_DEV_DOMAIN>.ngrok-free.dev
Token:  generated-token
```

If the Android app needs to connect to a server that already has a public IP or a public domain:

```bash
remindrun server --host 0.0.0.0 --port 8765 --token a-long-random-token
```

Then open TCP port `8765` in the cloud security group or firewall.

In the Android app:

```text
Server: http://<public-ip>:8765
Token:  a-long-random-token
```

For real public use, prefer HTTPS through a reverse proxy or tunnel. Plain `http://<public-ip>:8765` works for testing, but the token can be observed on an untrusted network.

## Android app

Open the `android/` directory in Android Studio.

For an emulator, the default server URL is:

```text
http://10.0.2.2:8765
```

For a physical phone, start the server with `--host 0.0.0.0`, put the phone on the same network, then set the app server URL to:

```text
http://<linux-machine-ip>:8765
```

If the server was started with `--token`, enter the same token in the app's Token field.

This prototype polls every 5 seconds while the app process is alive. A later version should move polling into a foreground service or push channel if you want reliable notifications while the app is fully backgrounded.
