Metadata-Version: 2.4
Name: localmoderationmatrix
Version: 1.1.0
Summary: A CLI tool for bulk message deletion, media cleanup, and sticker purge in public Matrix rooms.
Project-URL: Homepage, https://github.com/berkaygediz/LocalModerationMatrix
Project-URL: Repository, https://github.com/berkaygediz/LocalModerationMatrix
Project-URL: Issues, https://github.com/berkaygediz/LocalModerationMatrix/issues
Project-URL: Changelog, https://github.com/berkaygediz/LocalModerationMatrix/releases
Author: Berkay Gediz
License: Apache-2.0
License-File: LICENSE
Keywords: bulk-delete,chat-moderation,cli,community-management,matrix,matrix-bot,matrix-org,media-cleanup,moderation,purge,sticker,synapse
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Telecommunications Industry
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: matrix-nio>=0.26.0
Description-Content-Type: text/markdown

# LocalModeration for Matrix

A CLI tool for bulk message deletion, media cleanup, and sticker purge in public (unencrypted) Matrix rooms. Encrypted messages are skipped automatically.

## Installation

**View on PyPI:** [pypi.org/project/localmoderationmatrix](https://pypi.org/project/localmoderationmatrix/)

**Using pip:**

```bash
pip install localmoderationmatrix
```

**Using uv:**

```bash
uv tool install localmoderationmatrix
```

**Standalone Executable:** [GitHub Releases](https://github.com/berkaygediz/LocalModerationMatrix/releases)

## Session

Once logged in, your session is saved in your home directory. Just enter your **User ID** on the next run to auto-login.
If you need to clear the saved session, type `reset` as your User ID.

## Usage

```bash
localmoderationmatrix <room_id> [options]
```

### Parameters

| Parameter | Description |
| --- | --- |
| `room_id` | (Required) The Matrix room ID. |
| `--search` | Search for a single keyword. |
| `--file` | Search using a wordlist file (one word per line). |
| `--interactive` | Scan room once and enter Interactive Hub mode. |
| `--purge-media` | Delete media older than X days (`0` for all). |
| `--purge-sticker` | Delete stickers older than X days (`0` for all). |
| `--log-room` | Room ID to send moderation logs. |
| `--days` | Time filter: Days (Default: 0). |
| `--hours` | Time filter: Hours (Default: 1). |
| `--minutes` | Time filter: Minutes (Default: 0). |
| `--homeserver` | Custom homeserver URL. |

### Interactive Keys

* `y` : Delete.
* `n` : Skip.
* `a` : **Delete All** remaining items automatically.
* `q` : Quit current review (returns to menu in Interactive Mode).

## Examples

**Search for a keyword:**

```bash
localmoderationmatrix "!roomID:matrix.org" --search "spam"
```

**Scan with a wordlist and log actions:**

```bash
localmoderationmatrix "!roomID:matrix.org" --file words.txt --days 7 --log-room "!LogRoomID:matrix.org"
```

**Delete media older than 90 days:**

```bash
localmoderationmatrix "!roomID:matrix.org" --purge-media 90
```

**Interactive Mode (Scan once, filter instantly):**

```bash
localmoderationmatrix "!roomID:matrix.org" --interactive --days 7
```

## Building from Source

**PyPI Package:**

```bash
uv build
```

**Standalone Executable:**

```bash
pyinstaller --onefile --name LocalModerationMatrix --clean --noconfirm --optimize 2 --collect-all localmoderationmatrix src/localmoderationmatrix/cli.py
```

## License

Apache-2.0
