@tiny-fish/cli 0.22.1-next.198 → 0.23.0

package/README.md

@@ -44,6 +44,24 @@ With `--api-key`, Codex reads the key from `TINYFISH_API_KEY` instead of signing
 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 Grok
+
+Add TinyFish MCP and start the interactive walkthrough with one command:
+
+```bash
+npx -y @tiny-fish/cli@latest connect grok --launch --api-key sk-tinyfish-...
+```
+
+With a key, the registration carries `Authorization: Bearer ${TINYFISH_API_KEY}` and no browser
+sign-in is needed — Grok expands the variable at load, so the key itself never reaches argv or
+`config.toml`. The command exports it to your shell profile, so restart Grok (or open a new
+terminal) before using it. `X-API-Key` is not an option: Grok drops it whenever the server
+advertises OAuth metadata. Without a key, Grok has no `mcp login`, so sign in from `/mcps` inside
+Grok: select `tinyfish` and press `i`.
+
+Grok's skills come from its own marketplace plugin (`grok plugin install tinyfish --trust`), not
+the `use-tinyfish` skill this command installs for the other harnesses.
+
 ### Connect Hermes
 
 Add TinyFish MCP and the global `use-tinyfish` web skill, authenticate the CLI, and start the

package/dist/commands/connect.d.ts

@@ -11,6 +11,7 @@ interface NativeConnectOptions {
 }
 export declare function connectClaudeCode(options: NativeConnectOptions): Promise<ConnectAuthMode | undefined>;
 export declare function connectCodex(options: NativeConnectOptions): Promise<ConnectAuthMode | undefined>;
