Clarify Mint Format Instructions

cli/commands.mdx

@@ -2,7 +2,12 @@
 title: "Mintlify CLI command reference"
 sidebarTitle: "Commands"
 description: "Complete reference for Mintlify CLI commands and flags, including mint index, mint dev, mint validate, mint broken-links, and more."
-keywords: ["CLI", "mint", "commands", "flags", "reference"]
+keywords:
+  - "CLI"
+  - "mint"
+  - "commands"
+  - "flags"
+  - "reference"
 boost: 3
 ---
 
@@ -93,9 +98,9 @@
 
 | Client | Global configuration | Project configuration |
 | --- | --- | --- |
 | Claude Code | `~/.claude.json` | `.mcp.json` |
 | Cursor | `~/.cursor/mcp.json` | `.cursor/mcp.json` |
 | VS Code | User `mcp.json` | `.vscode/mcp.json` |
 | Codex | `~/.codex/config.toml` | `.codex/config.toml` |
 | OpenCode | `~/.config/opencode/opencode.json` | `opencode.json` |
 | Windsurf | `~/.codeium/windsurf/mcp_config.json` | Global only |
@@ -204,7 +209,7 @@
 
 Add the `TXT` records first, then add the `CNAME` once the verification records validate. See [Custom domain](/customize/custom-domain) for full DNS setup instructions, apex domain requirements, and TLS provisioning details.
 
 If the command fails with `Domain is already in use by another deployment in your organization` or `Domain is already claimed by another organization`, the domain is bound to another Mintlify deployment. See [Add domain fails with "Domain is already claimed by another organization"](/help-center/domain-already-claimed-by-another-organization) to release it and re-add it.
 
 <Note>
   If some `TXT` records are still generating when the command exits, check the [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) page in your dashboard for the remaining values.
@@ -351,7 +356,7 @@
 
 ### `mint analytics stats`
 
 Display top-line KPIs for a date range: views, visitors, searches, feedback, and assistant usage. The output reports human and agent traffic separately.
 
 ```bash
 mint analytics stats [flags]
@@ -500,7 +505,7 @@
 | `--check-redirects` | Also check that redirect destinations in `docs.json` resolve to valid paths. |
 | `--check-snippets` | Also check links inside `<Snippet>` components. |
 
 Pass `--files` to limit the check to specific pages. This is useful for validating a single page you just edited or scoping checks to a directory in CI. When `--files` is set with `--check-external`, only external URLs on the selected pages are fetched.
 
 ```bash
 # Check a specific page
@@ -639,13 +644,13 @@
 mint format
 ```
 
 Run the command from the root of your docs project. It walks every subdirectory, skipping paths matched by `.gitignore` and any Mintlify ignore rules. Files that already match the canonical output are left untouched.
 
 <Warning>
-  `mint format` rewrites files in place. Commit or stash your changes before running it so you can review the diff.
+  `mint format` rewrites files in place. Commit or stash your changes before running it so you can review the diff.<br /><br />Due to potentially large diffs, first resolve all important pending branches. Then create a new branch before running `mint format`.
 </Warning>
 
 When it finishes, the command prints how many MDX files were reformatted and how many failed to parse. If any file fails, the command exits with code `1` and prints the file path and error, so you can run it in CI to enforce consistent formatting.
 
 ---
 
@@ -700,7 +705,7 @@
 
 ## Telemetry
 
 The CLI collects anonymous usage telemetry to help improve Mintlify. Telemetry data includes the command name, CLI version, operating system, and architecture. Mintlify does **not** collect personally identifiable information, project content, or file paths.
 
 By default, the CLI collects telemetry data. You can opt out at any time using the `--telemetry` flag: