toolhive-cli-user
Guide for using ToolHive CLI (thv) to run and manage MCP servers and skills. Use when running, listing, stopping, building, or configuring MCP servers locally. Covers server lifecycle, registry browsing, secrets management, client registration, groups, container builds, exports, permissions, network isolation, authentication, and skill management (install, uninstall, list, info, build, push, validate). NOT for Kubernetes operator usage or ToolHive development/contributing.
- License 许可
- Apache-2.0
- 最近更新
- 2026-08-31
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- toolhive-cli-user
- license
- Apache-2.0
- version
- 0.3.0
- description
- Guide for using ToolHive CLI (thv) to run and manage MCP servers and skills. Use when running, listing, stopping, building, or configuring MCP servers locally. Covers server lifecycle, registry browsing, secrets management, client registration, groups, container builds, exports, permissions, network isolation, authentication, and skill management (install, uninstall, list, info, build, push, validate). NOT for Kubernetes operator usage or ToolHive development/contributing.
02 资源文件 2
- 参考文档references/COMMANDS.md12.0 KB
- 参考文档references/EXAMPLES.md12.1 KB
03 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) orwinget 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.
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 rmorpodman rmon ToolHive-managed containers -- always usethv rmfor proper cleanup. - NEVER pass secrets as
-e SECRET=value-- use--secretwith 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 serveto be running. If a skill command fails with a connection error, suggest startingthv servefirst. - If the user asks about Kubernetes deployment, this skill does not cover the operator -- direct them accordingly.
Error Handling
| Symptom | Cause | Recovery |
|---|---|---|
| Container can't reach localhost | Bridge network isolation | Use host.docker.internal (Docker Desktop), host.containers.internal (Podman), 172.17.0.1 (Linux) |
| Port already in use | Another server on same port | Use --proxy-port <different-port> |
| Permission denied on volume | Mount path or profile issue | Check volume mount paths and permission profiles (--permission-profile) |
| Container runtime not found | No runtime or socket issue | Run thv runtime check; override socket with TOOLHIVE_PODMAN_SOCKET, TOOLHIVE_COLIMA_SOCKET, or TOOLHIVE_DOCKER_SOCKET |
| Secret operation fails | Provider not configured | Run thv secret setup first |
| Image pull fails | Network or auth issue | Check network connectivity; for private registries, ensure credentials are configured |
| Remote auth token expired | OAuth token lifetime exceeded | Restart the server (thv restart) to trigger fresh authentication |
| Sensitive files exposed in mount | No .thvignore configured |
Add .thvignore in mounted directory or globally at ~/.config/toolhive/thvignore |
| Skill command fails with connection error | thv serve not running |
Start thv serve before using skill commands |
| Skill validation fails | Invalid SKILL.md or directory structure | Run thv skill validate ./path and fix reported errors |
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
04 同仓库更多 Skills
skill-installer
Install Codex skills into $CODEX_HOME/skills from a curated list or a GitHub repo path. Use when a user asks to list installable skills, install a curated skill, or install a skill from another repo (including private repos).
skill-creator
Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Codex's capabilities with specialized knowledge, workflows, or tool integrations.
openai-docs
Use for Codex models/pricing, scheduled tasks, skills, settings, setup, troubleshooting, customization, automations, and self-knowledge—including 'you,' 'your,' 'this app,' or 'this coding agent' when they refer to Codex—and for OpenAI APIs/products and ChatGPT Work. Also use for model choice/migration, prompting, SDKs, Responses, Realtime, agents, evals, and Chat/Work/Codex comparisons. Do not use for generic app/software tasks that merely mention Codex.
imagegen
Generate or edit raster images when the task benefits from AI-created bitmap visuals such as photos, illustrations, textures, sprites, mockups, or transparent-background cutouts. Use when Codex should create a brand-new image, transform an existing image, or derive visual variants from references, and the output should be a bitmap asset rather than repo-native code or vector. Do not use when the task is better handled by editing existing SVG/vector/code-native assets, extending an established icon or logo system, or building the visual directly in HTML/CSS/canvas.
skill-creator-cc
Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, update or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
prd-writing-guide
Write complete, unambiguous PRDs that development teams can implement without guesswork. Includes requirement discovery framework, structured documentation methodology, completeness checklists, and common pitfall avoidance. Use when: writing new PRDs, reviewing PRD drafts, validating requirement completeness, preparing for engineering handoff. Triggers: 'write PRD', '写PRD', '产品需求文档', '需求文档', '需求规格', '需求评审', '完善需求', 'create requirements doc', 'product requirements', 'feature spec', 'requirements document'. Anti-triggers: 'technical design doc', 'architecture design', 'implementation plan', 'API design', '架构设计', '技术方案', '实现方案', '接口设计'.