From 6b14901159a3595e5cd3924da164a900a3f896b2 Mon Sep 17 00:00:00 2001
From: Majo Richter <39386799+NobleMajo@users.noreply.github.com>
Date: Wed, 15 Jan 2025 11:19:07 +0100
Subject: [PATCH] Change: improve description, usage and difference to ssh2 npm
 lib

---
 README.md | 36 +++++++++++++++++++++++-------------
 1 file changed, 23 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index e709f66..e9c54a3 100644
--- a/README.md
+++ b/README.md
@@ -12,9 +12,9 @@
 <!-- ![](https://img.shields.io/badge/dynamic/json?color=darkred&label=open%20issues&query=open_issues&suffix=x&url=https%3A%2F%2Fapi.github.com%2Frepos%2Fnoblemajo%2Fhivessh)
 ![](https://img.shields.io/badge/dynamic/json?color=orange&label=subscribers&query=subscribers_count&suffix=x&url=https%3A%2F%2Fapi.github.com%2Frepos%2Fnoblemajo%2Fhivessh) -->
 
-HiveSsh simplifies SSH2 connections via promise-based task execution on Linux servers with built-in server utilities and powerful command execution functions.
+HiveSsh is an innovative library designed to streamline SSH2 connections and simplify task execution on Linux servers.
 
-HiveSsh is a library designed to streamline SSH2 connections and task execution on Linux servers. It provides user-friendly promise-based functions for efficient server operations without the need for a client application.
+It wraps around the ssh2-library, offering a [promise-based approach](#promisified) to avoid nested callbacks and adding useful features like [command existence checks](#command-existence-checks) and persistent [exec sessions](#exec-session).
 
 ----
 
@@ -34,6 +34,12 @@ HiveSsh is a library designed to streamline SSH2 connections and task execution
 - [License](#license)
 - [Disclaimer](#disclaimer)
 
+# SSH2
+The term `ssh2` has two meanings here, the `secure shell protocol` and the `npm library`. 
+When referring to the npm library, this repo will always refer to it as the `ssh2`-library.
+
+HiveSsh is a wrapper library of the `ssh2`-library with additional features and promise-based task execution instead of a callback function approach.
+
 # Key Features
 HiveSsh offers the following key features:
 - __All-Distributions__: SSH2 and SFTP operations for all Linux servers
@@ -88,7 +94,7 @@ const myHost = await SshHost.connect({
 Here are some using examples:
 
 ## Promisified
-### Execute and assets
+### Execute
 
 After connecting an `SshHost`, you can use the promisified execution (and other asset features) directly on the `SshHost` instance.
 ```ts
@@ -97,6 +103,19 @@ const homeDirFiles = await myHost.exec("ls -al")
 console.log("Home dir files:\n", homeDirFiles.out)
 ```
 
+### Execute at
+
+You can also execute commands on absolut path:
+```ts
+const etcDirFiles = await myHost.exec(
+  "ls -al",
+  { pwd: "/etc" }
+)
+console.log("Etc files: ", etcDirFiles.out)
+```
+
+### Command existence checks
+
 Get the hosts public ip address:
 ```ts
 // check if curl command exists
@@ -111,15 +130,6 @@ console.log("Host public ip: " + myIp.out)
 //other sources: `api.ipify.org`, `ipinfo.io/ip` or `ipecho.net/plain`
 ```
 
-You can also execute commands on absolut path:
-```ts
-const etcDirFiles = await myHost.exec(
-  "ls -al",
-  { pwd: "/etc" }
-)
-console.log("Etc files: ", etcDirFiles.out)
-```
-
 Also a git example:
 ```ts
 // check if git command exists
@@ -218,7 +228,7 @@ session.exec("node myApp.js")
 HiveSsh is built using the following technologies:
 - **TypeScript**
 - **Node.js**
-- **SSH2** ([NPM Package](https://www.npmjs.com/package/ssh2) & Protocol)
+- [`ssh2`-library](https://www.npmjs.com/package/ssh2)
 
 # Contributing
 Contributions to this project are welcome!