diff --git a/src/content/docs/cli.mdx b/src/content/docs/cli.mdx
index 2541a2ea5f..42e7ad36d5 100644
--- a/src/content/docs/cli.mdx
+++ b/src/content/docs/cli.mdx
@@ -65,4 +65,5 @@ mergify --token your_token_here <command>
 | `mergify stack` | Create and manage stacked pull requests | [Stacks](/stacks) |
 | `mergify freeze` | Schedule and manage merge freezes | [Scheduling Freezes](/merge-protections/freeze) |
 | `mergify queue` | Monitor merge queue status | [Monitoring](/merge-queue/monitoring) |
+| `mergify config` | Validate and simulate config | [Config](/configuration/file-format#validating-with-the-cli) |
 | `mergify ci` | Upload and analyze CI results | [CI Insights](/ci-insights) |
diff --git a/src/content/docs/configuration/file-format.mdx b/src/content/docs/configuration/file-format.mdx
index 521b758da3..b2823767fc 100644
--- a/src/content/docs/configuration/file-format.mdx
+++ b/src/content/docs/configuration/file-format.mdx
@@ -269,3 +269,31 @@ file, consider the following troubleshooting steps:
 By following these troubleshooting steps, you can effectively identify and
 resolve any issues with your Mergify configuration file, ensuring a smooth and
 efficient automation process for your repository.
+
+## Validating with the CLI
+
+The [Mergify CLI](/cli) can check your configuration file locally before you
+push, catching errors without waiting for a round-trip to GitHub.
+
+### Validate
+
+Check your configuration against the Mergify schema:
+
+```bash
+mergify config validate
+```
+
+This catches syntax errors, invalid keys, and type mismatches. It reads
+`.mergify.yml`, `.mergify/config.yml`, or `.github/mergify.yml` from the
+current directory.
+
+### Simulate
+
+Test your rules against an existing pull request without applying any actions:
+
+```bash
+mergify config simulate https://github.com/owner/repo/pull/142
+```
+
+Shows which rules would match and what actions Mergify would take. Useful for
+testing rule changes before merging your configuration update.