TinyFish Doctor

tinyfish doctor (CLI 0.18+) owns the diagnosis. Your job is to run it, do the one check it structurally cannot do, and act on what comes back. Never hand-edit config files — every repair goes through the CLI, which carries backup and merge rigor.

0. No shell?

Sandboxed surfaces (Claude.ai, Desktop, Cowork) have no npx. If you cannot run commands, skip to step 2 — it is the more valuable check anyway — then give the user the command from step 1 to run themselves.

1. Run doctor

npx -y @tiny-fish/cli@latest doctor

JSON on stdout: schema_version, checks[], harnesses[], repairs[].

Read schema_version before the fields. This skill describes 1 and 2. The command pins @latest, so a newer CLI can hand you a shape you do not know: above 2, stop reading fields, show the user --pretty output instead, and rely on step 2 for the verdict.

The difference between the two is what a keyed registration proves. 2 tests an API-key registration on the wire, so a stale key header fails outright and earns a connect repair. 1 passes it on config presence alone, and step 2 is the only thing that catches it.

A warn is not a failure and does not move the exit code: doctor is saying it could not check something, not that it is broken. On 2, registered, API key present but unverified means the key exists but doctor cannot read its value to test it, which is every Codex install and any harness whose config redacts the header. Never repair on a warn, prove it in step 2.

--pretty only when showing a human the list. Never put --debug output in a report — it is the one channel carrying raw stacks and absolute paths.

2. Prove the harness reach — the part doctor cannot do

harnesses[].proves_harness_reach is false whenever doctor could not prove that this harness authenticates. For OAuth harnesses it is always false, because the CLI cannot borrow the harness's token. You are the only one who can close that gap.

Run without --harness, so harnesses[] carries one entry per harness doctor knows — installed or not. Read the entry whose harness matches the agent you are running in, never the first one, and check its detected first: an absent harness reports detected: false, registered: "no", auth_mode: "unknown", which is not a fault to repair. doctor only knows claude-code, codex, cursor, hermes, openclaw, opencode; if you are none of those, no entry describes you and step 2 is your only evidence.

Count the TinyFish servers first. A plugin, a CLI-written entry, and an account-level connector can all be registered at once, all pointing at the same endpoint. doctor inspects only the one named tinyfish and cannot see its siblings. Note which server it reported on.

Then call search once with a cheap query, and note which server answered — the tool namespace names it.

What a registration: pass proves depends on schema_version. On 2 an API-key registration was tested on the wire, so a stale key header is already a fail with a connect repair beside it. On 1, and on every OAuth or auth_mode: unknown registration at either version, pass is presence only: doctor read config, not the wire, and a stale key still passes while every call 401s. Neither version says anything about siblings, and a healthy sibling will answer cheerfully while the broken one stays broken.

3. Repair

Run only commands that appear in repairs[], and show command before running it. Keep the order they arrive in: auth login comes before connect because connect writes whichever key is stored, so a dead one has to be replaced first.

• Terminal with the user present → doctor --fix

• Non-interactive → doctor --fix --yes; only unattended_safe: true repairs run and the rest return as skipped. Never report a skipped repair as a fix.

• unattended_safe: false → hand it to the user, do not run it. Expect most repairs to be false: auth login always is, and connect <harness> is unsafe for every harness except Cursor — and on 2 Cursor only while the CLI's own authenticated call passes, since a revoked key still resolves as a credential. Read the field, do not infer it.

• OAuth credential failures have no CLI repair: re-authenticate in the harness itself.

  Harness	Re-auth
  Codex, Hermes	no login command — auth runs on first tool use; trigger a TinyFish tool and finish the browser sign-in
  OpenCode	opencode mcp auth tinyfish
  Claude Code	/mcp in-app, or claude mcp login tinyfish
  OpenClaw, Cursor	key-based — tinyfish auth login, then tinyfish connect <harness> to rewrite the header

Re-run step 2 after any repair. Success means showing the real search result — the user should see their agent touch the live web.

4. Still broken

Attach doctor's stdout JSON verbatim. It is schema-versioned and already redaction-safe: undeclared fields are stripped on parse and every message is authored rather than raw. Do not build your own report, add fields, or paste config contents. On exit 2 there is no JSON — say so rather than filing an empty report.

Then file it at https://github.com/tinyfish-io/tinyfish-cookbook/issues.