Skip to main content

Access the CLI from ToolHive UI

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.

  2. Verify the CLI is available:

    thv version

  3. Run any CLI command:

    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 and command reference.

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 (.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 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​

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
    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", you have both ToolHive UI and a standalone CLI installed. See CLI conflict resolution for the error message and resolution steps.