pages/setup/command-line-options.md

@@ -22,7 +22,7 @@ oscam -b -c /etc/oscam
 oscam -d 255
 
 # Start with custom directories and pidfile
-oscam -b -c /etc/oscam -t /var/tmp/oscam -B /var/run/oscam.pid
+oscam -b -c /etc/oscam -t /var/tmp/oscam -B /run/oscam/oscam.pid
 ```
 
 ## Directory Configuration
@@ -46,25 +46,30 @@ Control how OSCam runs as a system process.
 
 | Option | Description | Notes |
 | --- | --- | --- |
-| `-b, --daemon` | Run as background daemon | Standard mode for production |
-| `-f, --foreground` | Run in foreground | Only on STAPI/STAPI5 systems |
+| `-b, --daemon` | Run as background daemon | Standard mode for normal non-STAPI builds |
+| `-f, --foreground` | Run in foreground | Available only on STAPI/STAPI5 builds |
 | `-B, --pidfile <file>` | Create PID file at specified path | Useful for init scripts |
 | `-w, --wait <seconds>` | Wait for system clock sync at startup | Default: `60` seconds |
 
 **Daemon vs Foreground:**
 
-- Use `-b` (daemon) for most systems to run OSCam in the background
-- Use `-f` (foreground) on STAPI/STAPI5 systems or when debugging
+- On standard builds, use `-b` to run OSCam in the background
+- On STAPI/STAPI5 builds, OSCam exposes `-f` instead of `-b`
+- For debugging on standard builds, simply omit `-b` and run OSCam attached to the terminal
 
 **Example:**
 
 ```bash
-oscam -b -B /var/run/oscam.pid -w 30
+oscam -b -B /run/oscam/oscam.pid -w 30
 ```
 
+If you do not pass `-B`, OSCam falls back to its configured `pidfile` setting or a default PID file in its temporary directory.
+
+For the `systemd` service example used in [Linux Installation](pages/installation/linux-installation), use `/run/oscam/oscam.pid` so it matches `RuntimeDirectory=oscam`. Outside that setup, any writable PID-file path is acceptable.
+
 ## Restart Behavior
 
-Configure how OSCam handles restart requests (requires WebIf module).
+Configure how OSCam handles restart requests. These options are only available when OSCam is built with WebIf support.
 
 | Option | Description |
 | --- | --- |
@@ -207,7 +212,7 @@ oscam -V
 oscam -b \
       -c /etc/oscam \
       -t /var/tmp/oscam \
-      -B /var/run/oscam.pid \
+      -B /run/oscam/oscam.pid \
       -r 2 \
       -I oscam-prod
 ```
@@ -246,9 +251,10 @@ oscam -d 65535 \
 
 ### For Production
 
-- Always use `-b` (daemon mode) on standard systems
+- Always use `-b` (daemon mode) on standard non-STAPI systems
 - Set `-r 2` for automatic recovery from crashes
 - Use `-B` with pidfile for proper init script integration
+- Keep the PID-file path aligned with your service manager, for example `/run/oscam/oscam.pid` when using `RuntimeDirectory=oscam`
 - Keep debug level at `0` unless troubleshooting
 
 ### For Testing
@@ -268,8 +274,8 @@ oscam -d 65535 \
 
 **STAPI/STAPI5 Systems:**
 
-- Use `-f` (foreground) instead of `-b` (daemon)
-- These platforms require foreground operation
+- These builds expose `-f` (foreground) instead of `-b` (daemon)
+- Do not expect both switches to be available in the same build
 
 **Embedded Devices:**