[Gap]: CLI guides gap analysis #654
Description
Summary
A systematic comparison of the CLI guides (docs/toolhive/guides-cli/) against the auto-generated CLI reference (docs/toolhive/reference/cli/) and the ToolHive source code reveals a number of documentation gaps. This issue captures the full analysis for prioritization.
Related issues and PRs
- [Gap]: Document authenticating to custom build registries #359 - Document authenticating to custom build registries (
set-build-auth-file) - [Gap]: Bearer token support in UI/CLI #456 - Bearer token support in UI/CLI
- Update docs for ToolHive v0.12.3–v0.13.0 #641 - Open PR covering v0.12.3-v0.13.0 changes (K8s/vMCP focus)
High-priority gaps
Entire features or commands with no coverage in CLI guides.
1. Skills system
The thv skill command tree (build, install, list, info, validate, push, uninstall) has no guide in guides-cli/. PR #641 adds thv skill install docs but only in the vMCP context. The CLI needs its own skills guide covering the full workflow.
2. Audit logging
--enable-audit and --audit-config flags on thv run are not mentioned in any CLI guide.
3. thv serve OIDC authentication
api-server.mdx states the API server has "no auth/authz" - this is now inaccurate. The thv serve command has full OIDC flags: --oidc-issuer, --oidc-client-id, --oidc-audience, --oidc-jwks-url, --oidc-introspection-url, --oidc-scopes. The guide needs to be corrected and the auth capability documented.
4. Registry login/logout
thv registry login and thv registry logout commands exist in the CLI reference but are not mentioned in registry.mdx.
5. Export to Kubernetes format
thv export --format k8s generates MCPServer YAML for Kubernetes. run-mcp-servers.mdx only documents JSON export.
6. Image verification
--image-verification flag on thv run (values: warn, enabled, disabled) controls container image trust verification. Not documented in any guide.
7. Bearer token support
Tracked in #456. --remote-auth-bearer-token and --remote-auth-bearer-token-file flags on thv run.
8. Build auth files for custom registries
Tracked in #359. thv config set-build-auth-file for npmrc/netrc/yarnrc authentication.
Medium-priority gaps
Missing flags or options in existing guides.
| # | Gap | Affected guide | Details |
|---|---|---|---|
| 1 | --publish / -p flag |
run-mcp-servers.mdx | Port publishing (hostPort:containerPort) not documented |
| 2 | --network flag |
run-mcp-servers.mdx | Network mode (host, custom network, bridge) not documented |
| 3 | --env-file / --env-file-dir |
run-mcp-servers.mdx | Loading env vars from files not documented; only -e is shown |
| 4 | --foreground / -f flag |
run-mcp-servers.mdx, manage-mcp-servers.mdx | Foreground mode not documented for thv run or thv start |
| 5 | --proxy-mode flag |
run-mcp-servers.mdx | Proxy mode selection (streamable-http vs sse) not documented |
| 6 | --runtime-image / --runtime-add-package |
build-containers.mdx, run-mcp-servers.mdx | Build/runtime customization flags not documented |
| 7 | thv status command |
manage-mcp-servers.mdx | Detailed server status command not mentioned; only thv list is shown |
| 8 | thv logs prune |
manage-mcp-servers.mdx | Log pruning subcommand not documented |
| 9 | thv restart |
manage-mcp-servers.mdx | Mentioned in install.mdx but missing from the lifecycle section in manage-mcp-servers.mdx |
| 10 | environment secrets provider |
secrets-management.mdx | TOOLHIVE_SECRET_* env var provider not documented; only encrypted and 1Password shown |
| 11 | thv secret provider command |
secrets-management.mdx | Direct provider setting for scripted/CI deployments not documented |
| 12 | Registry OIDC auth on set-registry |
registry.mdx | --issuer, --client-id, --audience, --scopes flags on thv config set-registry not documented |
| 13 | --allow-private-ip on set-registry |
registry.mdx | Private IP flag not documented |
| 14 | Newer supported clients | client-configuration.mdx | CLI reference shows amp-cli, gemini-cli, zed, windsurf, continue - verify all are listed in the guide |
Lower-priority gaps
Niche or advanced flags that may not need dedicated guide coverage but should be considered.
| # | Gap | Details |
|---|---|---|
| 1 | --label / -l |
Container labels on thv run |
| 2 | --trust-proxy-headers |
Trust X-Forwarded-* headers |
| 3 | --endpoint-prefix |
SSE endpoint path prefix |
| 4 | --allow-docker-gateway |
Allow Docker gateway connections with network isolation |
| 5 | --jwks-allow-private-ip, --jwks-auth-token-file |
JWKS flags for private deployments |
| 6 | --oidc-insecure-allow-http |
Allow HTTP OIDC for development |
| 7 | --resource-url |
RFC 9728 explicit resource URL |
| 8 | --remote-auth-callback-port |
OAuth callback port customization |
| 9 | --oidc-introspection-url |
Token introspection endpoint |
| 10 | --stop --timeout |
Configurable stop timeout |
| 11 | --list --label filter |
Label-based filtering on list |
Inaccuracies in existing docs
| # | Issue | Location | Details |
|---|---|---|---|
| 1 | API server described as having "no auth/authz" | api-server.mdx | thv serve now has full OIDC flags (see high-priority #3 above) |
| 2 | Missing restart from lifecycle section |
manage-mcp-servers.mdx | Shows stop/start/rm but not restart |
Methodology
This analysis compared three sources:
- CLI guides in
docs/toolhive/guides-cli/(20 files) - Auto-generated CLI reference in
docs/toolhive/reference/cli/(kept in sync with the CLI) - ToolHive CLI source code (command definitions and flag registrations)
Excluded from scope: thv proxy / thv proxy tunnel (the main use case is covered by thv run for remote servers; thv proxy stdio is already documented in the client compatibility reference).