Readme

README.md

@@ -18,16 +18,50 @@ In the end, this is the current result that works pretty well for my understandi
 
 Install it from the custom package index using
 
-```
+```shell
 pip install --extra-index-url https://forgejo.neshweb.net/api/packages/Firq/pypi/simple/ dockge-cli
 ```
 
 Alternativly, install it using this repository. When installing for development, make sure to install with the additional dependencies
 
-```
+```shell
 pip install -e .[lint,typing]
 ```
 
 ## Usage
 
 Call the CLI using `dockge-cli` or `dockge`.
+
+```shell
+usage: dockge_cli [-h] [--version] {host,login,logout,list,status,restart,start,stop,down,update,exit,help}
+
+CLI interface for interacting with Dockge
+
+positional arguments:
+  {host,login,logout,list,status,restart,start,stop,down,update,exit,help}
+
+options:
+  -h, --help            show this help message and exit
+  --version             show program's version number and exit
+```
+
+Help for each individual command can be invoked by calling `dockge-cli help <command>`
+
+## The magic behind this
+
+Generally, this makes use of the underlying Websockets API that the Dockge frontend uses to communicate with the server. By analyzing the traffic and looking into the codebase, I was able to reverse most of the packets that are being sent. This allows me to then contruct, send and receive my own packets, making the whole thing work.
+
+There are some things that need to be taken into account for this: For one, dockge uses socket.io for the websocket communication. This meant I had to find the corresponding socket.io version to get the correct version of python-socketio. In addition, I had to find out how the authorization mechanism behind this works.
+
+After finishing up the first prototype, the workings are as follows:
+
+1. A websocket session is established using socket.io - this happens automatically
+2. After the session is ready, the `login` command is sent together with a provided username and password
+3. Once the CLI is authorized, the selected command is sent
+4. The CLI waits for any response values and exits once the command has executed successfully
+
+To provide a smooth experience, both the credentials and the remote host URI are stored on disk. just like the `docker` cli, the credentials are not encrypted, meaning it is advised to either clear the credentials after use OR to use the `--username` and `--password` parameters. This is especially recommended for CI applications.
+
+## Known issues
+
+This CLI does not work when Mullvad is used, as Mullvad actively blocks port forwarding (which python-socketio uses)