docs: enhance CLI configuration documentation and guidance

Add examples and guidance for using CLI flags to override profile settings while preserving authentic fingerprint data.

Author: MSTU0

README.md

@@ -158,6 +158,25 @@ chromium-browser \
   --bot-profile="/path/to/chrome139_win11_x64.enc"
 ```
 
+#### Flexible Configuration with CLI Flags
+```bash
+# Keep profile integrity, override only what you need
+chrome.exe --bot-profile="authentic_user.enc" \
+           --proxy-server="http://user:pass@proxy.com:8080" \
+           --bot-title="Session-A"
+
+# Same profile, different runtime settings
+chrome.exe --bot-profile="authentic_user.enc" \
+           --proxy-server="socks5://user:pass@proxy2.com:1080" \
+           --bot-title="Session-B"
+```
+
+> 💡 **CLI flags override profile settings without modifying the encrypted profile file**
+> 
+> This approach preserves authentic user fingerprints while enabling runtime flexibility.
+> 
+> 📖 **For all available CLI flags**, see [CLI Flags Reference](cli-flags.md)
+
 #### 2. [Playwright](examples/playwright) / [Puppeteer](examples/puppeteer) Examples
 
 ```javascript

cli-flags.md

@@ -7,6 +7,7 @@ This document provides a comprehensive reference for **BotBrowser-specific** com
 - [🎯 Core BotBrowser Flags](#-core-botbrowser-flags)
 - [🌐 Enhanced Proxy Configuration](#-enhanced-proxy-configuration)
 - [🎨 BotBrowser Customization](#-botbrowser-customization)
+- [⚙️ Profile Configuration Override Flags](#️-profile-configuration-override-flags)
 - [📝 Usage Examples](#-usage-examples)
 
 ---
@@ -42,7 +43,7 @@ BotBrowser enhanced the standard `--proxy-server` flag to accept embedded creden
 --proxy-server="http://username:password@proxy.example.com:8080"
 --proxy-server="https://username:password@proxy.example.com:8080"
 
-# SOCKS5 proxy with credentials  
+# SOCKS5 proxy with credentials
 --proxy-server="socks5://username:password@proxy.example.com:1080"
 ```
 
@@ -99,6 +100,63 @@ Accepts a JSON string containing bookmark data for startup.
 
 ---
 
+## ⚙️ Profile Configuration Override Flags
+
+**High-priority configuration overrides - these CLI flags override any profile settings**
+
+BotBrowser now supports command-line flags that override profile configuration values with the highest priority. These flags start with `--bot-config-` and directly map to profile `configs` properties.
+
+> 💡 **Recommended Approach:** Use these CLI flags instead of modifying profile files. They provide the highest priority and don't require editing profile JSON files.
+
+### Available Configuration Override Flags
+
+The following `--bot-config-*` flags correspond directly to profile `configs` properties:
+
+```bash
+--bot-config-browser-brand="chrome"           # Browser brand: chrome, chromium, edge, brave
+--bot-config-color-scheme="light"             # Color scheme: light, dark
+--bot-config-disable-debugger=true            # Disable JavaScript debugger: true, false
+--bot-config-disable-device-scale-factor=true # Disable device scale factor: true, false
+--bot-config-fonts="profile"                  # Font settings: profile (use profile fonts), real (system fonts)
+--bot-config-inject-random-history=true       # Inject random history: true, false
+--bot-config-keyboard="profile"               # Keyboard settings: profile (emulated), real (system keyboard)
+--bot-config-languages="en-US,en"             # Languages: "lang1,lang2" (comma-separated) or "auto" (IP-based)
+--bot-config-locale="en-US"                   # Browser locale: language code (e.g. en-US, zh-CN, fr-FR)
+--bot-config-location="40.7128,-74.0060"      # Location: "lat,lon" (coordinates) or "auto" (IP-based)
+--bot-config-media-devices="profile"          # Media devices: profile (fake devices), real (system devices)
+--bot-config-noise-audio-context=true         # Audio context noise: true, false
+--bot-config-noise-canvas=true                # Canvas fingerprint noise: true, false
+--bot-config-noise-client-rects=false         # Client rects noise: true, false
+--bot-config-noise-text-rects=true            # Text rects noise: true, false
+--bot-config-noise-webgl-image=true           # WebGL image noise: true, false
+--bot-config-screen="profile"                 # Screen properties: profile (use profile), real (system screen)
+--bot-config-speech-voices="profile"          # Speech voices: profile (synthetic), real (system voices)
+--bot-config-timezone="auto"                  # Timezone: "auto" (IP-based), "real" (system), or timezone name
+--bot-config-ua-full-version="139.0.6778.85"  # User agent version: full version string matching Chromium major
+--bot-config-webgl="profile"                  # WebGL: profile (use profile), real (system), disabled (off)
+--bot-config-webgpu="profile"                 # WebGPU: profile (use profile), real (system), disabled (off)
+--bot-config-webrtc="profile"                 # WebRTC: profile (use profile), real (native), disabled (off)
+--bot-config-window="profile"                 # Window dimensions: profile (use profile), real (system window)
+```
+
+### Key Benefits of CLI Configuration Flags
+
+**✅ Highest Priority:** These flags override any profile settings
+
+**✅ No Profile Editing:** Avoid modifying complex profile JSON files
+
+**✅ Dynamic Configuration:** Perfect for automated deployments and scripts
+
+**✅ Session Isolation:** Different configurations per browser instance without profile conflicts
+
+### Configuration Priority Order
+
+1. **🥇 CLI `--bot-config-*` flags** (Highest priority)
+2. **🥈 Profile `configs` settings** (Medium priority)
+3. **🥉 Profile default values** (Lowest priority)
+
+---
+
 ## 📝 Usage Examples
 
 ### Basic BotBrowser Setup
@@ -135,9 +193,40 @@ chromium-browser \
   --remote-debugging-port=9222
 ```
 
-### Complete Stealth Setup
+### Configuration Override Examples
+```bash
+# Override specific profile settings with CLI flags
+chromium-browser \
+  --bot-profile="./profiles/chrome139_win11_x64.enc" \
+  --bot-config-browser-brand="edge" \
+  --bot-config-timezone="Europe/London" \
+  --bot-config-webgl="disabled" \
+  --bot-config-noise-canvas=true \
+  --bot-title="Custom Session"
+```
+
+### Dynamic Multi-Instance Setup
+```bash
+# Instance 1 - Chrome brand with profile window settings
+chromium-browser \
+  --bot-profile="./profiles/profile.enc" \
+  --bot-config-browser-brand="chrome" \
+  --bot-config-window="profile" \
+  --bot-config-timezone="America/New_York" \
+  --user-data-dir="/tmp/instance1" &
+
+# Instance 2 - Edge brand with real window settings
+chromium-browser \
+  --bot-profile="./profiles/profile.enc" \
+  --bot-config-browser-brand="edge" \
+  --bot-config-window="real" \
+  --bot-config-timezone="Europe/London" \
+  --user-data-dir="/tmp/instance2" &
+```
+
+### Complete Stealth Setup with Configuration Overrides
 ```bash
-# All BotBrowser features combined
+# All BotBrowser features combined with CLI configuration
 chromium-browser \
   --no-sandbox \
   --headless \
@@ -146,6 +235,11 @@ chromium-browser \
   --bot-cookies='[{"name":"auth","value":"token123","domain":".site.com"}]' \
   --bot-bookmarks='[{"name":"Home","url":"https://example.com"}]' \
   --proxy-server="http://user:pass@proxy.example.com:8080" \
+  --bot-config-browser-brand="chrome" \
+  --bot-config-timezone="auto" \
+  --bot-config-webgl="profile" \
+  --bot-config-noise-canvas=true \
+  --bot-config-noise-webgl-image=true \
   --user-data-dir="$(mktemp -d)" \
   --remote-debugging-port=9222
 ```
@@ -165,7 +259,7 @@ chromium-browser \
 
 ### BotBrowser-Specific Considerations
 
-**Profile Priority:** Profile `configs` settings override equivalent CLI flags where applicable.
+**Configuration Priority:** CLI `--bot-config-*` flags have the highest priority and override profile `configs` settings.
 
 **Session Management:** Use `--bot-title` to easily identify different browser instances in your system.
 

profiles/README.md

@@ -114,19 +114,36 @@ await page.goto("https://abrahamjuliot.github.io/creepjs/");
 
 ---
 
-## ⚙️ Profile Configuration
+## 🎛️ Configuration Approaches
 
-**2025 Update:** Full environment customization now supported directly inside profiles.
+### Profile-Based Configuration
+- **Purpose**: Stores authentic user fingerprints and base settings
+- **When to use**: For core browser identity and fingerprint data
+- **Limitation**: Encrypted files are difficult to modify
 
-**Configurable Settings:**
-- Proxy configuration
-- Timezone and language
-- Screen size and device pixel ratio
-- System properties
+### CLI-Based Configuration  
+- **Purpose**: Runtime overrides without modifying profile files
+- **When to use**: For session-specific settings like proxy, title, cookies
+- **Advantage**: Preserves profile integrity while enabling flexibility
 
-👉 **See [`profile-configs.md`](https://github.com/botswin/BotBrowser/blob/main/profiles/profile-configs.md) for complete configuration options.**
+### Best Practice: Hybrid Approach
+```bash
+# Keep authentic fingerprint data in profile
+# Override session-specific settings via CLI
+--bot-profile="real_user_fingerprint.enc" \
+--proxy-server="session_specific_proxy" \
+--bot-title="current_session_id"
+```
 
-*No more manual CDP configuration required!*
+## ⚡ Why CLI Flags Matter
+- **🔒 Preserve authenticity**: Don't modify real user fingerprint data
+- **🚀 Runtime flexibility**: Adjust settings per session without file edits  
+- **💼 Session isolation**: Multiple instances with different settings
+- **🛡️ Security**: Keep sensitive data (like proxy credentials) out of profile files
+
+📖 **For complete CLI flags documentation**, see [CLI Flags Reference](../cli-flags.md)
+
+👉 **See [`profile-configs.md`](https://github.com/botswin/BotBrowser/blob/main/profiles/profile-configs.md) for complete configuration options.**
 
 ---
 

profiles/profile-configs.md

@@ -1,9 +1,12 @@
 # 📚 BotBrowser Profile Configuration Guide
 
-This document explains how to configure custom browser properties inside a **BotBrowser profile**, without relying on CDP.
+This document explains how to configure custom browser properties using **BotBrowser profiles** and **CLI configuration flags**.
+
+> 💡 **Recommended Approach:** Use CLI `--bot-config-*` flags instead of modifying profile files. CLI flags have the highest priority and don't require editing profile JSON files. See [CLI Flags Reference](../cli-flags.md#⚙️-profile-configuration-override-flags).
 
 ## 📋 Table of Contents
 
+- [⚙️ Configuration Priority System](#️-configuration-priority-system)
 - [⚠️ Important: Profile Data Integrity](#️-important-profile-data-integrity)
 - [🔧 How to Apply Configuration](#-how-to-apply-configuration)
 - [🛠️ Configurable Fields](#️-configurable-fields)
@@ -13,6 +16,36 @@ This document explains how to configure custom browser properties inside a **Bot
 
 ---
 
+## ⚙️ Configuration Priority System
+
+BotBrowser uses a three-tier priority system for configuration:
+
+### Priority Order (Highest to Lowest)
+
+1. **🥇 CLI `--bot-config-*` flags** - Highest priority, overrides everything
+2. **🥈 Profile `configs` settings** - Medium priority, overrides profile defaults  
+3. **🥉 Profile default values** - Lowest priority, built-in profile data
+
+### 💡 Why CLI Flags Are Recommended
+
+**✅ Highest Priority:** Always takes precedence over profile settings  
+**✅ No Profile Editing:** Avoid modifying complex encrypted profile files  
+**✅ Dynamic Configuration:** Perfect for automation and different environments  
+**✅ Session Isolation:** Different settings per browser instance without conflicts  
+
+**Example:**
+```bash
+# Use CLI flags to override profile settings dynamically
+chromium-browser \
+  --bot-profile="./profiles/profile.enc" \
+  --bot-config-browser-brand="edge" \
+  --bot-config-timezone="Europe/London"
+```
+
+> 📖 **Complete CLI flags reference:** [CLI Flags Reference](../cli-flags.md#⚙️-profile-configuration-override-flags)
+
+---
+
 ## ⚠️ Important: Profile Data Integrity
 
 **Profile data comes from real users; unless you are certain about the impact of a change, do not override any fingerprint property - keeping the defaults ensures the most authentic behavior.**
@@ -60,17 +93,15 @@ All configurations are embedded in the `configs` field inside your profile JSON
 | `proxy.username` | Proxy username for basic auth (optional). | `""`    |
 | `proxy.password` | Proxy password for basic auth (optional). | `""`    |
 
-> 💡 **Tip:** If you prefer not to embed proxy settings in your profile, you can use BotBrowser's CLI parameters instead:
-> ```bash
-> --proxy-server=<username:password@hostname:port>
-> --proxy-server=<scheme://username:password@hostname:port>
-> ```
-> or
->
+> 💡 **Better Approach:** Use CLI flags for proxy configuration:
 > ```bash
-> --proxy-server=<hostname:port>
-> --proxy-username=<user>
-> --proxy-password=<pass>
+> # Embedded credentials (recommended)
+> --proxy-server="http://username:password@proxy.example.com:8080"
+> 
+> # Separate credentials
+> --proxy-server="proxy.example.com:8080"
+> --proxy-username="username"
+> --proxy-password="password"
 > ```
 >
 > 📖 **For complete CLI flags documentation**, see [CLI Flags Reference](../cli-flags.md)
@@ -232,7 +263,7 @@ All configurations are embedded in the `configs` field inside your profile JSON
 - Profile data comes from real users; change only if necessary and you understand the impact.
 - All string fields support multi-purpose values: string literal (`"auto"`, `"real"`, or custom), or object schema when more parameters are needed.
 - If a field is omitted, BotBrowser uses profile defaults where appropriate.
-- Values in the `configs` block **override** equivalent command-line arguments like `--window-size`, `--window-position`, etc.
+- CLI `--bot-config-*` flags **override** profile `configs` settings with highest priority
 - **uaFullVersion Tip**: When JavaScript calls `navigator.userAgentData.fullVersion`, BotBrowser will replace the default value with this field. Ensure that the specified full version corresponds to the Chromium engine’s major version (e.g., Chromium 138 → full version should begin with “138.”). You can look up the latest full version for each major release on https://chromiumdash.appspot.com/releases.
 
 ---