@tiny-fish/cli 0.30.2-next.265 → 0.30.2-next.267

package/dist/commands/connect.js

@@ -16,7 +16,7 @@ import { SIGN_IN_PROBES } from '../lib/registration-detect.js';
 import { errLine, warnLine } from '../lib/output.js';
 import { z } from 'zod';
 import { verifyMcpAuth } from '../lib/verify.js';
-import { DEFAULT_MCP_URL, isDefaultEndpoint } from '../lib/mcp-endpoint.js';
+import { apiBaseFromMcpUrl, DEFAULT_MCP_URL } from '../lib/mcp-endpoint.js';
 function removeExistingRegistration(client, removal, verbose) {
     const result = spawnRemoval(client.command, removal.args);
     if (result.status === 0)
@@ -48,9 +48,43 @@ function exportApiKey(apiKey, displayName, deferOutro) {
     }
     return true;
 }
+/** Undefined leaves the client on its keyless path, if any. */
+function resolveKeyedAdd(client, storedKey, keyAuthSupported, deferOutro) {
+    if (!storedKey || !keyAuthSupported || !client.keyAuth)
+        return undefined;
+    const keyed = { key: storedKey, spec: client.keyAuth };
+    // Before the removals: a failed export must not strand the old registration.
+    if (keyed.spec.envVar && !exportApiKey(keyed.key, client.displayName, deferOutro)) {
+        return undefined;
+    }
+    return keyed;
+}
+/** No sign-in to degrade to, so the install stops. */
+function refuseKeylessInstall(client, keyAuthSupported) {
+    const noSignIn = `TinyFish does not sign in to ${client.displayName} any other way`;
+    const rerun = `re-run: tinyfish connect ${client.connectClient}`;
+    if (!client.keyAuth) {
+        throw new ConnectStepError(`${client.displayName} cannot take a TinyFish API key, and ${noSignIn}. ` +
+            `Run: tinyfish connect ${client.connectClient}`, 'key_auth_unsupported');
+    }
+    if (!keyAuthSupported) {
+        throw new ConnectStepError(`This ${client.displayName} install cannot take a TinyFish API key, and ${noSignIn}. ` +
+            `Update it, then ${rerun}`, 'harness_too_old');
+    }
+    throw new ConnectStepError(`Connecting ${client.displayName} needs a TinyFish API key, and ${noSignIn}. ` +
+        `Run: tinyfish auth login, then ${rerun}`, 'invalid_config');
+}
+/** Resolved before the removals, so a refusal strands no registration. */
+function keylessAddArgs(client, keyAuthSupported, oauthResource) {
+    if (!client.addArgs)
+        refuseKeylessInstall(client, keyAuthSupported);
+    const addArgs = client.addArgs;
+    return (mcpUrl) => addArgs(mcpUrl, oauthResource);
+}
 /** Runs before any write: a refused key strands nothing. */
