metergraph-cli 0.2.0-preview.4 → 0.2.0-preview.6

package/src/auth-login.js

@@ -39,6 +39,11 @@ import { deadline, trapSignals } from "./transport.js";
 // server-verified workspace UUID. Token values, the authorization code, the
 // PKCE verifier, absolute paths and server text never leave this module.
 // progress(text) prints human progress lines; it is a no-op with --json.
+// options.announce(data), given only with --json --no-browser, receives the
+// login data with an open_url next action as soon as the authorization URL
+// exists, while the listener keeps waiting. The caller prints it as the one
+// JSON line, so an agent can hand the URL to a person; approval-handoff.js
+// lets the agent's command exit then while this process keeps waiting.
 
 export async function runLogin(options, progress) {
   const ctx = {
@@ -58,21 +63,12 @@ export async function runLogin(options, progress) {
   if (options.runtime !== "local") return end("unsupported", "runtime_not_supported", GUIDE);
   const remote = detectRemoteSession();
   if (remote !== null) return end("unsupported", remote, GUIDE);
-  // --json cannot show a person the --no-browser URL. A rerun with a saved,
-  // working grant needs no URL, so only refuse once approval is required.
-  const noBrowserHandoff = () => end("unsupported", "no_browser_requires_terminal", {
-    kind: "run_in_terminal",
-    message: "Run the same login command in a terminal without --json to see the sign in URL.",
-  });
-  const urlUnshowable = options.json && options.noBrowser;
-
   const trap = trapSignals();
   try {
     const root = resolveProject(options.project);
     const configDir = resolveConfigDir(options.configDir);
     const existing = readBinding(root);
     const bound = existing?.binding ?? null;
-    if (urlUnshowable && (bound === null || options.reconnect)) return noBrowserHandoff();
     // Setup pins a deployment model before sign in. A stale binding for a
     // different profile must never be silently reused or reconnected.
     if (options.expectedProfile && bound !== null && !options.reconnect &&
@@ -102,9 +98,11 @@ export async function runLogin(options, progress) {
       }
       if (session.outcome !== "login_required") return end(session.outcome, session.reason);
     }
-    if (urlUnshowable) return noBrowserHandoff();
 
-    const flow = await authorize(options, ctx, trap.signal, progress);
+    const announce = options.announce
+      ? (next) => options.announce(loginData({ ...ctx, status: "approval_pending" }, next))
+      : null;
+    const flow = await authorize(options, ctx, trap.signal, progress, announce);
     if (!flow.ok) return end(flow.outcome, flow.reason, flow.next ?? null);
     const { endpoints, clientId, grant } = flow;
 
@@ -169,7 +167,7 @@ export async function runLogin(options, progress) {
 // written here. A validated grant that is not accepted is sent for revocation
 // before returning; that is best effort, and a token response that fails
 // validation cannot be revoked.
-async function authorize(options, ctx, cancel, progress) {
+async function authorize(options, ctx, cancel, progress, announce) {
   const preflight = await runDoctor({ origin: ctx.origin, timeoutMs: AUTH_HTTP_TIMEOUT_MS });
   if (cancel.aborted) return fail("authorization_failed", "cancelled");
   if (preflight.outcome !== "authentication_required") return fail(preflight.outcome, preflight.reason);
@@ -217,7 +215,9 @@ async function authorize(options, ctx, cancel, progress) {
     const seconds = Math.round(options.timeoutMs / 1000);
     // A wait armed after Ctrl+C has already settled; do not show the URL.
     if (cancel.aborted) return fail("authorization_failed", "cancelled");
-    if (options.noBrowser) {
+    if (options.noBrowser && announce) {
+      announce(openUrl(url, seconds, "sign in with Metadata access"));
+    } else if (options.noBrowser) {
       progress(
         "Open this URL in a browser on this machine to sign in:\n" +
           `${url}\n` +
@@ -375,6 +375,20 @@ function fail(outcome, reason, next = null) {
   return { ok: false, outcome, reason, next };
 }
 
+// The next action a --json --no-browser run prints while it waits. The URL is
+// the authorization request: public client ID, loopback redirect, state and
+// PKCE challenge. It carries no token, code or verifier.
+export function openUrl(url, seconds, purpose) {
+  return {
+    kind: "open_url",
+    url,
+    timeout_seconds: seconds,
+    message: `Show this URL to the person now and ask them to open it in a browser on this machine to ` +
+      `${purpose}. A background process waits up to ${seconds} seconds for their approval. ` +
+      "After they approve, run the same command again to continue.",
+  };
+}
+
 const GUIDE = { kind: "connection_guide", url: CONNECTION_GUIDE_URL };
 const RECONNECT = {
   kind: "reconnect",

package/src/cli.js

@@ -10,14 +10,15 @@ import {
   helpData,
   helpText,
   skillText,
+  skillsText,
   toJsonLine,
   versionData,
 } from "./output.js";
 import { runRead } from "./read.js";
 import { readMessage, readText } from "./read-output.js";
-import { runSkill } from "./skill.js";
+import { listSkillPack, runSkill, runSkillPack } from "./skill.js";
 import { runSetup } from "./setup.js";
-import { containsKnownCredential, preflightNonHostedSetup } from "./setup-deployment.js";
+import { containsKnownCredential, preflightNonHostedSetup, prerequisiteGuide, resumeNonHostedRoute } from "./setup-deployment.js";
 import { VERSION } from "./constants.js";
 import { runVerify } from "./verify.js";
 import { verifyMessage, verifyText } from "./verify-output.js";
@@ -74,8 +75,10 @@ async function run(argv, { stdout, stderr }) {
     // Human progress goes to stderr, never with --json, so stdout carries
     // only the final result.
     const progress = parsed.json ? () => {} : (text) => stderr.write(`${text}\n`);
+    const pending = announcer(parsed, stdout, (data) => data);
     const { outcome, reason, data } =
-      parsed.command === "login" ? await runLogin(parsed, progress) : await runLogout(parsed);
+      parsed.command === "login" ? await runLogin({ ...parsed, announce: pending.announce }, progress) : await runLogout(parsed);
+    if (pending.result) return pending.result;
     const message = authMessage(outcome, reason);
     const result = envelope({
       command: parsed.command,
@@ -89,14 +92,18 @@ async function run(argv, { stdout, stderr }) {
   }
 
   if (parsed.command === "setup") {
-    const routed = parsed.deployment === "managed"
+    const options = resumeNonHostedRoute(parsed);
+    const routed = options.deployment === "managed"
       ? { proceed: true, profile: "managed" }
-      : await preflightNonHostedSetup(parsed);
+      : await preflightNonHostedSetup(options);
     const progress = parsed.json ? () => {} : (line) =>
       stderr.write(containsKnownCredential(line, routed) ? "Setup progress.\n" : `${line}\n`);
+    // The announced line is checked for known credentials like the final one.
+    const pending = announcer(parsed, stdout, (data) => containsKnownCredential(data, routed) ? null : data);
     const response = routed.proceed
-      ? await runSetup({ ...parsed, expectedProfile: routed.profile ?? null }, progress)
+      ? await runSetup({ ...options, expectedProfile: routed.profile ?? null, announce: pending.announce }, progress)
       : routed;
+    if (pending.result) return pending.result;
     const { outcome, reason, data } = response;
     let result = envelope({ command: "setup", outcome, reason, data,
       message: outcome === "ok" ? null : "Setup did not complete. Review the reason and retry safely." });
@@ -106,7 +113,8 @@ async function run(argv, { stdout, stderr }) {
     const receipt = result.data?.receipt;
     const summary = receipt ? `Workspace: ${receipt.workspace_id}\nDeployment: ${receipt.deployment_profile} at ${receipt.origin}\nCompleted: ${receipt.completed_steps.join(", ")}\nPending: ${receipt.pending_steps.join(", ")}\n` : "";
     const identity = repositoryLine(result.data?.repository);
-    const human = `Metergraph setup: ${result.data?.status ?? "not_ready"}\n${summary}${identity}Application traffic verified: no\n${result.ok ? "Next: instrument your application and verify an exact trace.\n" : `Result: ${result.outcome} (${result.error.reason})\n`}`;
+    const guide = handoffLines(result.data);
+    const human = `Metergraph setup: ${result.data?.status ?? "not_ready"}\n${summary}${identity}${guide}Application traffic verified: no\n${result.ok ? "Next: instrument your application and verify an exact trace.\n" : `Result: ${result.outcome} (${result.error.reason})\n`}`;
     if (containsKnownCredential(human, routed)) {
       result = envelope({ command: "setup", outcome: "unsupported", reason: "credential_echo" });
       stdout.write(parsed.json ? toJsonLine(result) : "Setup stopped.\n");
@@ -151,6 +159,20 @@ async function run(argv, { stdout, stderr }) {
     return result;
   }
 
+  if (parsed.command === "skills") {
+    const { outcome, reason, message, data } =
+      parsed.action === "list" ? listSkillPack(parsed) : runSkillPack(parsed);
+    const result = envelope({
+      command: `skills ${parsed.action}`,
+      outcome,
+      reason,
+      data,
+      message: outcome === "ok" ? null : message,
+    });
+    stdout.write(parsed.json ? toJsonLine(result) : skillsText(result, message));
+    return result;
+  }
+
   const { outcome, reason, report } = await runDoctor({
     origin: parsed.origin,
     timeoutMs: parsed.timeoutMs,
@@ -166,6 +188,47 @@ async function run(argv, { stdout, stderr }) {
   return result;
 }
 
+// With --json --no-browser, login and setup print their one JSON line as
+// soon as a person must open an approval URL, then keep waiting for the
+// callback; bin/metergraph.js has already moved this process to the
+// background (approval-handoff.js). Whatever the run does afterwards, that
+// line is its result; the agent reruns the command to continue. screen(data) returns
+// the data to print, or null to print a credential_echo refusal instead.
+function announcer(parsed, stdout, screen) {
+  const pending = { announce: null, result: null };
+  if (!parsed.json || !parsed.noBrowser) return pending;
+  pending.announce = (data) => {
+    if (pending.result) return;
+    const safe = screen(data);
+    pending.result = safe === null
+      ? envelope({ command: parsed.command, outcome: "unsupported", reason: "credential_echo" })
+      : envelope({ command: parsed.command, outcome: "action_required", reason: "browser_approval_required",
+        data: safe, message: authMessage("action_required", "browser_approval_required") });
+    stdout.write(toJsonLine(pending.result));
+  };
+  return pending;
+}
+
+// What an operator handoff is waiting for, in fixed text: the route, each
+// unconfirmed prerequisite with its guidance, and the next action.
+function handoffLines(data) {
+  if (data?.status !== "operator_handoff") return "";
+  let text = data.origin ? `Deployment: ${data.deployment_profile} at ${data.origin}\n` : "";
+  if (data.workspace_id) text += `Workspace: ${data.workspace_id}\n`;
+  if (data.pending_prerequisites.length > 0) {
+    text += "Confirm each prerequisite, then rerun with --confirm-prerequisites:\n";
+    for (const name of data.pending_prerequisites) {
+      text += `  - ${name}: ${prerequisiteGuide(name, data.deployment_profile) ?? "see the guide"}\n`;
+    }
+  }
+  const next = data.next_action;
+  if (next?.message && !(next.kind === "complete_prerequisite" && data.pending_prerequisites.includes(next.prerequisite))) {
+    text += `Next: ${next.message}\n`;
+  }
+  if (next?.url) text += `Guide: ${next.url}\n`;
+  return text;
+}
+
 // One line on the repository identity setup found or recorded. The value is
 // owner/name only; a remote URL is never shown.
 function repositoryLine(repository) {

package/src/constants.js

@@ -39,6 +39,10 @@ export const SKILL_CLIENTS = Object.freeze({
 });
 export const SKILL_RUNTIMES = Object.freeze(["local", "cloud"]);
 
+// Where every Metergraph skill is published. Claude Desktop installs the
+// skills from here as a plugin marketplace instead of from project files.
+export const SKILLS_REPOSITORY_URL = "https://github.com/metergraph/skills";
+
 // Recognized values that cannot load project skill files. They get a pointer
 // to the connection guide instead of a usage error, and nothing is written.
 export const HANDOFF_SKILL_CLIENTS = Object.freeze({
@@ -137,6 +141,7 @@ export const EXIT_CODES = Object.freeze({
   permission_denied: 15,
   rate_limited: 16,
   cancelled: 17,
+  action_required: 18,
 });
 
 export const EXIT_CODE_MEANINGS = Object.freeze({
@@ -173,4 +178,8 @@ export const EXIT_CODE_MEANINGS = Object.freeze({
   rate_limited: "The service asked the CLI to slow down. Nothing was retried. Try again later.",
   cancelled:
     "A read command was interrupted before it finished. Read commands never change workspace configuration or telemetry.",
+  action_required:
+    "A person must act before this command can finish; data.next_action says what to do. " +
+    "With --json --no-browser the command exits as soon as the approval URL exists, and a background " +
+    "process waits for approval until --timeout-ms. After approval, run the same command again to continue.",
 });

package/src/deployment-route.js

@@ -117,7 +117,7 @@ const DEPLOYMENT_PATH = "/v1/deployment";
 const MIN_TIMEOUT_MS = 100;
 const MAX_TIMEOUT_MS = 60000;
 
-function action(kind, prerequisite = null) {
+export function action(kind, prerequisite = null) {
   // Kinds are constants from this module, so this is a programming error.
   if (!ACTION_KINDS.includes(kind)) throw new Error("unknown next action kind");
   return { kind, prerequisite, url: CONNECTION_GUIDE_URL };

package/src/output.js

@@ -73,15 +73,46 @@ const SKILL_OPTIONS = [
   {
     name: "--runtime",
     value: "RUNTIME",
-    summary: "Required. local or cloud: where the client runs. Recorded, not detected.",
+    summary: "local (default) or cloud: where the client runs. Recorded, not detected.",
   },
   { name: "--project", value: "DIR", summary: "Existing project directory. Default: the current directory." },
   { name: "--json", value: null, summary: "Print one JSON line on stdout." },
 ];
 
 const SKILL_USAGE = [
-  "metergraph skill install --client CLIENT --runtime RUNTIME [--project DIR] [--json]",
-  "metergraph skill update --client CLIENT --runtime RUNTIME [--project DIR] [--json]",
+  "metergraph skill install --client CLIENT [--runtime RUNTIME] [--project DIR] [--json]",
+  "metergraph skill update --client CLIENT [--runtime RUNTIME] [--project DIR] [--json]",
+];
+
+const SKILLS_USAGE = [
+  "metergraph skills install --client CLIENT [--runtime RUNTIME] [--project DIR] [--json]",
+  "metergraph skills update --client CLIENT [--runtime RUNTIME] [--project DIR] [--json]",
+  "metergraph skills list [--project DIR] [--json]",
+];
+
+const SKILLS_LIST_OPTIONS = [
+  { name: "--project", value: "DIR", summary: "Existing project directory. Default: the current directory." },
+  { name: "--json", value: null, summary: "Print one JSON line on stdout." },
+];
+
+const SKILLS_STATE_LABELS = {
+  not_installed: "not installed",
+  installed: "installed",
+  outdated: "older revision; run skills update",
+  modified: "changed since install; left alone",
+  missing: "receipt only; run skills install",
+  not_owned: "not installed by this CLI; left alone",
+  receipt_invalid: "receipt not valid",
+  unsafe_path: "unsafe path",
+};
+
+// How a coding agent gets an approval URL from login or setup. Many agent
+// shells show output only after the command exits, which is too late.
+const AGENT_APPROVAL_HELP = [
+  "From a coding agent: with --json --no-browser, a step that needs approval exits at once",
+  "with exit 18 action_required and the URL in data.next_action.url, while a background",
+  "process keeps waiting for the approval until --timeout-ms. Show the URL to the person,",
+  "and after they approve, run the same command again to continue.",
 ];
 
 const CONFIG_DIR_OPTION = {
@@ -112,7 +143,7 @@ const LOGIN_OPTIONS = [
     summary: `Time to wait for the browser, ${LOGIN_MIN_TIMEOUT_MS} to ${LOGIN_MAX_TIMEOUT_MS}. Default ${LOGIN_DEFAULT_TIMEOUT_MS}.`,
   },
   { name: "--signup", value: null, summary: "Start at the hosted sign up page. Managed service only." },
-  { name: "--no-browser", value: null, summary: "Print the sign in URL on stderr instead of opening a browser. With --json, only a rerun that needs no sign in succeeds." },
+  { name: "--no-browser", value: null, summary: "Print the sign in URL on stderr instead of opening a browser. With --json, exit 18 with it in data.next_action (open_url)." },
   { name: "--reconnect", value: null, summary: "Allow switching a bound project to another origin or workspace." },
   { name: "--json", value: null, summary: "Print one JSON line on stdout." },
 ];
@@ -257,6 +288,7 @@ export function helpData(topic) {
       "metergraph --version [--json]",
       "metergraph doctor [--url ORIGIN] [--timeout-ms N] [--json]",
       ...SKILL_USAGE,
+      ...SKILLS_USAGE,
       LOGIN_USAGE,
       LOGOUT_USAGE,
       SETUP_USAGE,
@@ -283,6 +315,25 @@ export function helpData(topic) {
           "Replace a skill this CLI installed, and that is unchanged since, with the bundled revision.",
         options: SKILL_OPTIONS,
       },
+      {
+        name: "skills install",
+        summary:
+          "Copy the Metergraph workflow skills bundled with this CLI, such as the model-swap loop, into one " +
+          "client's project skill directory. Never replaces a skill it did not install. No network requests, no sign in.",
+        options: SKILL_OPTIONS,
+      },
+      {
+        name: "skills update",
+        summary:
+          "Replace workflow skills this CLI installed, and that are unchanged since, with the bundled revisions, " +
+          "and install skills added since.",
+        options: SKILL_OPTIONS,
+      },
+      {
+        name: "skills list",
+        summary: "List the bundled workflow skills and whether each is installed for each client. Writes nothing.",
+        options: SKILLS_LIST_OPTIONS,
+      },
       {
         name: "login",
         summary:
@@ -311,7 +362,7 @@ export function helpData(topic) {
           { name: "--timeout-ms", value: "N", summary: "Time to wait for browser approval." },
           { name: "--signup", value: null, summary: "Start at hosted sign up when the project needs login." },
           { name: "--reconnect", value: null, summary: "Permit switching an existing project binding." },
-          { name: "--no-browser", value: null, summary: "Print approval URL on stderr. With --json, only a rerun that needs no approval succeeds." },
+          { name: "--no-browser", value: null, summary: "Print approval URL on stderr. With --json, exit 18 with it in data.next_action (open_url); rerun after approval." },
           { name: "--repair", value: null, summary: "Explicitly approve replacement of an acknowledged key that no longer verifies." },
           { name: "--deployment", value: "MODEL", summary: "managed, customer-local, byoc or oss. Default managed." },
           { name: "--confirm-prerequisites", value: null, summary: "Attest deployment prerequisites are met; it does not verify bundle publication." },
@@ -375,6 +426,7 @@ export function helpText(topic) {
       const flag = option.value ? `${option.name} ${option.value}` : option.name;
       lines.push(`  ${flag.padEnd(25)}${option.summary}`);
     }
+    lines.push("", ...AGENT_APPROVAL_HELP);
   } else if (topic === "login" || topic === "logout") {
     const login = topic === "login";
     lines.push(`Usage: ${login ? LOGIN_USAGE : LOGOUT_USAGE}`, "");
@@ -407,6 +459,7 @@ export function helpText(topic) {
       const flag = option.value ? `${option.name} ${option.value}` : option.name;
       lines.push(`  ${flag.padEnd(18)}${option.summary}`);
     }
+    if (login) lines.push("", ...AGENT_APPROVAL_HELP);
   } else if (topic === "verify") {
     lines.push(`Usage: ${VERIFY_USAGE}`, "", "Uses the saved Metadata grant to poll for one exact, processed trace.",
       "The source label is supplied by the caller. A Metadata match alone does not prove application traffic.",
@@ -463,6 +516,40 @@ export function helpText(topic) {
       "",
       "Discovery stays pending until the client itself loads the skill.",
     );
+  } else if (topic === "skills") {
+    lines.push(
+      "Usage:",
+      ...SKILLS_USAGE.map((usage) => `  ${usage}`),
+      "",
+      "Copies the Metergraph workflow skills bundled with this CLI into one client's project",
+      "skill directory, one folder per skill, and records ownership of each in",
+      ".metergraph/skills/NAME.json. The skills come from https://github.com/metergraph/skills",
+      "at the commit this release pins. They cover investigation and the model-swap loop:",
+      "choose a workload, choose traces and models, define the eval, run the analysis,",
+      "summarize the report and rerun. The setup skill is installed by \"metergraph skill\".",
+      "",
+      "Writes nothing else. Makes no network requests, does not sign in and does not",
+      "configure MCP, client settings, AGENTS.md or CLAUDE.md.",
+      "",
+      "Options:",
+    );
+    for (const option of SKILL_OPTIONS) {
+      const flag = option.value ? `${option.name} ${option.value}` : option.name;
+      lines.push(`  ${flag.padEnd(18)}${option.summary}`);
+    }
+    lines.push(
+      "",
+      "install never replaces an existing skill. update replaces only skills this CLI",
+      "installed and that are unchanged since, and installs skills added since. A conflict",
+      "on one skill leaves the others in place. There is no force option.",
+      "list takes only --project and reports every client. It never writes.",
+      "",
+      "Claude Desktop (--client claude-desktop) cannot load project skill files. It exits",
+      "with code 6, writes nothing and points to the metergraph/skills plugin marketplace.",
+      "ChatGPT and cloud runtimes without a shell get the connection guide instead.",
+      "",
+      "Discovery stays pending until the client itself loads the skills.",
+    );
   } else {
     lines.push(
       `metergraph ${VERSION} (preview)`,
@@ -472,6 +559,7 @@ export function helpText(topic) {
       "  metergraph --version [--json]    Show the CLI version",
       "  metergraph doctor [options]      Check a Metergraph service, read only",
       "  metergraph skill install|update  Install or update the agent skill in a project",
+      "  metergraph skills install|update|list  Workflow skills, such as the model-swap loop",
       "  metergraph login [options]       Sign in and bind a project to a workspace",
       "  metergraph logout [options]      Revoke and remove a project's sign in",
       "  metergraph setup [options]       Approve and write a private ingest key",
@@ -485,6 +573,7 @@ export function helpText(topic) {
       "",
       'Run "metergraph help doctor" for doctor options.',
       'Run "metergraph help skill" for skill options.',
+      'Run "metergraph help skills" for workflow skill options.',
       'Run "metergraph help login" or "metergraph help logout" for sign in options.',
       'Run "metergraph help verify" for exact-trace verification options.',
       'Run "metergraph help COMMAND" for status, context, capabilities, usage, routes or traces.',
@@ -521,6 +610,46 @@ export function skillText(result, message) {
   return `${lines.join("\n")}\n`;
 }
 
+export function skillsText(result, message) {
+  const report = result.data;
+  const lines = [];
+  if (result.command === "skills list") {
+    lines.push("Metergraph skills bundled with this CLI");
+    if (report.source) lines.push(`Source: ${report.source.repository} at ${report.source.commit.slice(0, 12)}`);
+    if (!result.ok) {
+      lines.push("", `Result: ${result.outcome} (exit ${result.exit_code})`, message);
+      return `${lines.join("\n")}\n`;
+    }
+    for (const skill of report.skills) {
+      lines.push("", `${skill.name} (${skill.revision})`);
+      for (const [client, state] of Object.entries(skill.installs)) {
+        lines.push(`  ${SKILL_CLIENTS[client].label.padEnd(12)}${SKILLS_STATE_LABELS[state] ?? state}`);
+      }
+    }
+    return `${lines.join("\n")}\n`;
+  }
+  const label = SKILL_CLIENTS[report.client]?.label ?? HANDOFF_SKILL_CLIENTS[report.client] ?? report.client;
+  lines.push(`Metergraph ${result.command}: ${label}, ${report.runtime} runtime`);
+  if (report.source) lines.push(`Source: ${report.source.repository} at ${report.source.commit.slice(0, 12)}`);
+  for (const skill of report.skills) {
+    const status = skill.status === "failed" ? `failed (${skill.reason})` : skill.status;
+    lines.push(`  ${skill.name.padEnd(24)}${status.padEnd(12)}${skill.path}`);
+  }
+  if (result.ok) {
+    lines.push(
+      `Discovery: pending until ${label} loads the skills`,
+      "Authenticated: no",
+      "",
+      `Next: ${report.next_action.message}`,
+    );
+  } else {
+    lines.push("", `Result: ${result.outcome} (exit ${result.exit_code})`, message);
+    if (report.next_action?.kind === "plugin_marketplace") lines.push(`Next: ${report.next_action.message}`);
+    if (report.next_action?.kind === "connection_guide") lines.push(`Connection guide: ${report.next_action.url}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
 export function versionData() {
   return { name: PACKAGE_NAME, version: VERSION };
 }
@@ -601,9 +730,9 @@ const AUTH_MESSAGES = {
     "so sign in cannot finish here. Follow the connection guide instead. Nothing was written.",
   ci_environment:
     "This is a CI environment, where no person can approve sign in in a browser. Nothing was written.",
-  no_browser_requires_terminal:
-    "Approval is needed, and --no-browser prints its URL for a person to open, which --json cannot do. " +
-    "Run the same command without --json in a terminal. Nothing was done.",
+  browser_approval_required:
+    "A person must approve in a browser. Open data.next_action.url on this machine; a background process " +
+    "waits for the approval until the timeout. After approval, run the same command again to continue.",
   bound_to_other_origin:
     "This project is bound to a different origin. Nothing was changed. Use --reconnect to switch it.",
   bound_to_other_workspace:
@@ -619,7 +748,7 @@ const AUTH_MESSAGES = {
   timeout: "The operation did not finish within the time limit. Nothing was saved.",
   cancelled: "Sign in was cancelled. Nothing was saved.",
   browser_unavailable:
-    "The browser could not be opened. Run login again with --no-browser, without --json, and open the URL it prints.",
+    "The browser could not be opened. Run login again with --no-browser and open the URL it prints.",
   oauth_metadata_missing: "This service does not support CLI sign in yet. Nothing was written.",
   metadata_scope_unsupported:
     "This service does not offer Metadata-only access for the CLI yet. The CLI does not fall back to broader access.",