diff --git a/areal/api/cli_args.py b/areal/api/cli_args.py
index 7701dab081..e08c852ec4 100644
--- a/areal/api/cli_args.py
+++ b/areal/api/cli_args.py
@@ -1968,7 +1968,13 @@ def __post_init__(self):
 class WandBConfig:
     """Configuration for Weights & Biases experiment tracking."""
 
-    mode: str = "disabled"
+    mode: str = field(
+        default="disabled",
+        metadata={
+            "help": "Tracking mode. One of 'online', 'offline', 'disabled', or 'shared'.",
+            "choices": ["online", "offline", "disabled", "shared"],
+        },
+    )
     wandb_base_url: str = ""
     wandb_api_key: str = ""
     entity: str | None = None
@@ -1981,6 +1987,14 @@ class WandBConfig:
     config: dict | None = None
     id_suffix: str | None = "train"
 
+    def __post_init__(self):
+        """Validate WandB configuration."""
+        valid_modes = ("online", "offline", "disabled", "shared")
+        if self.mode not in valid_modes:
+            raise ValueError(
+                f"Invalid wandb mode: '{self.mode}'. Must be one of: {', '.join(valid_modes)}."
+            )
+
 
 @dataclass
 class SwanlabConfig:
@@ -1990,11 +2004,23 @@ class SwanlabConfig:
     name: str | None = None
     config: dict | None = None
     logdir: str | None = None
-    mode: str | None = "disabled"
+    mode: str = field(
+        default="disabled",
+        metadata={
+            "help": "Tracking mode. One of 'cloud', 'local', 'disabled', or 'offline'.",
+            "choices": ["cloud", "local", "disabled", "offline"],
+        },
+    )
     # set None to prevent info-leak in docs
     api_key: str | None = None
 
     def __post_init__(self):
+        """Validate SwanLab configuration."""
+        valid_modes = ("cloud", "local", "disabled", "offline")
+        if self.mode not in valid_modes:
+            raise ValueError(
+                f"Invalid swanlab mode: '{self.mode}'. Must be one of: {', '.join(valid_modes)}."
+            )
         if self.api_key is None:
             self.api_key = os.getenv("SWANLAB_API_KEY")
 
diff --git a/docs/en/cli_reference.md b/docs/en/cli_reference.md
index 3f05178349..d51c58866c 100644
--- a/docs/en/cli_reference.md
+++ b/docs/en/cli_reference.md
@@ -759,14 +759,14 @@ Configuration for experiment statistics logging and tracking services.
 
 Configuration for SwanLab experiment tracking and monitoring.
 
-| Parameter | Type           | Default      | Description |
-| --------- | -------------- | ------------ | ----------- |
-| `project` | string \| None | `None`       | -           |
-| `name`    | string \| None | `None`       | -           |
-| `config`  | `dict` \| None | `None`       | -           |
-| `logdir`  | string \| None | `None`       | -           |
-| `mode`    | string \| None | `"disabled"` | -           |
-| `api_key` | string \| None | `None`       | -           |
+| Parameter | Type           | Default      | Description                                                                                                            |
+| --------- | -------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| `project` | string \| None | `None`       | -                                                                                                                      |
+| `name`    | string \| None | `None`       | -                                                                                                                      |
+| `config`  | `dict` \| None | `None`       | -                                                                                                                      |
+| `logdir`  | string \| None | `None`       | -                                                                                                                      |
+| `mode`    | string         | `"disabled"` | Tracking mode. One of 'cloud', 'local', 'disabled', or 'offline'. **Choices:** `cloud`, `local`, `disabled`, `offline` |
+| `api_key` | string \| None | `None`       | -                                                                                                                      |
 
 (section-tensor-board)=
 
@@ -805,20 +805,20 @@ See: https://github.com/gradio-app/trackio
 
 Configuration for Weights & Biases experiment tracking.
 
