Metadata-Version: 2.4
Name: tellme-notify
Version: 0.0.2
Summary: Run a command and notify on completion
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: apprise>=1.8.0
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: PyYAML>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
Dynamic: license-file

# Tellme - Stop Watching Long-Running Server Jobs

[![PyPI version](https://img.shields.io/pypi/v/tellme-notify.svg)](https://pypi.org/project/tellme-notify/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Powered by Apprise](https://img.shields.io/badge/Powered%20by-Apprise-blue.svg)](https://github.com/caronc/apprise)
[![LINUX DO](https://img.shields.io/badge/LINUX--DO-Community-blue?logo=linux.do&logoColor=white)](https://linux.do/)

[中文说明 / Chinese README](README.zh-CN.md)

---

Running something large on a remote server, like downloading a model, installing packages over a slow network, or building a project, usually means one annoying tradeoff: either stay at the terminal and keep checking, or walk away and risk forgetting the result.

**Tellme** solves that problem.

Tellme is a lightweight CLI tool that wraps a long-running command, waits for it to finish, and then sends you a notification with the result: success or failure, exit code, elapsed time, a tail summary of stdout/stderr, and session hints so you can inspect the full output later.

Notifications are powered by [Apprise](https://github.com/caronc/apprise), so you can route them to services like Telegram, PushMe, and many other channels. See the [Apprise wiki](https://github.com/caronc/apprise/wiki) for all supported notification providers.

## Install

The recommended way to install it is with `pipx`:

```bash
pipx install tellme-notify
```

Upgrade later with:

```bash
pipx upgrade tellme-notify
```

Install directly from this repository:

```bash
pipx install .
```

## Usage

### Quick start

Run a command and get notified when it finishes:

```bash
tellme wget https://example.com/large-model.bin
```

For a quick one-shot notification without wrapping a command:

```bash
tellme echo "Task finished"
```

If the wrapped command itself starts with `-` flags, use `--` to separate Tellme's arguments from the target command:

```bash
tellme -- wget -q https://example.com/file
```

When the command exits, Tellme sends a message containing the command, exit code, duration, tail output summary, and session information.

### Configure notification targets

Use the interactive configuration screen to add your Apprise URLs:

```bash
tellme --configure
```

Inside the configurator, the single-key actions are:

- `a`: add an Apprise URL
- `r`: remove a URL
- `e`: enable or disable a URL
- `c`: clear all targets
- `t`: toggle WSL Windows Toast support
- `m`: set the max stdout/stderr summary length
- `s`: save config
- `q`: quit

The default config path is `~/.config/tellme/config.yaml`.

Example Apprise URLs:

- Telegram: `tgram://<BOT_TOKEN>/<CHAT_ID>/`
- PushMe: `pushme://<TOKEN>`

For safety, avoid putting tokens directly into shell history. Tellme stores config with private permissions where possible.

### Session management

Tellme provides session management similar to `screen`:

Start a named session:

```bash
tellme -N my-task long-running-command
```

Later, attach to it:

```bash
tellme -a -s my-task
```

Inside an attached session, press `Ctrl+A` then `D` to detach.

List all sessions:

```bash
tellme --sessions
```

Show the full output of one session:

```bash
tellme -s <SESSION_ID_OR_NAME>
```

Clean up exited session records:

```bash
tellme --clean
```

### Direct notifications with `echo`

For quick one-shot notifications without session overhead:

```bash
tellme echo "Build finished successfully"
```

This sends a notification immediately without creating a session or recording logs.

### Agent Skill Support

Tellme includes a built-in skill for AI agents. Install it to your project directory:

```bash
tellme --install-skill
```

This copies the bundled `TellUser` skill into your current directory. AI assistants can then use `tellme echo` to notify you when long tasks complete.

### Diagnostics

Run environment and config diagnostics:

```bash
tellme --doctor
```

### WSL Windows Toast

When running inside WSL, Tellme can send native Windows toast notifications through `powershell.exe`, without requiring a separate Windows-side app.

On non-WSL Linux systems, that channel is safely skipped.

## Contributing

If you find a bug or want to suggest an improvement, feel free to open an [Issue](https://github.com/aliyahzombie/tellme/issues) or a [Pull Request](https://github.com/aliyahzombie/tellme/pulls).

## License

This project is released under the [MIT License](LICENSE).

---

**Acknowledgement**: notification delivery is powered by [Apprise](https://github.com/caronc/apprise).
