toxio

README.md (4115B)

---

 # toxio: turn (almost) any CLI program/script into a Tox bot
 
 Toxio is a small Nim program that aims to do one thing: wrap any line-oriented CLI program or script to be able to communicate with it via the [Tox](https://tox.chat/) network. Toxio spawns any shell command of your choice as a subprocess and redirects your messages to its standard input and its output lines to the chat replies.
 
 ## Building
 
 To build toxio, you obviously would need a working Nim compiler, as well as [toxcore](https://github.com/TokTok/c-toxcore) library and [nim-toxcore](https://git.sr.ht/~ehmry/nim-toxcore) package installed. The latter is available using Nimble package manager (`nimble install toxcore`). You will also need any POSIX-compatible `make` command, although nothing prevents you from compiling the `toxio.nim` file manually.
 
 Once you have all dependencies sorted out, just run `make` in the project directory. If everything is successful, a `toxio` binary file should appear.
 
 ## Usage
 
 The overall command syntax is like this: `toxio [bot_name] [save_file] [r|w] [cmd]`. Now, let's go through the stages to set up your bot.
 
 ### 1. Obtain a Tox save data file
 
 First, you will need an existing toxcore-compatible save file. For safety reasons, toxio does not create any save files, you have to supply it externally. They may or may not already have friendlists, but if they do, beware that all the friends will have the access to the process running inside your bot. Thus, it's recommended to create a new profile save file (it must be unencrypted) in a client like Toxic and then use it solely for the purposes of this bot.
 
 ### 2. Add the bot users as friends
 
 Now that you have your save file (e.g. `save.tox`), you should run toxio in the **write-enable** mode with the `w` command line parameter and a dummy command like `cat` (which will essentially make toxio function as an echo bot for you to test it):
 
 ```
 toxio "My new bot" /path/to/save.tox w cat
 ```
 
 In the write-enable mode, the bot accepts all friend requests and saves them to your save file. This mode must only be used for initial set up and testing phase, never for normal usage!
 
 After running, the bot will print out its Tox ID that you can use to add as a friend to all your Tox identities you need to use the bot from. After you added this bot as a friend to every required ID, terminate it with Ctrl+C and make sure your save file is backed up in a safe place.
 
 ### 3. Run the bot normally
 
 Now, you can run the bot normally (in the **read-only** mode) like this (where "My new bot" is just its displayed name and `"cmd"` is the command line you need to run):
 
 ```
 toxio "My new bot" /path/to/save.tox r "cmd"
 ```
 
 When toxio gets online, every connected friend will be able to communicate with the subprocess using the chat with this bot. The status message will display the command line of the process the bot is currently serving.
 
 Keep in mind that you only start getting the program's output if you initially send a message. What to do with your messages is fully up to the program.
 
 You can also pause the program's output. If you run, for instance, some monitoring service and want to temporarily stop receiving messages from the bot, just send `/toxiostop` to it. The output will resume automatically whenever you send any other message.
 
 ## Limitations
 
 - Text messages only.
 - Single subprocess per bot by design. This means that every connected friend will communicate with exactly the same subprocess and receive identical output from it.
 - The program's output must end with newline characters.
 - Every output line is sent as a separate message.
 - The stdout and stderr streams are merged. This is hardcoded: find `poStdErrToStdOut` option in the `toxio.nim` file and remove it if you don't need this behavior.
 - You need an external client to initially set up the bot's Tox ID and generate the save file.
 - Only one DHT bootstrap node hardcoded for now.
 - Only tested on Unix-like OSes, compatibility is not guaranteed for others.
  
 ## Credits
 
 Created by Luxferre in 2024, released into public domain.
 
 Made in Ukraine.