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

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 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.
  2. Click the Settings icon (gear icon) in the top navigation.
  3. 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:

    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.

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" when running thv, you have a standalone CLI installed alongside ToolHive UI. See the CLI and UI coexistence section for resolution steps.