@tiny-fish/cli 0.20.1 → 0.20.2-next.190

package/README.md

@@ -40,6 +40,10 @@ One-command OAuth requires a Codex release whose `codex mcp add` command support
 `--oauth-resource`. Update Codex if support is unavailable, or add TinyFish manually with
 `codex mcp add`.
 
+With `--api-key`, Codex reads the key from `TINYFISH_API_KEY` instead of signing in — the command
+exports it to your shell profile, so restart Codex (or open a new terminal) before using it. Needs
+`codex mcp add --bearer-token-env-var`; without that flag the command falls back to OAuth.
+
 ### Connect Hermes
 
 Add TinyFish MCP and the global `use-tinyfish` web skill, authenticate the CLI, and start the
@@ -49,8 +53,10 @@ interactive walkthrough with one command:
 npx -y @tiny-fish/cli@latest connect hermes --launch --api-key sk-tinyfish-...
 ```
 
-Hermes completes OAuth while adding the MCP server. After setup, the command starts the walkthrough
-in a Hermes session and leaves that session open for your replies.
+Hermes completes OAuth while adding the MCP server. `hermes mcp add` accepts no header flag, so
+`--api-key` cannot replace the Hermes sign-in — its only header path, `--auth header`, prompts
+interactively. After setup, the command starts the walkthrough in a Hermes session and leaves that
+session open for your replies.
 
 ### Connect OpenClaw
 

package/dist/commands/connect.d.ts

@@ -1,17 +1,20 @@
 import { Command } from "commander";
-import { type AgentClient } from "../lib/connect-runtime.js";
+import { type AgentClient, type ConnectAuthMode } from "../lib/connect-runtime.js";
 export declare const DEFAULT_MCP_URL = "https://agent.tinyfish.ai/mcp";
 interface NativeConnectOptions {
     apiKey?: string;
     mcpUrl: string;
     launch: boolean;
     attemptId?: string;
+    /** Headless: refuse rather than fall back to an unfinishable browser sign-in. */
+    keyAuthOnly?: boolean;
 }
-export declare function connectClaudeCode(options: NativeConnectOptions): Promise<void>;
-export declare function connectCodex(options: NativeConnectOptions): Promise<void>;
-export declare function connectHermes(options: NativeConnectOptions): Promise<void>;
-export declare function connectOpencode(options: NativeConnectOptions): Promise<void>;
+export declare function connectClaudeCode(options: NativeConnectOptions): Promise<ConnectAuthMode | undefined>;
+export declare function connectCodex(options: NativeConnectOptions): Promise<ConnectAuthMode | undefined>;
+export declare function connectHermes(options: NativeConnectOptions): Promise<ConnectAuthMode | undefined>;
+export declare function connectOpencode(options: NativeConnectOptions): Promise<ConnectAuthMode | undefined>;
 export declare function connectOpenClaw(options: {
+    apiKey?: string;
     mcpUrl: string;
     launch: boolean;
     installCli?: boolean;

package/dist/commands/connect.js

@@ -1,8 +1,8 @@
 import spawn from "cross-spawn";
-import { CONNECT_SOURCE, saveConnectContext, validateKeyFormat, validatedApiKey, } from "../lib/auth.js";
+import { CONNECT_SOURCE, persistApiKeyToEnvironment, saveConnectContext, validateKeyFormat, validatedApiKey, } from "../lib/auth.js";
 import { CLAUDE_CODE, CODEX, HERMES, OPENCLAW, OPENCLAW_SKILL_INSTALL_ARGS, OPENCODE, launchNativeMcpClient, launchOpenClawWalkthrough, openExternalUrl, } from "../lib/connect-clients.js";
-import { ensureCliAuthenticated, installTinyFishCli, installWebSkill, SKILL_INSTALL_TIMEOUT_MS, TINYFISH_CLI_NOT_FOUND_MESSAGE, UPGRADE_HINT, } from "../lib/connect-install.js";
-import { commandNotFound, ConnectInterruptedError, createConnectTelemetry, requireCommandSupport, runGuarded, settle, throwIfInterrupted, NON_INTERACTIVE_TIMEOUT_MS, } from "../lib/connect-runtime.js";
+import { ensureCliAuthenticated, installTinyFishCli, installWebSkill, SKILL_INSTALL_TIMEOUT_MS, UPGRADE_HINT, } from "../lib/connect-install.js";
+import { ConnectInterruptedError, createConnectTelemetry, requireCommandSupport, runGuarded, settle, throwIfInterrupted, NON_INTERACTIVE_TIMEOUT_MS, } from "../lib/connect-runtime.js";
 import { cursorInstallDeeplink, cursorMcpPath, writeCursorMcpConfig, } from "../lib/cursor-config.js";
 import { runConnectAll } from "../lib/connect-all.js";
 import { detectHumanInitiated } from "../lib/harness.js";
@@ -29,13 +29,46 @@ function removeExistingRegistration(client, removal) {
     }
     throw new Error(`Could not remove existing ${removal.label}: ${details}`);
 }
+/** false: fall back to OAuth — a config naming an unset variable authenticates nothing. */
+function exportApiKey(apiKey, displayName) {
+    try {
+        persistApiKeyToEnvironment(apiKey);
+    }
+    catch (error) {
+        errLine(`Could not export TINYFISH_API_KEY (${error instanceof Error ? error.message : String(error)}); ` +
+            "signing in instead.");
+        return false;
+    }
+    process.env["TINYFISH_API_KEY"] = apiKey;
+    errLine(`Exported TINYFISH_API_KEY to your shell profile — ${displayName} reads the key from there, ` +
+        "so restart it (or open a new terminal) before use.");
+    return true;
+}
 async function connectNativeMcpClient(client, options) {
     const telemetry = createConnectTelemetry(options.mcpUrl, client.connectClient, options);
     const state = { stage: "prerequisite_check", settled: false };
     await runGuarded(state, telemetry, () => {
         telemetry.track("started");
-        const { optionalSupported } = requireCommandSupport(client);
+        const { optionalSupported, keyAuthSupported } = requireCommandSupport(client);
         state.harnessDegraded = !!client.loginArgs && !optionalSupported;
+        // Prod MCP accepts X-API-Key, so a stored key replaces the browser OAuth hop.
+        const storedKey = validatedApiKey(options.apiKey);
+        let keyedAdd = storedKey && keyAuthSupported && client.keyAuth
+            ? { key: storedKey, spec: client.keyAuth }
+            : undefined;
+        // Before the removals: a failed export must not strand the old registration.
+        if (keyedAdd?.spec.viaEnv && !exportApiKey(keyedAdd.key, client.displayName)) {
+            keyedAdd = undefined;
+        }
+        const useKeyAuth = !!keyedAdd;
+        if (options.keyAuthOnly && !useKeyAuth) {
+            // No keyAuth at all is structural (Hermes); a missing flag is just an old install.
+            throw new Error(client.keyAuth
+                ? `This ${client.displayName} install cannot take a TinyFish API key, and signing in ` +
+                    `needs a terminal. Update it, then re-run: tinyfish connect ${client.connectClient}`
+                : `${client.displayName} cannot take a TinyFish API key, and signing in needs a ` +
+                    `terminal. Run: tinyfish connect ${client.connectClient}`);
+        }
         telemetry.track("checkpoint", { phase: "prerequisite_ok" });
         state.stage = "registration_cleanup";
         for (const removal of client.removals)
@@ -44,9 +77,6 @@ async function connectNativeMcpClient(client, options) {
         mcpUrl.searchParams.set("source", CONNECT_SOURCE);
         mcpUrl.searchParams.set("client", client.connectClient);
         mcpUrl.searchParams.set("connect_attempt_id", telemetry.attemptId);
-        // Prod MCP accepts X-API-Key, so a stored key replaces the browser OAuth hop.
-        const storedKey = validatedApiKey(options.apiKey);
-        const useKeyAuth = client.headerAuthSupported === true && !!storedKey;
         // Undefining `loginArgs` reuses the deferred-auth path codex/hermes already take.
         const loginDegraded = state.harnessDegraded === true;
         const loginArgs = loginDegraded ? undefined : client.loginArgs;
@@ -54,12 +84,11 @@ async function connectNativeMcpClient(client, options) {
         state.stage =
             loginArgs && !client.probeAuthenticated ? "registration" : "registration_or_authentication";
         errLine(`Adding TinyFish to ${client.displayName}...`);
-        const addResult = spawn.sync(client.command, [
-            ...client.addArgs(mcpUrl.toString(), options.mcpUrl),
-            // Key rides argv — readable via /proc/<pid>/cmdline. Accepted because these CLIs
-            // take headers no other way.
-            ...(useKeyAuth ? ["--header", `X-API-Key: ${storedKey}`] : []),
-        ], {
+        // Header keys ride argv (/proc/<pid>/cmdline); these CLIs take headers no other way.
+        const addArgs = keyedAdd
+            ? keyedAdd.spec.addArgs(mcpUrl.toString(), keyedAdd.key)
+            : client.addArgs(mcpUrl.toString(), options.mcpUrl);
+        const addResult = spawn.sync(client.command, addArgs, {
             stdio: "inherit",
         });
         if (addResult.error || addResult.status !== 0) {
@@ -105,10 +134,12 @@ async function connectNativeMcpClient(client, options) {
             : signInDeferred
                 ? "deferred"
                 : "oauth";
+        state.authMode = authMode;
         // Registration/OAuth make MCP work; later steps are cosmetic and must not fail the attempt.
         settle(state, telemetry, "completed", { authMode });
         runPostInstallSteps(client, options, state, telemetry, signInDeferred);
     });
+    return state.authMode;
 }
 function connectedLine(client, signInDeferred) {
     // The CLI never observes deferred auth, so don't claim "connected".
@@ -157,16 +188,16 @@ function reportPostInstallFailure(connectClient, displayName, state, telemetry,
     errLine(`Finish setup with: npx -y @tiny-fish/cli@latest connect ${connectClient}`);
 }
 export async function connectClaudeCode(options) {
-    await connectNativeMcpClient(CLAUDE_CODE, options);
+    return connectNativeMcpClient(CLAUDE_CODE, options);
 }
 export async function connectCodex(options) {
-    await connectNativeMcpClient(CODEX, options);
+    return connectNativeMcpClient(CODEX, options);
 }
 export async function connectHermes(options) {
-    await connectNativeMcpClient(HERMES, options);
+    return connectNativeMcpClient(HERMES, options);
 }
 export async function connectOpencode(options) {
-    await connectNativeMcpClient(OPENCODE, options);
+    return connectNativeMcpClient(OPENCODE, options);
 }
 export async function connectOpenClaw(options) {
     const telemetry = createConnectTelemetry(options.mcpUrl, "openclaw", options);
@@ -198,29 +229,9 @@ export async function connectOpenClaw(options) {
             });
         }
         telemetry.track("checkpoint", { phase: "skill_installed" });
+        // Stores the key before probing, so a passed --api-key never reaches an interactive login.
         state.stage = "authentication";
-        const authStatus = spawn.sync("tinyfish", ["auth", "status"], {
-            stdio: "ignore",
-            timeout: NON_INTERACTIVE_TIMEOUT_MS,
-        });
-        if (commandNotFound(authStatus.error)) {
-            throw new Error(TINYFISH_CLI_NOT_FOUND_MESSAGE, { cause: authStatus.error });
-        }
-        if (authStatus.status !== 0) {
-            errLine("Signing in to TinyFish...");
-            const loginResult = spawn.sync("tinyfish", ["auth", "login", "--source", "openclaw"], {
-                stdio: "inherit",
-            });
-            if (commandNotFound(loginResult.error)) {
-                throw new Error(TINYFISH_CLI_NOT_FOUND_MESSAGE, { cause: loginResult.error });
-            }
-            if (loginResult.error || loginResult.status !== 0) {
-                throwIfInterrupted(loginResult);
-                throw new Error("Could not authenticate TinyFish for OpenClaw", {
-                    cause: loginResult.error,
-                });
-            }
-        }
+        ensureCliAuthenticated("openclaw", options.apiKey);
         telemetry.track("checkpoint", { phase: "authenticated" });
         saveConnectContext("openclaw", telemetry.attemptId);
         errLine(UPGRADE_HINT);
@@ -400,6 +411,8 @@ export function registerConnect(program) {
             mcpUrl,
             launch: options.launch ?? false,
             attemptId,
+            // A key that the install cannot use leaves only a browser hop no agent can finish.
+            keyAuthOnly: !detectHumanInitiated() && !!validatedApiKey(options.apiKey),
         };
         if (client === "claude-code") {
             await connectClaudeCode(connectOptions);

package/dist/commands/upgrade.d.ts

@@ -1,5 +1,6 @@
 import { Command } from "commander";
-export declare function runUpgrade(): void;
+/** Returns the version now installed, so the caller reports exactly what the user was told. */
+export declare function runUpgrade(): string | null;
 /** `runUpgrade` plus its outcome telemetry, which must never change what the upgrade does. */
 export declare function runUpgradeCommand(): Promise<void>;
 export declare function registerUpgrade(program: Command): void;

package/dist/commands/upgrade.js

@@ -1,6 +1,7 @@
 import spawn from "cross-spawn";
 import { resolvedApiKey } from "../lib/auth.js";
 import { CLI_VERSION, TINYFISH_CLI_PACKAGE } from "../lib/constants.js";
+import { installRoot, readInstalledVersion } from "../lib/install-root.js";
 import { suppressNotice } from "../lib/notice.js";
 import { errLine } from "../lib/output.js";
 import { sendUpgradeCompleted, telemetryDisabled, } from "../lib/setup-telemetry.js";
@@ -24,6 +25,7 @@ function attempt(label, run) {
         return message;
     }
 }
+/** Returns the version now installed, so the caller reports exactly what the user was told. */
 export function runUpgrade() {
     errLine("Upgrading TinyFish...");
     try {
@@ -40,12 +42,21 @@ export function runUpgrade() {
             throw error;
         errLine(INTERRUPTED_MESSAGE);
         process.exitCode = SIGNAL_EXIT_CODES.SIGINT;
-        return;
+        return null;
     }
-    errLine("TinyFish is up to date. Restart your agent to pick up the refreshed skill.");
+    const version = installedCliVersion();
+    errLine(version
+        ? `TinyFish CLI ${version} is up to date. Restart your agent to pick up the refreshed skill.`
+        : "TinyFish is up to date. Restart your agent to pick up the refreshed skill.");
+    return version;
 }
 /** The version now on disk. Only the upgrade's own npm call knows what "latest" resolved to. */
 function installedCliVersion() {
+    const root = installRoot();
+    return (root ? readInstalledVersion(root.nodeModules) : null) ?? globalCliVersion();
+}
+/** Fallback when no prefix was detected: npm's own global tree is the only place left to look. */
+function globalCliVersion() {
     try {
         const result = spawn.sync("npm", ["ls", "--global", "--depth=0", "--json", TINYFISH_CLI_PACKAGE], { encoding: "utf8", timeout: VERSION_READ_TIMEOUT_MS });
         const parsed = JSON.parse(result.stdout ?? "");
@@ -60,17 +71,17 @@ export async function runUpgradeCommand() {
     // This command is the upgrade, so a trailing "an update is available" would be noise.
     suppressNotice();
     let reported = false;
+    let printedVersion = null;
     // Read on the failed path too: a failed skill refresh still leaves an upgraded CLI, so
     // `outcome` reports whether every step ran and `to_version` whether the binary moved.
     const report = async (outcome) => {
         if (reported)
             return;
         reported = true;
-        // Ahead of the version and key reads; an opted-out run does neither.
         if (telemetryDisabled())
             return;
         // Interrupted skips the read — racing the exit. Undercounts; see posthog-events.md.
-        const toVersion = outcome === "interrupted" ? null : installedCliVersion();
+        const toVersion = outcome === "interrupted" ? null : (printedVersion ?? installedCliVersion());
         await sendUpgradeCompleted(CLI_VERSION, toVersion, outcome, resolvedApiKey());
     };
     const uninstallSignalGuard = installSignalGuard(async () => {
@@ -79,7 +90,7 @@ export async function runUpgradeCommand() {
     });
     let outcome = "updated";
     try {
-        runUpgrade();
+        printedVersion = runUpgrade();
         if (process.exitCode === SIGNAL_EXIT_CODES.SIGINT)
             outcome = "interrupted";
     }

package/dist/lib/connect-all.js

@@ -2,6 +2,7 @@ import * as readline from "node:readline/promises";
 import spawn from "cross-spawn";
 import { connectClaudeCode, connectCodex, connectCursor, connectHermes, connectOpenClaw, connectOpencode, } from "../commands/connect.js";
 import { validatedApiKey } from "./auth.js";
+import { NATIVE_MCP_CLIENTS } from "./connect-clients.js";
 import { detectInstalledHarnesses, ALL_HARNESSES, } from "./harness-detect.js";
 import { detectHumanInitiated } from "./harness.js";
 import { emitNotice } from "./notice.js";
@@ -20,10 +21,14 @@ const DISPLAY_NAMES = {
 // `codex mcp add` succeeds unauthenticated; OAuth lands at first tool use.
 // TODO(PF-3580): connect now probes Codex sign-in, so this over-warns a signed-in install.
 const AUTH_DEFERRED_AT_INSTALL = new Set(["codex"]);
-// Harnesses that drive their own OAuth at install — a stored TinyFish key says nothing
-// about their session, so it must never unlock a headless run for them.
-const HARNESS_OWN_AUTH = new Set(["claude-code", "codex", "hermes", "opencode"]);
 const AUTH_CHECK_CAPABLE = new Set(["cursor", "openclaw"]);
+// Descriptor-derived so a harness that cannot carry a key is skipped, not failed, when headless.
+// Cursor and OpenClaw hold the key themselves rather than handing it to a harness `mcp add`.
+const KEY_AUTH_CAPABLE = new Set([
+    ...NATIVE_MCP_CLIENTS.filter((client) => !!client.keyAuth).map((client) => client.connectClient),
+    "cursor",
+    "openclaw",
+]);
 // Real removal commands — harness id is not the binary name.
 const UNINSTALL_POINTERS = {
     "claude-code": "claude mcp remove tinyfish --scope user",
@@ -33,24 +38,28 @@ const UNINSTALL_POINTERS = {
     // OpenCode ships no `mcp remove`, so the only removal is editing the config it wrote.
     opencode: "remove the tinyfish entry from ~/.config/opencode/opencode.json",
 };
-async function runHarnessConnect(harness, opts) {
-    const base = { apiKey: opts.apiKey, mcpUrl: opts.mcpUrl, launch: false };
+async function runHarnessConnect(harness, opts, keyAuthOnly) {
+    const base = { apiKey: opts.apiKey, mcpUrl: opts.mcpUrl, launch: false, keyAuthOnly };
     if (harness === "claude-code")
         return connectClaudeCode(base);
     if (harness === "codex")
         return connectCodex(base);
     if (harness === "hermes")
         return connectHermes(base);
-    if (harness === "openclaw")
-        return connectOpenClaw({ mcpUrl: opts.mcpUrl, launch: false });
+    if (harness === "openclaw") {
+        // Without the key the child shells an interactive `tinyfish auth login`.
+        await connectOpenClaw({ apiKey: opts.apiKey, mcpUrl: opts.mcpUrl, launch: false });
+        return undefined;
+    }
     if (harness === "opencode")
         return connectOpencode(base);
-    return connectCursor({ apiKey: opts.apiKey, mcpUrl: opts.mcpUrl });
+    await connectCursor({ apiKey: opts.apiKey, mcpUrl: opts.mcpUrl });
+    return undefined;
 }
-async function verifyHarness(harness, mcpUrl, apiKey) {
+async function verifyHarness(harness, mcpUrl, keyed, apiKey) {
     const health = await verifyMcpHealth(mcpUrl);
-    // claude-code is auth-checkable only in key mode (header-authed config).
-    const capable = AUTH_CHECK_CAPABLE.has(harness) || (harness === "claude-code" && !!apiKey);
+    // The own-OAuth harnesses are auth-checkable only in key mode (key-authed config).
+    const capable = AUTH_CHECK_CAPABLE.has(harness) || keyed;
     if (!capable || !health.ok)
         return health;
     if (!apiKey)
@@ -110,15 +119,18 @@ async function processHarness(detection, opts, prompt) {
     if (opts.uninstall)
         return uninstallHarness(harness, configPath);
     const isTTY = detectHumanInitiated();
-    // claude-code leaves the own-OAuth set when a key is stored: `mcp add --header
-    // X-API-Key` replaces its login. codex/hermes have no header path, so they keep the skip.
-    const keyed = !!validatedApiKey(opts.apiKey);
-    const ownAuthHarness = HARNESS_OWN_AUTH.has(harness) && !(harness === "claude-code" && keyed);
-    const alreadyAuthed = !ownAuthHarness && keyed;
-    if (!isTTY && !alreadyAuthed) {
-        return { ...base, outcome: "no_tty_auth_skip", fixCommand: `tinyfish connect ${harness}` };
+    const apiKey = validatedApiKey(opts.apiKey);
+    // A key only leaves the own-OAuth set where the harness can actually carry one.
+    const keyed = !!apiKey && KEY_AUTH_CAPABLE.has(harness);
+    if (!isTTY && !keyed) {
+        return {
+            ...base,
+            outcome: "no_tty_auth_skip",
+            keyUnusable: !!apiKey,
+            fixCommand: `tinyfish connect ${harness}`,
+        };
     }
-    if (isTTY && !alreadyAuthed && prompt) {
+    if (isTTY && !keyed && prompt) {
         errLine(`step: waiting for browser sign-in to TinyFish for ${DISPLAY_NAMES[harness]}`);
         try {
             await prompt(`Press enter to open the browser and sign in to TinyFish for ${DISPLAY_NAMES[harness]}... `);
@@ -130,8 +142,10 @@ async function processHarness(detection, opts, prompt) {
     }
     // runGuarded swallows Ctrl+C and sets exitCode 130 instead of throwing.
     const interruptedBefore = process.exitCode === 130;
+    let authMode;
     try {
-        await runHarnessConnect(harness, opts);
+        // Headless: an install too old for key auth must fail, not open a browser.
+        authMode = await runHarnessConnect(harness, opts, !isTTY);
     }
     catch (e) {
         return {
@@ -144,7 +158,9 @@ async function processHarness(detection, opts, prompt) {
     if (!interruptedBefore && process.exitCode === 130) {
         return { ...base, outcome: "interrupted", fixCommand: `tinyfish connect ${harness}` };
     }
-    const verify = await verifyHarness(harness, opts.mcpUrl, validatedApiKey(opts.apiKey));
+    // The probe, not the flag, decides: a harness that degraded to OAuth is not key-authed.
+    const keyAuthed = authMode ? authMode === "api-key" : keyed;
+    const verify = await verifyHarness(harness, opts.mcpUrl, keyAuthed, apiKey);
     return {
         ...base,
         installed: true,
@@ -152,6 +168,7 @@ async function processHarness(detection, opts, prompt) {
         verifyDepth: verify.depth,
         verifyOk: verify.ok,
         verifyReason: verify.reason,
+        keyAuthed,
     };
 }
 function summaryLine(result, uninstall) {
@@ -169,7 +186,10 @@ function summaryLine(result, uninstall) {
         return `… ${name} — ${result.fixCommand}`;
     }
     if (result.outcome === "no_tty_auth_skip") {
-        return `… ${name} — skipped, no stored credentials and no terminal to sign in. Fix: ${result.fixCommand}`;
+        const why = result.keyUnusable
+            ? `${name} cannot take an API key and there is no terminal to sign in`
+            : "no stored credentials and no terminal to sign in";
+        return `… ${name} — skipped, ${why}. Fix: ${result.fixCommand}`;
     }
     if (result.outcome === "uninstall_pointer") {
         return `… ${name} — not removed automatically (config is owned by ${name}). Run: ${result.fixCommand}`;
@@ -188,7 +208,8 @@ function summaryLine(result, uninstall) {
     if (result.outcome === "failed") {
         return `✗ ${name} — install failed: ${result.errorMessage}. Fix: ${result.fixCommand}`;
     }
-    const authDeferred = AUTH_DEFERRED_AT_INSTALL.has(result.harness);
+    // A keyed install has no sign-in left, so the deferred-auth warning would contradict it.
+    const authDeferred = AUTH_DEFERRED_AT_INSTALL.has(result.harness) && !result.keyAuthed;
     const verifyLabel = result.verifyDepth ? `verified: ${result.verifyDepth}` : "not verified";
     if (authDeferred || result.verifyOk === false) {
         const reason = authDeferred

package/dist/lib/connect-clients.d.ts

@@ -6,8 +6,12 @@ export declare const OPENCLAW_ONBOARDING_PROMPT: string;
 export interface NativeMcpClient extends SupportedCommand {
     connectClient: Exclude<AgentClient, "openclaw">;
     skillAgent: "claude-code" | "codex" | "hermes-agent" | "opencode";
-    /** `mcp add --header` support: a stored TinyFish key replaces the OAuth login. */
-    headerAuthSupported?: boolean;
+    /** Replaces `addArgs` when a stored key is available: key auth removes the OAuth hop. */
+    keyAuth?: {
+        /** Key reaches the client through TINYFISH_API_KEY, not argv. */
+        viaEnv?: boolean;
+        addArgs: (mcpUrl: string, apiKey: string) => string[];
+    };
     loginArgs?: string[];
     /** Replaces the `loginArgs` step when `supportCheck.optionalPatterns` miss. */
     degradedAuthNotes?: {
@@ -35,6 +39,8 @@ export declare function openExternalUrl(url: string): ReturnType<typeof spawn.sy
 export declare const CODEX: NativeMcpClient;
 export declare const HERMES: NativeMcpClient;
 export declare const OPENCODE: NativeMcpClient;
+/** Every native MCP client. Derive from this, so a new harness cannot be missed. */
+export declare const NATIVE_MCP_CLIENTS: readonly NativeMcpClient[];
 export declare const OPENCLAW: SupportedCommand;
 export declare function launchNativeMcpClient(client: NativeMcpClient): boolean;
 export declare function launchOpenClawWalkthrough(): boolean;

package/dist/lib/connect-clients.js

@@ -54,6 +54,22 @@ export const OPENCLAW_ONBOARDING_PROMPT = "I just installed the TinyFish skill.
     "want to search and wait for my reply before using TinyFish Search. Show me the results, ask " +
     "which result I want to read, and wait before using TinyFish Fetch. Then ask what browser task " +
     "I want to complete and wait before using TinyFish Agent. Never skip ahead or choose for me.";
+const HEADER_FLAG = /(?:^|\s)--header(?:[\s<=]|$)/m;
+const claudeAddArgs = (mcpUrl) => [
+    "mcp",
+    "add",
+    "--scope",
+    "user",
+    "--transport",
+    "http",
+    "tinyfish",
+    mcpUrl,
+];
+const urlAddArgs = (mcpUrl) => ["mcp", "add", "tinyfish", "--url", mcpUrl];
+// OpenCode takes `--header NAME=VALUE`, not Claude Code's `NAME: VALUE`.
+const headerKeyAuth = {
+    addArgs: (mcpUrl, apiKey) => [...urlAddArgs(mcpUrl), "--header", `X-API-Key=${apiKey}`],
+};
 export const CLAUDE_CODE = {
     command: "claude",
     connectClient: "claude-code",
@@ -63,9 +79,12 @@ export const CLAUDE_CODE = {
         args: ["mcp", "--help"],
         patterns: [/^\s*add(?:\s|\[)/m],
         optionalPatterns: [/^\s*login(?:\s|\[)/m],
+        keyAuthPattern: HEADER_FLAG,
         unavailableMessage: MCP_ADD_UNAVAILABLE_MESSAGE,
     },
-    headerAuthSupported: true,
+    keyAuth: {
+        addArgs: (mcpUrl, apiKey) => [...claudeAddArgs(mcpUrl), "--header", `X-API-Key: ${apiKey}`],
+    },
     loginArgs: ["mcp", "login", "tinyfish"],
     degradedAuthNotes: {
         keyed: CLAUDE_CODE_KEYED_FALLBACK_NOTE,
@@ -79,7 +98,7 @@ export const CLAUDE_CODE = {
             label: "local TinyFish registration",
         },
     ],
-    addArgs: (mcpUrl) => ["mcp", "add", "--scope", "user", "--transport", "http", "tinyfish", mcpUrl],
+    addArgs: (mcpUrl) => claudeAddArgs(mcpUrl),
 };
 /**
  * `cmd` re-parses its command line after `/c`, so an unquoted `&` in the query string ends the
@@ -115,22 +134,21 @@ export const CODEX = {
     supportCheck: {
         args: ["mcp", "add", "--help"],
         patterns: [/--oauth-resource(?:\s|<)/],
+        keyAuthPattern: /(?:^|\s)--bearer-token-env-var(?:[\s<=]|$)/m,
         unavailableMessage: CODEX_OAUTH_RESOURCE_UNAVAILABLE_MESSAGE,
     },
+    // Codex has no `--header`; the MCP server takes a key as `Bearer sk-…`.
+    // Omitting `--oauth-resource` is what keeps `mcp add` from running OAuth.
+    keyAuth: {
+        viaEnv: true,
+        addArgs: (mcpUrl) => [...urlAddArgs(mcpUrl), "--bearer-token-env-var", "TINYFISH_API_KEY"],
+    },
     launchWalkthrough: launchCodexWalkthrough,
     probeAuthenticated: codexOauthCompleted,
     // Retry only: running it after a finished inline OAuth is a second browser hop.
     loginArgs: ["mcp", "login", "tinyfish"],
     removals: [{ args: ["mcp", "remove", "tinyfish"], label: "TinyFish registration from Codex" }],
-    addArgs: (mcpUrl, oauthResource) => [
-        "mcp",
-        "add",
-        "tinyfish",
-        "--url",
-        mcpUrl,
-        "--oauth-resource",
-        oauthResource,
-    ],
+    addArgs: (mcpUrl, oauthResource) => [...urlAddArgs(mcpUrl), "--oauth-resource", oauthResource],
 };
 function launchHermesWalkthrough() {
     const seedResult = spawn.sync("hermes", ["chat", "-Q", "-q", DEFAULT_ONBOARDING_PROMPT], {
@@ -168,9 +186,10 @@ export const HERMES = {
         patterns: [/--auth\s+\{[^}]*oauth[^}]*\}/],
         unavailableMessage: HERMES_OAUTH_UNAVAILABLE_MESSAGE,
     },
+    // No `keyAuth`: `hermes mcp add` has no --header, and `--auth header` prompts interactively.
     removals: [{ args: ["mcp", "remove", "tinyfish"], label: "TinyFish registration from Hermes" }],
     // Hermes completes OAuth while adding the server; a separate `mcp login` would authenticate twice.
-    addArgs: (mcpUrl) => ["mcp", "add", "tinyfish", "--url", mcpUrl, "--auth", "oauth"],
+    addArgs: (mcpUrl) => [...urlAddArgs(mcpUrl), "--auth", "oauth"],
     launchWalkthrough: launchHermesWalkthrough,
 };
 // OpenCode's TUI takes a positional as a project directory, so a bare `opencode "<prompt>"`
@@ -197,16 +216,25 @@ export const OPENCODE = {
     supportCheck: {
         args: ["mcp", "add", "--help"],
         patterns: [/--url(?:\s|$)/m],
+        keyAuthPattern: HEADER_FLAG,
         unavailableMessage: OPENCODE_MCP_ADD_UNAVAILABLE_MESSAGE,
     },
+    keyAuth: headerKeyAuth,
     // `opencode mcp add` upserts by name and there is no `opencode mcp remove`, so no cleanup step.
     removals: [],
     // OpenCode writes ~/.config/opencode/opencode.jsonc itself; `mcp auth` is the separate OAuth step.
-    addArgs: (mcpUrl) => ["mcp", "add", "tinyfish", "--url", mcpUrl],
+    addArgs: (mcpUrl) => urlAddArgs(mcpUrl),
     loginArgs: ["mcp", "auth", "tinyfish"],
     launchWalkthrough: launchOpencode,
     postConnectNote: OPENCODE_MODEL_NOTE,
 };
+/** Every native MCP client. Derive from this, so a new harness cannot be missed. */
+export const NATIVE_MCP_CLIENTS = [
+    CLAUDE_CODE,
+    CODEX,
+    HERMES,
+    OPENCODE,
+];
 export const OPENCLAW = {
     command: "openclaw",
     displayName: "OpenClaw",

package/dist/lib/connect-install.js

@@ -1,9 +1,10 @@
 import * as path from "node:path";
 import spawn from "cross-spawn";
 import { loadConfig, persistApiKeyToEnvironment, validateKeyFormat, writeConfig } from "./auth.js";
-import { CLAUDE_CODE, CODEX, HERMES, OPENCLAW_SKILL_INSTALL_ARGS, OPENCODE, } from "./connect-clients.js";
+import { NATIVE_MCP_CLIENTS, OPENCLAW_SKILL_INSTALL_ARGS, } from "./connect-clients.js";
 import { commandNotFound, throwIfInterrupted, NON_INTERACTIVE_TIMEOUT_MS, } from "./connect-runtime.js";
 import { TINYFISH_CLI_PACKAGE } from "./constants.js";
+import { installRoot } from "./install-root.js";
 import { errLine } from "./output.js";
 export const SKILL_INSTALL_TIMEOUT_MS = 120_000;
 export const TINYFISH_CLI_NOT_FOUND_MESSAGE = "TinyFish CLI installed but is not available on PATH. Open a new terminal and retry.";
@@ -15,7 +16,10 @@ const TINYFISH_WEB_SKILL_SOURCE = "tinyfish-io/tinyfish-cookbook";
 const TINYFISH_WEB_SKILL = "use-tinyfish";
 export function installTinyFishCli() {
     errLine("Installing the TinyFish CLI...");
-    const result = spawn.sync("npm", ["install", "--global", TINYFISH_CLI_INSTALL_SPEC], {
+    // Without the prefix, a curl install upgrades npm's global tree and never the PATH binary.
+    const root = installRoot();
+    const prefixArgs = root ? ["--prefix", root.prefix] : [];
+    const result = spawn.sync("npm", ["install", "--global", ...prefixArgs, TINYFISH_CLI_INSTALL_SPEC], {
         stdio: "inherit",
         timeout: SKILL_INSTALL_TIMEOUT_MS,
     });
@@ -85,7 +89,7 @@ export function installWebSkill(client) {
 export function updateWebSkill() {
     // One entry per `tinyfish connect <client>`, persisted by PF-3169.
     const connected = loadConfig().connect ?? {};
-    const skillAgents = [CLAUDE_CODE, CODEX, HERMES, OPENCODE]
+    const skillAgents = NATIVE_MCP_CLIENTS
         .filter((client) => connected[client.connectClient])
         .map((client) => client.skillAgent);
     const hasOpenClaw = Boolean(connected["openclaw"]);

package/dist/lib/connect-runtime.d.ts

@@ -19,6 +19,8 @@ export interface ConnectRunState {
     settled: boolean;
     /** On state, not per-call: otherwise degraded installs never appear to fail. */
     harnessDegraded?: boolean;
+    /** Resolved after the probe, so callers read real key use rather than key presence. */
+    authMode?: ConnectAuthMode;
 }
 interface ConnectStageDetail {
     failedStage?: ConnectFailureStage;
@@ -47,11 +49,14 @@ export interface SupportedCommand {
         patterns: RegExp[];
         /** Missing → degrade to key or deferred auth, never refuse. */
         optionalPatterns?: RegExp[];
+        /** Missing → this install cannot take a stored key; fall back to OAuth. */
+        keyAuthPattern?: RegExp;
         unavailableMessage: string;
     };
 }
 export declare function requireCommandSupport(client: SupportedCommand): {
     optionalSupported: boolean;
+    keyAuthSupported: boolean;
 };
 export declare function createConnectTelemetry(mcpUrl: string, client: AgentClient, opts?: {
     apiKey?: string;

package/dist/lib/connect-runtime.js

@@ -95,7 +95,9 @@ export function requireCommandSupport(client) {
     const listed = (patterns) => patterns.every((pattern) => pattern.test(output));
     const essential = listed(client.supportCheck.patterns);
     const optionalSupported = listed(client.supportCheck.optionalPatterns ?? []);
-    if ((!essential || !optionalSupported) && process.env["TINYFISH_DEBUG"]) {
+    const keyAuthPattern = client.supportCheck.keyAuthPattern;
+    const keyAuthSupported = keyAuthPattern ? keyAuthPattern.test(output) : true;
+    if ((!essential || !optionalSupported || !keyAuthSupported) && process.env["TINYFISH_DEBUG"]) {
         errLine(`${client.command} ${client.supportCheck.args.join(" ")} printed:\n${output.trim()}`);
     }
     if (!essential) {
@@ -103,7 +105,7 @@ export function requireCommandSupport(client) {
             harnessVersion: probeHarnessVersion(client.command),
         });
     }
-    return { optionalSupported };
+    return { optionalSupported, keyAuthSupported };
 }
 /** Best-effort; the server rejects non-printable characters and >32 chars. */
 function probeHarnessVersion(command) {

package/dist/lib/install-root.d.ts

@@ -0,0 +1,15 @@
+/** Where this CLI is installed: `prefix` for npm, `nodeModules` for reading the version back. */
+export type InstallRoot = {
+    prefix: string;
+    nodeModules: string;
+};
+/**
+ * The prefix to upgrade in place, or null when the layout is not npm's.
+ *
+ * Guarded on purpose: npx, pnpm and bun all nest the package under a bare `node_modules`, and
+ * installing into their trees would report a success the PATH binary never sees.
+ */
+export declare function resolveInstallRoot(packageRoot: string, platform: typeof process.platform, onDisk?: (candidate: string) => boolean): InstallRoot | null;
+export declare function installRoot(): InstallRoot | null;
+/** The version on disk under a prefix, which is the only account of what `@latest` resolved to. */
+export declare function readInstalledVersion(nodeModules: string): string | null;

package/dist/lib/install-root.js

@@ -0,0 +1,49 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { TINYFISH_CLI_PACKAGE } from "./constants.js";
+function isDirectory(candidate) {
+    try {
+        return fs.statSync(candidate).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The prefix to upgrade in place, or null when the layout is not npm's.
+ *
+ * Guarded on purpose: npx, pnpm and bun all nest the package under a bare `node_modules`, and
+ * installing into their trees would report a success the PATH binary never sees.
+ */
+export function resolveInstallRoot(packageRoot, platform, onDisk = isDirectory) {
+    const p = platform === "win32" ? path.win32 : path.posix;
+    // npx's win32 cache uses the same bare layout as a global install.
+    if (packageRoot.split(p.sep).includes("_npx"))
+        return null;
+    const nodeModules = p.resolve(packageRoot, "..", "..");
+    if (p.basename(nodeModules) !== "node_modules")
+        return null;
+    const container = p.dirname(nodeModules);
+    // Only win32 puts node_modules directly under the prefix.
+    if (platform !== "win32" && p.basename(container) !== "lib")
+        return null;
+    if (!onDisk(nodeModules))
+        return null;
+    return { prefix: platform === "win32" ? container : p.dirname(container), nodeModules };
+}
+export function installRoot() {
+    // Two levels up from dist/lib/ is the package root, and tsc mirrors src/ into dist/.
+    const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+    return resolveInstallRoot(packageRoot, process.platform);
+}
+/** The version on disk under a prefix, which is the only account of what `@latest` resolved to. */
+export function readInstalledVersion(nodeModules) {
+    try {
+        const manifest = fs.readFileSync(path.join(nodeModules, ...TINYFISH_CLI_PACKAGE.split("/"), "package.json"), "utf8");
+        return JSON.parse(manifest).version ?? null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/lib/registration-detect.js

@@ -224,7 +224,7 @@ function fromMcpList(command, output, registeredMode, urlPattern) {
     }
     return { registered: "no", authMode: "unknown" };
 }
-// Hermes registers with `--auth oauth` and has no key path today, so mode is fixed.
+// connect only ever writes an OAuth Hermes entry, so `oauth` is a fact, not a detection gap.
 function probeHermes() {
     const probe = runProbe("hermes", ["mcp", "list"]);
     if (probe.outcome === "unavailable") {
@@ -259,7 +259,7 @@ function probeOpenClaw() {
         ? { registered: "yes", authMode: "api-key" }
         : { registered: "no", authMode: "unknown" };
 }
-// Connect registers with `mcp add --url` then `mcp auth`, so there is no key path today.
+// `opencode mcp list` prints no headers, so a key-authed registration is indistinguishable.
 function probeOpencode() {
     const probe = runProbe("opencode", ["mcp", "list"]);
     if (probe.outcome === "unavailable") {
@@ -272,7 +272,7 @@ function probeOpencode() {
             reason: `\`opencode mcp list\` exited ${probe.exitCode}`,
         };
     }
-    return fromMcpList("opencode", probe.output, "oauth", OPENCODE_ROW_URL);
+    return fromMcpList("opencode", probe.output, "unknown", OPENCODE_ROW_URL);
 }
 const PROBES = {
     "claude-code": () => fromMcpGet("claude", API_KEY_HEADER),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiny-fish/cli",
-  "version": "0.20.1",
+  "version": "0.20.2-next.190",
   "description": "TinyFish CLI — run web automations from your terminal",
   "type": "module",
   "bin": {