+export declare function connectGrok(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: {

package/dist/commands/connect.js

@@ -1,6 +1,6 @@
 import spawn from "cross-spawn";
 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 { CLAUDE_CODE, CODEX, GROK, HERMES, OPENCLAW, OPENCLAW_SKILL_INSTALL_ARGS, OPENCODE, launchNativeMcpClient, launchOpenClawWalkthrough, openExternalUrl, } from "../lib/connect-clients.js";
 import { ensureCliAuthenticated, installTinyFishCli, installWebSkill, SKILL_INSTALL_TIMEOUT_MS, UPGRADE_HINT, } from "../lib/connect-install.js";
 import { ConnectInterruptedError, ConnectStepError, createConnectTelemetry, requireCommandSupport, runGuarded, settle, spawnStepError, throwIfInterrupted, NON_INTERACTIVE_TIMEOUT_MS, } from "../lib/connect-runtime.js";
 import { cursorInstallDeeplink, cursorMcpPath, writeCursorMcpConfig, } from "../lib/cursor-config.js";
@@ -21,7 +21,8 @@ function removeExistingRegistration(client, removal) {
         return;
     throwIfInterrupted(result);
     const details = result.stderr?.trim() || result.error?.message || "unknown error";
-    if (/No MCP server named "tinyfish"/i.test(details))
+    // Claude Code double-quotes the name, Grok single-quotes it.
+    if (/No MCP server named ['"]tinyfish['"]/i.test(details))
         return;
     throw spawnStepError(`Could not remove existing ${removal.label}: ${details}`, result);
 }
@@ -135,6 +136,8 @@ async function connectNativeMcpClient(client, options) {
 function connectedLine(client, signInDeferred) {
     // The CLI never observes deferred auth, so don't claim "connected".
     if (signInDeferred) {
+        if (client.signInHint)
+            return client.signInHint;
         return (`TinyFish is configured in ${client.displayName}. ${client.displayName} will ask you ` +
             "to sign in to TinyFish the first time you use it.");
     }
@@ -147,9 +150,11 @@ function runPostInstallSteps(client, options, state, telemetry, signInDeferred)
         // Verbose on purpose: first-run setup must not go silent.
         installTinyFishCli({ verbose: true });
         telemetry.track("checkpoint", { phase: "cli_installed" });
-        state.stage = "skill_install";
-        installWebSkill(client);
-        telemetry.track("checkpoint", { phase: "skill_installed" });
+        if (client.skillAgent) {
+            state.stage = "skill_install";
+            installWebSkill(client);
+            telemetry.track("checkpoint", { phase: "skill_installed" });
+        }
         state.stage = "authentication";
         ensureCliAuthenticated(client.connectClient, options.apiKey);
         telemetry.track("checkpoint", { phase: "authenticated" });
@@ -164,6 +169,9 @@ function runPostInstallSteps(client, options, state, telemetry, signInDeferred)
             return;
         }
         state.stage = "walkthrough_launch";
+        // Before the handover, or the only sign-in instructions scroll past under the agent.
+        if (signInDeferred && client.signInHint)
+            errLine(client.signInHint);
         launchNativeMcpClient(client);
     }
     catch (error) {
@@ -188,6 +196,9 @@ export async function connectClaudeCode(options) {
 export async function connectCodex(options) {
     return connectNativeMcpClient(CODEX, options);
 }
+export async function connectGrok(options) {
+    return connectNativeMcpClient(GROK, options);
+}
 export async function connectHermes(options) {
     return connectNativeMcpClient(HERMES, options);
 }
@@ -321,6 +332,9 @@ export function launchAgent(client) {
     else if (client === "opencode") {
         launchNativeMcpClient(OPENCODE);
     }
+    else if (client === "grok") {
+        launchNativeMcpClient(GROK);
+    }
     else if (client === "openclaw") {
         launchOpenClawWalkthrough();
     }
@@ -337,7 +351,7 @@ export function registerConnect(program) {
     program
         .command("connect")
         .description("Connect TinyFish to an AI agent")
-        .argument("[client]", "Agent client to connect (claude-code, codex, cursor, hermes, openclaw, or opencode)")
+        .argument("[client]", "Agent client to connect (claude-code, codex, cursor, grok, hermes, openclaw, or opencode)")
         .option("--all", "Detect and connect every supported harness found on this machine")
         .option("--dry-run", "Print planned writes per harness without touching anything (--all only)")
         .option("--uninstall", "Remove TinyFish entries written by connect --all")
@@ -396,7 +410,7 @@ export function registerConnect(program) {
             throw new Error("--dry-run, --uninstall and --skip-launch are only supported with --all.");
         }
         if (!client) {
-            throw new Error("Pass a client (claude-code, codex, cursor, hermes, openclaw) or --all.");
+            throw new Error("Pass a client (claude-code, codex, cursor, grok, hermes, openclaw, opencode) or --all.");
         }
         const connectOptions = {
             apiKey: options.apiKey,
@@ -412,6 +426,9 @@ export function registerConnect(program) {
         else if (client === "codex") {
             await connectCodex(connectOptions);
         }
+        else if (client === "grok") {
+            await connectGrok(connectOptions);
+        }
         else if (client === "hermes") {
             await connectHermes(connectOptions);
         }
@@ -432,7 +449,7 @@ export function registerConnect(program) {
         else {
             throw new Error("Unsupported client: " +
                 client +
-                ". Supported clients: claude-code, codex, cursor, hermes, openclaw, opencode");
+                ". Supported clients: claude-code, codex, cursor, grok, hermes, openclaw, opencode");
         }
         // Deferred to here so the notice lands after install output, not interleaved with it.
         emitNotice();

package/dist/lib/connect-all.js

@@ -24,8 +24,13 @@ const AUTH_DEFERRED_AT_INSTALL = new Set(["codex"]);
 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`.
+// `--all` only reaches harnesses it can detect; Grok has a keyAuth but no detection yet.
 const KEY_AUTH_CAPABLE = new Set([
-    ...NATIVE_MCP_CLIENTS.filter((client) => !!client.keyAuth).map((client) => client.connectClient),
+    ...NATIVE_MCP_CLIENTS.filter((client) => !!client.keyAuth)
+        .map((client) => client.connectClient)
+        .filter((client) => ALL_HARNESSES.includes(client))
+        // Second map only narrows connectClient to Harness; the filter above is the real gate.
+        .map((client) => client),
     "cursor",
     "openclaw",
 ]);

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

@@ -5,13 +5,16 @@ export declare const DEFAULT_ONBOARDING_PROMPT: string;
 export declare const OPENCLAW_ONBOARDING_PROMPT: string;
 export interface NativeMcpClient extends SupportedCommand {
     connectClient: Exclude<AgentClient, "openclaw">;
-    skillAgent: "claude-code" | "codex" | "hermes-agent" | "opencode";
+    /** Omitted where the `skills` CLI has no agent for this harness (Grok ships its own plugin). */
+    skillAgent?: "claude-code" | "codex" | "hermes-agent" | "opencode";
     /** 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[];
     };
+    /** Shown when a keyless install leaves sign-in to the harness. */
+    signInHint?: string;
     loginArgs?: string[];
     /** Replaces the `loginArgs` step when `supportCheck.optionalPatterns` miss. */
     degradedAuthNotes?: {
@@ -37,6 +40,7 @@ export declare const CLAUDE_CODE: NativeMcpClient;
  */
 export declare function openExternalUrl(url: string): ReturnType<typeof spawn.sync>;
 export declare const CODEX: NativeMcpClient;
+export declare const GROK: 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. */

package/dist/lib/connect-clients.js

@@ -23,6 +23,14 @@ const HERMES_OAUTH_UNAVAILABLE_MESSAGE = "Could not confirm this Hermes installa
     "mcp add --help` did not list `--auth oauth`. Update Hermes and retry, or add TinyFish " +
     "manually with `hermes mcp add`." +
     SUPPORT_CHECK_DEBUG_HINT;
+const GROK_HTTP_UNAVAILABLE_MESSAGE = "Could not confirm this Grok installation supports remote MCP servers: `grok mcp add --help` " +
+    "did not list `--transport`. Update Grok and retry, or add TinyFish manually with " +
+    "`grok mcp add`." +
+    SUPPORT_CHECK_DEBUG_HINT;
+// Grok has no `mcp login`; sign-in only happens inside the TUI. No key nudge here: a revoked
+// key leaves Grok with no OAuth fallback, and doctor cannot spot that yet (PF-3618).
+const GROK_SIGN_IN_HINT = "TinyFish is registered in Grok. Open Grok, run `/mcps`, select tinyfish, and press `i` to " +
+    "sign in.";
 const OPENCLAW_SKILL_UNAVAILABLE_MESSAGE = "Could not confirm this OpenClaw installation supports global skill installation: `openclaw " +
     "skills install --help` did not list `--global` and `--acknowledge-clawhub-risk`. Update " +
     "OpenClaw and retry, or install manually with `openclaw skills install @tinyfish/tinyfish " +
@@ -150,6 +158,38 @@ export const CODEX = {
     removals: [{ args: ["mcp", "remove", "tinyfish"], label: "TinyFish registration from Codex" }],
     addArgs: (mcpUrl, oauthResource) => [...urlAddArgs(mcpUrl), "--oauth-resource", oauthResource],
 };
+const grokAddArgs = (mcpUrl) => [
+    "mcp",
+    "add",
+    "--transport",
+    "http",
+    "tinyfish",
+    mcpUrl,
+];
+export const GROK = {
+    command: "grok",
+    connectClient: "grok",
+    displayName: "Grok",
+    supportCheck: {
+        args: ["mcp", "add", "--help"],
+        patterns: [/--transport(?:[\s<=]|$)/m],
+        keyAuthPattern: HEADER_FLAG,
+        unavailableMessage: GROK_HTTP_UNAVAILABLE_MESSAGE,
+    },
+    // X-API-Key is dropped whenever the server advertises OAuth metadata; Bearer is not.
+    // Grok expands `${VAR}` in headers at load, so the key stays out of argv and config.toml.
+    keyAuth: {
+        viaEnv: true,
+        addArgs: (mcpUrl) => [
+            ...grokAddArgs(mcpUrl),
+            "--header",
+            "Authorization: Bearer ${TINYFISH_API_KEY}",
+        ],
+    },
+    signInHint: GROK_SIGN_IN_HINT,
+    removals: [{ args: ["mcp", "remove", "tinyfish"], label: "TinyFish registration from Grok" }],
+    addArgs: grokAddArgs,
+};
 function launchHermesWalkthrough() {
     const seedResult = spawn.sync("hermes", ["chat", "-Q", "-q", DEFAULT_ONBOARDING_PROMPT], {
         encoding: "utf8",
@@ -229,6 +269,7 @@ export const OPENCODE = {
 export const NATIVE_MCP_CLIENTS = [
     CLAUDE_CODE,
     CODEX,
+    GROK,
     HERMES,
     OPENCODE,
 ];

package/dist/lib/connect-install.js

@@ -81,6 +81,8 @@ const SKILL_UNCHECKABLE_PATTERN = /cannot be checked automatically/;
 // `skills add` exits non-zero on a fatal error, but per-skill install failures only print.
 const SKILL_INSTALL_FAILURE_PATTERN = /Failed to install/;
 export function installWebSkill(client) {
+    if (!client.skillAgent)
+        return;
     errLine(`Installing the TinyFish web skill in ${client.displayName}...`);
     // Piped rather than inherited so the per-skill failure line can be matched; echoed back
     // so the user still sees what `skills` reported.
@@ -112,11 +114,15 @@ export function updateWebSkill({ verbose }) {
     const connected = loadConfig().connect ?? {};
     const skillAgents = NATIVE_MCP_CLIENTS
         .filter((client) => connected[client.connectClient])
-        .map((client) => client.skillAgent);
+        .map((client) => client.skillAgent)
+        .filter((agent) => agent !== undefined);
     const hasOpenClaw = Boolean(connected["openclaw"]);
-    // Installs predating PF-3169 recorded nothing; ask `skills` to refresh what it tracks.
-    if (skillAgents.length === 0 && !hasOpenClaw)
-        return refreshWebSkillByHash(verbose);
+    // Installs predating PF-3169 recorded nothing; ask `skills` to refresh what it tracks. A
+    // skill-less recorded install (Grok, Cursor) may still have one from before, so refresh anyway
+    // — but there having been none is then expected, not an upgrade failure.
+    if (skillAgents.length === 0 && !hasOpenClaw) {
+        return refreshWebSkillByHash(verbose, Object.keys(connected).length > 0);
+    }
     let refreshed = false;
     if (skillAgents.length > 0) {
         reinstallWebSkill(skillAgents, verbose);
@@ -162,8 +168,8 @@ function reinstallWebSkill(skillAgents, verbose) {
     if (failed)
         throw new Error("Could not refresh the TinyFish web skill", { cause: result.error });
 }
-/** Fallback when no harness is recorded: ask `skills` to refresh whatever it tracks. */
-function refreshWebSkillByHash(verbose) {
+/** Fallback when no skill-bearing harness is recorded: refresh whatever `skills` tracks. */
+function refreshWebSkillByHash(verbose, untrackedIsExpected = false) {
     if (verbose)
         errLine("Refreshing the TinyFish web skill...");
     const result = spawn.sync("npx", ["-y", SKILLS_CLI_PACKAGE, "update", TINYFISH_WEB_SKILL, "--global", "--yes"], {
@@ -184,6 +190,8 @@ function refreshWebSkillByHash(verbose) {
         throw new Error("Could not refresh the TinyFish web skill", { cause: result.error });
     if (unchecked) {
         errLine("Run `tinyfish connect <client>` to reinstall the skill and restore update tracking.");
+        if (untrackedIsExpected)
+            return false;
         throw new Error("The TinyFish web skill cannot be checked for updates");
     }
     if (SKILL_NOT_INSTALLED_PATTERN.test(output)) {

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

@@ -1,6 +1,6 @@
 import { AuthMode } from "./harness-detect.js";
 export declare const NON_INTERACTIVE_TIMEOUT_MS = 10000;
-export type AgentClient = "claude-code" | "codex" | "cursor" | "hermes" | "openclaw" | "opencode";
+export type AgentClient = "claude-code" | "codex" | "cursor" | "grok" | "hermes" | "openclaw" | "opencode";
 type ConnectStage = "started" | "checkpoint" | "completed" | "failed" | "aborted" | "post_install_failed";
 type ConnectFailureStage = "prerequisite_check" | "registration_cleanup" | "registration" | "registration_or_authentication" | "client_oauth" | "cli_install" | "skill_install" | "authentication" | "walkthrough_launch";
 export declare const CONNECT_FAILURE_REASONS: readonly ["harness_not_installed", "harness_command_unsupported", "harness_too_old", "command_not_found", "timeout", "spawn_error", "nonzero_exit", "invalid_config"];

package/package.json

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