stacklok · samuv · Feb 4, 2026 · Feb 4, 2026 · Feb 4, 2026 · Feb 4, 2026
diff --git a/docs/toolhive/faq.mdx b/docs/toolhive/faq.mdx
@@ -34,6 +34,18 @@ comes with comprehensive documentation.
 Yes, ToolHive is open source (Apache 2.0 licensed) and free to use. You can find
 the source code on GitHub and use it without any licensing fees.
 
+### Can I use ToolHive UI and the standalone CLI together?
+
+No. When the ToolHive UI is installed, it manages the CLI installation for
+version compatibility. ToolHive UI creates a symlink to its bundled CLI and
+configures your PATH automatically. If you have a standalone CLI installed (via
+Homebrew, WinGet, or manually), it will show a conflict error when run.
+
+To use the CLI with ToolHive UI, simply open a new terminal after installing
+ToolHive UI. The `thv` command will use the UI-managed CLI. For more
+information, see the [CLI access guide](./guides-ui/cli-access.mdx) and
+[CLI and UI coexistence](./guides-cli/install.mdx#cli-and-ui-coexistence).
+
 ## Using MCP servers
 
 ### How do I find available MCP servers?

diff --git a/docs/toolhive/guides-cli/index.mdx b/docs/toolhive/guides-cli/index.mdx
@@ -17,12 +17,11 @@ custom permissions, network access filtering, and telemetry.
 It's designed for developers who prefer working in a terminal or need to
 integrate MCP server management into scripts or automation workflows.
 
-:::tip[Did you know?]
+:::info[Using ToolHive UI?]
 
-The ToolHive CLI can be used alongside the
-[ToolHive UI](../guides-ui/index.mdx), which provides a graphical interface. You
-can use both tools together to get the best of both worlds: the ease of use of a
-graphical interface and the flexibility of the CLI.
+If you have the ToolHive UI installed, it automatically manages the CLI for you.
+You don't need to install the CLI separately. See
+[CLI and UI coexistence](./install.mdx#cli-and-ui-coexistence) for details.
 
 :::
 

diff --git a/docs/toolhive/guides-cli/install.mdx b/docs/toolhive/guides-cli/install.mdx
@@ -154,6 +154,57 @@ information, see the [FAQ](../faq.mdx#does-toolhive-collect-any-data).
 
 :::
 
+## CLI and UI coexistence
+
+If you have the ToolHive UI installed, it automatically manages the CLI for
+version compatibility. ToolHive UI creates a symlink to its bundled CLI and
+configures your shell's PATH, so you don't need to install the CLI separately.
+
+When ToolHive UI manages the CLI, running a standalone CLI binary (installed via
+Homebrew, WinGet, or manually) shows a conflict error:
+
+```text title="CLI conflict error"
+Error: CLI conflict detected
+
+The ToolHive Desktop application manages a CLI installation at:
+  /Applications/ToolHive Studio.app/Contents/Resources/bin/darwin-arm64/thv
+
+You are running a different CLI binary at:
+  /usr/local/bin/thv
+
+To avoid conflicts, please use the desktop-managed CLI or uninstall
+the ToolHive Desktop application.
+
+To use the desktop-managed CLI, ensure your PATH includes:
+  ~/.toolhive/bin
+
+Or run the desktop CLI directly:
+  ~/.toolhive/bin/thv [command]
+
+Desktop version: 0.8.3
+```
+
+### Using the standalone CLI with ToolHive UI installed
+
+If you see this error, you have two options:
+
+1. **Use the UI-managed CLI (recommended)**: Open a new terminal window to pick
+   up the PATH changes. The `thv` command should now use the UI-managed CLI.
+
+2. **Uninstall the standalone CLI**: If you want to use only the UI-managed CLI,
+   uninstall the standalone version:
+   - Homebrew: `brew uninstall thv`
+   - WinGet: `winget uninstall stacklok.thv`
+   - Manual: Remove the binary from your PATH
+
+:::note[Debugging override]
+
+For debugging purposes, you can bypass the conflict check by setting
+`TOOLHIVE_SKIP_DESKTOP_CHECK=1`. This is not recommended for normal use as it
+may cause version compatibility issues.
+
+:::
+
 ## Upgrade ToolHive
 
 ToolHive automatically checks for updates and notifies you when a new version is

diff --git a/docs/toolhive/guides-ui/cli-access.mdx b/docs/toolhive/guides-ui/cli-access.mdx
@@ -0,0 +1,167 @@
+---
+title: Access the CLI from ToolHive UI
+description:
+  How to use the ToolHive CLI when using the ToolHive UI application for
+  advanced features and terminal-based workflows.
+---
+
+ToolHive UI includes the CLI for advanced users who want terminal access or
+features not yet available in the graphical interface. ToolHive UI automatically
+installs and manages the CLI, so you don't need to install it separately.
+
+## Why use the CLI with ToolHive UI?
+
+While the ToolHive UI covers most common tasks, you might want to use the CLI
+for:
+
+- **Advanced features**: Some features are available in the CLI before they're
+  added to the graphical interface
+- **Scripting and automation**: Integrate MCP server management into local
+  scripts or automated workflows
+- **Personal preference**: If you prefer working in a terminal for certain
+  tasks, the CLI is available without a separate installation
+
+## How ToolHive UI manages the CLI
+
+When you install ToolHive UI, it automatically:
+
+1. **Creates a symlink** to its bundled CLI binary:
+   - macOS/Linux: `~/.toolhive/bin/thv`
+   - Windows: `%LOCALAPPDATA%\ToolHive\bin\thv.exe`
+
+2. **Configures your PATH** by adding entries to your shell configuration files:
+   - Bash: `~/.bashrc`
+   - Zsh: `~/.zshrc`
+   - Fish: `~/.config/fish/config.fish`
+   - Windows: User PATH environment variable
+
+This ensures the CLI version always matches the ToolHive UI version, preventing
+compatibility issues with the API.
+
+:::note
+
+You don't need to install the CLI separately when using ToolHive UI. If you have
+a standalone CLI installed (via Homebrew, WinGet, or manually), it will show a
+conflict error. See the
+[CLI install guide](../guides-cli/install.mdx#cli-and-ui-coexistence) for
+details.
+
+:::
+
+## The Settings > CLI page
+
+ToolHive UI includes a dedicated settings page to manage the CLI installation.
+To access it:
+
+1. Open ToolHive UI.
+1. Click the **Settings** icon (gear icon) in the top navigation.
+1. Select **CLI** from the sidebar.
+
+### CLI Installation section
+
+The CLI Installation section displays:
+
+- **Status**: Shows whether the CLI is properly installed (Valid/Invalid)
+- **CLI Version**: The version number of the installed CLI
+- **Install Method**: How the CLI was installed (Symlink on macOS/Linux, Copy on
+  Windows)
+- **Managed by**: Confirms that ToolHive UI manages the CLI
+
+Click **Reinstall** to repair the CLI installation if needed.
+
+### CLI Location section
+
+This section shows:
+
+- The symlink path (for example, `~/.toolhive/bin/thv`)
+- The target path it points to (the bundled CLI inside the ToolHive UI app)
+
+### PATH Configuration section
+
+This section displays:
+
+- **Shell PATH** status: Confirms whether the CLI is accessible from your
+  terminal
+- **Modified files**: Lists the shell configuration files that were updated to
+  include the CLI in your PATH
+
+## Use CLI commands
+
+After ToolHive UI installation, you can use the CLI from your terminal:
+
+1. Open a new terminal window to pick up the PATH changes.
+
+2. Verify the CLI is available:
+
+   ```bash
+   thv version
+   ```
+
+3. Run any CLI command:
+
+   ```bash
+   thv list              # List running MCP servers
+   thv registry list     # Browse available servers
+   thv --help            # View all commands
+   ```
+
+For detailed command reference, see the [CLI guides](../guides-cli/index.mdx)
+and [command reference](../reference/cli/thv.md).
+
+## Troubleshooting
+
+<details>
+<summary>CLI not found in terminal</summary>
+
+If `thv` is not recognized after installing ToolHive UI:
+
+1. **Open a new terminal window**: The PATH changes only take effect in new
+   terminal sessions.
+
+2. **Check the Settings > CLI page**: Verify that the PATH Configuration shows
+   "Valid" status.
+
+3. **Manually source your shell configuration**:
+
+   ```bash
+   # Bash
+   source ~/.bashrc
+
+   # Zsh
+   source ~/.zshrc
+
+   # Fish
+   source ~/.config/fish/config.fish
+   ```
+
+4. **Reinstall the CLI**: Go to Settings > CLI and click **Reinstall**.
+
+</details>
+
+<details>
+<summary>Broken symlink after moving ToolHive UI</summary>
+
+If you move the ToolHive UI application to a different location, the CLI symlink
+may break. To fix this:
+
+1. Open ToolHive UI from its new location.
+2. Go to Settings > CLI.
+3. Click **Reinstall** to create a new symlink pointing to the correct location.
+
+</details>
+
+<details>
+<summary>CLI conflict error when running thv</summary>
+
+If you see "CLI conflict detected" when running `thv`, you have a standalone CLI
+installed alongside ToolHive UI. See the
+[CLI and UI coexistence](../guides-cli/install.mdx#cli-and-ui-coexistence)
+section for resolution steps.
+
+</details>
+
+## Related information
+
+- [CLI guides](../guides-cli/index.mdx)
+- [CLI command reference](../reference/cli/thv.md)
+- [CLI and UI coexistence](../guides-cli/install.mdx#cli-and-ui-coexistence)
diff --git a/docs/toolhive/guides-ui/index.mdx b/docs/toolhive/guides-ui/index.mdx
@@ -36,10 +36,10 @@ on something, [let us know](https://discord.gg/stacklok)!
 
 :::tip[Advanced users]
 
-If you want more control or want to experiment with more advanced features like
-custom permissions and telemetry, the ToolHive UI can work side-by-side with the
-[ToolHive CLI](../guides-cli/index.mdx) while still providing a graphical
-interface to quickly see and control your MCP servers.
+ToolHive UI includes the CLI for advanced users who want terminal access or
+features not yet available in the graphical interface. ToolHive UI automatically
+installs and manages the CLI, so you don't need to install it separately. See
+[Access the CLI from ToolHive UI](./cli-access.mdx) for details.
 
 :::
 

diff --git a/docs/toolhive/guides-ui/install.mdx b/docs/toolhive/guides-ui/install.mdx
@@ -205,6 +205,14 @@ improvement. Review the
 Now that you have ToolHive installed, you can start using it to run and manage
 MCP servers. See [Run MCP servers](./run-mcp-servers.mdx) to get started.
 
+:::tip[CLI access for advanced users]
+
+ToolHive UI includes the CLI for terminal access and advanced features like
+custom permissions, telemetry, and CI/CD integration. See
+[Access the CLI from ToolHive UI](./cli-access.mdx) to learn more.
+
+:::
+
 ## Related information
 
 - Quickstart:

diff --git a/sidebars.ts b/sidebars.ts
@@ -66,6 +66,7 @@ const sidebars: SidebarsConfig = {
           ],
         },
         'toolhive/guides-ui/client-configuration',
+        'toolhive/guides-ui/cli-access',
         'toolhive/guides-ui/mcp-optimizer',
         'toolhive/guides-ui/playground',
       ],