stacklok · samuv · Feb 10, 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,19 @@ 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 CLI together?
+
+Yes, but ToolHive UI manages the CLI automatically. When you install ToolHive
+UI, it creates a symlink to its bundled CLI and configures your PATH. You can
+use the `thv` command from your terminal—it uses the UI-managed version.
+
+If you have a standalone CLI installed separately (via Homebrew, WinGet, or
+manually), it will conflict with the UI-managed version and show an error.
+Uninstall the standalone version to resolve this.
+
+For more information, see the [CLI access guide](./guides-ui/cli-access.mdx) and
+[CLI conflict resolution](./guides-cli/install.mdx#cli-conflict-resolution).
+
 ## 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,12 @@ 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.
+ToolHive UI includes and manages the CLI automatically. You don't need to
+install the CLI separately. See
+[CLI conflict resolution](./install.mdx#cli-conflict-resolution) if you have
+both installed.
 
 :::
 

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 conflict resolution
+
+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.
+
+Running a standalone CLI binary (installed via Homebrew, WinGet, or manually)
+while ToolHive UI is installed 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
+```
+
+### Resolving the conflict
+
+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,140 @@
+---
+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
+
+## 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.
+
+1. Verify the CLI is available:
+
+   ```bash
+   thv version
+   ```
+
+1. 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).
+
+## 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`
+
+1. **Configures your PATH** by adding entries to your shell configuration files
+   (`.bashrc`, `.zshrc`, `config.fish`, or the Windows User PATH)
+
+This ensures the CLI version always matches the ToolHive UI version, preventing
+compatibility issues with the API.
+
+:::note
+
+If you have a standalone CLI installed (via Homebrew, WinGet, or manually), it
+will show a conflict error. See
+[CLI conflict resolution](../guides-cli/install.mdx#cli-conflict-resolution) for
+details.
+
+:::
+
+## The Settings > CLI page
+
+ToolHive UI includes a dedicated settings page to manage the CLI installation.
+Access it from **Settings** (gear icon) > **CLI**.
+
+The page displays:
+
+- CLI installation status and version
+- Symlink location and target path
+- Shell configuration status
+
+Use the **Reinstall** button if the CLI becomes unavailable or the symlink
+breaks (for example, after moving the ToolHive UI application).
+
+## 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.
+
+1. **Check the Settings > CLI page**: Verify that the PATH Configuration shows
+   "Valid" status.
+
+1. **Manually source your shell configuration**:
+
+   ```bash
+   # Bash
+   source ~/.bashrc
+
+   # Zsh
+   source ~/.zshrc
+
+   # Fish
+   source ~/.config/fish/config.fish
+   ```
+
+1. **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.
+1. Go to Settings > CLI.
+1. 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", you have both ToolHive UI and a standalone
+CLI installed. See
+[CLI conflict resolution](../guides-cli/install.mdx#cli-conflict-resolution) for
+the error message and resolution steps.
+
+</details>
+
+## Related information
+
+- [CLI guides](../guides-cli/index.mdx)
+- [CLI command reference](../reference/cli/thv.md)
+- [CLI conflict resolution](../guides-cli/install.mdx#cli-conflict-resolution)
diff --git a/docs/toolhive/guides-ui/index.mdx b/docs/toolhive/guides-ui/index.mdx
@@ -36,10 +36,9 @@ 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 and manages the CLI automatically for terminal access and
+advanced features. 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,13 @@ 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. 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',
       ],