-async function verifyKeyBeforeSeeding(apiKey, displayName) {
-    const verified = await verifyMcpAuth(apiKey);
+async function verifyKeyBeforeSeeding(apiKey, displayName, mcpUrl) {
+    // One host serves `/mcp` and `/v1`, so `--url` decides where the key is checked.
+    const verified = await verifyMcpAuth(apiKey, apiBaseFromMcpUrl(mcpUrl));
     if (verified.ok)
         return;
     // No status means the network failed, not the key.
@@ -114,6 +148,124 @@ async function runMissingHarnessFallback(displayName, connectClient, state, tele
     errLine('The TinyFish CLI is installed and working.');
     errLine('Using a different agent? Run: tinyfish connect --all');
 }
+/** Resolved before the removals, so a refusal strands no registration. */
+async function prepareInstallAuth(client, options, keyAuthSupported) {
+    // Prod MCP accepts X-API-Key, so a stored key replaces the browser OAuth hop.
+    const storedKey = validatedApiKey(options.apiKey);
+    const keyedAdd = resolveKeyedAdd(client, storedKey, keyAuthSupported, options.deferOutro);
+    // Refuses here when key-required; others keep their OAuth argv.
+    const buildAddArgs = keyedAdd
+        ? (mcpUrl) => keyedAdd.spec.addArgs(mcpUrl, keyedAdd.key)
+        : keylessAddArgs(client, keyAuthSupported, options.mcpUrl);
+    if (options.keyAuthOnly && !keyedAdd) {
+        // All native clients have keyAuth; missing flags mean an old install.
+        if (client.keyAuth) {
+            throw new ConnectStepError(`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}`, 'harness_too_old');
+        }
+        throw new ConnectStepError(`${client.displayName} cannot take a TinyFish API key, and signing in needs a ` +
+            `terminal. Run: tinyfish connect ${client.connectClient}`, 'key_auth_unsupported');
+    }
+    // Verify first: a revoked key in a foreign .env is unrecoverable.
+    if (keyedAdd?.spec.seedKey) {
+        await verifyKeyBeforeSeeding(keyedAdd.key, client.displayName, options.mcpUrl);
+    }
+    return { keyedAdd, buildAddArgs };
+}
+/** Returns the seeded-credential note when a key was written into a user-owned file. */
+function performMcpAdd(client, options, plan, attemptId) {
+    const { keyedAdd, buildAddArgs } = plan;
+    const mcpUrl = new URL(options.mcpUrl);
+    mcpUrl.searchParams.set('source', CONNECT_SOURCE);
+    mcpUrl.searchParams.set('client', client.connectClient);
+    mcpUrl.searchParams.set('connect_attempt_id', attemptId);
+    errLine(`Adding TinyFish to ${client.displayName}...`);
+    // Header keys ride argv (/proc/<pid>/cmdline); these CLIs take headers no other way.
+    const addArgs = buildAddArgs(mcpUrl.toString());
+    // Capturing an inline-OAuth add hides the sign-in URL and hangs.
+    const interactiveAdd = !(client.nonInteractiveAdd || keyedAdd);
+    // After the removals: an interrupt there leaves no key behind.
+    const seeded = keyedAdd?.spec.seedKey?.(keyedAdd.key);
+    const addOptions = interactiveAdd
+        ? { stdio: 'inherit', timeout: options.authTimeoutMs }
+        : seeded
+            ? {
+                encoding: 'utf8',
+                // Without it, the 1 MiB default overflows into a misread Ctrl+C.
+                maxBuffer: STEP_MAX_BUFFER,
+                // The unattended path had no bound at all before; captureStdio's is the floor.
+                timeout: options.authTimeoutMs ?? SKILL_INSTALL_TIMEOUT_MS,
+                input: seeded.stdinInput,
+                env: seeded.env,
+            }
+            : captureStdio(options.verbose ?? false);
+    const addResult = spawn.sync(client.command, addArgs, addOptions);
+    // Rolls back first: signInStepError throws on a Ctrl+C.
+    const failAdd = (build) => {
+        seeded?.rollback();
+        const error = build();
+        replay(capturedOutput(addResult));
+        throw error;
+    };
+    if (addResult.error || addResult.status !== 0) {
+        failAdd(() => signInStepError(`Could not add TinyFish to ${client.displayName}`, addResult, interactiveAdd && options.authTimeoutMs !== undefined));
+    }
+    const registration = seeded?.confirmRegistered();
+    if (registration && !registration.ok) {
+        failAdd(() => new ConnectStepError(`${client.displayName} reported success but TinyFish is not enabled there` +
+            `${registration.detail ? `: ${registration.detail}` : ''}.`, 'invalid_config'));
+    }
+    return seeded?.note;
+}
+function performLoginStep(client, pendingLogin, options) {
+    errLine('Signing in to TinyFish...');
+    const loginResult = spawn.sync(client.command, [...pendingLogin], {
+        stdio: 'inherit',
+        timeout: options.authTimeoutMs,
+    });
+    if (loginResult.error || loginResult.status !== 0) {
+        throw signInStepError(`Could not authenticate TinyFish in ${client.displayName}`, loginResult, options.authTimeoutMs !== undefined);
+    }
+}
+function announceAuthNotes(useKeyAuth, degradedNotes, seededNote) {
+    if (useKeyAuth) {
+        errLine(degradedNotes?.keyed ?? 'Using your stored TinyFish API key — no browser sign-in needed.');
+        // Every other credential the CLI writes into a user-owned file says so too.
+        if (seededNote)
+            errLine(seededNote);
+    }
+    else if (degradedNotes) {
+        // Printed here, not with the closing line, so a `--launch` run sees it before the handover.
+        errLine(degradedNotes.deferred);
+    }
+}
+function completeAuthFlow(client, options, state, telemetry, ctx) {
+    const { useKeyAuth, loginDegraded, loginArgs, probeAuthenticated } = ctx;
+    // Codex runs OAuth inside `mcp add` and exits 0 either way, so the recorded state decides
+    // whether the login step below still runs. Unknown keeps the pre-probe behaviour.
+    const addSignedIn = probeAuthenticated?.();
+    if (addSignedIn)
+        telemetry.track('checkpoint', { phase: 'oauth_done' });
+    announceAuthNotes(useKeyAuth, loginDegraded ? client.degradedAuthNotes : undefined, ctx.seededNote);
+    // A probed client signs in again only when its inline OAuth is known to have been abandoned.
+    const retryLogin = probeAuthenticated ? addSignedIn === false : true;
+    const pendingLogin = !useKeyAuth && retryLogin ? loginArgs : undefined;
+    let signInDeferred = !useKeyAuth && !addSignedIn && !pendingLogin;
+    if (pendingLogin) {
+        state.stage = 'client_oauth';
+        performLoginStep(client, pendingLogin, options);
+        if (probeAuthenticated?.() === false)
+            signInDeferred = true;
+        else
+            telemetry.track('checkpoint', { phase: 'oauth_done' });
+    }
+    const authMode = useKeyAuth
+        ? AuthMode.ApiKey
+        : signInDeferred
+            ? 'deferred'
+            : AuthMode.OAuth;
+    return { authMode, signInDeferred };
+}
 async function connectNativeMcpClient(client, options) {
     const telemetry = createConnectTelemetry(options.mcpUrl, client.connectClient, options);
     const state = { stage: 'prerequisite_check', settled: false };
@@ -126,123 +278,27 @@ async function connectNativeMcpClient(client, options) {
         const { optionalSupported, keyAuthSupported, harnessVersion } = support;
         telemetry.setHarnessVersion(harnessVersion);
         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.envVar &&
-            !exportApiKey(keyedAdd.key, client.displayName, options.deferOutro)) {
-            keyedAdd = undefined;
-        }
-        const useKeyAuth = !!keyedAdd;
-        if (options.keyAuthOnly && !useKeyAuth) {
-            // All native clients have keyAuth; missing flags mean an old install.
-            if (client.keyAuth) {
-                throw new ConnectStepError(`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}`, 'harness_too_old');
-            }
-            throw new ConnectStepError(`${client.displayName} cannot take a TinyFish API key, and signing in needs a ` +
-                `terminal. Run: tinyfish connect ${client.connectClient}`, 'key_auth_unsupported');
-        }
-        // Off-default endpoints skip it: the check hits BASE_URL, not `--url`.
-        if (keyedAdd?.spec.seedKey && isDefaultEndpoint(options.mcpUrl)) {
-            await verifyKeyBeforeSeeding(keyedAdd.key, client.displayName);
-        }
+        const plan = await prepareInstallAuth(client, options, keyAuthSupported);
+        const useKeyAuth = !!plan.keyedAdd;
         telemetry.track('checkpoint', { phase: 'prerequisite_ok' });
         state.stage = 'registration_cleanup';
         for (const removal of client.removals)
             removeExistingRegistration(client, removal, options.verbose ?? false);
-        const mcpUrl = new URL(options.mcpUrl);
-        mcpUrl.searchParams.set('source', CONNECT_SOURCE);
-        mcpUrl.searchParams.set('client', client.connectClient);
-        mcpUrl.searchParams.set('connect_attempt_id', telemetry.attemptId);
         // Undefining `loginArgs` reuses the deferred-auth path codex/hermes already take.
         const loginDegraded = state.harnessDegraded === true;
         const loginArgs = loginDegraded ? undefined : client.loginArgs;
         // A probed client authenticates inside `mcp add` too, so a failure there is either.
         state.stage =
             loginArgs && !probeAuthenticated ? 'registration' : 'registration_or_authentication';
-        errLine(`Adding TinyFish to ${client.displayName}...`);
-        // 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);
-        // Capturing an inline-OAuth add hides the sign-in URL and hangs.
-        const interactiveAdd = !(client.nonInteractiveAdd || keyedAdd);
-        // After the removals: an interrupt there leaves no key behind.
-        const seeded = keyedAdd?.spec.seedKey?.(keyedAdd.key);
-        const addOptions = interactiveAdd
-            ? { stdio: 'inherit', timeout: options.authTimeoutMs }
-            : seeded
-                ? {
-                    encoding: 'utf8',
-                    // Without it, the 1 MiB default overflows into a misread Ctrl+C.
-                    maxBuffer: STEP_MAX_BUFFER,
-                    // The unattended path had no bound at all before; captureStdio's is the floor.
-                    timeout: options.authTimeoutMs ?? SKILL_INSTALL_TIMEOUT_MS,
-                    input: seeded.stdinInput,
-                    env: seeded.env,
-                }
-                : captureStdio(options.verbose ?? false);
-        const addResult = spawn.sync(client.command, addArgs, addOptions);
-        // Rolls back first: signInStepError throws on a Ctrl+C.
-        const failAdd = (build) => {
-            seeded?.rollback();
-            const error = build();
-            replay(capturedOutput(addResult));
-            throw error;
-        };
-        if (addResult.error || addResult.status !== 0) {
-            failAdd(() => signInStepError(`Could not add TinyFish to ${client.displayName}`, addResult, interactiveAdd && options.authTimeoutMs !== undefined));
-        }
-        const registration = seeded?.confirmRegistered();
-        if (registration && !registration.ok) {
-            failAdd(() => new ConnectStepError(`${client.displayName} reported success but TinyFish is not enabled there` +
-                `${registration.detail ? `: ${registration.detail}` : ''}.`, 'invalid_config'));
-        }
+        const seededNote = performMcpAdd(client, options, plan, telemetry.attemptId);
         telemetry.track('checkpoint', { phase: 'registered' });
-        // Codex runs OAuth inside `mcp add` and exits 0 either way, so the recorded state decides
-        // whether the login step below still runs. Unknown keeps the pre-probe behaviour.
-        const addSignedIn = probeAuthenticated?.();
-        if (addSignedIn)
-            telemetry.track('checkpoint', { phase: 'oauth_done' });
-        const degradedNotes = loginDegraded ? client.degradedAuthNotes : undefined;
-        if (useKeyAuth) {
-            errLine(degradedNotes?.keyed ?? 'Using your stored TinyFish API key — no browser sign-in needed.');
-            // Every other credential the CLI writes into a user-owned file says so too.
-            if (seeded)
-                errLine(seeded.note);
-        }
-        else if (degradedNotes) {
-            // Printed here, not with the closing line, so a `--launch` run sees it before the handover.
-            errLine(degradedNotes.deferred);
-        }
-        // A probed client signs in again only when its inline OAuth is known to have been abandoned.
-        const retryLogin = probeAuthenticated ? addSignedIn === false : true;
-        const pendingLogin = !useKeyAuth && retryLogin ? loginArgs : undefined;
-        let signInDeferred = !useKeyAuth && !addSignedIn && !pendingLogin;
-        if (pendingLogin) {
-            state.stage = 'client_oauth';
-            errLine('Signing in to TinyFish...');
-            const loginResult = spawn.sync(client.command, pendingLogin, {
-                stdio: 'inherit',
-                timeout: options.authTimeoutMs,
-            });
-            if (loginResult.error || loginResult.status !== 0) {
-                throw signInStepError(`Could not authenticate TinyFish in ${client.displayName}`, loginResult, options.authTimeoutMs !== undefined);
-            }
-            if (probeAuthenticated?.() === false)
-                signInDeferred = true;
-            else
-                telemetry.track('checkpoint', { phase: 'oauth_done' });
-        }
-        const authMode = useKeyAuth
-            ? AuthMode.ApiKey
-            : signInDeferred
-                ? 'deferred'
-                : AuthMode.OAuth;
+        const { authMode, signInDeferred } = completeAuthFlow(client, options, state, telemetry, {
+            useKeyAuth,
+            loginDegraded,
+            loginArgs,
+            probeAuthenticated,
+            seededNote,
+        });
         state.authMode = authMode;
         // Registration/OAuth make MCP work; later steps are cosmetic and must not fail the attempt.
         settle(state, telemetry, 'completed', { authMode });
@@ -582,6 +638,89 @@ const CLIENT_CONNECTORS = {
         }
     },
 };
+function parseMcpUrlOption(options) {
+    let mcpUrl = options.url ?? DEFAULT_MCP_URL;
+    if (mcpUrl.startsWith('-')) {
+        throw new Error(`Invalid --url value: ${mcpUrl}`);
+    }
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(mcpUrl);
+    }
+    catch {
+        throw new Error(`Invalid --url value: ${mcpUrl}`);
+    }
+    if (!['http:', 'https:'].includes(parsedUrl.protocol)) {
+        throw new Error(`Invalid --url value: ${mcpUrl}`);
+    }
+    // Page-minted attempt id rides in on --url. Strip before the URL becomes the MCP
+    // base — registration re-stamps it, and nothing else may carry it.
+    const pageAttemptId = parsedUrl.searchParams.get('connect_attempt_id');
+    let attemptId;
+    if (pageAttemptId !== null) {
+        parsedUrl.searchParams.delete('connect_attempt_id');
+        mcpUrl = parsedUrl.toString();
+        if (z.uuid().safeParse(pageAttemptId).success)
+            attemptId = pageAttemptId;
+    }
+    return { mcpUrl, attemptId };
+}
+async function connectAllPath(options, mcpUrl) {
+    if (options.launch) {
+        throw new Error('--launch is not supported with --all. Connect a single client to launch it.');
+    }
+    const exitCode = await runConnectAll({
+        apiKey: options.apiKey,
+        mcpUrl,
+        dryRun: options.dryRun ?? false,
+        uninstall: options.uninstall ?? false,
+        noLaunch: options.skipLaunch === true,
+        verbose: options.verbose ?? false,
+    });
+    // Preserve the 130 runGuarded set on Ctrl+C.
+    if (!process.exitCode)
+        process.exitCode = exitCode;
+}
+async function connectPickPath(options, mcpUrl) {
+    if (options.launch) {
+        throw new Error('--launch is not supported with --all. Connect a single client to launch it.');
+    }
+    const humanInitiated = detectHumanInitiated();
+    if (!humanInitiated) {
+        errLine('No terminal detected: connecting every detected harness (same as tinyfish connect --all).');
+    }
+    const exitCode = await runConnectAll({
+        apiKey: options.apiKey,
+        mcpUrl,
+        dryRun: false,
+        uninstall: false,
+        pick: humanInitiated,
+        verbose: options.verbose ?? false,
+    });
+    // Preserve the 130 runGuarded set on Ctrl+C.
+    if (!process.exitCode)
+        process.exitCode = exitCode;
+}
+async function connectSingleClient(client, options, mcpUrl, attemptId) {
+    const connectOptions = {
+        apiKey: options.apiKey,
+        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),
+        // Only here: a missing harness rescues via the CLI (PF-3707).
+        fallbackWhenMissing: true,
+        verbose: options.verbose ?? false,
+    };
+    const connector = CLIENT_CONNECTORS[client];
+    if (!connector) {
+        throw new Error('Unsupported client: ' +
+            client +
+            '. Supported clients: claude-code, codex, cursor, grok, hermes, openclaw, opencode');
+    }
+    await connector(connectOptions);
+}
 export function registerConnect(program) {
     program
         .command('connect')
@@ -599,94 +738,22 @@ export function registerConnect(program) {
         if (options.apiKey && !validateKeyFormat(options.apiKey)) {
             throw new Error('Invalid --api-key value');
         }
-        let mcpUrl = options.url ?? DEFAULT_MCP_URL;
-        if (mcpUrl.startsWith('-')) {
-            throw new Error(`Invalid --url value: ${mcpUrl}`);
-        }
-        let parsedUrl;
-        try {
-            parsedUrl = new URL(mcpUrl);
-        }
-        catch {
-            throw new Error(`Invalid --url value: ${mcpUrl}`);
-        }
-        if (!['http:', 'https:'].includes(parsedUrl.protocol)) {
-            throw new Error(`Invalid --url value: ${mcpUrl}`);
-        }
-        // Page-minted attempt id rides in on --url. Strip before the URL becomes the MCP
-        // base — registration re-stamps it, and nothing else may carry it.
-        const pageAttemptId = parsedUrl.searchParams.get('connect_attempt_id');
-        let attemptId;
-        if (pageAttemptId !== null) {
-            parsedUrl.searchParams.delete('connect_attempt_id');
-            mcpUrl = parsedUrl.toString();
-            if (z.uuid().safeParse(pageAttemptId).success)
-                attemptId = pageAttemptId;
-        }
+        const { mcpUrl, attemptId } = parseMcpUrlOption(options);
         if (options.all) {
             if (client) {
                 throw new Error('Pass either a client or --all, not both.');
             }
-            if (options.launch) {
-                throw new Error('--launch is not supported with --all. Connect a single client to launch it.');
-            }
-            const exitCode = await runConnectAll({
-                apiKey: options.apiKey,
-                mcpUrl,
-                dryRun: options.dryRun ?? false,
-                uninstall: options.uninstall ?? false,
-                noLaunch: options.skipLaunch === true,
-                verbose: options.verbose ?? false,
-            });
-            // Preserve the 130 runGuarded set on Ctrl+C.
-            if (!process.exitCode)
-                process.exitCode = exitCode;
+            await connectAllPath(options, mcpUrl);
             return;
         }
         if (options.dryRun || options.uninstall || options.skipLaunch) {
             throw new Error('--dry-run, --uninstall and --skip-launch are only supported with --all.');
         }
         if (!client) {
-            if (options.launch) {
-                throw new Error('--launch is not supported with --all. Connect a single client to launch it.');
-            }
-            const humanInitiated = detectHumanInitiated();
-            if (!humanInitiated) {
-                errLine('No terminal detected: connecting every detected harness (same as tinyfish connect --all).');
-            }
-            const exitCode = await runConnectAll({
-                apiKey: options.apiKey,
-                mcpUrl,
-                dryRun: false,
-                uninstall: false,
-                pick: humanInitiated,
-                verbose: options.verbose ?? false,
-            });
-            // Preserve the 130 runGuarded set on Ctrl+C.
-            if (!process.exitCode)
-                process.exitCode = exitCode;
+            await connectPickPath(options, mcpUrl);
             return;
         }
-        const connectOptions = {
-            apiKey: options.apiKey,
-            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),
-            // Only here: a missing harness rescues via the CLI (PF-3707).
-            fallbackWhenMissing: true,
-            verbose: options.verbose ?? false,
-        };
-        const connector = CLIENT_CONNECTORS[client];
-        if (connector) {
-            await connector(connectOptions);
-        }
-        else {
-            throw new Error('Unsupported client: ' +
-                client +
-                '. Supported clients: claude-code, codex, cursor, grok, hermes, openclaw, opencode');
-        }
+        await connectSingleClient(client, options, mcpUrl, attemptId);
         // Deferred to here so the notice lands after install output, not interleaved with it.
         emitNotice();
     });

