@zenrows/cli 1.3.0 → 1.3.1

package/dist/src/adapters/protected-fetch.js

@@ -93,11 +93,13 @@ export function buildParams(opts, config) {
         params.response_type = RESPONSE_TYPE[opts.output];
     return params;
 }
-export async function runFetch(opts, config, policy, apiKey) {
+export async function runFetch(opts, config, policy, apiKey, 
+/** The workspace `config` came from, when it is not the one above the cwd. */
+projectRoot) {
     assertDomainAllowed(opts.url, policy);
     validateAutoManual(opts, config);
     const params = buildParams(opts, config);
     const mode = params.mode === "auto" ? "auto" : "manual";
-    const result = await scrape(config.apiBase, apiKey, params, { timeoutMs: opts.timeoutMs });
+    const result = await scrape(config.apiBase, apiKey, params, { timeoutMs: opts.timeoutMs, projectRoot });
     return { result, params, mode };
 }

package/dist/src/cli/commands/init.js

@@ -141,7 +141,7 @@ export const init = {
                 section("Test Protected Fetch");
                 try {
                     const apiKey = requireApiKey(root);
-                    const { result } = await runFetch({ url: SMOKE_URL }, loadConfig(root), loadPolicy(root), apiKey);
+                    const { result } = await runFetch({ url: SMOKE_URL }, loadConfig(root), loadPolicy(root), apiKey, root);
                     log.success(`Protected Fetch OK — HTTP ${result.status}, ${result.body.length} bytes, ${formatRequestCost(result.costUsd, result.costCredits)}.`);
                 }
                 catch (err) {

package/dist/src/cli/commands/status.js

@@ -80,6 +80,7 @@ export const status = {
     },
 };
 /** Reachability probe that does not consume credits. */
+// Deliberately sends no X-ZenRows-Client: unauthenticated, non-billable reachability check.
 async function probe(apiBase) {
     try {
         const controller = new AbortController();

package/dist/src/core/agent-account.js

@@ -6,7 +6,8 @@
  * accountId, the human-facing claim URL, and claim metadata.
  */
 import { chmodSync, existsSync, unlinkSync } from "node:fs";
-import { attributionEnabled, getOrCreateTelemetryId, loadConfig, CLI_VERSION } from "./config.js";
+import { attributionEnabled, getOrCreateTelemetryId, loadConfig, CLI_USER_AGENT, CLI_VERSION } from "./config.js";
+import { agentClientHeader } from "./agent-client.js";
 import { ToolkitError } from "./errors.js";
 import { AGENT_SIGNUP_API_URL, WELL_KNOWN_PROTECTED_RESOURCE } from "./open-url.js";
 import { detectClient } from "./provenance.js";
@@ -42,7 +43,7 @@ export async function discoverSignupUrl(projectRoot, opts = {}) {
         const doFetch = opts.fetchImpl ?? fetch;
         const res = await doFetch(url, {
             method: "GET",
-            headers: { Accept: "application/json", "User-Agent": "zenrows-cli" },
+            headers: { Accept: "application/json", "User-Agent": CLI_USER_AGENT, ...agentClientHeader({ projectRoot }) },
         });
         if (!res.ok)
             return null;
@@ -128,7 +129,8 @@ export async function signupAgent(opts = {}) {
     // `telemetry:"off"` / ZENROWS_TELEMETRY=off suppresses every X-ZR-* header.
     const headers = {
         "content-type": "application/json",
-        "User-Agent": "zenrows-cli",
+        "User-Agent": CLI_USER_AGENT,
+        ...agentClientHeader(),
     };
     if (attributionEnabled()) {
         const p = detectClient();
@@ -211,7 +213,7 @@ export async function fetchAccountStatus(apiKey, opts = {}) {
     const doFetch = opts.fetchImpl ?? fetch;
     const res = await doFetch(url, {
         method: "GET",
-        headers: { "X-API-Key": apiKey, Accept: "application/json", "User-Agent": "zenrows-cli" },
+        headers: { "X-API-Key": apiKey, Accept: "application/json", "User-Agent": CLI_USER_AGENT, ...agentClientHeader() },
     });
     if (res.status !== 200) {
         const body = await res.text();

package/dist/src/core/agent-client.js

@@ -0,0 +1,98 @@
+/**
+ * Which AI coding agent is running the CLI, sent to Zenrows as the
+ * `X-ZenRows-Client` header so the dashboard Activity Log can say "CLI, driven
+ * by Claude Code" instead of just "CLI".
+ *
+ * Only the derived name is sent, never an environment value: the header carries
+ * one of the fixed names below, or the user's own `ZENROWS_CLIENT` override.
+ * When no agent is detected, no header is sent at all. `ZENROWS_TELEMETRY=off`
+ * (or config `telemetry: "off"`) suppresses it, override included.
+ *
+ * The gateway resolves the value against its own list of client names and
+ * stores anything it does not know as "other", so a name that is new here is
+ * harmless there.
+ */
+import { attributionEnabled } from "./config.js";
+/** The request header the Zenrows gateway reads the client name from. */
+export const CLIENT_HEADER = "X-ZenRows-Client";
+/** Env var a user sets to name the client themselves. It wins over detection. */
+export const CLIENT_OVERRIDE_ENV = "ZENROWS_CLIENT";
+/**
+ * The gateway considers at most 32 bytes of the header.
+ * Anything we send must also be a legal header value, or `fetch` throws on
+ * every request, so the override is held to a plain-token charset.
+ */
+const CLIENT_NAME = /^[a-z0-9][a-z0-9._-]{0,31}$/;
+/**
+ * Each agent's signal is a variable the agent itself sets in the shells it runs
+ * commands in, verified against the agent's docs or source. Agents we found no
+ * such variable for (Windsurf, Aider, Copilot CLI, the Copilot cloud agent) are
+ * left out rather than guessed.
+ *
+ * The first match wins. Every variable here is set by the agent itself when it
+ * launches a command, never by an IDE or extension in a terminal a person types
+ * in, so a human at the keyboard is never labelled as an agent.
+ */
+const AGENT_SIGNALS = [
+    // Cursor agent terminals: "Use the CURSOR_AGENT environment variable in your
+    // shell config to detect when Cursor is running".
+    // https://cursor.com/docs/agent/tools/terminal
+    { client: "cursor", vars: ["CURSOR_AGENT"] },
+    // GitHub Copilot agent mode in VS Code sets COPILOT_AGENT=1 in agent terminals.
+    // Sent as "vscode", the name the gateway already has for VS Code's agent.
+    // https://github.com/microsoft/vscode/pull/316267
+    // https://github.com/microsoft/vscode/blob/45373f06ff77cc97a7754a376548d8937fb3af54/src/vs/workbench/contrib/terminalContrib/chatAgentTools/browser/toolTerminalCreator.ts#L156-L159
+    { client: "vscode", vars: ["COPILOT_AGENT"] },
+    // OpenAI Codex CLI injects CODEX_THREAD_ID into every shell-tool environment,
+    // and CODEX_SANDBOX when the command runs sandboxed.
+    // https://github.com/openai/codex/blob/b741e480e203f037ca726bc2a76d99a8e8668e66/codex-rs/protocol/src/shell_environment.rs#L151-L154
+    // https://github.com/openai/codex/blob/b741e480e203f037ca726bc2a76d99a8e8668e66/codex-rs/core/src/spawn.rs#L23-L26
+    { client: "codex", vars: ["CODEX_THREAD_ID", "CODEX_SANDBOX"] },
+    // Gemini CLI sets GEMINI_CLI=1 for every shell command it executes.
+    // https://google-gemini.github.io/gemini-cli/docs/cli/commands.html
+    // https://github.com/google-gemini/gemini-cli/blob/fb972b2f87fe7d5b06d37eac711490162d98de2c/packages/core/src/services/shellExecutionService.ts#L582-L585
+    { client: "gemini-cli", vars: ["GEMINI_CLI"] },
+    // Claude Code sets CLAUDE_CODE_CHILD_SESSION=1 in what its Bash, PowerShell and
+    // Monitor tools, hooks and status line spawn, "only set by Claude Code itself
+    // ... and not by IDE extensions" (v2.1.172+). Not CLAUDECODE: the IDE extensions
+    // export that into every integrated terminal, so a person typing `zenrows` there
+    // would read as Claude Code. Older versions send no name rather than a wrong one,
+    // and so does a stdio MCP server, which gets neither variable's guarantee.
+    // https://code.claude.com/docs/en/env-vars
+    { client: "claude-code", vars: ["CLAUDE_CODE_CHILD_SESSION"] },
+];
+/** Every variable detection reads, so tests can keep the ambient shell out. */
+export const AGENT_ENV_VARS = AGENT_SIGNALS.flatMap((s) => s.vars);
+/**
+ * The client name to send, or `undefined` to send nothing. Pure: reads only
+ * `env`. A valid `ZENROWS_CLIENT` override is sent even when no agent is
+ * detected: setting it is an explicit opt-in. It replaces detection entirely, so
+ * an override that is not a valid name sends nothing rather than a detected name
+ * the user asked not to send.
+ */
+export function detectAgentClient(env) {
+    const override = env[CLIENT_OVERRIDE_ENV]?.trim();
+    if (override) {
+        // Same normalisation the gateway applies: lower-case, spaces to dashes.
+        const name = override.toLowerCase().split(/\s+/).join("-");
+        return CLIENT_NAME.test(name) ? name : undefined;
+    }
+    return AGENT_SIGNALS.find((s) => s.vars.some((v) => isSet(env[v])))?.client;
+}
+/** Empty, `0` and `false` (any case) count as unset, the way `CLAUDE_CODE_CHILD_SESSION=0` reads. */
+function isSet(value) {
+    const v = value?.trim().toLowerCase();
+    return Boolean(v) && v !== "0" && v !== "false";
+}
+/**
+ * The header to spread into a request to a Zenrows API: `{ "X-ZenRows-Client":
+ * name }` when there is a name and attribution is on, `{}` otherwise. Pass
+ * `projectRoot` when the caller works on a workspace other than the one above
+ * the cwd (`init --workspace`), so that workspace's `telemetry: "off"` applies.
+ */
+export function agentClientHeader(opts = {}) {
+    if (!attributionEnabled(opts.projectRoot))
+        return {};
+    const client = detectAgentClient(opts.env ?? process.env);
+    return client ? { [CLIENT_HEADER]: client } : {};
+}

package/dist/src/core/batch-api.js

@@ -19,6 +19,8 @@ import { join } from "node:path";
 import { ToolkitError, isKeyCapReached, keyCapReached, quotaExhausted } from "./errors.js";
 import { readAccount } from "./agent-account.js";
 import { registerSecret } from "./logger.js";
+import { CLI_USER_AGENT } from "./config.js";
+import { agentClientHeader } from "./agent-client.js";
 /** Confirmed Batch API base (no trailing slash). */
 export const DEFAULT_BATCH_API_BASE = "https://async.api.zenrows.com/v1";
 /** Env var to override the Batch API base (local/staging testing). */
@@ -50,7 +52,8 @@ export async function batchRequest(method, path, opts) {
     const headers = {
         "X-API-Key": opts.apiKey,
         Accept: "application/json",
-        "User-Agent": "zenrows-cli",
+        "User-Agent": CLI_USER_AGENT,
+        ...agentClientHeader(),
     };
     if (opts.body !== undefined)
         headers["Content-Type"] = "application/json";

package/dist/src/core/browser-api.js

@@ -14,7 +14,8 @@
 import { ToolkitError, isKeyCapReached, keyCapReached, quotaExhausted } from "./errors.js";
 import { readAccount } from "./agent-account.js";
 import { registerSecret } from "./logger.js";
-import { CLI_VERSION } from "./config.js";
+import { CLI_USER_AGENT } from "./config.js";
+import { agentClientHeader } from "./agent-client.js";
 /** Managed Browser session API base (no trailing slash). Tied to the MCP host. */
 export const DEFAULT_BROWSER_BASE = "https://mcp.zenrows.com";
 /** Env var to override the Browser API base (local/staging testing). */
@@ -42,7 +43,8 @@ export async function browserRequest(method, path, opts) {
     const headers = {
         Authorization: `Bearer ${opts.apiKey}`,
         Accept: "application/json",
-        "User-Agent": `zenrows-cli/${CLI_VERSION}`,
+        "User-Agent": CLI_USER_AGENT,
+        ...agentClientHeader(),
     };
     if (opts.body !== undefined)
         headers["Content-Type"] = "application/json";

package/dist/src/core/config.js

@@ -11,19 +11,23 @@ export const CONFIG_VERSION = "0.1.0";
  * entrypoint) so core modules — telemetry, signup provenance — can read it
  * without an import cycle. `VERSION` in `cli/index.ts` re-exports this.
  */
-export const CLI_VERSION = "1.3.0";
+export const CLI_VERSION = "1.3.1";
+/** The User-Agent on every request to a Zenrows API. The gateway reads the version from it. */
+export const CLI_USER_AGENT = `zenrows-cli/${CLI_VERSION}`;
 /** Env var to override the Fetch and Extract API base (local/staging testing). */
 export const API_BASE_ENV = "ZENROWS_API_BASE";
 /**
  * Env var to opt out of anonymous attribution. The toolkit never POSTs to a
  * telemetry endpoint; attribution is only anonymous provenance headers on the
- * signup request + `utm_*` params on the browser URLs a human opens. Setting
- * this to `off` (or config `telemetry: "off"`) suppresses all of it.
+ * signup request, the `X-ZenRows-Client` agent name on API requests
+ * (`agent-client.ts`), and `utm_*` params on the browser URLs a human opens.
+ * Setting this to `off` (or config `telemetry: "off"`) suppresses all of it.
  */
 export const TELEMETRY_ENV = "ZENROWS_TELEMETRY";
 /**
- * Whether to attach anonymous attribution (signup provenance headers + `utm_*`
- * on browser URLs). Off when `ZENROWS_TELEMETRY=off` or config `telemetry:"off"`.
+ * Whether to attach anonymous attribution (signup provenance headers, the
+ * `X-ZenRows-Client` agent name, `utm_*` on browser URLs). Off when
+ * `ZENROWS_TELEMETRY=off` or config `telemetry:"off"`.
  * There is no telemetry beacon — this only gates what rides on requests/URLs
  * the toolkit already makes.
  */

package/dist/src/core/http.js

@@ -9,7 +9,8 @@ import { ToolkitError, isKeyCapReached, keyCapReached, quotaExhausted } from "./
 import { readAccount } from "./agent-account.js";
 import { ENV_KEY, resolveApiKey } from "./auth.js";
 import { registerSecret } from "./logger.js";
-import { CLI_VERSION } from "./config.js";
+import { CLI_USER_AGENT } from "./config.js";
+import { agentClientHeader } from "./agent-client.js";
 /**
  * Client-side timeout for a Fetch and Extract request, deliberately ABOVE the
  * gateway's own 90s request budget.
@@ -56,7 +57,7 @@ export async function scrape(apiBase, apiKey, params, opts = {}) {
     try {
         res = await fetch(full, {
             method: "GET",
-            headers: { "User-Agent": `zenrows-cli/${CLI_VERSION}`, "Accept-Encoding": "gzip, deflate" },
+            headers: { "User-Agent": CLI_USER_AGENT, "Accept-Encoding": "gzip, deflate", ...agentClientHeader({ projectRoot: opts.projectRoot }) },
             signal: controller.signal,
         });
     }

package/dist/src/core/usage.js

@@ -11,6 +11,8 @@ import { isQuotaError, zrErrorDetail } from "./http.js";
 import { readAccount } from "./agent-account.js";
 import { ENV_KEY, resolveApiKey } from "./auth.js";
 import { registerSecret } from "./logger.js";
+import { CLI_USER_AGENT } from "./config.js";
+import { agentClientHeader } from "./agent-client.js";
 /** Build the plan-usage URL from the configured API base. */
 export function usageUrl(apiBase) {
     const base = apiBase.endsWith("/") ? apiBase : apiBase + "/";
@@ -27,7 +29,7 @@ export async function fetchUsage(apiBase, apiKey, opts = {}) {
     try {
         res = await doFetch(url, {
             method: "GET",
-            headers: { "X-API-Key": apiKey, Accept: "application/json", "User-Agent": "zenrows-cli" },
+            headers: { "X-API-Key": apiKey, Accept: "application/json", "User-Agent": CLI_USER_AGENT, ...agentClientHeader() },
             signal: controller.signal,
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zenrows/cli",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Open-source CLI, MCP, skills, templates, workflows, recipes, and evals layer for giving AI agents reliable access to protected web data through Zenrows cloud infrastructure.",
   "type": "module",
   "license": "MIT",