CLI UX gaps around updating/recreating an existing workload's config

[reyortiz3]

Summary

Investigating a customer report (TKT-90) about thv run fetch "seeming off" on v0.44.0/macOS surfaced several CLI UX gaps around updating/recreating an existing workload's configuration, plus one silently-swallowed error. None of these are specific to the fetch server — they apply to any named workload.

Reproduced against main @ 4440a7ddf unless noted otherwise.

Issues found

1. Unhelpful "already exists" error on thv run. cmd/thv/app/run.go:233 — running thv run <name> for a workload that already exists (even if stopped) returns workload with name 'x' already exists with no pointer to the fix. Should suggest remediation, e.g. ... already exists; run 'thv rm <name>' to remove it first, or 'thv start <name>' to resume it.

2. thv list (default) hides stopped workloads, contradicting the "already exists" error. thv list only shows running/auth_retrying workloads by default; a stopped workload needs thv list --all/-a. This means a user can see "No MCP servers found" from list while thv run <name> correctly (but confusingly) reports "already exists" for that same name. Reproduced: thv run fetch → thv stop fetch → thv list shows nothing → thv run fetch → already-exists error.

3. thv start/thv restart silently reject run-time config flags with a bare "unknown flag" error. thv start is an alias for restartCmd (cmd/thv/app/restart.go:22-31) and only accepts --all, --group, -f/--foreground — it resumes a workload from its already-persisted config and was never meant to take flags like --permission-profile or --allow-docker-gateway (those live only on thv run, cmd/thv/app/run_flags.go). The generic Cobra "unknown flag" error doesn't explain why, which led a user to cycle through start/restart trying to apply a new permission profile before finding the correct flow (thv rm <name> then thv run ... <name> again).

4. No top-level thv --version flag, only the thv version subcommand (cmd/thv/app/version.go). Inconsistent with how prominently the CLI already surfaces version info via its upgrade-nag banner on every command.

5. Upgrade-nag banner prints unconditionally, even on commands that immediately fail. checkForUpdates() (pkg/updates/checker.go) is called at cmd/thv/app/commands.go:86, inside NewRootCmd() before cmd.Execute() — so it fires before Cobra even parses/validates flags. A user gets "A new version of ToolHive is available" noise on top of an unknown flag error, adding confusion in an already-confusing error loop.

6. Registry-lookup errors are silently swallowed and misreported as a container-image pull failure. handleRegistryLookup (pkg/runner/retriever/retriever.go:218-254) calls provider.GetServer(serverOrImage); any error from that call (genuine not-found, parse failure, network/API error, ambiguous short-name match) is swallowed at lines 247-251 and silently treated as "not in registry, try as a literal image reference." The real cause is only logged at slog.Debug and never surfaced to the user. This produces a misleading final error like failed to retrieve or pull image: image not found in registry, please check the image name or tag: fetch — which reads like the server name wasn't found, but is actually a suppressed registry-lookup failure being masked as a raw image-pull attempt. Should at minimum surface a Warn-level message like could not resolve '%s' via registry (%v), attempting to pull as a container image so users aren't left debugging a confusing error with no visibility into the real cause.

Suggested fixes (not exhaustive, open to discussion)

• Add remediation hints to the "already exists" error (item 1).
• Either default thv list to include stopped workloads, or clarify in --help/docs that a "not shown" workload may still block thv run (item 2).
• Improve the error path for run-only flags passed to start/restart (item 3), e.g. detect known run-flags and return a clearer message.
• Add a top-level --version flag as an alias for thv version (item 4).
• Skip or defer the upgrade-check banner until after flag parsing/validation succeeds, or suppress it on error exits (item 5).
• Surface the swallowed registry-lookup error at Warn level instead of Debug (item 6).

Docs follow-up (tracked separately, not in this repo)

The public guide (docs.stacklok.com/toolhive/guides-mcp/fetch) has no guidance for updating an existing workload's config — it should mention thv rm <name> as the required step before re-running with new flags, and clarify that thv start/restart cannot apply new config.

[reyortiz3]

Follow-up: root cause of the "image not found in registry: fetch" symptom

Traced the customer's specific "server not found in registry" failure to completion — this turned out to be user-side config, not a code bug, but noting it here since it's directly related to the confusion documented above.

With --debug, the customer's actual v0.46.0 release binary logged:

"msg":"No protocol scheme detected, attempting to retrieve image or registry server","server_or_image":"fetch"
"msg":"Server not found in registry","server":"fetch","error":"server not found: fetch"

Confirmed the v0.46.0 tag's embedded registry data (pinned github.com/stacklok/toolhive-catalog v0.20260824.0, same as main) does contain a fetch entry resolving to ghcr.io/stackloklabs/gofetch/server:1.0.5 — reproduced locally with a stock build resolving fine. So a default-configured v0.46.0 CLI should never hit this.

Root cause: ToolHive supports pointing the CLI at a custom registry via thv config set-registry <url-or-path>, persisted as registry_url / registry_api_url / local_registry_path in the user's config file (pkg/config/config.go:35-37, resolved with that priority order in pkg/registry/factory.go:52-88). If any of these is set, only that registry is consulted — the built-in stacklok catalog (and its fetch entry) is bypassed entirely, with no indication to the user that a different registry source is in effect. thv config get-registry reveals what's configured; thv config unset-registry reverts to the default.

Suggested additional fix (item 7): when a registry lookup fails, the error message should mention which registry source was consulted (default vs. a configured custom URL/path), e.g. server not found in registry (custom registry: <url>): fetch or ... (default registry): fetch. This alone would have made the root cause obvious immediately instead of requiring a --debug run and code archaeology to explain "why does everyone else's fetch work but not mine."