package/dist/lib/client.d.ts

@@ -7,7 +7,7 @@ export declare function buildConnectHeaders(connect: ConnectMap, caller: string
 export declare function runSync(req: CliAgentRunParams, apiKey: string): Promise<AgentRunResponse>;
 export declare function runAsync(req: CliAgentRunParams, apiKey: string): Promise<AgentRunAsyncResponse>;
 export declare function runStream(req: CliAgentRunParams, apiKey: string, signal?: AbortSignal): AsyncGenerator<AgentRunWithStreamingResponse>;
-export declare function listRuns(opts: RunListParams, apiKey: string, timeout?: number): Promise<RunListResponse>;
+export declare function listRuns(opts: RunListParams, apiKey: string, timeout?: number, baseUrl?: string): Promise<RunListResponse>;
 export declare function getRun(runId: string, apiKey: string): Promise<Run>;
 export declare function getRunSteps(runId: string, apiKey: string): Promise<RunStepsResponse>;
 export declare function searchQuery(params: SearchQueryParams, apiKey: string): Promise<SearchQueryResponse>;

package/dist/lib/client.js

@@ -93,10 +93,12 @@ class TinyFishCliClient extends TinyFish {
         return (await response.json());
     }
 }
-function createSdkClient(apiKey, timeout) {
+function createSdkClient(apiKey, timeout, baseUrl) {
+    // An explicit base outranks the env default.
+    const resolvedBase = baseUrl ?? API_URL_OVERRIDE;
     return new TinyFishCliClient({
         apiKey,
-        ...(API_URL_OVERRIDE !== undefined ? { baseURL: API_URL_OVERRIDE } : {}),
+        ...(resolvedBase !== undefined ? { baseURL: resolvedBase } : {}),
         maxRetries: 0,
         // Fires per HTTP attempt, but maxRetries is 0 and the notice latches once per invocation.
         onResponse: ({ headers }) => captureNotice(headers),
@@ -263,9 +265,9 @@ export async function* runStream(req, apiKey, signal) {
         }
     }
 }
-export async function listRuns(opts, apiKey, timeout) {
+export async function listRuns(opts, apiKey, timeout, baseUrl) {
     try {
-        return await createSdkClient(apiKey, timeout).runs.list(opts);
+        return await createSdkClient(apiKey, timeout, baseUrl).runs.list(opts);
     }
     catch (error) {
         rethrowSdkError(error);

package/dist/lib/connect-all.js

@@ -40,6 +40,8 @@ const BROWSER_SIGN_IN = new Set(ALL_HARNESSES.filter((harness) => {
     const native = NATIVE_BY_HARNESS.get(harness);
     return !!native?.loginArgs || !!native?.oauthInAdd;
 }));
+// Derived: these refuse a keyless install, so no sign-in helps.
+const KEY_REQUIRED = new Set(ALL_HARNESSES.filter((harness) => !!NATIVE_BY_HARNESS.get(harness)?.keyRequired));
 // Derived: a native add carries the key, or the CLI holds it itself.
 const KEY_AUTH_CAPABLE = new Set(ALL_HARNESSES.filter((harness) => !!NATIVE_BY_HARNESS.get(harness)?.keyAuth || HARNESS_CAPABILITIES[harness].keyHeldByCli));
 // OpenCode ships no `mcp remove`, so the only removal is editing the config it wrote.
@@ -311,7 +313,8 @@ async function processHarness(detection, opts, prompt, oauthBudget, hoistedCliIn
         }
         headlessAuth = true;
     }
-    if (isTTY && !keyed && prompt) {
+    // Key-required harnesses refuse below; offering a browser sign-in would mislead.
+    if (isTTY && !keyed && prompt && !KEY_REQUIRED.has(harness)) {
         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]}... `);

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

@@ -34,7 +34,7 @@ export interface SeededInstall {
         detail?: string;
     };
 }
-export interface NativeMcpClient extends SupportedCommand {
+interface BaseMcpClient extends SupportedCommand {
     connectClient: Exclude<AgentClient, 'openclaw'>;
     /** Omitted where the `skills` CLI has no agent for this harness (Grok ships its own plugin). */
     skillAgent?: SkillAgent;
@@ -62,7 +62,6 @@ export interface NativeMcpClient extends SupportedCommand {
         args: string[];
         label: string;
     }[];
-    addArgs: (mcpUrl: string, oauthResource: string) => string[];
     /** Blocking terminal walkthrough; runs only behind the TTY gate. */
     launchWalkthrough?: () => void;
     /** Own window, never inherits stdio; reports its own outcome. */
@@ -70,6 +69,21 @@ export interface NativeMcpClient extends SupportedCommand {
     /** Printed after a successful connect, on both the launch and non-launch paths. */
     postConnectNote?: string;
 }
+/** Keyless installs use this argv; the harness signs itself in. */
+export interface OauthCapableMcpClient extends BaseMcpClient {
+    keyRequired?: false;
+    addArgs: (mcpUrl: string, oauthResource: string) => string[];
+}
+/** No sign-in exists here, so connect refuses a keyless install (Hermes). */
+export interface KeyRequiredMcpClient extends BaseMcpClient {
+    keyRequired: true;
+    keyAuth: NonNullable<BaseMcpClient['keyAuth']>;
+    /** Restoring any of these three would restore the OAuth fallback. */
+    addArgs?: never;
+    oauthInAdd?: never;
+    loginArgs?: never;
+}
+export type NativeMcpClient = OauthCapableMcpClient | KeyRequiredMcpClient;
 export declare const CLAUDE_CODE: NativeMcpClient;
 /**
  * `cmd` re-parses its command line after `/c`, so an unquoted `&` in the query string ends the
@@ -84,7 +98,7 @@ export declare function hermesRegistrationEnabled(home: string): {
     ok: boolean;
     detail?: string;
 };
-export declare const HERMES: NativeMcpClient;
+export declare const HERMES: KeyRequiredMcpClient;
 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[];

package/dist/lib/connect-clients.js

@@ -291,6 +291,7 @@ export const HERMES = {
     connectClient: 'hermes',
     skillAgent: 'hermes-agent',
     displayName: 'Hermes',
+    keyRequired: true,
     supportCheck: {
         args: ['mcp', 'add', '--help'],
         patterns: [/--auth\s+\{[^}]*oauth[^}]*\}/],
@@ -303,9 +304,6 @@ export const HERMES = {
         seedKey: seedHermesKey,
     },
     removals: [{ args: ['mcp', 'remove', 'tinyfish'], label: 'TinyFish registration from Hermes' }],
-    // Hermes completes OAuth while adding the server; a separate `mcp login` would authenticate twice.
-    oauthInAdd: true,
-    addArgs: (mcpUrl) => [...urlAddArgs(mcpUrl), '--auth', 'oauth'],
     launchWalkthrough: launchHermesWalkthrough,
     postConnectNote: 'Restart your Hermes session to pick up TinyFish — Hermes discovers MCP servers at startup.',
 };

package/dist/lib/mcp-endpoint.d.ts

@@ -1,4 +1,6 @@
 export declare const DEFAULT_MCP_URL = "https://agent.tinyfish.ai/mcp";
 export declare function endpointOf(url: string): string;
-/** `verifyMcpAuth` hits BASE_URL, so a sandbox key would 401 against prod. */
+/** One host serves `/mcp` and `/v1`, so origin is the API base. */
+export declare function apiBaseFromMcpUrl(mcpUrl: string): string | undefined;
+/** doctor reuses the CLI's own BASE_URL check; off-default endpoints cannot. */
 export declare function isDefaultEndpoint(mcpUrl: string): boolean;

package/dist/lib/mcp-endpoint.js

@@ -4,7 +4,16 @@ export function endpointOf(url) {
     const parsed = new URL(url);
     return `${parsed.origin}${parsed.pathname.replace(/\/$/, '')}`;
 }
-/** `verifyMcpAuth` hits BASE_URL, so a sandbox key would 401 against prod. */
+/** One host serves `/mcp` and `/v1`, so origin is the API base. */
+export function apiBaseFromMcpUrl(mcpUrl) {
+    try {
+        return new URL(mcpUrl).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** doctor reuses the CLI's own BASE_URL check; off-default endpoints cannot. */
 export function isDefaultEndpoint(mcpUrl) {
     try {
         return endpointOf(mcpUrl) === endpointOf(DEFAULT_MCP_URL);

package/dist/lib/verify.d.ts

@@ -11,4 +11,4 @@ export interface VerifyResult {
 /** Reachability check. Verify failure is a warning, never install failure. */
 export declare function verifyMcpHealth(mcpUrl: string): Promise<VerifyResult>;
 /** Authenticated check — where the CLI holds the key (Cursor, OpenClaw, Hermes). */
-export declare function verifyMcpAuth(apiKey: string): Promise<VerifyResult>;
+export declare function verifyMcpAuth(apiKey: string, apiBaseUrl?: string): Promise<VerifyResult>;

package/dist/lib/verify.js

@@ -62,10 +62,10 @@ export async function verifyMcpHealth(mcpUrl) {
     }
 }
 /** Authenticated check — where the CLI holds the key (Cursor, OpenClaw, Hermes). */
-export async function verifyMcpAuth(apiKey) {
+export async function verifyMcpAuth(apiKey, apiBaseUrl) {
     try {
         // Bound it: the SDK default is 600s, and a warning-only check must never hang an install.
-        await listRuns({ limit: 1 }, apiKey, VERIFY_TIMEOUT_MS);
+        await listRuns({ limit: 1 }, apiKey, VERIFY_TIMEOUT_MS, apiBaseUrl);
         return { depth: 'health+auth', ok: true };
     }
     catch (e) {

package/package.json

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