-| Parameter        | Type                   | Default      | Description |
-| ---------------- | ---------------------- | ------------ | ----------- |
-| `mode`           | string                 | `"disabled"` | -           |
-| `wandb_base_url` | string                 | `""`         | -           |
-| `wandb_api_key`  | string                 | `""`         | -           |
-| `entity`         | string \| None         | `None`       | -           |
-| `project`        | string \| None         | `None`       | -           |
-| `name`           | string \| None         | `None`       | -           |
-| `job_type`       | string \| None         | `None`       | -           |
-| `group`          | string \| None         | `None`       | -           |
-| `notes`          | string \| None         | `None`       | -           |
-| `tags`           | list of string \| None | `None`       | -           |
-| `config`         | `dict` \| None         | `None`       | -           |
-| `id_suffix`      | string \| None         | `"train"`    | -           |
+| Parameter        | Type                   | Default      | Description                                                                                                                |
+| ---------------- | ---------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| `mode`           | string                 | `"disabled"` | Tracking mode. One of 'online', 'offline', 'disabled', or 'shared'. **Choices:** `online`, `offline`, `disabled`, `shared` |
+| `wandb_base_url` | string                 | `""`         | -                                                                                                                          |
+| `wandb_api_key`  | string                 | `""`         | -                                                                                                                          |
+| `entity`         | string \| None         | `None`       | -                                                                                                                          |
+| `project`        | string \| None         | `None`       | -                                                                                                                          |
+| `name`           | string \| None         | `None`       | -                                                                                                                          |
+| `job_type`       | string \| None         | `None`       | -                                                                                                                          |
+| `group`          | string \| None         | `None`       | -                                                                                                                          |
+| `notes`          | string \| None         | `None`       | -                                                                                                                          |
+| `tags`           | list of string \| None | `None`       | -                                                                                                                          |
+| `config`         | `dict` \| None         | `None`       | -                                                                                                                          |
+| `id_suffix`      | string \| None         | `"train"`    | -                                                                                                                          |
 
 (section-archon-engine)=
 
diff --git a/docs/zh/cli_reference.md b/docs/zh/cli_reference.md
index 21fb56f489..afd64db4af 100644
--- a/docs/zh/cli_reference.md
+++ b/docs/zh/cli_reference.md
@@ -757,14 +757,14 @@ Configuration for experiment statistics logging and tracking services.
 
 Configuration for SwanLab experiment tracking and monitoring.
 
-| Parameter | Type           | Default      | Description |
-| --------- | -------------- | ------------ | ----------- |
-| `project` | string \| None | `None`       | -           |
-| `name`    | string \| None | `None`       | -           |
-| `config`  | `dict` \| None | `None`       | -           |
-| `logdir`  | string \| None | `None`       | -           |
-| `mode`    | string \| None | `"disabled"` | -           |
-| `api_key` | string \| None | `None`       | -           |
+| Parameter | Type           | Default      | Description                                                                                                            |
+| --------- | -------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| `project` | string \| None | `None`       | -                                                                                                                      |
+| `name`    | string \| None | `None`       | -                                                                                                                      |
+| `config`  | `dict` \| None | `None`       | -                                                                                                                      |
+| `logdir`  | string \| None | `None`       | -                                                                                                                      |
+| `mode`    | string         | `"disabled"` | Tracking mode. One of 'cloud', 'local', 'disabled', or 'offline'. **Choices:** `cloud`, `local`, `disabled`, `offline` |
+| `api_key` | string \| None | `None`       | -                                                                                                                      |
 
 (section-tensor-board)=
 
@@ -803,20 +803,20 @@ See: https://github.com/gradio-app/trackio
 
 Configuration for Weights & Biases experiment tracking.
 
-| Parameter        | Type                   | Default      | Description |
-| ---------------- | ---------------------- | ------------ | ----------- |
-| `mode`           | string                 | `"disabled"` | -           |
-| `wandb_base_url` | string                 | `""`         | -           |
-| `wandb_api_key`  | string                 | `""`         | -           |
-| `entity`         | string \| None         | `None`       | -           |
-| `project`        | string \| None         | `None`       | -           |
-| `name`           | string \| None         | `None`       | -           |
-| `job_type`       | string \| None         | `None`       | -           |
-| `group`          | string \| None         | `None`       | -           |
-| `notes`          | string \| None         | `None`       | -           |
-| `tags`           | list of string \| None | `None`       | -           |
-| `config`         | `dict` \| None         | `None`       | -           |
-| `id_suffix`      | string \| None         | `"train"`    | -           |
+| Parameter        | Type                   | Default      | Description                                                                                                                |
+| ---------------- | ---------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| `mode`           | string                 | `"disabled"` | Tracking mode. One of 'online', 'offline', 'disabled', or 'shared'. **Choices:** `online`, `offline`, `disabled`, `shared` |
+| `wandb_base_url` | string                 | `""`         | -                                                                                                                          |
+| `wandb_api_key`  | string                 | `""`         | -                                                                                                                          |
+| `entity`         | string \| None         | `None`       | -                                                                                                                          |
+| `project`        | string \| None         | `None`       | -                                                                                                                          |
+| `name`           | string \| None         | `None`       | -                                                                                                                          |
+| `job_type`       | string \| None         | `None`       | -                                                                                                                          |
+| `group`          | string \| None         | `None`       | -                                                                                                                          |
+| `notes`          | string \| None         | `None`       | -                                                                                                                          |
+| `tags`           | list of string \| None | `None`       | -                                                                                                                          |
+| `config`         | `dict` \| None         | `None`       | -                                                                                                                          |
+| `id_suffix`      | string \| None         | `"train"`    | -                                                                                                                          |
 
 (section-archon-engine)=