diff --git a/docs/cli/ory-update-oauth2-client.md b/docs/cli/ory-update-oauth2-client.md
index e25a1e040a..8bc2fdd1aa 100644
--- a/docs/cli/ory-update-oauth2-client.md
+++ b/docs/cli/ory-update-oauth2-client.md
@@ -15,7 +15,9 @@ Update an OAuth 2.0 Client
### Synopsis
-This command replaces an OAuth 2.0 Client by its ID. Please be aware that this command replaces the entire client. If only the name flag (-n "my updated app") is provided, the all other fields are updated to their default values.
+This command updates an OAuth 2.0 Client by its ID. Only the fields provided as flags are changed; all other fields keep their current values.
+
+To replace the entire client with a new configuration, use the --file flag. Fields missing from the file are reset to their default values.
```
ory update oauth2-client [id] [flags]
diff --git a/docs/hydra/cli/hydra-update-oauth2-client.md b/docs/hydra/cli/hydra-update-oauth2-client.md
index ecaf267bb5..905de6be0d 100644
--- a/docs/hydra/cli/hydra-update-oauth2-client.md
+++ b/docs/hydra/cli/hydra-update-oauth2-client.md
@@ -15,7 +15,9 @@ Update an OAuth 2.0 Client
### Synopsis
-This command replaces an OAuth 2.0 Client by its ID. Please be aware that this command replaces the entire client. If only the name flag (-n "my updated app") is provided, the all other fields are updated to their default values.
+This command updates an OAuth 2.0 Client by its ID. Only the fields provided as flags are changed; all other fields keep their current values.
+
+To replace the entire client with a new configuration, use the --file flag. Fields missing from the file are reset to their default values.
```
hydra update oauth2-client [id] [flags]
diff --git a/docs/hydra/guides/oauth2-clients.mdx b/docs/hydra/guides/oauth2-clients.mdx
index 5d5588bbed..532ef387b5 100644
--- a/docs/hydra/guides/oauth2-clients.mdx
+++ b/docs/hydra/guides/oauth2-clients.mdx
@@ -122,15 +122,17 @@ To update an existing OAuth2 client, use the following methods:
+To replace the entire client, pass a complete client definition from a file. Fields missing from the file are reset to their
+default values:
+
```
ory update oauth2-client --project --workspace {client.id} \
- --grant-type authorization_code --grant-type refresh_token --grant-type client_credentials \
- --response-type code \
- --scope openid --scope offline_access \
- --token-endpoint-auth-method client_secret_post \
- --redirect-uri https://a-new-callback
+ --file client.json
```
+To change individual fields without touching the rest of the configuration, pass them as flags instead. See
+[Patch OAuth2 client](#patch-oauth2-client).
+
@@ -162,6 +164,17 @@ To partially update an existing OAuth2 client, use the following methods:
3. Click on the **pen symbol** to update the client's configuration.
3. When you are finished, scroll to the top and click **Save**.
+
+
+
+Pass only the fields you want to change as flags. All other fields keep their current values:
+
+```
+ory update oauth2-client --project --workspace {client.id} \
+ --scope openid --scope offline_access \
+ --redirect-uri https://a-new-callback
+```
+