Enhance CLI documentation with practical usage details

installation.mdx

@@ -1,7 +1,7 @@
 ---
 title: "Install the CLI"
 description: "Use the CLI to preview docs locally, test changes in real-time, and catch issues before deploying your documentation site."
 keywords: ["CLI", "npm", "local development", "Node.js"]
 ---
 
 <img
@@ -15,13 +15,13 @@
   alt="Decorative graphic representing the CLI."
 />
 
 Use the [CLI](https://www.npmjs.com/package/mint) to preview your documentation locally as you write and edit. View changes in real-time before deploying, test your documentation site's appearance and functionality, and catch issues like broken links or accessibility problems.
 
 The CLI also has utilities for maintaining your documentation, including commands to rename files, validate OpenAPI specifications, and migrate content between formats.
 
 ## Prerequisites
 
 - [Node.js](https://nodejs.org/en) v20.17.0+ (LTS versions recommended) installed
 - [Git](https://git-scm.com/downloads) installed
 - Your documentation repository cloned locally
 
@@ -30,7 +30,7 @@
 <Steps>
 <Step title="Locate your repository">
   1. Go to the [Git settings](https://dashboard.mintlify.com/settings/deployment/git-settings) page of your dashboard.
   2. Note your repository location. It is one of these formats:
     - `mintlify-community/docs-{org-name}-{id}` (Mintlify-hosted repository)
     - `your-org/your-repo` (your own GitHub repository)
 </Step>
@@ -61,7 +61,7 @@
 
 ## Install the CLI
 
 Run the following command to install the CLI:
 
 <CodeGroup>
   ```bash npm
@@ -83,34 +83,55 @@
 
 A local preview of your documentation is available at `http://localhost:3000`.
 
+The local preview:
+- Hot-reloads when you save changes to MDX files or `docs.json`
+- Mirrors your production documentation's appearance and functionality
+- Validates your content and displays warnings for issues
+- Works offline once initially loaded
+
 Alternatively, if you do not want to install the CLI globally, you can run a one-time script:
 
 ```bash
 npx mint dev
 ```
 
+<Note>
+Using `npx` downloads and runs the CLI without installing it globally. This is useful for trying the CLI or running it in CI/CD environments, but `mint dev` is faster for regular development.
+</Note>
+
 ### Custom ports
 
 By default, the CLI uses port 3000. You can customize the port using the `--port` flag. To run the CLI on port 3333, for instance, use this command:
 
 ```bash
 mint dev --port 3333
 ```
 
 If you attempt to run on a port that is already in use, the CLI uses the next available port:
 
 ```mdx
 Port 3000 is already in use. Trying 3001 instead.
 ```
 
-## Skip OpenAPI processing
+This is useful when:
+- Port 3000 is already in use by another application
+- You need to run multiple documentation sites simultaneously
+- Your development environment requires specific ports
+
+### Skip OpenAPI processing
 
 If you have many OpenAPI files, skip OpenAPI file processing during local development to improve performance by using the `--disable-openapi` flag:
 
 ```bash
 mint dev --disable-openapi
 ```
 
+This significantly speeds up the development server startup time when you have large or multiple OpenAPI specifications. Your API documentation pages will show placeholder content instead of generated content.
+
+<Warning>
+Use this flag only during content development. Always test with OpenAPI processing enabled before deploying to ensure your API documentation renders correctly.
+</Warning>
+
 ### Preview as a specific group
 
 If you use partial authentication to restrict access to your documentation, you can preview as a specific authentication group by using the `--groups [groupname]` flag.
@@ -121,6 +142,12 @@
 mint dev --groups admin
 ```
 
+This allows you to:
+- Test group-specific content visibility
+- Verify authentication rules work correctly
+- Preview documentation as different user types
+- Ensure restricted content displays properly for authorized groups
+
 ## Create a new project
 
 To create a new documentation project, run the following command:
@@ -129,17 +156,24 @@
 mint new [directory]
 ```
 
 This command clones the [starter kit](https://github.com/mintlify/starter) into a specified directory. If you do not specify a directory, the CLI tool prompts you to create a new subdirectory or overwrite the current directory.
 
 <Warning>
   Overwriting the current directory deletes any existing files.
 </Warning>
 
 The CLI tool prompts you for a project name and [theme](/customize/themes) to finish setting up your project.
 
+The starter kit includes:
+- Pre-configured `docs.json` with common settings
+- Sample MDX pages demonstrating components and formatting
+- Example navigation structure
+- Basic styling and theme configuration
+- Ready-to-use folder structure
+
 You can run `mint new` with the following flags:
 
-* `--theme`: Set the theme of the new project.
+* `--theme`: Set the theme of the new project (options: `quill`, `linden`, `venus`, `petal`).
 * `--name`: Set the name of the new project.
 * `--force`: Overwrite the current directory if it already exists.
 
@@ -148,15 +182,25 @@
 ```bash
 mint new docs --name my-project --theme linden
 ```
+
+<Tip>
+After creating a new project, run `mint dev` in the project directory to preview your documentation and start customizing it.
+</Tip>
 ## Update the CLI
 
 If your local preview is out of sync with what you see on the web in the production version, update your local CLI:
 
 ```bash
 mint update
 ```
 
+You should update the CLI when:
+- Your local preview doesn't match production
+- New features or components aren't rendering locally
+- You encounter unexpected errors or warnings
+- Release notes mention CLI updates
+
 If this `mint update` command is not available on your local version, re-install the CLI with the latest version:
 
  <CodeGroup>
     ```bash npm
@@ -168,6 +212,10 @@
     ```
   </CodeGroup>
 
+<Tip>
+Check for CLI updates regularly to ensure you have the latest features and bug fixes. Run `mint --version` to see your current version.
+</Tip>
+
 ## Additional commands
 
 ### Find broken links
@@ -178,8 +226,13 @@
 mint broken-links
 ```
 
 The command ignores files matching [.mintignore](/organize/mintignore) patterns. Links that point to ignored files are reported as broken.
 
+This is useful for:
+- Catching broken links before deploying to production
+- Identifying outdated references after restructuring your documentation
+- Ensuring all navigation items point to valid pages
+
 ### Find accessibility issues
 
 Test the color contrast ratios and search for missing alt text on images and videos in your documentation with the following command:
@@ -198,6 +251,12 @@
 mint a11y --skip-alt-text
 ```
 
+The accessibility checker helps you:
+- Meet WCAG 2.1 AA standards for color contrast
+- Ensure all images and videos have descriptive alt text
+- Improve documentation usability for users with visual impairments
+- Identify accessibility issues before they reach production
+
 ### Check OpenAPI spec
 
 Check your OpenAPI file for errors with the following command:
@@ -206,8 +265,16 @@
 mint openapi-check <OpenAPI filename or URL>
 ```
 
 Pass a filename (for example, `./openapi.yaml`) or a URL (for example, `https://petstore3.swagger.io/api/v3/openapi.json`).
 
+This command validates:
+- OpenAPI specification syntax and structure
+- Required fields and proper formatting
+- Schema definitions and references
+- Compatibility with Mintlify's API documentation features
+
+Use this before deploying to catch specification errors early and ensure your API documentation renders correctly.
+
 ### Rename files
 
 Rename and update all references to files with the following command:
@@ -216,6 +283,14 @@
 mint rename <path/to/old-filename> <path/to/new-filename>
 ```
 
+This command automatically:
+- Renames the specified file
+- Updates all internal links pointing to the old filename
+- Updates navigation references in `docs.json`
+- Preserves your documentation's link integrity
+
+This is safer than manually renaming files, which can break internal links and navigation.
+
 ### Migrate MDX endpoint pages
 
 Migrate MDX endpoint pages to autogenerated pages from your OpenAPI specification with the following command:
@@ -226,13 +301,43 @@
 
 This command converts individual MDX endpoint pages to autogenerated pages defined in your `docs.json`, moves MDX content to the `x-mint` extension in your OpenAPI specification, and updates your navigation. See [Migrating from MDX](/guides/migrating-from-mdx) for detailed information.
 
+Benefits of migration:
+- Automatically sync API documentation with your OpenAPI spec
+- Reduce manual maintenance of endpoint documentation
+- Ensure consistency between your API spec and documentation
+- Keep custom content while leveraging auto-generation
+
+### Get CLI version
+
+Check your current CLI version with the following command:
+
+```bash
+mint --version
+```
+
+Use this to verify you're running the latest version or when troubleshooting issues.
+
+### Get help
+
+View all available commands and options with the following command:
+
+```bash
+mint --help
+```
+
+For help with a specific command, use:
+
+```bash
+mint <command> --help
+```
+
 ## Formatting
 
 While developing locally, we recommend using extensions in your IDE to recognize and format MDX files.
 
 If you use Cursor, Windsurf, or VS Code, we recommend the [MDX VS Code extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting.
 
 If you use JetBrains, we recommend the [MDX IntelliJ IDEA plugin](https://plugins.jetbrains.com/plugin/14944-mdx) for syntax highlighting, and setting up [Prettier](https://prettier.io/docs/webstorm) for code formatting.
 
 ## Troubleshooting
 
@@ -245,7 +350,7 @@
     3. Reinstall the mint CLI: `npm install -g mint`
   </Accordion>
   <Accordion title="Issue: Encountering an unknown error">
     **Solution**: Go to the root of your device and delete the `~/.mintlify` folder. Afterwards, run `mint dev` again.
   </Accordion>
   <Accordion title="Error: permission denied">
     This is due to not having the required permissions to globally install node packages.
@@ -253,12 +358,12 @@
     **Solution**: Try running `sudo npm i -g mint`. You will be prompted for your password, which is the one you use to unlock your computer.
   </Accordion>
   <Accordion title="The local preview doesn't look the same as my docs do on the web">
     This is likely due to an outdated version of the CLI.
 
    **Solution:** Run `mint update` to get the latest changes.
   </Accordion>
   <Accordion title="mintlify vs. mint package">
     If you have any problems with the CLI package, you should first run `npm ls -g`. This command shows what packages are globally installed on your machine.
 
     If you don't use npm or don't see it in the -g list, try `which mint` to locate the installation.