stacklok/toolhive/toolhive-cli-user

Trust tier 3
  • community
Source check pending

Checking that the SKILL.md file is still in the repository.

Guide for using ToolHive CLI (thv) to run and manage MCP servers, skills, and AI-client plugins. Use when managing `thv ai-plugin` installs, project sync or upgrades, or plugin publishing for Claude Code or Codex; also use for MCP server and skill lifecycle commands. Covers server lifecycle, registries, secrets, client registration, builds, permissions, skills, and AI plugins. NOT for Kubernetes operator usage, ToolHive development/contributing, or general AI-client configuration unrelated to ToolHive.

Install

npx vskill@latest install stacklok/toolhive/toolhive-cli-user

SKILL.md

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

bash
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.

bash
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

bash
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

bash
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:

bash
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.

bash
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).

bash
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:

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

Client Configuration

bash
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):

bash
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:

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

Volume mounts for filesystem access:

bash
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

bash
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).

bash
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.

bash
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:

bash
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

bash
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

This is the start of the file. Read the full SKILL.md on GitHub.

Security

  • Security scanPassed, 95 of 100Pattern checks on the skill's files.
  • Model reviewPassed

See the full security report

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

Popularity

Repository stars
2,230
Repository forks
309
7-day trend score
39

Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/stacklok/toolhive/toolhive-cli-user/badge)](https://verified-skill.com/skills/stacklok/toolhive/toolhive-cli-user)

Something wrong with this skill or its page? Tell us.