Expanded documentation!

README.md

@@ -1,6 +1,3 @@
-> [!NOTE]
-> *If you experience issues or have suggestions, submit an issue! https://github.com/DaanSelen/meshbook/issues I'll respond ASAP!*
-
 # Meshbook
 
 A way to programmatically manage MeshCentral-managed machines, a bit like Ansible does.<br>
@@ -11,10 +8,15 @@ And many people will be comfortable with YAML configurations! It's almost like J
 
 The quickest way to start is to grab a template from the templates folder in this repository.<br>
 Make sure to correctly pass the MeshCentral websocket API as `wss://<MeshCentral-Host>/control.ashx`.<br>
-And make sure to fill in the credentails of an account which has remote commands permissions.<br>
+And make sure to fill in the credentails of an account which has `Remote Commands` permissions and `Device Details` permissions on the targeted devices or groups.<br>
+
+> I did this through a "Global Service" group which I added the meshbook account to!
+
 Then make a yaml with a target and some commands! See below examples as a guideline. And do not forget to look at the bottom's notice.<br>
 To install, follow the following commands:<br>
 
+### Linux setup:
+
 ```shell
 git clone https://github.com/daanselen/meshbook
 cd ./meshbook
@@ -22,15 +24,84 @@ python3 -m venv ./venv
 source ./venv/bin/activate
 pip3 install -r ./meshbook/requirements.txt
 ```
+
+### Windows setup:
+
+```shell
+git clone https://github.com/daanselen/meshbook
+cd ./meshbook
+python3 -m venv ./venv
+.\venv\Scripts\activate # Make sure to check the terminal prefix.
+pip3 install -r ./meshbook/requirements.txt
+```
+
 Now copy the configuration template from ./templates and fill it in with the correct details. The url should start with `wss://` and end in `control.ashx`.<br>
 After this you can use meshbook, for example:
+
+### Linux run:
+
 ```shell
-python3 ./meshbook/meshbook.py -pb examples/echo.yaml
+python3 .\meshbook\meshbook.py -pb .\examples\echo.yaml
 ```
 
+### Windows run:
+
+```shell
+.\venv\Scripts\python.exe .\meshbook\meshbook.py -pb .\examples\echo.yaml
+```
+
+### How to check if everything is okay?
+
+The python virtual environment can get messed up, therefor...<br>
+To check if everything is in working order, make sure that the lists from the following commands are aligned:
+
+```
+python3 -m pip list
+pip3 list
+```
+
+If not, perhaps you are using the wrong executable, the wrong environment and so on...
+
+# How to create a configuration?
+
+This paragraph explains how the program interprets certain information.
+
+### Targeting:
+
+MeshCentral has `meshes` or `groups`, in this program they are called `companies`. Because of the way I designed this.<br>
+So to target for example a mesh/group in MeshCentral called: "Nerthus" do:
+
+> If your group has multiple words, then you need to use `"` to group the words.
+
+```yaml
+---
+name: example configuration
+company: "Nerthus"
+variables:
+  - name: var1
+    value: "This is the first variable"
+tasks:
+  - name: echo the first variable!
+    command: 'echo "{{ var1 }}"'
+```
+
+It is also possible to target a single device, as seen in: [here](./examples/echo.yaml).<br>
+
+### Variables:
+
+Variables are done by replacing the placeholders just before the runtime.<br>
+So if you have var1 declared, then the value of that declaration is placed wherever it finds {{ var1 }}.<br>
+This is done to imitate popular methods. See below [from the example](./examples/variable_example.yaml).<br>
+
+### Tasks:
+
+The tasks you want to run should be contained under the `tasks:` with two fields, `name` and `command`.<br>
+The name field is for the user of meshbook, to clarify what the following command does in a summary.<br>
+The command field actually gets executed on the end-point.<br>
+
 # Example:
 
-For the example, I used the following yaml file:
+For the example, I used the following yaml file (you can find more in [this directory](./examples/)):
 
 The below group: `Temp-Agents` has four devices, of which one is offline.<br>
 You can expand the command chain as follows:<br>
@@ -56,7 +127,7 @@ tasks:
     command: "{{ command1 }} {{ host2 }} {{ cmd_arguments }}"
 ```
 
-The following response it received when executing the first yaml of the above files.
+The following response it received when executing the first yaml of the above files (with the `-s` and the `-i` parameters).
 
 ```shell
 python3 meshbook/meshbook.py -pb examples/variable_example.yaml -si