CommunitySolidServer · joachimvh · Mar 4, 2025 · Mar 3, 2025 · Mar 4, 2025
diff --git a/documentation/markdown/README.md b/documentation/markdown/README.md
@@ -38,6 +38,7 @@ the [changelog](https://github.com/CommunitySolidServer/CommunitySolidServer/blo
 * [How to automatically seed pods on startup](usage/seeding-pods.md)
 * [Receiving notifications when resources change](usage/notifications.md)
 * [Using the CSS as a development server in another project](usage/dev-configuration.md)
+* [Adding a new CLI parameter to the server](usage/new-cli-parameter.md)
 * [Which authorization method to pick](usage/authorization-methods.md)
 
 ## What the internals look like

diff --git a/documentation/markdown/usage/new-cli-parameter.md b/documentation/markdown/usage/new-cli-parameter.md
@@ -0,0 +1,94 @@
+# Adding a new CLI parameter to initialize your server
+
+Sometimes, there is a value in your server configuration that you do not want to hardcode.
+A good example of this is the password for your email account,
+should you have one enabled.
+Fortunately, due to the customizability of the server,
+it is possible to add such an option entirely through additions to your `Components.js` configuration.
+Below is an overview of the required additions.
+The example covers how to use a variable for the email account password,
+but it can be generalized to any situation.
+
+For more details of how to configure the CLI system,
+have a look at the [architecture documentation](../architecture/features/cli.md).
+
+Although only a new CLI parameter is covered here,
+a new environment variable is also available as described in
+the [server initialization documentation](./starting-server.md).
+
+## Creating the variable
+
+For every variable in your configuration,
+you need to explicitly define that this URI corresponds to a variable.
+The block below defines a new variable named `urn:custom:default:variable:emailPass`.
+
+```json
+{
+  "@id": "urn:custom:default:variable:emailPass",
+  "@type": "Variable"
+}
+```
+
+## Parsing the CLI parameter
+
+For this example, we introduce a new CLI parameter `emailPass` and tell the server to parse it.
+We do this with the following block:
+
+```json
+{
+  "@id": "urn:solid-server-app-setup:default:CliExtractor",
+  "@type": "YargsCliExtractor",
+  "parameters": [
+    {
+      "@type": "YargsParameter",
+      "name": "emailPass",
+      "options": {
+        "requiresArg": true,
+        "type": "string",
+        "describe": "The password for the email server."
+      }
+    }
+  ]
+}
+```
+
+The `options` block can contain all values that are defined
+in the [yargs options documentation](https://yargs.js.org/docs/#api-reference-optionskey-opt).
+The above example tells the CLI parser that the `emailPass` parameter requires an argument to follow it,
+and that it needs to be interpreted as a string.
+
+## Putting the CLI value into the variable
+
+Once the CLI parameter has been parsed, we need to tell the server which variable to link to that value.
+Here we can reference the variable we defined above:
+
+```json
+{
+  "@id": "urn:solid-server-app-setup:default:ShorthandResolver",
+  "@type": "CombinedShorthandResolver",
+  "resolvers": [
+    {
+      "CombinedShorthandResolver:_resolvers_key": "urn:custom:default:variable:emailPass",
+      "CombinedShorthandResolver:_resolvers_value": {
+        "@type": "KeyExtractor",
+        "key": "emailPass"
+      }
+    }
+  ]
+}
+```
+
+This tells the server to extract the value from the CLI variable `emailPass`,
+and put it directly into the variable `urn:custom:default:variable:emailPass`,
+thus linking the previous two blocks together.
+
+## Using the variable in your configuration
+
+All of the above is to introduce the value of a CLI parameter into the configuration.
+From this point on, this value can be used anywhere in the configuration.
+For this part, let's assume that you already have a block in your configuration to define your email account settings.
+This could, for example, be the block generated by the [configuration generator](https://communitysolidserver.github.io/configuration-generator/).
+In that block, you now need to replace the password line,
+which probably looks something like `"emailConfig_auth_pass": "mySecretPassword`,
+with `"emailConfig_auth_pass": { "@id": "urn:custom:default:variable:emailPass" }`.
+From then on, when you start the server, the value assigned to the password will be the one provided through the CLI.
diff --git a/documentation/mkdocs.yml b/documentation/mkdocs.yml
@@ -93,6 +93,7 @@ nav:
       - Seeding pods: usage/seeding-pods.md
       - Notifications: usage/notifications.md
       - Development server: usage/dev-configuration.md
+      - Adding a new CLI parameter: usage/new-cli-parameter.md
       - Authorization methods: usage/authorization-methods.md
   - Architecture:
       - Overview: architecture/overview.md