@roarkanalytics/cli 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## [0.3.0](https://github.com/roarkhq/cli-roark-analytics/compare/v0.2.0...v0.3.0) (2026-09-02)
+
+
+### Features
+
+* **auth:** browser-based login (OAuth authorization-code + PKCE) ([#6](https://github.com/roarkhq/cli-roark-analytics/issues/6)) ([62c476e](https://github.com/roarkhq/cli-roark-analytics/commit/62c476ea4d383842bf57fe9645ba65a77297d503))
+* **auth:** verify token on login, warn on env-var shadow, clearer errors ([#5](https://github.com/roarkhq/cli-roark-analytics/issues/5)) ([5b7a256](https://github.com/roarkhq/cli-roark-analytics/commit/5b7a2568149cf36d1cabe2cfe84afc63b4ef7939))
+* **cli:** add the roark command line interface ([9ad4541](https://github.com/roarkhq/cli-roark-analytics/commit/9ad45413fca0e0864db5827c9511b4c2757103eb))
+* **cli:** cli update ([e28294f](https://github.com/roarkhq/cli-roark-analytics/commit/e28294fec4df79eb40a184b6996a31f2ed45a7db))
+* **cli:** cli update ([8c16aed](https://github.com/roarkhq/cli-roark-analytics/commit/8c16aed1a2b5fdebfd0303f0905b8d596b4d2acb))
+* **cli:** cli update ([131c7c3](https://github.com/roarkhq/cli-roark-analytics/commit/131c7c37e05b28ea31934708c774c4c512191a60))
+* **cli:** cli update ([c46b935](https://github.com/roarkhq/cli-roark-analytics/commit/c46b935e23f0e40e290a2430879e3c5bb9e7fe77))
+* **cli:** cli update ([35b9b0b](https://github.com/roarkhq/cli-roark-analytics/commit/35b9b0b5eee942b4ed24e4ca6e6aedf5fafa5a54))
+* **cli:** config diff/apply for config-as-code directories ([#1143](https://github.com/roarkhq/cli-roark-analytics/issues/1143)) ([d4ff899](https://github.com/roarkhq/cli-roark-analytics/commit/d4ff8999e223e9c3c0e36c6f910d08058507841b))
+* **cli:** install with a script, not a global npm install ([6db9132](https://github.com/roarkhq/cli-roark-analytics/commit/6db91327c257d38de08dcf816cd103eb13ee3aaa))
+* **cli:** ship a shrinkwrap so an install resolves the same tree twice ([415cc82](https://github.com/roarkhq/cli-roark-analytics/commit/415cc8269939265d9b3a3a9827c4a09a568144bb))
+
+
+### Bug Fixes
+
+* **cli:** do not send a stored credential to a base URL a project file chose ([1d50a94](https://github.com/roarkhq/cli-roark-analytics/commit/1d50a9447e1a5bc988e9d2e2d641f58ed5865b87))
+* **cli:** make a truncated download do nothing ([9a52f2f](https://github.com/roarkhq/cli-roark-analytics/commit/9a52f2fb6dc1938bbd6d5919fae2a4673622f15f))
+* **cli:** only read stdin when there is something to read from ([66c7061](https://github.com/roarkhq/cli-roark-analytics/commit/66c706157bee14727b96a1970fa49474755f0812))
+* **cli:** report the version the package actually publishes ([bbaf3ac](https://github.com/roarkhq/cli-roark-analytics/commit/bbaf3ac48a3e39c6f626810547caf9b7329fb4bd))
+* **cli:** warn instead of failing when the shrinkwrap cannot be built ([09f0a2c](https://github.com/roarkhq/cli-roark-analytics/commit/09f0a2c793ec5ab3efdc55608229a7da9bb1f414))
+
+
+### Chores
+
+* **cli:** 0.2.0 ([cd35004](https://github.com/roarkhq/cli-roark-analytics/commit/cd350040d4dcbbb4eaeaa714ce5a759ffe627c88))
+* **cli:** drop the inert x-release-please-version marker ([e3747f7](https://github.com/roarkhq/cli-roark-analytics/commit/e3747f7b30bb9b345020debc8475a685576a4c60))
+* **cli:** pin shell scripts to LF line endings ([1a65bea](https://github.com/roarkhq/cli-roark-analytics/commit/1a65bea0f823abfa84818646b738031d018cf73c))
+* **cli:** start the CLI at 0.1.0 rather than mirroring the SDK ([e9dad1d](https://github.com/roarkhq/cli-roark-analytics/commit/e9dad1d3e8672a71bfda639599361ef1e2d70c3a))
+* stand the package up on its own ([068005f](https://github.com/roarkhq/cli-roark-analytics/commit/068005f5f6154e7131926328246ec96ae10e0626))

package/commands.js

@@ -1375,7 +1375,7 @@ exports.COMMANDS = [
                 path: ['branchingMode'],
                 location: 'body',
                 required: false,
-                description: 'Scripted flows only.',
+                description: 'Scripted flows only. How a run walks the graph. DETERMINISTIC ("Simulate every path" in the app) places one call per variant, each following its path exactly whatever the agent says. ADAPTIVE ("Adapt to your agent") collapses the paths into one call PER PERSONA, on which the simulated customer picks a branch from what the agent actually said. Both modes speak the exact authored lines, and neither changes how metrics or expectations grade.',
                 valueKind: 'string',
                 enumValues: ['DETERMINISTIC', 'ADAPTIVE'],
                 repeatable: false,
@@ -1756,15 +1756,15 @@ exports.COMMANDS = [
         bodyVariants: [
             {
                 name: 'PromptMetricInput',
-                required: ['calculationType', 'name', 'outputType', 'analysisPackageId'],
+                required: ['calculationType', 'name', 'outputType'],
             },
             {
                 name: 'FormulaMetricInput',
-                required: ['calculationType', 'name', 'outputType', 'formula', 'sources', 'analysisPackageId'],
+                required: ['calculationType', 'name', 'outputType', 'formula', 'sources'],
             },
             {
                 name: 'PatternMetricInput',
-                required: ['calculationType', 'name', 'operation', 'outcome', 'analysisPackageId'],
+                required: ['calculationType', 'name', 'operation', 'outcome'],
             },
         ],
         acceptsBody: true,

package/man/roark-customer-flow-update.1

@@ -22,7 +22,7 @@ Optional.
 Optional.
 .TP
 \fB\-\-branching\-mode\fR \fI<value>\fR
-Scripted flows only. One of: DETERMINISTIC, ADAPTIVE. Optional.
+Scripted flows only. How a run walks the graph. DETERMINISTIC ("Simulate every path" in the app) places one call per variant, each following its path exactly whatever the agent says. ADAPTIVE ("Adapt to your agent") collapses the paths into one call PER PERSONA, on which the simulated customer picks a branch from what the agent actually said. Both modes speak the exact authored lines, and neither changes how metrics or expectations grade. One of: DETERMINISTIC, ADAPTIVE. Optional.
 .TP
 \fB\-\-agent\-ids\fR \fI<value>\fR
 Replaces the linked agents. Omit to leave them unchanged. An improv flow must keep at least one; a scripted flow can be left with none. Repeatable. Optional.

package/man/roark-metric-definition-create.1

@@ -13,13 +13,13 @@ POST /v1/metric/definitions
 This endpoint accepts one of several request shapes, so the body is supplied as JSON through \e\-\e\-data or on standard input rather than as individual flags.
 .TP
 \fBPromptMetricInput\fR
-Requires calculationType, name, outputType, analysisPackageId.
+Requires calculationType, name, outputType.
 .TP
 \fBFormulaMetricInput\fR
-Requires calculationType, name, outputType, formula, sources, analysisPackageId.
+Requires calculationType, name, outputType, formula, sources.
 .TP
 \fBPatternMetricInput\fR
-Requires calculationType, name, operation, outcome, analysisPackageId.
+Requires calculationType, name, operation, outcome.
 .SH "GLOBAL OPTIONS"
 .TP
 \fB\-\-data\fR \fI<json>\fR

package/npm-shrinkwrap.json

@@ -0,0 +1,54 @@
+{
+  "name": "@roarkanalytics/cli",
+  "version": "0.3.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@roarkanalytics/cli",
+      "version": "0.3.0",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@roarkanalytics/sdk": "^3.2.1",
+        "commander": "^14.0.3",
+        "yaml": "^2.9.0"
+      },
+      "bin": {
+        "roark": "bin.js"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/@roarkanalytics/sdk": {
+      "version": "3.2.1",
+      "resolved": "https://registry.npmjs.org/@roarkanalytics/sdk/-/sdk-3.2.1.tgz",
+      "integrity": "sha512-5K8cMDUBWD4Id1BGHSiHe71tJSW9kn119XgFsSAckgpnaYtsP8SooRuz6XOuMXortSTUgLyqVrtBnExuw36jyw==",
+      "license": "Apache-2.0"
+    },
+    "node_modules/commander": {
+      "version": "14.0.3",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-14.0.3.tgz",
+      "integrity": "sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/yaml": {
+      "version": "2.9.0",
+      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz",
+      "integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==",
+      "license": "ISC",
+      "bin": {
+        "yaml": "bin.mjs"
+      },
+      "engines": {
+        "node": ">= 14.6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/eemeli"
+      }
+    }
+  }
+}

package/package.json

@@ -1,15 +1,14 @@
 {
   "name": "@roarkanalytics/cli",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "The official command line interface for the Roark API",
   "author": "Roark <james@roark.ai>",
   "type": "commonjs",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/roarkhq/sdk-roark-analytics-node.git",
-    "directory": "packages/cli"
+    "url": "git+https://github.com/roarkhq/cli-roark-analytics.git"
   },
-  "homepage": "https://github.com/roarkhq/sdk-roark-analytics-node/tree/main/packages/cli#readme",
+  "homepage": "https://github.com/roarkhq/cli-roark-analytics#readme",
   "license": "Apache-2.0",
   "packageManager": "pnpm@10.30.1",
   "private": false,
@@ -26,11 +25,11 @@
     "build": "./build",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "jest",
-    "lint": "eslint .",
-    "fix": "eslint --fix ."
+    "lint": "eslint . && prettier --check .",
+    "fix": "eslint --fix . && prettier --write ."
   },
   "dependencies": {
-    "@roarkanalytics/sdk": "^3.1.0",
+    "@roarkanalytics/sdk": "^3.2.1",
     "commander": "^14.0.3",
     "yaml": "^2.9.0"
   },
@@ -100,4 +99,4 @@
     "./man/roark-webhook-get.1",
     "./man/roark-webhook-list.1"
   ]
-}
+}

package/runtime/browser-login.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Browser-based `auth login` (OAuth authorization-code + PKCE over a loopback redirect).
+ *
+ * The CLI starts a throwaway `127.0.0.1` listener, opens the platform's consent page, and waits for
+ * the approved code to come back to that listener. It then exchanges the code (with its PKCE
+ * verifier) for a freshly minted API key at the public token endpoint. No token is ever typed or
+ * pasted; the secret only exists in the final exchange response.
+ */
+export declare const generatePkce: () => {
+    verifier: string;
+    challenge: string;
+};
+/**
+ * Where the consent page lives, derived from the API base URL. `api.roark.ai` -> `platform.roark.ai`.
+ * `ROARK_PLATFORM_URL` overrides for local/self-hosted stages where the mapping doesn't hold.
+ */
+export declare const platformOriginFor: (apiBaseUrl: string) => string;
+export interface BrowserLoginOptions {
+    apiBaseUrl: string;
+    platformOrigin: string;
+    clientName: string;
+    timeoutMs?: number;
+    onAuthorizeUrl?: (url: string) => void;
+    open?: (url: string) => void;
+}
+export declare const browserLogin: (options: BrowserLoginOptions) => Promise<string>;

package/runtime/browser-login.js

@@ -0,0 +1,132 @@
+"use strict";
+/**
+ * Browser-based `auth login` (OAuth authorization-code + PKCE over a loopback redirect).
+ *
+ * The CLI starts a throwaway `127.0.0.1` listener, opens the platform's consent page, and waits for
+ * the approved code to come back to that listener. It then exchanges the code (with its PKCE
+ * verifier) for a freshly minted API key at the public token endpoint. No token is ever typed or
+ * pasted; the secret only exists in the final exchange response.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.browserLogin = exports.platformOriginFor = exports.generatePkce = void 0;
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const node_http_1 = require("node:http");
+const base64url = (buf) => buf.toString('base64url');
+// A PKCE pair: a random verifier and its S256 challenge (base64url(sha256(verifier))).
+const generatePkce = () => {
+    const verifier = base64url((0, node_crypto_1.randomBytes)(32));
+    const challenge = base64url((0, node_crypto_1.createHash)('sha256').update(verifier).digest());
+    return { verifier, challenge };
+};
+exports.generatePkce = generatePkce;
+/**
+ * Where the consent page lives, derived from the API base URL. `api.roark.ai` -> `platform.roark.ai`.
+ * `ROARK_PLATFORM_URL` overrides for local/self-hosted stages where the mapping doesn't hold.
+ */
+const platformOriginFor = (apiBaseUrl) => {
+    const override = process.env['ROARK_PLATFORM_URL'];
+    if (override && override.trim().length > 0)
+        return override.replace(/\/+$/, '');
+    try {
+        const url = new URL(apiBaseUrl);
+        if (url.hostname === 'api.roark.ai')
+            return 'https://platform.roark.ai';
+        if (url.hostname.startsWith('api.'))
+            return `${url.protocol}//platform.${url.hostname.slice('api.'.length)}`;
+        // localhost / an unrecognised host: assume the web app shares the origin.
+        return url.origin;
+    }
+    catch {
+        return 'https://platform.roark.ai';
+    }
+};
+exports.platformOriginFor = platformOriginFor;
+const closeHtml = (title, body) => `<!doctype html><meta charset="utf-8"><title>${title}</title>` +
+    `<body style="font:15px system-ui;margin:4rem auto;max-width:28rem;text-align:center;color:#222">` +
+    `<h2 style="margin:0 0 .5rem">${title}</h2><p style="color:#666">${body}</p></body>`;
+// Best-effort browser open. If it fails, the caller has already printed the URL to open by hand.
+const openBrowser = (url) => {
+    const [command, args] = process.platform === 'darwin' ? ['open', [url]]
+        : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]]
+            : ['xdg-open', [url]];
+    try {
+        const child = (0, node_child_process_1.spawn)(command, [...args], { stdio: 'ignore', detached: true });
+        child.on('error', () => undefined);
+        child.unref();
+    }
+    catch {
+        /* the printed URL is the fallback */
+    }
+};
+// Run the full loopback + PKCE flow and return the minted bearer token.
+const browserLogin = async (options) => {
+    const { verifier, challenge } = (0, exports.generatePkce)();
+    const state = base64url((0, node_crypto_1.randomBytes)(16));
+    const code = await new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            server.close();
+            // This is a one-shot listener; drop any keep-alive socket so nothing lingers after we're done.
+            server.closeAllConnections?.();
+            fn();
+        };
+        const server = (0, node_http_1.createServer)((req, res) => {
+            const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+            if (url.pathname !== '/callback') {
+                res.writeHead(404);
+                res.end();
+                return;
+            }
+            const returnedCode = url.searchParams.get('code');
+            const returnedState = url.searchParams.get('state');
+            const errorParam = url.searchParams.get('error');
+            const ok = !errorParam && returnedCode && returnedState === state;
+            res.writeHead(200, { 'Content-Type': 'text/html' });
+            res.end(ok ?
+                closeHtml('Logged in', 'You can close this tab and return to your terminal.')
+                : closeHtml('Login failed', 'You can close this tab and return to your terminal.'));
+            if (ok)
+                finish(() => resolve(returnedCode));
+            else if (errorParam)
+                finish(() => reject(new Error(`authorization was ${errorParam}`)));
+            else
+                finish(() => reject(new Error('authorization response was invalid')));
+        });
+        const timer = setTimeout(() => finish(() => reject(new Error('timed out waiting for authorization in the browser'))), options.timeoutMs ?? 300_000);
+        timer.unref?.();
+        server.on('error', (error) => finish(() => reject(error)));
+        server.listen(0, '127.0.0.1', () => {
+            const { port } = server.address();
+            const redirectUri = `http://127.0.0.1:${port}/callback`;
+            const authorizeUrl = `${options.platformOrigin}/cli/authorize?` +
+                new URLSearchParams({
+                    code_challenge: challenge,
+                    state,
+                    redirect_uri: redirectUri,
+                    name: options.clientName,
+                }).toString();
+            options.onAuthorizeUrl?.(authorizeUrl);
+            (options.open ?? openBrowser)(authorizeUrl);
+        });
+    });
+    const response = await fetch(`${options.apiBaseUrl.replace(/\/+$/, '')}/v1/cli/auth/token`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ code, code_verifier: verifier }),
+    });
+    if (!response.ok) {
+        const detail = await response.text().catch(() => '');
+        throw new Error(`token exchange failed (${response.status})${detail ? `: ${detail}` : ''}`);
+    }
+    const body = (await response.json());
+    const token = body.data?.token;
+    if (!token)
+        throw new Error('token exchange returned no token');
+    return token;
+};
+exports.browserLogin = browserLogin;

package/runtime/commands/auth.d.ts

@@ -1,9 +1,16 @@
 /**
  * `roark auth login | logout | status`
  *
- * The token is never accepted as a flag value: flags land in shell history and
- * in the process table, where a bearer token has no business being. It is read
- * from a prompt with echo off, or from stdin so CI can pipe it in.
+ * `login` defaults to a browser flow (OAuth authorization-code + PKCE): it opens the platform's
+ * consent page, mints a key on approval, and stores it. Non-interactive/piped input, `--paste`, or
+ * `--no-browser` fall back to taking a bearer token. A token is never accepted as a flag value:
+ * flags land in shell history and the process table, where a bearer token has no business being; it
+ * is read from a prompt with echo off, or from stdin so CI can pipe it in.
  */
 import { Command } from 'commander';
-export declare const registerAuthCommands: (root: Command, binaryName: string) => void;
+import type Roark from '@roarkanalytics/sdk';
+/** How the program builds an authenticated client; injected so tests can stub it (and skip the
+ * network entirely by omitting it). Matches the factory the other commands receive. */
+type ClientFor = (options: never) => Roark;
+export declare const registerAuthCommands: (root: Command, binaryName: string, clientFor?: ClientFor) => void;
+export {};

package/runtime/commands/auth.js

@@ -2,18 +2,67 @@
 /**
  * `roark auth login | logout | status`
  *
- * The token is never accepted as a flag value: flags land in shell history and
- * in the process table, where a bearer token has no business being. It is read
- * from a prompt with echo off, or from stdin so CI can pipe it in.
+ * `login` defaults to a browser flow (OAuth authorization-code + PKCE): it opens the platform's
+ * consent page, mints a key on approval, and stores it. Non-interactive/piped input, `--paste`, or
+ * `--no-browser` fall back to taking a bearer token. A token is never accepted as a flag value:
+ * flags land in shell history and the process table, where a bearer token has no business being; it
+ * is read from a prompt with echo off, or from stdin so CI can pipe it in.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerAuthCommands = void 0;
 const commander_1 = require("commander");
+const node_os_1 = require("node:os");
 const node_readline_1 = require("node:readline");
+const browser_login_1 = require("../browser-login");
 const errors_1 = require("../errors");
 const config_1 = require("../config");
 const output_1 = require("../output");
 const confirm_1 = require("../confirm");
+// The SDK's default when no base URL is configured; the token exchange targets the same host.
+const DEFAULT_BASE_URL = 'https://api.roark.ai';
+// Any authenticated endpoint works as a liveness probe: `requireAuth` runs first, so a bad token is
+// a 401 while a valid one that merely lacks this endpoint's permission is a 403 — both prove the
+// token authenticates. `/v1/agent` is a stable GET that every project has.
+const AUTH_PROBE_PATH = '/v1/agent';
+/**
+ * Confirm the stored credential actually authenticates, so a mistyped or half-pasted token is caught
+ * here instead of on the user's next real command. Best-effort: it never fails the login (the token
+ * is already saved) and stays quiet-but-honest when offline.
+ */
+const verifyCredential = async (clientFor, binaryName, color) => {
+    let client;
+    try {
+        // Resolve the client the same way a real command would (no forced --token), so the base-url
+        // trust guard still applies: we must not send the credential to a host a checked-in .roark.json
+        // chose. This verifies the effective credential, which is exactly what the next command will use.
+        client = clientFor({});
+    }
+    catch (error) {
+        // e.g. the trust guard refused, or config is malformed. Don't fail the login, but say the check
+        // was skipped so it doesn't look like the feature silently didn't run.
+        const reason = error.message.split('\n')[0];
+        (0, output_1.write)((0, output_1.paint)(`Saved, but skipped the token check (${reason}).`, 'dim', color), process.stderr);
+        return;
+    }
+    const verified = () => (0, output_1.write)(`${(0, output_1.paint)('Verified', 'green', color)} the token authenticates.`, process.stderr);
+    try {
+        await client.get(AUTH_PROBE_PATH, { query: { limit: '1' } });
+        verified();
+    }
+    catch (error) {
+        const status = error.status;
+        if (status === 401) {
+            (0, output_1.write)((0, output_1.paint)(`Warning: the token was rejected (401). It may be wrong, expired, or revoked. It is still saved; run \`${binaryName} auth login\` again to replace it.`, 'yellow', color), process.stderr);
+        }
+        else if (status !== undefined && status < 500) {
+            // 403 (authenticated, lacks agent:read) or any other client-level response: auth succeeded.
+            verified();
+        }
+        else {
+            (0, output_1.write)((0, output_1.paint)(`Saved, but could not verify it right now (${error.message}). It will be used as-is.`, 'dim', color), process.stderr);
+        }
+    }
+};
 /** Reads a secret without echoing it, so it is not left on screen or in a scrollback. */
 const promptSecret = async (prompt) => {
     const input = process.stdin;
@@ -39,7 +88,7 @@ const promptSecret = async (prompt) => {
         output.write('\n');
     }
 };
-const readToken = async () => {
+const readToken = async (binaryName) => {
     if (!(0, confirm_1.isInteractive)()) {
         const piped = await new Promise((resolve, reject) => {
             let buffer = '';
@@ -50,33 +99,81 @@ const readToken = async () => {
         });
         const token = piped.trim();
         if (token.length === 0) {
-            throw new errors_1.UsageError('No token on stdin. Pipe one in, or run this in a terminal.');
+            throw new errors_1.UsageError(`No token on stdin. Pipe one in (echo "$ROARK_API_BEARER_TOKEN" | ${binaryName} auth login), or run this in a terminal to be prompted.`);
         }
         return token;
     }
     const token = (await promptSecret('Bearer token: ')).trim();
-    if (token.length === 0)
-        throw new errors_1.UsageError('No token entered.');
+    if (token.length === 0) {
+        // The most common cause: a paste that the hidden prompt did not capture. Point at the reliable
+        // path rather than just saying "nothing entered".
+        throw new errors_1.UsageError(`No token entered. If you pasted and nothing happened, pipe it instead: echo "$ROARK_API_BEARER_TOKEN" | ${binaryName} auth login`);
+    }
     return token;
 };
-const registerAuthCommands = (root, binaryName) => {
+// Save the token and report where it went (masked). Shared by the browser and paste paths.
+const persistToken = (token) => {
+    const path = (0, config_1.writeUserConfig)({ ...(0, config_1.readUserConfig)(), bearerToken: token });
+    const color = (0, output_1.supportsColor)(process.stderr);
+    (0, output_1.write)(`${(0, output_1.paint)('Saved', 'green', color)} ${(0, config_1.maskToken)(token)} to ${path}`, process.stderr);
+    return { color };
+};
+// A set environment variable outranks the stored token (see the precedence in config.ts), so without
+// this a login looks like it "did nothing" when a stale export shadows what we just saved.
+const warnEnvShadow = (token, color) => {
+    const fromEnv = process.env['ROARK_API_BEARER_TOKEN'];
+    if (fromEnv && fromEnv !== token) {
+        (0, output_1.write)((0, output_1.paint)(`Note: ROARK_API_BEARER_TOKEN is set and overrides this stored token. Unset it to use the credential you just saved.`, 'yellow', color), process.stderr);
+    }
+};
+const registerAuthCommands = (root, binaryName, clientFor) => {
     const auth = new commander_1.Command('auth').description('Manage the stored credential').showHelpAfterError();
     auth.action(() => auth.outputHelp());
     auth
         .command('login')
-        .description('Store a bearer token for future commands')
+        .description('Authorize this CLI in your browser, or store a bearer token')
+        .option('--no-browser', 'do not open a browser; paste or pipe a token instead')
+        .option('--paste', 'paste or pipe a bearer token instead of using the browser')
         .addHelpText('after', [
         '',
-        'The token is read from a hidden prompt, or from stdin when not a terminal:',
+        'By default an interactive terminal opens your browser to approve access and stores the',
+        'minted key. Non-interactive (piped) input always takes a token, so CI keeps working:',
         '',
         `  ${binaryName} auth login`,
+        `  ${binaryName} auth login --paste`,
         `  echo "$ROARK_API_BEARER_TOKEN" | ${binaryName} auth login`,
     ].join('\n'))
-        .action(async () => {
-        const token = await readToken();
-        const path = (0, config_1.writeUserConfig)({ ...(0, config_1.readUserConfig)(), bearerToken: token });
-        const color = (0, output_1.supportsColor)(process.stderr);
-        (0, output_1.write)(`${(0, output_1.paint)('Saved', 'green', color)} ${(0, config_1.maskToken)(token)} to ${path}`, process.stderr);
+        .action(async (options) => {
+        // Browser flow when we're an interactive terminal and it wasn't opted out. A piped /
+        // non-interactive invocation always uses the token path so `echo "$TOKEN" | auth login` works.
+        const useBrowser = options.browser !== false && options.paste !== true && (0, confirm_1.isInteractive)();
+        if (useBrowser) {
+            const color = (0, output_1.supportsColor)(process.stderr);
+            const apiBaseUrl = (0, config_1.resolveConfig)({}).config.baseURL ?? DEFAULT_BASE_URL;
+            (0, output_1.write)((0, output_1.paint)('Opening your browser to authorize this CLI…', 'dim', color), process.stderr);
+            let token;
+            try {
+                token = await (0, browser_login_1.browserLogin)({
+                    apiBaseUrl,
+                    platformOrigin: (0, browser_login_1.platformOriginFor)(apiBaseUrl),
+                    clientName: `CLI on ${(0, node_os_1.hostname)()}`,
+                    onAuthorizeUrl: (url) => (0, output_1.write)((0, output_1.paint)(`If your browser didn't open, visit:\n  ${url}`, 'dim', color), process.stderr),
+                });
+            }
+            catch (error) {
+                throw new errors_1.UsageError(`Browser login failed: ${error.message}\n` +
+                    `Run \`${binaryName} auth login --paste\` to paste or pipe a token instead.`);
+            }
+            const { color: savedColor } = persistToken(token);
+            warnEnvShadow(token, savedColor);
+            return;
+        }
+        const token = await readToken(binaryName);
+        const { color } = persistToken(token);
+        // Confirm the token actually works, so a bad paste surfaces now rather than on the next command.
+        if (clientFor)
+            await verifyCredential(clientFor, binaryName, color);
+        warnEnvShadow(token, color);
     });
     auth
         .command('logout')

package/runtime/program.js

@@ -258,7 +258,7 @@ const createProgram = (options) => {
             continue;
         addApiCommand(root, options, definition);
     }
-    (0, auth_1.registerAuthCommands)(root, options.binaryName);
+    (0, auth_1.registerAuthCommands)(root, options.binaryName, clientFor);
     (0, config_as_code_1.registerConfigAsCodeCommands)(root, options.binaryName, clientFor, exports.resolveOutput);
     (0, config_1.registerConfigCommands)(root, options.binaryName);
     (0, api_1.registerApiCommand)(root, options.binaryName, clientFor, exports.resolveOutput);

package/version.d.ts

@@ -1 +1 @@
-export declare const version = "0.1.1";
+export declare const version = "0.3.0";

package/version.js

@@ -8,4 +8,4 @@ exports.version = void 0;
 // It exists at all because the CLI is not in release-please-config.json's
 // `extra-files` - it ships from publish-cli.yml rather than the vendor's
 // release train - so nothing else keeps this in step.
-exports.version = '0.1.1';
+exports.version = '0.3.0';