BukuBot/README.md

# Bookmarks bot for XMPP

## BukuBot

BukuBot is a bookmarks bot for the XMPP communication network.

BukuBot is a powered by [buku](https://github.com/jarun/buku) and [slixmpp](https://codeberg.org/poezio/slixmpp).

## XMPP

XMPP is the Extensible Messaging and Presence Protocol, a set of open technologies for instant messaging, presence, multi-party chat, voice and video calls, collaboration, lightweight middleware, content syndication, and generalized routing of XML data.

Visit [XMPP](https://xmpp.org/) for more information [about](https://xmpp.org/about/) the XMPP protocol and check the [list](https://xmpp.org/software/) of XMPP clients.

BukuBot is primarily designed for XMPP (aka Jabber), yet it is built to be extended to other protocols.

## Features

- **Search** - Filter and search bookmarks by keywords and tags.
- **Portable** - Export and import bookmarks to buku database, HTML, Markdown, Orgfile, or XBEL.
- **Simultaneous** - BukuBot is designed to handle multiple contacts, including groupchats, Simultaneously.
- **Visual interface** - Interactive interface for XMPP using Ad-Hoc Commands,

## Preview

BukuBot as appears with Cheogram.

<img alt="Chat: Search" src="bukubot/documentation/screenshots/chat_search.jpg" width="200px"/>
<img alt="Ad-Hoc: Commands" src="bukubot/documentation/screenshots/adhoc_commands.jpg" width="200px"/>
<img alt="Ad-Hoc: Browse" src="bukubot/documentation/screenshots/adhoc_browse.jpg" width="200px"/>
<img alt="Ad-Hoc: Add" src="bukubot/documentation/screenshots/adhoc_add.jpg" width="200px"/>
<img alt="Ad-Hoc: Edit bookmark" src="bukubot/documentation/screenshots/adhoc_edit.jpg" width="200px"/>
<img alt="Ad-Hoc: Seach" width="200px" src="bukubot/documentation/screenshots/adhoc_search.jpg"/>

## Getting Started

### Install

It is possible to install BukuBot using pip and pipx.

#### pip inside venv

```
$ python3 -m venv .venv
$ source .venv/bin/activate
$ pip install git+https://git.xmpp-it.net/sch/BukuBot
```

#### pipx

##### Install

```
$ pipx install git+https://git.xmpp-it.net/sch/BukuBot
```

##### Update

```
$ pipx uninstall bukubot
$ pipx install git+https://git.xmpp-it.net/sch/BukuBot
```

### Start

Start by executing the command `bukubot` and enter Username and Password of an existing XMPP account.

```
$ bukubot
```

You can also start BukuBot as follows:

```
$ bukubot --jid ACCOUNT_JABBER_ID --password ACCOUNT_PASSWORD
```

It is advised to use a dedicated extra account for BukuBot.

## Recommended Clients

BukuBot works with any XMPP chat client; if you want to make use of the visual interface which BukuBot has to offer (i.e. Ad-Hoc Commands), then you are advised to use [Cheogram](https://cheogram.com), [Converse](https://conversejs.org), [Gajim](https://gajim.org), [monocles chat](https://monocles.chat), [Movim](https://mov.im), [Poezio](https://poez.io), [Profanity](https://profanity-im.github.io), [Psi](https://psi-im.org) or [Psi+](https://psi-plus.com).

### Support

Please join our support groupchat whether you want help, discuss new features or just greet us.

- [Main Groupchat](xmpp:bukubot@chat.woodpeckersnest.space?join) (International)

## Authors

[Schimon](xmpp:sch@pimux.de?message) (Author).

## License

MIT license.

## Copyright

Schimon Zackary, 2024