From f5cacfa9ab754372ab6e4a5dbdae4c5c7fb11c24 Mon Sep 17 00:00:00 2001 From: Samuele Verzi Date: Wed, 4 Feb 2026 12:31:19 +0100 Subject: [PATCH 1/7] Add CLI access guide for ToolHive UI Document how ToolHive UI manages CLI installation, the Settings > CLI page, and troubleshooting for CLI access issues. --- docs/toolhive/guides-ui/cli-access.mdx | 167 +++++++++++++++++++++++++ sidebars.ts | 1 + 2 files changed, 168 insertions(+) create mode 100644 docs/toolhive/guides-ui/cli-access.mdx diff --git a/docs/toolhive/guides-ui/cli-access.mdx b/docs/toolhive/guides-ui/cli-access.mdx new file mode 100644 index 00000000..cc9271fb --- /dev/null +++ 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 Desktop. +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 Studio 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 + +
+CLI not found in terminal + +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**. + +
+ +
+Broken symlink after moving ToolHive UI + +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. + +
+ +
+CLI conflict error when running thv + +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. + +
+ +## 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/sidebars.ts b/sidebars.ts index fede9f63..46da0bda 100644 --- 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', ], From 97387cbbf69a567cbb755a4bf1a19d5143d1eeab Mon Sep 17 00:00:00 2001 From: Samuele Verzi Date: Wed, 4 Feb 2026 12:31:32 +0100 Subject: [PATCH 2/7] Update index pages with CLI/UI coexistence info Revise tips in UI and CLI index pages to reflect that ToolHive UI manages CLI installation automatically. --- docs/toolhive/guides-cli/index.mdx | 9 ++++----- docs/toolhive/guides-ui/index.mdx | 8 ++++---- 2 files changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/toolhive/guides-cli/index.mdx b/docs/toolhive/guides-cli/index.mdx index 3a0fc7f1..ad14c13e 100644 --- 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-ui/index.mdx b/docs/toolhive/guides-ui/index.mdx index 7d84a221..8aef6ce4 100644 --- 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. ::: From 1ffc05bec15c084384db5b0094eab0ba060a0d28 Mon Sep 17 00:00:00 2001 From: Samuele Verzi Date: Wed, 4 Feb 2026 12:31:42 +0100 Subject: [PATCH 3/7] Add CLI and UI coexistence section to CLI install guide Document conflict detection when standalone CLI runs alongside ToolHive UI, including error message and resolution options. --- docs/toolhive/guides-cli/install.mdx | 51 ++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/docs/toolhive/guides-cli/install.mdx b/docs/toolhive/guides-cli/install.mdx index 267063c5..e48c34c4 100644 --- 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 From 7f77db27085d5adcb74859dd777fb4fa99e523e1 Mon Sep 17 00:00:00 2001 From: Samuele Verzi Date: Wed, 4 Feb 2026 12:31:53 +0100 Subject: [PATCH 4/7] Add CLI access tip to UI install guide Link to new CLI access guide in the Next steps section. --- docs/toolhive/guides-ui/install.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/toolhive/guides-ui/install.mdx b/docs/toolhive/guides-ui/install.mdx index 2601a139..b70c5219 100644 --- 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: From 5d62c86005620414be91630ce95f2e376054260c Mon Sep 17 00:00:00 2001 From: Samuele Verzi Date: Wed, 4 Feb 2026 12:32:09 +0100 Subject: [PATCH 5/7] Add FAQ entry for CLI/UI coexistence Explain that ToolHive UI and standalone CLI cannot be used together. --- docs/toolhive/faq.mdx | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/toolhive/faq.mdx b/docs/toolhive/faq.mdx index 572f09fa..cc016a1f 100644 --- 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? From 7077b803c9a5b753829614fc3d130ee7381562f9 Mon Sep 17 00:00:00 2001 From: Samuele V <4377202+samuv@users.noreply.github.com> Date: Thu, 5 Feb 2026 14:51:34 +0100 Subject: [PATCH 6/7] Update docs/toolhive/guides-ui/cli-access.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/toolhive/guides-ui/cli-access.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/toolhive/guides-ui/cli-access.mdx b/docs/toolhive/guides-ui/cli-access.mdx index cc9271fb..0d2ec601 100644 --- a/docs/toolhive/guides-ui/cli-access.mdx +++ b/docs/toolhive/guides-ui/cli-access.mdx @@ -65,7 +65,7 @@ The CLI Installation section displays: - **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 Studio manages the CLI +- **Managed by**: Confirms that ToolHive UI manages the CLI Click **Reinstall** to repair the CLI installation if needed. From d89cfdf62988981cedeba0c00e84d51ab3f78ffc Mon Sep 17 00:00:00 2001 From: Samuele V <4377202+samuv@users.noreply.github.com> Date: Thu, 5 Feb 2026 15:04:37 +0100 Subject: [PATCH 7/7] Update docs/toolhive/guides-ui/cli-access.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/toolhive/guides-ui/cli-access.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/toolhive/guides-ui/cli-access.mdx b/docs/toolhive/guides-ui/cli-access.mdx index 0d2ec601..0e5525f5 100644 --- a/docs/toolhive/guides-ui/cli-access.mdx +++ b/docs/toolhive/guides-ui/cli-access.mdx @@ -53,7 +53,7 @@ details. ToolHive UI includes a dedicated settings page to manage the CLI installation. To access it: -1. Open ToolHive Desktop. +1. Open ToolHive UI. 1. Click the **Settings** icon (gear icon) in the top navigation. 1. Select **CLI** from the sidebar.