Toolhive CLI User

ToolHive CLI User Guide

Prerequisites

• Container Runtime: Docker, Podman, Colima, or Rancher Desktop (with dockerd/moby)
• ToolHive CLI: Install with brew install stacklok/tap/thv (macOS/Linux) or winget install stacklok.thv (Windows)

Verify: thv version

Quick Start

thv run filesystem      # Run server from registry
thv list                # List running servers
thv status filesystem   # Detailed server info
thv logs filesystem     # View logs
thv stop filesystem     # Stop server
thv rm filesystem       # Remove server

Running MCP Servers

Five input methods: registry name, container image, protocol scheme (uvx://, npx://, go://), exported config (--from-config), or remote URL.

thv run filesystem                                          # Registry
thv run ghcr.io/github/github-mcp-server:latest -- <args>   # Container image
thv run uvx://mcp-server-git                                # Python (uvx)
thv run npx://@modelcontextprotocol/server-filesystem       # Node.js (npx)
thv run go://github.com/example/mcp-server                  # Go
thv run --from-config ./config.json                         # Exported config
thv run https://api.example.com/mcp --name my-remote        # Remote URL

For all flags, authentication options, and telemetry configuration, see COMMANDS.md. For detailed usage patterns, see EXAMPLES.md.

Managing Servers

thv list                          # Running servers
thv list --all                    # Include stopped
thv list --format json            # JSON output
thv list --format mcpservers      # MCP client config format
thv list --group production       # Filter by group

thv status filesystem             # Detailed server info (URL, port, transport, uptime)
thv status filesystem --format json

thv stop filesystem github        # Stop specific servers
thv stop --all                    # Stop all

thv start filesystem              # Resume stopped server
thv start --all                   # Start all stopped servers
thv start --group development     # Start all in group
thv restart filesystem            # Alias for start (backward compat)

thv rm filesystem github          # Remove servers
thv rm --all                      # Remove all

thv logs filesystem               # Container logs
thv logs filesystem --follow      # Real-time
thv logs filesystem --proxy       # Proxy logs
thv logs prune                    # Clean orphaned logs

Note: Remote servers trigger fresh OAuth authentication on start.

Registry Operations

thv registry list                    # List all servers
thv registry list --format json      # JSON output
thv search github                    # Search by keyword
thv registry info github             # Detailed server info

Custom registry:

thv config set-registry https://my-registry.example.com  # Remote
thv config set-registry /path/to/local/registry          # Local
thv config get-registry                                   # View current
thv config unset-registry                                 # Reset to default

Group Management

All servers are assigned to default group unless specified.

thv group create development           # Create group
thv group list                         # List groups
thv run fetch --group development      # Assign server to group
thv group run kubernetes               # Run all servers from registry group
thv group rm development               # Remove group (servers move to default)
thv group rm development --with-workloads  # Remove group AND its servers

Each server belongs to one group. To run same server in multiple groups, create uniquely named instances.

Secrets Management

Setup is required before use: thv secret setup (interactive provider selection).

Providers: Encrypted (AES-256-GCM, password in OS keyring) or 1Password (read-only, requires OP_SERVICE_ACCOUNT_TOKEN).

thv secret set MY_API_KEY              # Interactive input
echo "value" | thv secret set MY_KEY   # Piped input
thv secret list                        # List all
thv secret get MY_API_KEY              # Retrieve
thv secret delete MY_API_KEY           # Remove

Using secrets with servers:

thv run github --secret GITHUB_TOKEN,target=GITHUB_PERSONAL_ACCESS_TOKEN
thv run server --secret KEY1,target=ENV1 --secret KEY2,target=ENV2

Client Configuration

thv client status              # Check all supported clients
thv client setup               # Interactive setup
thv client register claude-code --group development  # Register with group
thv client list-registered     # List registered
thv client remove              # Remove client

Permissions and Network Isolation

Permission profiles control what a container can access (filesystem, network):

thv run myserver --permission-profile network          # Network access only
thv run myserver --permission-profile none             # No extra permissions
thv run myserver --permission-profile ./custom.json    # Custom profile (JSON)

Registry servers include a default profile. Without registry info, default is network.

Network isolation restricts outbound traffic to an allowlist via an egress proxy:

thv run myserver --isolate-network    # Block all outbound except allowlisted hosts

Volume mounts for filesystem access:

thv run filesystem -v /home/user/projects:/workspace:ro    # Read-only mount

.thvignore hides sensitive files from volume mounts using gitignore-style patterns. Place .thvignore in mounted directories or globally at ~/.config/toolhive/thvignore. Disable global patterns with --ignore-globally=false.

For detailed examples, see EXAMPLES.md.

Building, Export, and Tool Overrides

thv build uvx://mcp-server-git                                      # Build container
thv build --tag my-registry/server:v1.0 npx://package               # Custom tag
thv build --dry-run --output Dockerfile.mcp uvx://mcp-server-git    # Dockerfile only

thv export my-server ./config.json              # Export JSON
thv export my-server ./server.yaml --format k8s # Export Kubernetes YAML
thv run --from-config ./config.json             # Import config

For tool overrides, see EXAMPLES.md.

Skills Management

Requires thv serve to be running. Skills have two scopes: user (global, default) and project (local to a project root).

thv skill install my-skill                              # Install from registry
thv skill install ghcr.io/org/skill:v1.0                # Install by OCI reference
thv skill install my-skill --clients claude-code          # Target specific client(s)
thv skill install my-skill --scope project --project-root .  # Project-scoped
thv skill install my-skill --group development           # Add to group
thv skill install my-skill --force                       # Overwrite existing

thv skill list                                           # List all installed
thv skill ls --scope user --format json                  # Filter and format
thv skill ls --client claude-code --group dev            # Filter by client/group

thv skill info my-skill                                  # Show details
thv skill info my-skill --format json                    # JSON output

thv skill uninstall my-skill                             # Remove skill
thv skill uninstall my-skill --scope project --project-root .

thv skill validate ./my-skill-dir                        # Check skill definition
thv skill build ./my-skill-dir                           # Build OCI artifact
thv skill build ./my-skill-dir --tag ghcr.io/org/skill:v1.0
thv skill push ghcr.io/org/skill:v1.0                   # Push to registry

For all flags and detailed examples, see COMMANDS.md and EXAMPLES.md.

AI Plugin Management

Use thv ai-plugin for manifest-based bundles for AI clients, not ToolHive itself. Plugins may contain commands, agents, skills, hooks, and declared MCP/LSP entries; they are distinct from standalone ToolHive skills and MCP workloads. Plugin-declared MCP/LSP entries are not ToolHive-managed workloads.

These commands use the ToolHive API; start thv serve first. The supported plugin clients are claude-code and codex; target either, or all available clients, with --clients. Install an exact registry name, OCI reference, or git://host/org/repo[@ref][#subdir] source, then use list/info to inspect what ToolHive installed. Verification and lock-file trust are project-only: user-scoped installs do not use lock-file verification.

thv ai-plugin install example-plugin --clients claude-code
thv ai-plugin install ghcr.io/example-org/example-plugin:v1.0 --scope project --project-root .
thv ai-plugin install git://github.com/example-org/example-plugin@v1.0#plugin --scope project --project-root .
thv ai-plugin list --scope project --project-root .
thv ai-plugin sync --check --project-root .
thv ai-plugin upgrade --preview --project-root .

ToolHive extracts, registers, and enables Claude Code plugins. For Codex, ToolHive only materializes the ToolHive marketplace; complete activation yourself:

codex plugin install example-plugin@toolhive

ToolHive does not edit Codex config.toml or invoke Codex. Installed-component metadata only describes the extracted/materialized tree; it does not prove client activation. A client can leave unsupported components in that tree without loading them.

For command details, trust boundaries, and publishing, see COMMANDS.md and EXAMPLES.md.

Debugging

thv inspector filesystem                        # MCP Inspector UI
thv mcp list tools --server filesystem
thv mcp list resources --server filesystem
thv mcp list prompts --server filesystem
thv mcp call read_file --server filesystem --args '{"path":"/etc/hosts"}'  # Invoke a tool
thv runtime check                               # Verify container runtime

For tool invocation patterns (file args, stdin, JSON output, error handling), see EXAMPLES.md.

Guardrails

• NEVER use docker rm or podman rm on ToolHive-managed containers -- always use thv rm for proper cleanup.
• NEVER pass secrets as -e SECRET=value -- use --secret with managed secrets instead.
• Confirm destructive operations (thv rm --all, thv stop --all, thv group rm --with-workloads) with the user before running.
• Skill commands require thv serve to be running. If a skill command fails with a connection error, suggest starting thv serve first.
• AI plugin commands also require thv serve. Treat plugin content as AI-followed instructions: inspect the source and use project-scoped installs only in the intended project.
• For an externally key-pair-signed OCI plugin, give --public-key only on its first project install; ToolHive pins the key in toolhive.lock.yaml for sync and upgrade. Do not replace that pin without explicit review.
• Never add --allow-unsigned, --allow-signer-change, --allow-ref-change, --force, --prune, or --yes silently. Unsigned consent is explicit and does not bypass invalid signature verification. Confirm before sync/upgrade applies content or builds remove deletes a local artifact.
• If the user asks about Kubernetes deployment, this skill does not cover the operator -- direct them accordingly.

Error Handling

Global Options

• --debug: Verbose output
• -h, --help: Command help

Container runtime auto-detected: Podman -> Colima -> Docker.

See Also

• COMMANDS.md - Complete command reference with all flags
• EXAMPLES.md - Detailed usage examples and workflows