Add documentation for commands with examples

documentation/cmd/import.md

@@ -0,0 +1,56 @@
+# Import Command
+
+The `import` command in Microcks CLI is used to upload and register API specification artifacts (like OpenAPI, AsyncAPI, Postman collections, etc.) into a Microcks server.
+
+📝 Description
+
+The `import` command enables developers to push one or multiple API artifacts to a Microcks instance. It supports secure authentication via Keycloak and allows custom TLS configurations for secure communication.
+
+📌 Usage
+```bash
+microcks import <specificationFile1[:primary]>,<specificationFile2[:primary]> \
+  --microcksURL <microcks-api-url> \
+  --keycloakClientId <client-id> \
+  --keycloakClientSecret <client-secret> \
+  [--insecure] \
+  [--caCerts <cert-paths>] \
+  [--verbose]
+```
+Arguments
+- `<specificationFile[:primary]>`:
+A comma-separated list of specification file paths to import.
+Optionally, each file can be suffixed with `:true` or `:false` to indicate whether it's the primary artifact.
+
+| Flag                    | Type    | Required | Description                                                                 |
+|-------------------------|---------|----------|-----------------------------------------------------------------------------|
+| `--microcksURL`         | string  | ✅        | The URL of the Microcks API endpoint.                                      |
+| `--keycloakClientId`    | string  | ✅        | The Keycloak Service Account Client ID for OAuth2 authentication.          |
+| `--keycloakClientSecret`| string  | ✅        | The Keycloak Service Account Client Secret for authentication.             |
+| `--insecure`            | bool    | ❌        | Allow insecure TLS connections (e.g., self-signed certs).                  |
+| `--caCerts`             | string  | ❌        | Comma-separated paths to additional CA certificate files (PEM format).     |
+| `--verbose`             | bool    | ❌        | Enable verbose mode to dump HTTP requests and responses to the console.    |
+
+🧪 Examples
+- Basic Import
+```bash
+microcks import my-api.yaml \
+  --microcksURL http://localhost:8080/api \
+  --keycloakClientId my-client \
+  --keycloakClientSecret my-secret
+```
+- Import Multiple Files with Primary Indicator
+```bash
+microcks import openapi.yaml:true,postman.json:false \
+  --microcksURL https://microcks.example.com/api \
+  --keycloakClientId my-client \
+  --keycloakClientSecret my-secret
+```
+- Using Custom TLS CA Certificates and Verbose Logging
+```bash
+microcks-cli import spec.yaml \
+  --microcksURL https://microcks.example.com/api \
+  --keycloakClientId my-client \
+  --keycloakClientSecret my-secret \
+  --caCerts /etc/ssl/certs/ca1.crt,/etc/ssl/certs/ca2.crt \
+  --verbose
+```

documentation/cmd/importURL.md

@@ -0,0 +1,60 @@
+# ImportURL Command
+
+The `import-url` command in Microcks CLI is used to upload and register API specification artifacts(like OpenAPI, AsyncAPI, Postman collections, etc.) from URLs into a Microcks server.
+
+📝 Description
+
+The `import-url` command provides a convenient way to register API specifications (OpenAPI, AsyncAPI, Postman collections, etc.) hosted online without needing to download them manually. This is useful for CI/CD pipelines or importing frequently updated remote specs.
+
+📌 Usage
+```bash
+microcks import-url <url1[:primary]>,<url2[:primary]> \
+  --microcksURL <microcks-api-url> \
+  --keycloakClientId <client-id> \
+  --keycloakClientSecret <client-secret> \
+  [--insecure] \
+  [--caCerts <cert-paths>] \
+  [--verbose]
+```
+
+Arguments
+-   `<url[:primary]>`:
+A comma-separated list of publicly accessible URLs pointing to specification files.
+Optionally, each URL can be suffixed with `:true` or `:false` to mark it as a primary artifact.
+
+
+| Flag                    | Type    | Required | Description                                                                 |
+|-------------------------|---------|----------|-----------------------------------------------------------------------------|
+| `--microcksURL`         | string  | ✅        | The URL of the Microcks API endpoint.                                      |
+| `--keycloakClientId`    | string  | ✅        | The Keycloak Service Account Client ID for OAuth2 authentication.          |
+| `--keycloakClientSecret`| string  | ✅        | The Keycloak Service Account Client Secret for authentication.             |
+| `--insecure`            | bool    | ❌        | Allow insecure TLS connections (e.g., self-signed certs).                  |
+| `--caCerts`             | string  | ❌        | Comma-separated paths to additional CA certificate files (PEM format).     |
+| `--verbose`             | bool    | ❌        | Enable verbose mode to dump HTTP requests and responses to the console.    |
+
+🧪 Examples
+- Importing from a Single URL
+```bash
+microcks import-url https://example.com/api/openapi.yaml \
+  --microcksURL http://localhost:8080/api \
+  --keycloakClientId my-client \
+  --keycloakClientSecret my-secret
+```
+
+- Importing Multiple Remote Artifacts with Primary Designation
+```bash
+microcks import-url https://example.com/openapi.yaml:true,https://example.com/postman.json:false \
+  --microcksURL https://microcks.example.com/api \
+  --keycloakClientId my-client \
+  --keycloakClientSecret my-secret
+```
+
+- Using Custom TLS CA Certificates and Verbose Logging
+```bash
+microcks import-url https://mydomain.com/api/spec.yaml \
+  --microcksURL https://microcks.example.com/api \
+  --keycloakClientId my-client \
+  --keycloakClientSecret my-secret \
+  --caCerts /etc/ssl/certs/ca1.crt,/etc/ssl/certs/ca2.crt \
+  --verbose
+```

documentation/cmd/start.md

@@ -0,0 +1,34 @@
+# Start Command
+
+The `start` command allows you to launch a Microcks instance using a container runtime like Docker or Podman. It either starts a new container or resumes a previously created one based on saved configuration.
+
+📌 Usage
+```bash
+microcks start [flags]
+```
+
+🚩 Flags
+| Flag       | Description                                        | Required | Default                                        |
+| ---------- | -------------------------------------------------- | -------- | ---------------------------------------------- |
+| `--name`   | Name of the Microcks container/instance            | No       | `microcks`                                     |
+| `--port`   | Host port to expose Microcks                       | No       | `8585`                                         |
+| `--image`  | Image to use for creating the container            | No       | `quay.io/microcks/microcks-uber:latest-native` |
+| `--rm`     | Auto-remove container on exit (like `docker --rm`) | No       | `false`                                        |
+| `--driver` | Container runtime to use (`docker` or `podman`)    | No       | `docker`                                       |
+
+
+🧪 Examples
+
+Start Microcks with default settings:
+```sh
+microcks start
+```
+Start Microcks on port 9090 using Podman:
+```sh
+microcks start --port 9090 --driver podman
+```
+
+Start with a custom container name and image:
+```sh
+microcks start --name dev-microcks --image custom/microcks:latest
+```