lmnr-cli 0.1.9 → 0.1.11

package/dist/index.cjs

@@ -6,7 +6,7 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __commonJSMin = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
 var __copyProps = (to, from, except, desc) => {
 	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
 		key = keys[i];
@@ -25,11 +25,15 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 let commander = require("commander");
 let fs = require("fs");
 let path = require("path");
+let path$2 = __toESM(path, 1);
 path = __toESM(path);
 let pino = require("pino");
+let pino$3 = __toESM(pino, 1);
 pino = __toESM(pino);
 let pino_pretty = require("pino-pretty");
-let uuid = require("uuid");
+let node_fs_promises = require("node:fs/promises");
+let node_path = require("node:path");
+let node_os = require("node:os");
 let csv_parser = require("csv-parser");
 csv_parser = __toESM(csv_parser);
 let export_to_csv = require("export-to-csv");
@@ -37,104 +41,34 @@ let fs_promises = require("fs/promises");
 fs_promises = __toESM(fs_promises);
 let cli_table3 = require("cli-table3");
 cli_table3 = __toESM(cli_table3);
-let chokidar = require("chokidar");
-chokidar = __toESM(chokidar);
-let http = require("http");
-http = __toESM(http);
-let events = require("events");
-let eventsource_parser = require("eventsource-parser");
-let child_process = require("child_process");
-let readline = require("readline");
-readline = __toESM(readline);
-//#region package.json
-var version$1 = "0.1.9";
+let open = require("open");
+open = __toESM(open);
+let picocolors = require("picocolors");
+let node_readline_promises = require("node:readline/promises");
+let node_child_process = require("node:child_process");
+let node_util = require("node:util");
+let giget = require("giget");
+//#region ../types/dist/index.mjs
+const errorMessage = (error) => error instanceof Error ? error.message : String(error);
 //#endregion
-//#region ../../node_modules/.pnpm/dotenv@17.2.3/node_modules/dotenv/package.json
-var require_package = /* @__PURE__ */ __commonJSMin(((exports, module) => {
-	module.exports = {
-		"name": "dotenv",
-		"version": "17.2.3",
-		"description": "Loads environment variables from .env file",
-		"main": "lib/main.js",
-		"types": "lib/main.d.ts",
-		"exports": {
-			".": {
-				"types": "./lib/main.d.ts",
-				"require": "./lib/main.js",
-				"default": "./lib/main.js"
-			},
-			"./config": "./config.js",
-			"./config.js": "./config.js",
-			"./lib/env-options": "./lib/env-options.js",
-			"./lib/env-options.js": "./lib/env-options.js",
-			"./lib/cli-options": "./lib/cli-options.js",
-			"./lib/cli-options.js": "./lib/cli-options.js",
-			"./package.json": "./package.json"
-		},
-		"scripts": {
-			"dts-check": "tsc --project tests/types/tsconfig.json",
-			"lint": "standard",
-			"pretest": "npm run lint && npm run dts-check",
-			"test": "tap run tests/**/*.js --allow-empty-coverage --disable-coverage --timeout=60000",
-			"test:coverage": "tap run tests/**/*.js --show-full-coverage --timeout=60000 --coverage-report=text --coverage-report=lcov",
-			"prerelease": "npm test",
-			"release": "standard-version"
-		},
-		"repository": {
-			"type": "git",
-			"url": "git://github.com/motdotla/dotenv.git"
-		},
-		"homepage": "https://github.com/motdotla/dotenv#readme",
-		"funding": "https://dotenvx.com",
-		"keywords": [
-			"dotenv",
-			"env",
-			".env",
-			"environment",
-			"variables",
-			"config",
-			"settings"
-		],
-		"readmeFilename": "README.md",
-		"license": "BSD-2-Clause",
-		"devDependencies": {
-			"@types/node": "^18.11.3",
-			"decache": "^4.6.2",
-			"sinon": "^14.0.1",
-			"standard": "^17.0.0",
-			"standard-version": "^9.5.0",
-			"tap": "^19.2.0",
-			"typescript": "^4.8.4"
-		},
-		"engines": { "node": ">=12" },
-		"browser": { "fs": false }
-	};
-}));
+//#region package.json
+var version$1 = "0.1.11";
 //#endregion
-//#region ../client/dist/index.mjs
-var import_main = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
+//#region ../../node_modules/.pnpm/dotenv@17.4.2/node_modules/dotenv/lib/main.js
+var require_main = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	const fs$1 = require("fs");
 	const path$1 = require("path");
 	const os = require("os");
 	const crypto$1 = require("crypto");
-	const version = require_package().version;
 	const TIPS = [
-		"🔐 encrypt with Dotenvx: https://dotenvx.com",
-		"🔐 prevent committing .env to code: https://dotenvx.com/precommit",
-		"🔐 prevent building .env in docker: https://dotenvx.com/prebuild",
-		"📡 add observability to secrets: https://dotenvx.com/ops",
-		"👥 sync secrets across teammates & machines: https://dotenvx.com/ops",
-		"🗂️ backup and recover secrets: https://dotenvx.com/ops",
-		"✅ audit secrets and track compliance: https://dotenvx.com/ops",
-		"🔄 add secrets lifecycle management: https://dotenvx.com/ops",
-		"🔑 add access controls to secrets: https://dotenvx.com/ops",
-		"🛠️  run anywhere with `dotenvx run -- yourcommand`",
-		"⚙️  specify custom .env file path with { path: '/custom/path/.env' }",
-		"⚙️  enable debug logging with { debug: true }",
-		"⚙️  override existing env vars with { override: true }",
-		"⚙️  suppress all logs with { quiet: true }",
-		"⚙️  write to custom object with { processEnv: myObject }",
-		"⚙️  load multiple .env files with { path: ['.env.local', '.env'] }"
+		"◈ encrypted .env [www.dotenvx.com]",
+		"◈ secrets for agents [www.dotenvx.com]",
+		"⌁ auth for agents [www.vestauth.com]",
+		"⌘ custom filepath { path: '/custom/path/.env' }",
+		"⌘ enable debugging { debug: true }",
+		"⌘ override existing { override: true }",
+		"⌘ suppress logs { quiet: true }",
+		"⌘ multiple files { path: ['.env.local', '.env'] }"
 	];
 	function _getRandomTip() {
 		return TIPS[Math.floor(Math.random() * TIPS.length)];
@@ -198,13 +132,13 @@ var import_main = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
 		return DotenvModule.parse(decrypted);
 	}
 	function _warn(message) {
-		console.error(`[dotenv@${version}][WARN] ${message}`);
+		console.error(`⚠ ${message}`);
 	}
 	function _debug(message) {
-		console.log(`[dotenv@${version}][DEBUG] ${message}`);
+		console.log(`┆ ${message}`);
 	}
 	function _log(message) {
-		console.log(`[dotenv@${version}] ${message}`);
+		console.log(`◇ ${message}`);
 	}
 	function _dotenvKey(options) {
 		if (options && options.DOTENV_KEY && options.DOTENV_KEY.length > 0) return options.DOTENV_KEY;
@@ -262,7 +196,7 @@ var import_main = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
 	function _configVault(options) {
 		const debug = parseBoolean(process.env.DOTENV_CONFIG_DEBUG || options && options.debug);
 		const quiet = parseBoolean(process.env.DOTENV_CONFIG_QUIET || options && options.quiet);
-		if (debug || !quiet) _log("Loading env from encrypted .env.vault");
+		if (debug || !quiet) _log("loading env from encrypted .env.vault");
 		const parsed = DotenvModule._parseVault(options);
 		let processEnv = process.env;
 		if (options && options.processEnv != null) processEnv = options.processEnv;
@@ -277,7 +211,7 @@ var import_main = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
 		let debug = parseBoolean(processEnv.DOTENV_CONFIG_DEBUG || options && options.debug);
 		let quiet = parseBoolean(processEnv.DOTENV_CONFIG_QUIET || options && options.quiet);
 		if (options && options.encoding) encoding = options.encoding;
-		else if (debug) _debug("No encoding is specified. UTF-8 is used by default");
+		else if (debug) _debug("no encoding is specified (UTF-8 is used by default)");
 		let optionPaths = [dotenvPath];
 		if (options && options.path) if (!Array.isArray(options.path)) optionPaths = [_resolveHome(options.path)];
 		else {
@@ -286,11 +220,11 @@ var import_main = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
 		}
 		let lastError;
 		const parsedAll = {};
-		for (const path$5 of optionPaths) try {
-			const parsed = DotenvModule.parse(fs$1.readFileSync(path$5, { encoding }));
+		for (const path$3 of optionPaths) try {
+			const parsed = DotenvModule.parse(fs$1.readFileSync(path$3, { encoding }));
 			DotenvModule.populate(parsedAll, parsed, options);
 		} catch (e) {
-			if (debug) _debug(`Failed to load ${path$5} ${e.message}`);
+			if (debug) _debug(`failed to load ${path$3} ${e.message}`);
 			lastError = e;
 		}
 		const populated = DotenvModule.populate(processEnv, parsedAll, options);
@@ -303,10 +237,10 @@ var import_main = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
 				const relative = path$1.relative(process.cwd(), filePath);
 				shortPaths.push(relative);
 			} catch (e) {
-				if (debug) _debug(`Failed to load ${filePath} ${e.message}`);
+				if (debug) _debug(`failed to load ${filePath} ${e.message}`);
 				lastError = e;
 			}
-			_log(`injecting env (${keysCount}) from ${shortPaths.join(",")} ${dim(`-- tip: ${_getRandomTip()}`)}`);
+			_log(`injected env (${keysCount}) from ${shortPaths.join(",")} ${dim(`// tip: ${_getRandomTip()}`)}`);
 		}
 		if (lastError) return {
 			parsed: parsedAll,
@@ -318,7 +252,7 @@ var import_main = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
 		if (_dotenvKey(options).length === 0) return DotenvModule.configDotenv(options);
 		const vaultPath = _vaultPath(options);
 		if (!vaultPath) {
-			_warn(`You set DOTENV_KEY but you are missing a .env.vault file at ${vaultPath}. Did you forget to build it?`);
+			_warn(`you set DOTENV_KEY but you are missing a .env.vault file at ${vaultPath}`);
 			return DotenvModule.configDotenv(options);
 		}
 		return DotenvModule._configVault(options);
@@ -387,23 +321,65 @@ var import_main = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
 	module.exports.parse = DotenvModule.parse;
 	module.exports.populate = DotenvModule.populate;
 	module.exports = DotenvModule;
-})))();
-var version = "0.8.18";
+}));
+//#endregion
+//#region ../../node_modules/.pnpm/uuid@14.0.0/node_modules/uuid/dist-node/stringify.js
+const byteToHex = [];
+for (let i = 0; i < 256; ++i) byteToHex.push((i + 256).toString(16).slice(1));
+function unsafeStringify(arr, offset = 0) {
+	return (byteToHex[arr[offset + 0]] + byteToHex[arr[offset + 1]] + byteToHex[arr[offset + 2]] + byteToHex[arr[offset + 3]] + "-" + byteToHex[arr[offset + 4]] + byteToHex[arr[offset + 5]] + "-" + byteToHex[arr[offset + 6]] + byteToHex[arr[offset + 7]] + "-" + byteToHex[arr[offset + 8]] + byteToHex[arr[offset + 9]] + "-" + byteToHex[arr[offset + 10]] + byteToHex[arr[offset + 11]] + byteToHex[arr[offset + 12]] + byteToHex[arr[offset + 13]] + byteToHex[arr[offset + 14]] + byteToHex[arr[offset + 15]]).toLowerCase();
+}
+//#endregion
+//#region ../../node_modules/.pnpm/uuid@14.0.0/node_modules/uuid/dist-node/rng.js
+const rnds8 = new Uint8Array(16);
+function rng() {
+	return crypto.getRandomValues(rnds8);
+}
+//#endregion
+//#region ../../node_modules/.pnpm/uuid@14.0.0/node_modules/uuid/dist-node/v4.js
+function v4(options, buf, offset) {
+	if (!buf && !options && crypto.randomUUID) return crypto.randomUUID();
+	return _v4(options, buf, offset);
+}
+function _v4(options, buf, offset) {
+	options = options || {};
+	const rnds = options.random ?? options.rng?.() ?? rng();
+	if (rnds.length < 16) throw new Error("Random bytes length must be >= 16");
+	rnds[6] = rnds[6] & 15 | 64;
+	rnds[8] = rnds[8] & 63 | 128;
+	if (buf) {
+		offset = offset || 0;
+		if (offset < 0 || offset + 16 > buf.length) throw new RangeError(`UUID byte range ${offset}:${offset + 15} is out of buffer bounds`);
+		for (let i = 0; i < 16; ++i) buf[offset + i] = rnds[i];
+		return buf;
+	}
+	return unsafeStringify(rnds);
+}
+//#endregion
+//#region ../client/dist/index.mjs
+var import_main = require_main();
+var version = "0.8.29";
 function getLangVersion() {
 	if (typeof process !== "undefined" && process.versions && process.versions.node) return `node-${process.versions.node}`;
 	if (typeof navigator !== "undefined" && navigator.userAgent) return `browser-${navigator.userAgent}`;
 	return null;
 }
 var BaseResource = class {
-	constructor(baseHttpUrl, projectApiKey) {
+	constructor(baseHttpUrl, auth) {
 		this.baseHttpUrl = baseHttpUrl;
-		this.projectApiKey = projectApiKey;
+		this.auth = auth;
+		this.credential = auth.type === "apiKey" ? auth.key : auth.token;
+	}
+	/** API path prefix: `/v1/cli` for CLI user-token auth, `/v1` otherwise. */
+	get apiPrefix() {
+		return this.auth.type === "userToken" ? "/v1/cli" : "/v1";
 	}
 	headers() {
 		return {
-			Authorization: `Bearer ${this.projectApiKey}`,
+			Authorization: `Bearer ${this.credential}`,
 			"Content-Type": "application/json",
-			Accept: "application/json"
+			Accept: "application/json",
+			...this.auth.type === "userToken" ? { "x-lmnr-project-id": this.auth.projectId } : {}
 		};
 	}
 	async handleError(response) {
@@ -412,8 +388,8 @@ var BaseResource = class {
 	}
 };
 var BrowserEventsResource = class extends BaseResource {
-	constructor(baseHttpUrl, projectApiKey) {
-		super(baseHttpUrl, projectApiKey);
+	constructor(baseHttpUrl, auth) {
+		super(baseHttpUrl, auth);
 	}
 	async send({ sessionId, traceId, events }) {
 		const payload = {
@@ -437,37 +413,64 @@ var BrowserEventsResource = class extends BaseResource {
 		if (!response.ok) await this.handleError(response);
 	}
 };
+/**
+* User-scoped CLI endpoints that don't target a specific project. Authed by the
+* BetterAuth user JWT (the `credential`); deliberately does NOT send an
+* `x-lmnr-project-id` header (these routes are project discovery, pre-selection).
+*
+* Discovery exception: this resource always hits `/v1/cli/projects` with the
+* bare bearer and overrides `BaseResource.headers()`/`apiPrefix`, so it works
+* even when constructed with a `userToken` auth that has no real project id yet.
+*/
+var CliResource = class extends BaseResource {
+	constructor(baseHttpUrl, auth) {
+		super(baseHttpUrl, auth);
+	}
+	/** Workspaces + projects the authenticated user can access. */
+	async listProjects() {
+		const response = await fetch(`${this.baseHttpUrl}/v1/cli/projects`, {
+			method: "GET",
+			headers: {
+				Authorization: `Bearer ${this.credential}`,
+				Accept: "application/json"
+			}
+		});
+		if (!response.ok) await this.handleError(response);
+		const body = await response.json();
+		return Array.isArray(body?.projects) ? body.projects : [];
+	}
+};
 function initializeLogger$1(options) {
 	const colorize = options?.colorize ?? true;
 	const level = options?.level ?? process.env.LMNR_LOG_LEVEL?.toLowerCase()?.trim() ?? "info";
-	return (0, pino.default)({ level }, (0, pino_pretty.PinoPretty)({
+	return (0, pino$3.default)({ level }, (0, pino_pretty.PinoPretty)({
 		colorize,
 		minimumLevel: level
 	}));
 }
-const logger$2$1 = initializeLogger$1();
+const logger$4$1 = initializeLogger$1();
 const isStringUUID = (id) => /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(id);
-const newUUID$1 = () => {
+const newUUID = () => {
 	if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") return crypto.randomUUID();
-	else return (0, uuid.v4)();
+	else return v4();
 };
 const otelSpanIdToUUID = (spanId) => {
 	let id = spanId.toLowerCase();
 	if (id.startsWith("0x")) id = id.slice(2);
-	if (id.length !== 16) logger$2$1.warn(`Span ID ${spanId} is not 16 hex chars long. This is not a valid OpenTelemetry span ID.`);
+	if (id.length !== 16) logger$4$1.warn(`Span ID ${spanId} is not 16 hex chars long. This is not a valid OpenTelemetry span ID.`);
 	if (!/^[0-9a-f]+$/.test(id)) {
-		logger$2$1.error(`Span ID ${spanId} is not a valid hex string. Generating a random UUID instead.`);
-		return newUUID$1();
+		logger$4$1.error(`Span ID ${spanId} is not a valid hex string. Generating a random UUID instead.`);
+		return newUUID();
 	}
 	return id.padStart(32, "0").replace(/^([0-9a-f]{8})([0-9a-f]{4})([0-9a-f]{4})([0-9a-f]{4})([0-9a-f]{12})$/, "$1-$2-$3-$4-$5");
 };
 const otelTraceIdToUUID = (traceId) => {
 	let id = traceId.toLowerCase();
 	if (id.startsWith("0x")) id = id.slice(2);
-	if (id.length !== 32) logger$2$1.warn(`Trace ID ${traceId} is not 32 hex chars long. This is not a valid OpenTelemetry trace ID.`);
+	if (id.length !== 32) logger$4$1.warn(`Trace ID ${traceId} is not 32 hex chars long. This is not a valid OpenTelemetry trace ID.`);
 	if (!/^[0-9a-f]+$/.test(id)) {
-		logger$2$1.error(`Trace ID ${traceId} is not a valid hex string. Generating a random UUID instead.`);
-		return newUUID$1();
+		logger$4$1.error(`Trace ID ${traceId} is not a valid hex string. Generating a random UUID instead.`);
+		return newUUID();
 	}
 	return id.replace(/^([0-9a-f]{8})([0-9a-f]{4})([0-9a-f]{4})([0-9a-f]{4})([0-9a-f]{12})$/, "$1-$2-$3-$4-$5");
 };
@@ -490,16 +493,16 @@ const loadEnv = (options) => {
 	const verbose = ["debug", "trace"].includes(logLevel.trim().toLowerCase());
 	const quiet = options?.quiet ?? !verbose;
 	(0, import_main.config)({
-		path: options?.paths ?? envFiles.map((envFile) => path.resolve(envDir, envFile)),
+		path: options?.paths ?? envFiles.map((envFile) => path$2.resolve(envDir, envFile)),
 		quiet
 	});
 };
-const logger$1$1 = initializeLogger$1();
+const logger$3$1 = initializeLogger$1();
 const DEFAULT_DATASET_PULL_LIMIT = 100;
 const DEFAULT_DATASET_PUSH_BATCH_SIZE$1 = 100;
 var DatasetsResource = class extends BaseResource {
-	constructor(baseHttpUrl, projectApiKey) {
-		super(baseHttpUrl, projectApiKey);
+	constructor(baseHttpUrl, auth) {
+		super(baseHttpUrl, auth);
 	}
 	/**
 	* List all datasets.
@@ -507,7 +510,7 @@ var DatasetsResource = class extends BaseResource {
 	* @returns {Promise<Dataset[]>} Array of datasets
 	*/
 	async listDatasets() {
-		const response = await fetch(this.baseHttpUrl + "/v1/datasets", {
+		const response = await fetch(this.baseHttpUrl + this.apiPrefix + "/datasets", {
 			method: "GET",
 			headers: this.headers()
 		});
@@ -522,7 +525,7 @@ var DatasetsResource = class extends BaseResource {
 	*/
 	async getDatasetByName(name) {
 		const params = new URLSearchParams({ name });
-		const response = await fetch(this.baseHttpUrl + `/v1/datasets?${params.toString()}`, {
+		const response = await fetch(this.baseHttpUrl + `${this.apiPrefix}/datasets?${params.toString()}`, {
 			method: "GET",
 			headers: this.headers()
 		});
@@ -549,9 +552,9 @@ var DatasetsResource = class extends BaseResource {
 		let response;
 		for (let i = 0; i < points.length; i += batchSize) {
 			const batchNum = Math.floor(i / batchSize) + 1;
-			logger$1$1.debug(`Pushing batch ${batchNum} of ${totalBatches}`);
+			logger$3$1.debug(`Pushing batch ${batchNum} of ${totalBatches}`);
 			const batch = points.slice(i, i + batchSize);
-			const fetchResponse = await fetch(this.baseHttpUrl + "/v1/datasets/datapoints", {
+			const fetchResponse = await fetch(this.baseHttpUrl + this.apiPrefix + "/datasets/datapoints", {
 				method: "POST",
 				headers: this.headers(),
 				body: JSON.stringify({
@@ -589,7 +592,7 @@ var DatasetsResource = class extends BaseResource {
 		if (name) paramsObj.name = name;
 		else paramsObj.datasetId = id;
 		const params = new URLSearchParams(paramsObj);
-		const response = await fetch(this.baseHttpUrl + `/v1/datasets/datapoints?${params.toString()}`, {
+		const response = await fetch(this.baseHttpUrl + `${this.apiPrefix}/datasets/datapoints?${params.toString()}`, {
 			method: "GET",
 			headers: this.headers()
 		});
@@ -597,11 +600,11 @@ var DatasetsResource = class extends BaseResource {
 		return response.json();
 	}
 };
-const logger$6 = initializeLogger$1();
+const logger$2$1 = initializeLogger$1();
 const INITIAL_EVALUATION_DATAPOINT_MAX_DATA_LENGTH = 16e6;
 var EvalsResource = class extends BaseResource {
-	constructor(baseHttpUrl, projectApiKey) {
-		super(baseHttpUrl, projectApiKey);
+	constructor(baseHttpUrl, auth) {
+		super(baseHttpUrl, auth);
 	}
 	/**
 	* Initialize an evaluation.
@@ -655,14 +658,14 @@ var EvalsResource = class extends BaseResource {
 	* @returns {Promise<StringUUID>} The datapoint ID
 	*/
 	async createDatapoint({ evalId, data, target, metadata, index, traceId }) {
-		const datapointId = newUUID$1();
+		const datapointId = newUUID();
 		const partialDatapoint = {
 			id: datapointId,
 			data,
 			target,
 			index: index ?? 0,
-			traceId: traceId ?? newUUID$1(),
-			executorSpanId: newUUID$1(),
+			traceId: traceId ?? newUUID(),
+			executorSpanId: newUUID(),
 			metadata
 		};
 		await this.saveDatapoints({
@@ -733,7 +736,7 @@ var EvalsResource = class extends BaseResource {
 	* @returns {Promise<GetDatapointsResponse>} Response from the datapoint retrieval
 	*/
 	async getDatapoints({ datasetName, offset, limit }) {
-		logger$6.warn("evals.getDatapoints() is deprecated. Use client.datasets.pull() instead.");
+		logger$2$1.warn("evals.getDatapoints() is deprecated. Use client.datasets.pull() instead.");
 		const params = new URLSearchParams({
 			name: datasetName,
 			offset: offset.toString(),
@@ -750,7 +753,7 @@ var EvalsResource = class extends BaseResource {
 		let length = initialLength;
 		let lastResponse = null;
 		for (let i = 0; i < maxRetries; i++) {
-			logger$6.debug(`Retrying save datapoints... ${i + 1} of ${maxRetries}, length: ${length}`);
+			logger$2$1.debug(`Retrying save datapoints... ${i + 1} of ${maxRetries}, length: ${length}`);
 			const response = await fetch(this.baseHttpUrl + `/v1/evals/${evalId}/datapoints`, {
 				method: "POST",
 				headers: this.headers(),
@@ -771,17 +774,12 @@ var EvalsResource = class extends BaseResource {
 		if (lastResponse && !lastResponse.ok) await this.handleError(lastResponse);
 	}
 };
-var EvaluatorScoreSourceType = /* @__PURE__ */ function(EvaluatorScoreSourceType) {
-	EvaluatorScoreSourceType["Evaluator"] = "Evaluator";
-	EvaluatorScoreSourceType["Code"] = "Code";
-	return EvaluatorScoreSourceType;
-}(EvaluatorScoreSourceType || {});
 /**
 * Resource for creating evaluator scores
 */
 var EvaluatorsResource = class extends BaseResource {
-	constructor(baseHttpUrl, projectApiKey) {
-		super(baseHttpUrl, projectApiKey);
+	constructor(baseHttpUrl, auth) {
+		super(baseHttpUrl, auth);
 	}
 	/**
 	* Create a score for a span or trace
@@ -814,25 +812,21 @@ var EvaluatorsResource = class extends BaseResource {
 	async score(options) {
 		const { name, metadata, score } = options;
 		let payload;
-		if ("traceId" in options && options.traceId) {
-			const formattedTraceId = isStringUUID(options.traceId) ? options.traceId : otelTraceIdToUUID(options.traceId);
-			payload = {
-				name,
-				metadata,
-				score,
-				source: EvaluatorScoreSourceType.Code,
-				traceId: formattedTraceId
-			};
-		} else if ("spanId" in options && options.spanId) {
-			const formattedSpanId = isStringUUID(options.spanId) ? options.spanId : otelSpanIdToUUID(options.spanId);
-			payload = {
-				name,
-				metadata,
-				score,
-				source: EvaluatorScoreSourceType.Code,
-				spanId: formattedSpanId
-			};
-		} else throw new Error("Either 'traceId' or 'spanId' must be provided.");
+		if ("traceId" in options && options.traceId) payload = {
+			name,
+			metadata,
+			score,
+			source: "Code",
+			traceId: isStringUUID(options.traceId) ? options.traceId : otelTraceIdToUUID(options.traceId)
+		};
+		else if ("spanId" in options && options.spanId) payload = {
+			name,
+			metadata,
+			score,
+			source: "Code",
+			spanId: isStringUUID(options.spanId) ? options.spanId : otelSpanIdToUUID(options.spanId)
+		};
+		else throw new Error("Either 'traceId' or 'spanId' must be provided.");
 		const response = await fetch(this.baseHttpUrl + "/v1/evaluators/score", {
 			method: "POST",
 			headers: this.headers(),
@@ -841,70 +835,139 @@ var EvaluatorsResource = class extends BaseResource {
 		if (!response.ok) await this.handleError(response);
 	}
 };
+const logger$1$1 = initializeLogger$1();
+/**
+* Map the opaque HIT `response` payload onto a {@link CachedSpan} the provider
+* wrappers can replay. The server-side shape of `response` is not yet frozen
+* (app-server plan 01 leaves it as a `serde_json::Value`), so this stays
+* deliberately tolerant: the whole payload is serialized into `output` (the only
+* field the AI SDK wrapper's `parseCachedSpan` actually reads, via
+* `JSON.parse`), and a `finishReason` is surfaced into `attributes` when the
+* payload carries one. `name`/`input` are irrelevant to replay and left empty.
+*/
+const toCachedSpan = (response) => {
+	const output = typeof response === "string" ? response : JSON.stringify(response ?? null);
+	const attributes = {};
+	if (response !== null && typeof response === "object" && typeof response.finishReason === "string") attributes["ai.response.finishReason"] = response.finishReason;
+	return {
+		name: "",
+		input: "",
+		output,
+		attributes
+	};
+};
 var RolloutSessionsResource = class extends BaseResource {
-	constructor(baseHttpUrl, projectApiKey) {
-		super(baseHttpUrl, projectApiKey);
+	constructor(baseHttpUrl, auth) {
+		super(baseHttpUrl, auth);
 	}
 	/**
-	* Connects to the SSE stream for rollout debugging sessions
-	* Returns the Response object for streaming SSE events
+	* Idempotently register (upsert) a debug session on the backend, keyed on the
+	* SDK-supplied session id. The backend stores the row so the session is
+	* visible in the UI; a null/omitted name never clobbers a name set elsewhere.
+	*
+	* Returns the backend-resolved `projectId` (derived from the API key) so the
+	* caller can build the debugger URL; null if the body can't be parsed.
 	*/
-	async connect({ sessionId, name, params, signal }) {
-		const response = await fetch(`${this.baseHttpUrl}/v1/rollouts/${sessionId}`, {
+	async register({ sessionId, name }) {
+		const response = await fetch(`${this.baseHttpUrl}${this.apiPrefix}/rollouts/${sessionId}`, {
 			method: "POST",
-			headers: {
-				...this.headers(),
-				"Accept": "text/event-stream"
-			},
-			body: JSON.stringify({
-				name,
-				params
-			}),
-			signal
-		});
-		if (!response.ok) throw new Error(`SSE connection failed: ${response.status} ${response.statusText}`);
-		if (!response.body) throw new Error("No response body");
-		return response;
-	}
-	async delete({ sessionId }) {
-		const response = await fetch(`${this.baseHttpUrl}/v1/rollouts/${sessionId}`, {
-			method: "DELETE",
-			headers: this.headers()
+			headers: this.headers(),
+			body: JSON.stringify({ name })
 		});
 		if (!response.ok) await this.handleError(response);
+		try {
+			return (await response.json()).projectId ?? null;
+		} catch (e) {
+			logger$1$1.warn(`Failed to parse rollout register response: ${errorMessage(e)}`);
+			return null;
+		}
 	}
-	async setStatus({ sessionId, status }) {
-		const response = await fetch(`${this.baseHttpUrl}/v1/rollouts/${sessionId}/status`, {
+	/**
+	* Rename an existing debug session. Update-only: the backend returns 404 (and
+	* this throws) when the session id is unknown for the project, so a mistyped
+	* id surfaces as an error rather than silently creating a session. Creation
+	* stays the SDK's job via {@link register}.
+	*/
+	async setName({ sessionId, name }) {
+		const response = await fetch(`${this.baseHttpUrl}${this.apiPrefix}/rollouts/${sessionId}/name`, {
 			method: "PATCH",
 			headers: this.headers(),
-			body: JSON.stringify({ status })
+			body: JSON.stringify({ name })
 		});
 		if (!response.ok) await this.handleError(response);
 	}
-	async sendSpanUpdate({ sessionId, span }) {
-		const response = await fetch(`${this.baseHttpUrl}/v1/rollouts/${sessionId}/update`, {
-			method: "PATCH",
-			headers: this.headers(),
-			body: JSON.stringify({
-				type: "spanStart",
-				spanId: otelSpanIdToUUID(span.spanId),
-				traceId: otelTraceIdToUUID(span.traceId),
-				parentSpanId: span.parentSpanId ? otelSpanIdToUUID(span.parentSpanId) : void 0,
-				attributes: span.attributes,
-				startTime: span.startTime,
-				name: span.name,
-				spanType: span.spanType
-			})
+	/**
+	* Look up the debug-replay cache for a single LLM call (debug-replay v2).
+	*
+	* The server is keyed by `inputHash` (hex blake3 of the canonicalized,
+	* system-stripped input messages). It returns one of three outcomes:
+	*   - `{ outcome: "hit", response }` — a cached response to replay.
+	*   - `{ outcome: "miss" }`          — no entry; caller latches live mode.
+	*   - `{ outcome: "live" }`          — run this call live (COLD degrade).
+	*
+	* Error posture: a non-OK response or a transport error degrades to
+	* `{ kind: "live" }` for THIS call only — it never throws and never latches
+	* the process-wide live flag (only a real MISS does that). This keeps a flaky
+	* cache backend from turning a replay into a crash.
+	*/
+	async cache({ sessionId, replayTraceId, cacheUntil, inputHash }) {
+		let response;
+		try {
+			response = await fetch(`${this.baseHttpUrl}${this.apiPrefix}/rollouts/${sessionId}/cache`, {
+				method: "POST",
+				headers: this.headers(),
+				body: JSON.stringify({
+					replayTraceId,
+					cacheUntil,
+					inputHash
+				})
+			});
+		} catch (e) {
+			logger$1$1.warn(`Debug cache lookup failed, running live: ${errorMessage(e)}`);
+			return { kind: "live" };
+		}
+		if (!response.ok) {
+			logger$1$1.warn(`Debug cache lookup returned ${response.status}, running live`);
+			return { kind: "live" };
+		}
+		let body;
+		try {
+			body = await response.json();
+		} catch (e) {
+			logger$1$1.warn(`Failed to parse debug cache response, running live: ${errorMessage(e)}`);
+			return { kind: "live" };
+		}
+		switch (body.outcome) {
+			case "hit":
+				if (body.response === null || body.response === void 0) {
+					logger$1$1.warn("Debug cache HIT had no response payload, running live");
+					return { kind: "live" };
+				}
+				return {
+					kind: "hit",
+					cached: toCachedSpan(body.response)
+				};
+			case "miss": return { kind: "miss" };
+			case "live": return { kind: "live" };
+			default:
+				logger$1$1.warn(`Unknown debug cache outcome "${body.outcome}", running live`);
+				return { kind: "live" };
+		}
+	}
+	async delete({ sessionId }) {
+		const response = await fetch(`${this.baseHttpUrl}${this.apiPrefix}/rollouts/${sessionId}`, {
+			method: "DELETE",
+			headers: this.headers()
 		});
 		if (!response.ok) await this.handleError(response);
 	}
 };
 var SqlResource = class extends BaseResource {
-	constructor(baseHttpUrl, projectApiKey) {
-		super(baseHttpUrl, projectApiKey);
+	constructor(baseHttpUrl, auth) {
+		super(baseHttpUrl, auth);
 	}
 	async query(sql, parameters = {}) {
-		const response = await fetch(`${this.baseHttpUrl}/v1/sql/query`, {
+		const response = await fetch(`${this.baseHttpUrl}${this.apiPrefix}/sql/query`, {
 			method: "POST",
 			headers: { ...this.headers() },
 			body: JSON.stringify({
@@ -919,8 +982,8 @@ var SqlResource = class extends BaseResource {
 /** Resource for tagging traces. */
 var TagsResource = class extends BaseResource {
 	/** Resource for tagging traces. */
-	constructor(baseHttpUrl, projectApiKey) {
-		super(baseHttpUrl, projectApiKey);
+	constructor(baseHttpUrl, auth) {
+		super(baseHttpUrl, auth);
 	}
 	/**
 	* Tag a trace with a list of tags. Note that the trace must be ended before
@@ -971,23 +1034,127 @@ var TagsResource = class extends BaseResource {
 		return response.json();
 	}
 };
-var LaminarClient = class {
-	constructor({ baseUrl, projectApiKey, port } = {}) {
+/** Resource for post-factum operations on existing traces. */
+const logger$5 = initializeLogger$1();
+var TracesResource = class extends BaseResource {
+	/** Resource for post-factum operations on existing traces. */
+	constructor(baseHttpUrl, auth) {
+		super(baseHttpUrl, auth);
+	}
+	/**
+	* Push a metadata patch to an existing trace.
+	*
+	* The patch is shallow-merged server-side into the trace's existing metadata
+	* (`existing || patch`, last-write-wins per top-level key). Useful for
+	* attaching post-factum signals — quality scores, human edits, triage labels —
+	* to a trace that has already finished. The patch does NOT extend `endTime`
+	* or change tokens / cost / top span / tags / span names. `numSpans` is
+	* incremented by 1 (paid by the virtual span that carried the patch through
+	* the ingestion queue) so the new ClickHouse row beats the prior version on
+	* `ReplacingMergeTree(numSpans)`. No row is added to the `spans` table.
+	*
+	* Compared to `Laminar.setTraceMetadata` (which sets metadata on the
+	* currently in-flight trace via OpenTelemetry attributes), this method
+	* operates on a finished trace by trace id, so it must be called after the
+	* trace has been flushed.
+	*
+	* A 404 response (the trace was not found in the project — typically because
+	* it has not been flushed yet) is logged as a warning and the call returns
+	* without throwing, since the 404 may be expected when pushing too soon
+	* after the trace run. Pass `failOnNotFound: true` to throw instead (e.g.
+	* CLI callers that must report the failure). Any other non-OK status throws.
+	*
+	* @param traceId - The trace id to push metadata to. Accepts a UUID string
+	*   or a 32-char OTel hex trace id.
+	* @param metadata - The metadata patch. Top-level keys are merged into the
+	*   trace's existing metadata. Must be non-empty (the server rejects empty
+	*   patches with 400).
+	* @param options - `failOnNotFound`: throw on 404 instead of warn-and-return.
+	* @example
+	* ```typescript
+	* import { Laminar, observe, LaminarClient } from "@lmnr-ai/lmnr";
+	* Laminar.initialize();
+	* const client = new LaminarClient();
+	*
+	* let traceId: string | null = null;
+	* await observe({ name: "generate" }, async () => {
+	*   traceId = await Laminar.getTraceId();
+	* });
+	* await Laminar.flush();
+	*
+	* if (traceId) {
+	*   await client.traces.pushMetadata(traceId, {
+	*     score: 0.85,
+	*     reviewer: "alice",
+	*     needsReview: false,
+	*   });
+	* }
+	* ```
+	*/
+	async pushMetadata(traceId, metadata, options) {
+		if (!metadata || Object.keys(metadata).length === 0) throw new Error("metadata must be a non-empty object");
+		const formattedTraceId = isStringUUID(traceId) ? traceId : otelTraceIdToUUID(traceId);
+		const url = this.baseHttpUrl + this.apiPrefix + "/traces/metadata";
+		const response = await fetch(url, {
+			method: "POST",
+			headers: this.headers(),
+			body: JSON.stringify({
+				traceId: formattedTraceId,
+				metadata
+			})
+		});
+		if (response.status === 404) {
+			const message = `Trace ${formattedTraceId} not found. The trace may not have been flushed yet — call await Laminar.flush() and retry.`;
+			if (options?.failOnNotFound) throw new Error(message);
+			logger$5.warn(message);
+			return;
+		}
+		if (!response.ok) await this.handleError(response);
+	}
+};
+var LaminarClient = class LaminarClient {
+	constructor({ baseUrl, port, auth, projectApiKey, cliUserProjectId } = {}) {
 		loadEnv();
-		this.projectApiKey = projectApiKey ?? process.env.LMNR_PROJECT_API_KEY;
+		this.auth = LaminarClient.normalizeAuth(auth, projectApiKey, cliUserProjectId);
 		const httpPort = port ?? (baseUrl?.match(/:\d{1,5}$/g) ? parseInt(baseUrl.match(/:\d{1,5}$/g)[0].slice(1)) : 443);
-		this.baseUrl = `${(baseUrl ?? process.env.LMNR_BASE_URL)?.replace(/\/$/, "").replace(/:\d{1,5}$/g, "") ?? "https://api.lmnr.ai"}:${httpPort}`;
-		this._browserEvents = new BrowserEventsResource(this.baseUrl, this.projectApiKey);
-		this._datasets = new DatasetsResource(this.baseUrl, this.projectApiKey);
-		this._evals = new EvalsResource(this.baseUrl, this.projectApiKey);
-		this._evaluators = new EvaluatorsResource(this.baseUrl, this.projectApiKey);
-		this._rolloutSessions = new RolloutSessionsResource(this.baseUrl, this.projectApiKey);
-		this._sql = new SqlResource(this.baseUrl, this.projectApiKey);
-		this._tags = new TagsResource(this.baseUrl, this.projectApiKey);
+		const baseUrlNoPort = (baseUrl ?? process.env.LMNR_BASE_URL)?.replace(/\/$/, "").replace(/:\d{1,5}$/g, "");
+		this.baseUrl = `${baseUrlNoPort ?? "https://api.lmnr.ai"}:${httpPort}`;
+		this._browserEvents = new BrowserEventsResource(this.baseUrl, this.auth);
+		this._cli = new CliResource(this.baseUrl, this.auth);
+		this._datasets = new DatasetsResource(this.baseUrl, this.auth);
+		this._evals = new EvalsResource(this.baseUrl, this.auth);
+		this._evaluators = new EvaluatorsResource(this.baseUrl, this.auth);
+		this._rolloutSessions = new RolloutSessionsResource(this.baseUrl, this.auth);
+		this._sql = new SqlResource(this.baseUrl, this.auth);
+		this._tags = new TagsResource(this.baseUrl, this.auth);
+		this._traces = new TracesResource(this.baseUrl, this.auth);
+	}
+	/**
+	* Normalize the constructor's auth inputs into a {@link LaminarAuth} union.
+	* Precedence: an explicit `auth` wins; otherwise the legacy
+	* `projectApiKey` (+ optional `cliUserProjectId`) is mapped — a present
+	* `cliUserProjectId` selects the user-token surface, otherwise the project
+	* key surface. Falls back to `LMNR_PROJECT_API_KEY` as a project key.
+	*/
+	static normalizeAuth(auth, projectApiKey, cliUserProjectId) {
+		if (auth) return auth;
+		const key = projectApiKey ?? process.env.LMNR_PROJECT_API_KEY;
+		if (cliUserProjectId) return {
+			type: "userToken",
+			token: key,
+			projectId: cliUserProjectId
+		};
+		return {
+			type: "apiKey",
+			key
+		};
 	}
 	get browserEvents() {
 		return this._browserEvents;
 	}
+	get cli() {
+		return this._cli;
+	}
 	get datasets() {
 		return this._datasets;
 	}
@@ -1006,6 +1173,9 @@ var LaminarClient = class {
 	get tags() {
 		return this._tags;
 	}
+	get traces() {
+		return this._traces;
+	}
 };
 //#endregion
 //#region src/utils/logger.ts
@@ -1019,94 +1189,544 @@ function initializeLogger(options) {
 	}));
 }
 //#endregion
-//#region src/utils/file.ts
-const logger$5 = initializeLogger();
+//#region src/utils/output.ts
 /**
-* Check if a file has a supported extension.
+* Write structured JSON to stdout. Use this for machine-readable output
+* when --json is set.
 */
-const isSupportedFile = (file) => {
-	const ext = path.extname(file).toLowerCase();
-	return [
-		".json",
-		".csv",
-		".jsonl"
-	].includes(ext);
-};
+function outputJson(data) {
+	console.log(JSON.stringify(data));
+}
 /**
-* Collect all supported files from the given paths.
-* Handles both files and directories.
+* Write a JSON error to stdout and exit with code 1.
+* Use this in --json mode so agents can parse the failure.
 */
-const collectFiles = async (paths, recursive = false) => {
-	const collectedFiles = [];
-	for (const filepath of paths) try {
-		const stats = await fs_promises.stat(filepath);
-		if (stats.isFile()) if (isSupportedFile(filepath)) collectedFiles.push(filepath);
-		else logger$5.warn(`Skipping unsupported file type: ${filepath}`);
-		else if (stats.isDirectory()) {
-			const entries = await fs_promises.readdir(filepath);
-			for (const entry of entries) {
-				const fullPath = path.join(filepath, entry);
-				const entryStats = await fs_promises.stat(fullPath);
-				if (entryStats.isFile() && isSupportedFile(fullPath)) collectedFiles.push(fullPath);
-				else if (recursive && entryStats.isDirectory()) {
-					const subFiles = await collectFiles([fullPath], true);
-					collectedFiles.push(...subFiles);
-				}
-			}
-		}
-	} catch (error) {
-		logger$5.warn(`Path does not exist or is not accessible: ${filepath}. Error: ${error instanceof Error ? error.message : String(error)}`);
-	}
-	return collectedFiles;
-};
+function outputJsonError(error, exitCode = 1) {
+	console.log(JSON.stringify({ error: errorMessage(error) }));
+	process.exit(exitCode);
+}
+//#endregion
+//#region src/constants.ts
+const DEFAULT_FRONTEND_URL$1 = "https://www.laminar.sh";
+const DEFAULT_BASE_URL$1 = "https://api.lmnr.ai";
+//#endregion
+//#region src/utils/project-link.ts
+const LINK_DIR = ".lmnr";
+const LINK_FILE = "project.json";
 /**
-* Read a JSON file and return its contents.
+* Find the nearest `.lmnr/project.json`, walking up from `startDir` to the
+* filesystem root (so commands work from subdirectories of a linked project).
+* Returns null if none is found.
 */
-const readJsonFile = async (filepath) => {
-	const content = await fs_promises.readFile(filepath, "utf-8");
-	const parsed = JSON.parse(content);
-	return Array.isArray(parsed) ? parsed : [parsed];
-};
+async function readProjectLink(startDir = process.cwd()) {
+	let dir = startDir;
+	const root = (0, node_path.parse)(dir).root;
+	while (true) {
+		const candidate = (0, node_path.join)(dir, LINK_DIR, LINK_FILE);
+		try {
+			const parsed = JSON.parse(await (0, node_fs_promises.readFile)(candidate, "utf8"));
+			if (parsed && typeof parsed.projectId === "string" && parsed.projectId.length > 0) return parsed;
+		} catch {}
+		const parent = (0, node_path.dirname)(dir);
+		if (parent === dir || dir === root) break;
+		dir = parent;
+	}
+	return null;
+}
+/** Write `.lmnr/project.json` under `dir` (default cwd). Returns the file path. */
+async function writeProjectLink(link, dir = process.cwd()) {
+	const linkDir = (0, node_path.join)(dir, LINK_DIR);
+	await (0, node_fs_promises.mkdir)(linkDir, { recursive: true });
+	const path = (0, node_path.join)(linkDir, LINK_FILE);
+	await (0, node_fs_promises.writeFile)(path, JSON.stringify(link, null, 2) + "\n", "utf8");
+	return path;
+}
+function globalLmnrDirectory() {
+	const xdg = process.env.XDG_CONFIG_HOME?.trim();
+	if (xdg && xdg.length > 0) return (0, node_path.join)(xdg, "lmnr");
+	const appData = process.env.APPDATA?.trim();
+	if (process.platform === "win32" && appData && appData.length > 0) return (0, node_path.join)(appData, "lmnr");
+	return (0, node_path.join)((0, node_os.homedir)(), ".config", "lmnr");
+}
+function credentialsPath() {
+	return (0, node_path.join)(globalLmnrDirectory(), "credentials.json");
+}
 /**
-* Try to parse a string as JSON. If it fails, return the original string.
+* Read the credentials file. Returns null when missing or not the current flat
+* v1 shape (treated as "not logged in" — `lmnr-cli login` overwrites).
 */
-const tryParseJson = (content) => {
-	if (typeof content !== "string") return content;
-	const trimmed = content.trim();
-	if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) return content;
+async function readCredentials() {
+	const path = credentialsPath();
+	let raw;
 	try {
-		return JSON.parse(content);
-	} catch (error) {
-		logger$5.debug(`Error parsing JSON: ${error instanceof Error ? error.message : String(error)}`);
-		return content;
+		raw = await (0, node_fs_promises.readFile)(path, "utf-8");
+	} catch (e) {
+		if (isNotFound(e)) return null;
+		throw e;
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return null;
+	}
+	if (parsed.version === 1 && typeof parsed.sessionToken === "string") return parsed;
+	return null;
+}
+async function writeCredentials(creds) {
+	const path = credentialsPath();
+	await (0, node_fs_promises.mkdir)((0, node_path.dirname)(path), {
+		recursive: true,
+		mode: 448
+	});
+	let mode = 384;
+	try {
+		mode = (await (0, node_fs_promises.stat)(path)).mode & 511;
+	} catch (e) {
+		if (!isNotFound(e)) throw e;
+	}
+	const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
+	await (0, node_fs_promises.writeFile)(tmp, JSON.stringify(creds, null, 2), {
+		mode,
+		flag: "wx"
+	});
+	await (0, node_fs_promises.rename)(tmp, path);
+}
+async function deleteCredentials() {
+	const path = credentialsPath();
+	try {
+		await (0, node_fs_promises.stat)(path);
+	} catch (e) {
+		if (isNotFound(e)) return false;
+		throw e;
+	}
+	await (0, node_fs_promises.rm)(path, { force: true });
+	return true;
+}
+function isNotFound(e) {
+	return typeof e === "object" && e !== null && "code" in e && e.code === "ENOENT";
+}
+//#endregion
+//#region src/auth/device.ts
+const CLI_CLIENT_ID = "lmnr-cli";
+const CLI_SCOPE = "projects:rw";
+const DEVICE_CODE_ENDPOINT = "/api/auth/device/code";
+const DEVICE_TOKEN_ENDPOINT = "/api/auth/device/token";
+const TOKEN_ENDPOINT = "/api/auth/token";
+const SESSION_ENDPOINT = "/api/auth/get-session";
+var DeviceFlowError = class extends Error {
+	constructor(code, message) {
+		super(message);
+		this.code = code;
 	}
 };
+function trimSlash$3(url) {
+	return url.replace(/\/+$/, "");
+}
+async function initiateDevice(issuer, scope = CLI_SCOPE) {
+	const url = `${trimSlash$3(issuer)}${DEVICE_CODE_ENDPOINT}`;
+	const res = await fetch(url, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify({
+			client_id: CLI_CLIENT_ID,
+			scope
+		})
+	});
+	if (!res.ok) {
+		const body = await safeJson(res) ?? {};
+		throw new DeviceFlowError(typeof body.error === "string" ? body.error : `http_${res.status}`, typeof body.error_description === "string" ? body.error_description : `Device authorization request failed (${res.status})`);
+	}
+	return await res.json();
+}
 /**
-* Parse each field in a CSV row, attempting to convert JSON strings back to objects.
-*/
-const parseCsvRow = (row) => {
-	const parsed = {};
-	for (const [key, value] of Object.entries(row)) parsed[key] = tryParseJson(value);
-	return parsed;
-};
-/**
-* Read a CSV file and return its contents as an array of objects.
+* Poll BetterAuth's native token endpoint until the user approves. Returns the
+* full token response (whose `access_token` is the durable session token).
 */
-const readCsvFile = async (filepath) => new Promise((resolve, reject) => {
-	const results = [];
-	(0, fs.createReadStream)(filepath).pipe((0, csv_parser.default)()).on("data", (data) => results.push(parseCsvRow(data))).on("end", () => resolve(results)).on("error", reject);
-});
+async function pollDevice(issuer, deviceCode, opts = {}) {
+	let intervalSeconds = Math.max(1, opts.intervalSeconds ?? 5);
+	const timeoutMs = (opts.timeoutSeconds ?? 900) * 1e3;
+	const deadline = Date.now() + timeoutMs;
+	while (true) {
+		if (Date.now() > deadline) throw new DeviceFlowError("expired_token", "Timed out waiting for authorization");
+		const url = `${trimSlash$3(issuer)}${DEVICE_TOKEN_ENDPOINT}`;
+		const res = await fetch(url, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({
+				grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+				device_code: deviceCode,
+				client_id: CLI_CLIENT_ID
+			})
+		});
+		if (res.ok) {
+			const body = await res.json();
+			if (!body.access_token) throw new DeviceFlowError("server_error", "Device token response missing access_token");
+			body.metadata = res.headers.get("x-lmnr-metadata");
+			return body;
+		}
+		const body = await safeJson(res) ?? {};
+		const code = typeof body.error === "string" ? body.error : `http_${res.status}`;
+		const description = typeof body.error_description === "string" ? body.error_description : code;
+		if (code === "authorization_pending") {
+			opts.onTick?.();
+			await sleep(intervalSeconds * 1e3);
+			continue;
+		}
+		if (code === "slow_down") {
+			intervalSeconds += 5;
+			await sleep(intervalSeconds * 1e3);
+			continue;
+		}
+		throw new DeviceFlowError(code, description);
+	}
+}
 /**
-* Read a JSONL file and return its contents as an array of objects.
+* Mint a fresh 15m EdDSA JWT from a session token. Throws DeviceFlowError
+* "invalid_grant" on 401 (session expired/revoked).
 */
-async function readJsonlFile(filepath) {
-	return (await fs_promises.readFile(filepath, "utf-8")).split("\n").filter((line) => line.trim()).map((line) => JSON.parse(line));
+async function mintAccessJwt(issuer, sessionToken) {
+	const url = `${trimSlash$3(issuer)}${TOKEN_ENDPOINT}`;
+	const res = await fetch(url, {
+		method: "GET",
+		headers: { authorization: `Bearer ${sessionToken}` }
+	});
+	if (res.status === 401) throw new DeviceFlowError("invalid_grant", "Session expired or revoked");
+	if (!res.ok) {
+		const body = await safeJson(res) ?? {};
+		throw new DeviceFlowError(typeof body.error === "string" ? body.error : `http_${res.status}`, `Failed to mint access token (${res.status})`);
+	}
+	const body = await res.json();
+	if (!body.token) throw new DeviceFlowError("server_error", "Token endpoint response missing token");
+	return body.token;
+}
+/** Fetch the BetterAuth session for profile metadata (userId, email). */
+async function fetchSession(issuer, sessionToken) {
+	const url = `${trimSlash$3(issuer)}${SESSION_ENDPOINT}`;
+	const res = await fetch(url, {
+		method: "GET",
+		headers: { authorization: `Bearer ${sessionToken}` }
+	});
+	if (!res.ok) throw new DeviceFlowError(`http_${res.status}`, `Failed to fetch session (${res.status})`);
+	const user = (await res.json())?.user;
+	if (!user?.id) throw new DeviceFlowError("server_error", "Session response missing user");
+	return {
+		id: user.id,
+		email: user.email ?? ""
+	};
 }
 /**
-* Read a single file and return its contents.
+* Decode a JWT's `exp` (seconds since epoch) → ISO string. No signature
+* verification — the CLI trusts a token it just received over TLS. Returns null
+* when the token is malformed or carries no numeric `exp`.
 */
-async function readFile(filepath) {
-	const ext = path.extname(filepath).toLowerCase();
+function decodeJwtExp(jwt) {
+	const parts = jwt.split(".");
+	if (parts.length < 2) return null;
+	try {
+		const json = Buffer.from(parts[1], "base64url").toString("utf-8");
+		const payload = JSON.parse(json);
+		if (typeof payload.exp !== "number") return null;
+		return (/* @__PURE__ */ new Date(payload.exp * 1e3)).toISOString();
+	} catch {
+		return null;
+	}
+}
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+* Extract the browser-selected projectId from the device-token `x-lmnr-metadata`
+* response header — a JSON string, e.g. `{"projectId":"<uuid>"}`, forwarded by
+* the server's /device/token route wrapper. Returns null when absent or malformed.
+*/
+function parseProjectFromMetadata(metadata) {
+	if (!metadata) return null;
+	try {
+		const pid = JSON.parse(metadata)?.projectId;
+		return typeof pid === "string" && UUID_RE.test(pid) ? pid : null;
+	} catch {
+		return null;
+	}
+}
+async function safeJson(res) {
+	try {
+		return await res.json();
+	} catch {
+		return null;
+	}
+}
+function sleep(ms) {
+	return new Promise((r) => setTimeout(r, ms));
+}
+//#endregion
+//#region src/auth/resolve.ts
+const REFRESH_SKEW_MS = 3e4;
+/**
+* HTTP port from `LMNR_HTTP_PORT`. The Laminar convention is that `baseUrl`
+* carries NO port and the port is supplied separately (mirrors the SDK's
+* `LMNR_HTTP_PORT` / `LMNR_GRPC_PORT`). Returns undefined when unset/invalid so
+* the client keeps its 443 default for Cloud. An explicit `--port` flag still
+* wins (callers do `opts.port ?? envHttpPort()`).
+*/
+function envHttpPort() {
+	const raw = process.env.LMNR_HTTP_PORT?.trim();
+	if (!raw) return void 0;
+	const n = Number.parseInt(raw, 10);
+	return Number.isFinite(n) ? n : void 0;
+}
+/**
+* Resolve the data-API base URL: `--base-url` flag → `LMNR_BASE_URL` env →
+* default. Intentionally NOT read from credentials.json — the endpoint is not
+* persisted at login, so a self-host `.env` change applies to every command
+* without re-logging-in (and base URL behaves symmetrically with the port).
+*/
+function resolveBaseUrl(optBaseUrl) {
+	return optBaseUrl?.trim() || process.env.LMNR_BASE_URL?.trim() || "https://api.lmnr.ai";
+}
+/**
+* CLI auth is **user-token only** — the CLI authenticates as the single
+* signed-in user via the stored BetterAuth session (refreshed access JWT),
+* never via a project API key.
+*
+* Project precedence (directory-scoped): `--project-id` flag > the nearest
+* `.lmnr/project.json` (written by `setup`). The project is NOT stored in
+* credentials.json — that holds only user auth.
+*/
+async function resolveAuth(opts) {
+	const creds = await readCredentials();
+	if (!creds) throw new Error("Not authenticated. Run `lmnr-cli login`.");
+	let projectId = opts.projectId;
+	if (!projectId || projectId.length === 0) projectId = (await readProjectLink())?.projectId;
+	if (!projectId || projectId.length === 0) throw new Error("No project for this directory. Run `lmnr-cli setup` here, or pass --project-id <id>.");
+	return {
+		bearer: (await refreshIfNeeded(creds)).accessToken,
+		baseUrl: resolveBaseUrl(opts.baseUrl),
+		port: opts.port ?? envHttpPort(),
+		projectId
+	};
+}
+/**
+* Resolve only the user-scoped access token (no project) — for discovery
+* endpoints like listing projects, which run BEFORE a project is selected.
+*/
+async function resolveUserToken(opts) {
+	const creds = await readCredentials();
+	if (!creds) throw new Error("Not authenticated. Run `lmnr-cli login`.");
+	return {
+		bearer: (await refreshIfNeeded(creds)).accessToken,
+		baseUrl: resolveBaseUrl(opts.baseUrl),
+		port: opts.port ?? envHttpPort()
+	};
+}
+/**
+* Re-mint the access JWT when it's near expiry and persist it. A 401 from the
+* token endpoint means the session is gone — surface a clear "run login" error.
+*
+* Logout race guard: we write credentials ONLY when we actually re-minted. The
+* old code unconditionally rewrote the file (just to bump lastUsedAt) on every
+* command, so a concurrent `logout` that deleted the file mid-flight could have
+* its delete clobbered by this in-flight atomic rename — logout would appear to
+* succeed while tokens remained on disk. For a fresh (not-near-expiry) token we
+* now do no write at all, eliminating that window for the common case.
+*/
+async function refreshIfNeeded(creds) {
+	const expMs = new Date(creds.accessTokenExpiresAt).getTime();
+	if (!(!Number.isFinite(expMs) || expMs - Date.now() <= REFRESH_SKEW_MS)) return creds;
+	const next = { ...creds };
+	try {
+		const jwt = await mintAccessJwt(creds.issuer, creds.sessionToken);
+		next.accessToken = jwt;
+		next.accessTokenExpiresAt = decodeJwtExp(jwt) ?? (/* @__PURE__ */ new Date()).toISOString();
+	} catch (e) {
+		if (e instanceof DeviceFlowError && e.code === "invalid_grant") throw new Error("Session expired — run `lmnr-cli login`.");
+		throw e;
+	}
+	next.lastUsedAt = (/* @__PURE__ */ new Date()).toISOString();
+	await writeCredentials(next);
+	return next;
+}
+//#endregion
+//#region src/auth/client.ts
+/**
+* Build a LaminarClient for CLI commands. Auth is user-token only: the bearer
+* is the stored BetterAuth access JWT (auto-refreshed near expiry) and requests
+* route to `/v1/cli/*` with the resolved project in `x-lmnr-project-id`.
+*/
+async function buildLaminarClient(opts) {
+	const auth = await resolveAuth(opts);
+	return new LaminarClient({
+		baseUrl: auth.baseUrl,
+		port: auth.port,
+		auth: {
+			type: "userToken",
+			token: auth.bearer,
+			projectId: auth.projectId
+		}
+	});
+}
+//#endregion
+//#region src/auth/with-client.ts
+const logger$4 = initializeLogger();
+const defaultExitCode = () => 1;
+/**
+* Pull the commander positionals out of an `.action(...)` argument list.
+* Commander invokes the handler as `(arg1, ..., argN, options, command)`, so
+* the positionals are everything except the trailing `(options, command)`.
+*/
+function splitCommanderArgs(cmdArgs) {
+	const command = cmdArgs.at(-1);
+	return {
+		positionals: cmdArgs.slice(0, -2),
+		command,
+		opts: command.optsWithGlobals()
+	};
+}
+/**
+* The error envelope shared by both wrappers: in `--json` mode emit a structured
+* error line and exit with the mapped code; otherwise log and exit. Owning this
+* here lets handlers stay pure `(client, ...args) => work` with no try/catch.
+*/
+function runWithEnvelope(work, opts, exitCodeFor) {
+	return work().catch((error) => {
+		const code = exitCodeFor(error);
+		if (opts.json) outputJsonError(error, code);
+		logger$4.error(errorMessage(error));
+		process.exit(code);
+	});
+}
+/**
+* Wrap a project-scoped command handler. Resolves a user-token
+* {@link LaminarClient} (routes to `/v1/cli/*` with the resolved project),
+* threads the commander positionals + options through, and owns the error
+* envelope.
+*
+* @example
+*   sqlCmd.command("query")
+*     .argument("<query>")
+*     .action(withProjectClient(handleSqlQuery)); // (client, query, opts) => work
+*/
+const withProjectClient = (action, exitCodeFor = defaultExitCode) => async (...cmdArgs) => {
+	const { positionals, opts } = splitCommanderArgs(cmdArgs);
+	await runWithEnvelope(async () => {
+		await action(await buildLaminarClient({
+			projectId: opts.projectId,
+			baseUrl: opts.baseUrl,
+			port: opts.port
+		}), ...positionals, opts);
+	}, opts, exitCodeFor);
+};
+/**
+* Wrap a discovery command handler. Resolves a user-token
+* {@link LaminarClient} with NO project (the discovery surface — e.g. listing
+* projects — runs before a project is selected), threads positionals +
+* options, and owns the error envelope.
+*/
+const withUserToken = (action, exitCodeFor = defaultExitCode) => async (...cmdArgs) => {
+	const { positionals, opts } = splitCommanderArgs(cmdArgs);
+	await runWithEnvelope(async () => {
+		const token = await resolveUserToken({
+			baseUrl: opts.baseUrl,
+			port: opts.port
+		});
+		await action(new LaminarClient({
+			baseUrl: token.baseUrl,
+			port: token.port,
+			auth: {
+				type: "userToken",
+				token: token.bearer,
+				projectId: ""
+			}
+		}), ...positionals, opts);
+	}, opts, exitCodeFor);
+};
+//#endregion
+//#region src/utils/file.ts
+const logger$3 = initializeLogger();
+/**
+* Check if a file has a supported extension.
+*/
+const isSupportedFile = (file) => {
+	const ext = path.extname(file).toLowerCase();
+	return [
+		".json",
+		".csv",
+		".jsonl"
+	].includes(ext);
+};
+/**
+* Collect all supported files from the given paths.
+* Handles both files and directories.
+*/
+const collectFiles = async (paths, recursive = false) => {
+	const collectedFiles = [];
+	for (const filepath of paths) try {
+		const stats = await fs_promises.stat(filepath);
+		if (stats.isFile()) if (isSupportedFile(filepath)) collectedFiles.push(filepath);
+		else logger$3.warn(`Skipping unsupported file type: ${filepath}`);
+		else if (stats.isDirectory()) {
+			const entries = await fs_promises.readdir(filepath);
+			for (const entry of entries) {
+				const fullPath = path.join(filepath, entry);
+				const entryStats = await fs_promises.stat(fullPath);
+				if (entryStats.isFile() && isSupportedFile(fullPath)) collectedFiles.push(fullPath);
+				else if (recursive && entryStats.isDirectory()) {
+					const subFiles = await collectFiles([fullPath], true);
+					collectedFiles.push(...subFiles);
+				}
+			}
+		}
+	} catch (error) {
+		logger$3.warn(`Path does not exist or is not accessible: ${filepath}. Error: ${errorMessage(error)}`);
+	}
+	return collectedFiles;
+};
+/**
+* Read a JSON file and return its contents.
+*/
+const readJsonFile = async (filepath) => {
+	const content = await fs_promises.readFile(filepath, "utf-8");
+	const parsed = JSON.parse(content);
+	return Array.isArray(parsed) ? parsed : [parsed];
+};
+/**
+* Try to parse a string as JSON. If it fails, return the original string.
+*/
+const tryParseJson = (content) => {
+	if (typeof content !== "string") return content;
+	const trimmed = content.trim();
+	if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) return content;
+	try {
+		return JSON.parse(content);
+	} catch (error) {
+		logger$3.debug(`Error parsing JSON: ${errorMessage(error)}`);
+		return content;
+	}
+};
+/**
+* Parse each field in a CSV row, attempting to convert JSON strings back to objects.
+*/
+const parseCsvRow = (row) => {
+	const parsed = {};
+	for (const [key, value] of Object.entries(row)) parsed[key] = tryParseJson(value);
+	return parsed;
+};
+/**
+* Read a CSV file and return its contents as an array of objects.
+*/
+const readCsvFile = async (filepath) => new Promise((resolve, reject) => {
+	const results = [];
+	(0, fs.createReadStream)(filepath).pipe((0, csv_parser.default)()).on("data", (data) => results.push(parseCsvRow(data))).on("end", () => resolve(results)).on("error", reject);
+});
+/**
+* Read a JSONL file and return its contents as an array of objects.
+*/
+async function readJsonlFile(filepath) {
+	return (await fs_promises.readFile(filepath, "utf-8")).split("\n").filter((line) => line.trim()).map((line) => JSON.parse(line));
+}
+/**
+* Read a single file and return its contents.
+*/
+async function readFile$1(filepath) {
+	const ext = path.extname(filepath).toLowerCase();
 	if (ext === ".json") return readJsonFile(filepath);
 	else if (ext === ".csv") return readCsvFile(filepath);
 	else if (ext === ".jsonl") return readJsonlFile(filepath);
@@ -1118,17 +1738,17 @@ async function readFile(filepath) {
 const loadFromPaths = async (paths, recursive = false) => {
 	const files = await collectFiles(paths, recursive);
 	if (files.length === 0) {
-		logger$5.warn("No supported files found in the specified paths");
+		logger$3.warn("No supported files found in the specified paths");
 		return [];
 	}
-	logger$5.info(`Found ${files.length} file(s) to read`);
+	logger$3.info(`Found ${files.length} file(s) to read`);
 	const result = [];
 	for (const file of files) try {
-		const data = await readFile(file);
+		const data = await readFile$1(file);
 		result.push(...data);
-		logger$5.info(`Read ${data.length} record(s) from ${file}`);
+		logger$3.info(`Read ${data.length} record(s) from ${file}`);
 	} catch (error) {
-		logger$5.error(`Error reading file ${file}: ${error instanceof Error ? error.message : String(error)}`);
+		logger$3.error(`Error reading file ${file}: ${errorMessage(error)}`);
 		throw error;
 	}
 	return result;
@@ -1168,7 +1788,7 @@ const writeToFile = async (filepath, data, format) => {
 	const dir = path.dirname(filepath);
 	await fs_promises.mkdir(dir, { recursive: true });
 	const ext = format ?? path.extname(filepath).slice(1);
-	if (format && format !== path.extname(filepath).slice(1)) logger$5.warn(`Output format ${format} does not match file extension ${path.extname(filepath).slice(1)}`);
+	if (format && format !== path.extname(filepath).slice(1)) logger$3.warn(`Output format ${format} does not match file extension ${path.extname(filepath).slice(1)}`);
 	if (ext === "json") await writeJsonFile(filepath, data);
 	else if (ext === "csv") await writeCsvFile(filepath, data);
 	else if (ext === "jsonl") await writeJsonlFile(filepath, data);
@@ -1193,7 +1813,7 @@ const printToConsole = (data, format = "json") => {
 	if (format === "json") console.log(JSON.stringify(data, null, 2));
 	else if (format === "csv") {
 		if (data.length === 0) {
-			logger$5.error("No data to print");
+			logger$3.error("No data to print");
 			return;
 		}
 		console.log(formatCsv(data));
@@ -1201,23 +1821,6 @@ const printToConsole = (data, format = "json") => {
 	else throw new Error(`Unsupported output format: ${String(format)}. (supported formats: json, csv, jsonl)`);
 };
 //#endregion
-//#region src/utils/output.ts
-/**
-* Write structured JSON to stdout. Use this for machine-readable output
-* when --json is set.
-*/
-function outputJson(data) {
-	console.log(JSON.stringify(data));
-}
-/**
-* Write a JSON error to stdout and exit with code 1.
-* Use this in --json mode so agents can parse the failure.
-*/
-function outputJsonError(error, exitCode = 1) {
-	console.log(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
-	process.exit(exitCode);
-}
-//#endregion
 //#region src/utils/table.ts
 const DEFAULT_TERMINAL_WIDTH = 80;
 const PADDING_RIGHT = 2;
@@ -1280,9 +1883,14 @@ function renderTable(head, rows) {
 }
 //#endregion
 //#region src/commands/dataset/index.ts
-const logger$4 = initializeLogger();
+const logger$2 = initializeLogger();
 const DEFAULT_DATASET_PULL_BATCH_SIZE = 100;
 const DEFAULT_DATASET_PUSH_BATCH_SIZE = 100;
+/** Throw on the name/id mutual-exclusion rule. The wrapper renders the error. */
+function requireSingleIdentifier(opts) {
+	if (!opts.name && !opts.id) throw new Error("Either name or id must be provided");
+	if (opts.name && opts.id) throw new Error("Only one of name or id must be provided");
+}
 /**
 * Pull all data from a dataset in batches.
 */
@@ -1307,1242 +1915,985 @@ const pullAllData = async (client, identifier, batchSize = DEFAULT_DATASET_PULL_
 	return result;
 };
 /**
-* Handle datasets list command.
+* Handle datasets list command. Pure handler — `withProjectClient` resolves the
+* client and owns the error envelope.
 */
-const handleDatasetsList = async (options) => {
-	const client = new LaminarClient({
-		projectApiKey: options.projectApiKey,
-		baseUrl: options.baseUrl,
-		port: options.port
+const handleDatasetsList = async (client, opts) => {
+	const datasets = await client.datasets.listDatasets();
+	if (opts.json) {
+		outputJson(datasets);
+		return;
+	}
+	if (datasets.length === 0) {
+		console.log("No datasets found.");
+		return;
+	}
+	const rows = datasets.map((dataset) => {
+		const createdAtStr = new Date(dataset.createdAt).toISOString().replace("T", " ").substring(0, 19);
+		return [
+			dataset.id,
+			createdAtStr,
+			dataset.name
+		];
 	});
-	try {
-		const datasets = await client.datasets.listDatasets();
-		if (options.json) {
-			outputJson(datasets);
-			return;
-		}
-		if (datasets.length === 0) {
-			console.log("No datasets found.");
-			return;
-		}
-		const rows = datasets.map((dataset) => {
-			const createdAtStr = new Date(dataset.createdAt).toISOString().replace("T", " ").substring(0, 19);
-			return [
-				dataset.id,
-				createdAtStr,
-				dataset.name
-			];
-		});
-		console.log(renderTable([
-			"ID",
-			"Created At",
-			"Name"
-		], rows));
-		console.log(`\nTotal: ${datasets.length} dataset(s)\n`);
-	} catch (error) {
-		if (options.json) outputJsonError(error);
-		logger$4.error(`Failed to list datasets: ${error instanceof Error ? error.message : String(error)}`);
-		process.exit(1);
-	}
+	console.log(renderTable([
+		"ID",
+		"Created At",
+		"Name"
+	], rows));
+	console.log(`\nTotal: ${datasets.length} dataset(s)\n`);
 };
 /**
 * Handle datasets push command.
 */
-const handleDatasetsPush = async (paths, options) => {
-	if (!options.name && !options.id) {
-		if (options.json) outputJsonError("Either name or id must be provided");
-		logger$4.error("Either name or id must be provided");
-		process.exit(1);
-	}
-	if (options.name && options.id) {
-		if (options.json) outputJsonError("Only one of name or id must be provided");
-		logger$4.error("Only one of name or id must be provided");
-		process.exit(1);
-	}
-	const client = new LaminarClient({
-		projectApiKey: options.projectApiKey,
-		baseUrl: options.baseUrl,
-		port: options.port
+const handleDatasetsPush = async (client, paths, opts) => {
+	requireSingleIdentifier(opts);
+	const data = await loadFromPaths(paths, opts.recursive);
+	if (data.length === 0) throw new Error("No data to push");
+	const identifier = opts.name ? { name: opts.name } : { id: opts.id };
+	const result = await client.datasets.push({
+		points: data,
+		...identifier,
+		batchSize: opts.batchSize ?? DEFAULT_DATASET_PUSH_BATCH_SIZE
 	});
-	try {
-		const data = await loadFromPaths(paths, options.recursive);
-		if (data.length === 0) {
-			if (options.json) outputJsonError("No data to push");
-			logger$4.error("No data to push. Skipping");
-			process.exit(1);
-		}
-		const identifier = options.name ? { name: options.name } : { id: options.id };
-		const result = await client.datasets.push({
-			points: data,
-			...identifier,
-			batchSize: options.batchSize ?? DEFAULT_DATASET_PUSH_BATCH_SIZE
+	if (opts.json) {
+		outputJson({
+			datasetId: result?.datasetId,
+			count: data.length
 		});
-		if (options.json) {
-			outputJson({
-				datasetId: result?.datasetId,
-				count: data.length
-			});
-			return;
-		}
-		logger$4.info(`Pushed ${data.length} data points to dataset ${options.name || options.id}`);
-	} catch (error) {
-		if (options.json) outputJsonError(error);
-		logger$4.error(`Failed to push dataset: ${error instanceof Error ? error.message : String(error)}`);
-		process.exit(1);
+		return;
 	}
+	logger$2.info(`Pushed ${data.length} data points to dataset ${opts.name || opts.id}`);
 };
 /**
 * Handle datasets pull command.
 */
-const handleDatasetsPull = async (outputPath, options) => {
-	if (!options.name && !options.id) {
-		if (options.json) outputJsonError("Either name or id must be provided");
-		logger$4.error("Either name or id must be provided");
-		process.exit(1);
-	}
-	if (options.name && options.id) {
-		if (options.json) outputJsonError("Only one of name or id must be provided");
-		logger$4.error("Only one of name or id must be provided");
-		process.exit(1);
-	}
-	const client = new LaminarClient({
-		projectApiKey: options.projectApiKey,
-		baseUrl: options.baseUrl,
-		port: options.port
-	});
-	const identifier = options.name ? { name: options.name } : { id: options.id };
-	try {
-		const result = await pullAllData(client, identifier, options.batchSize ?? DEFAULT_DATASET_PULL_BATCH_SIZE, options.offset ?? 0, options.limit);
-		if (outputPath) {
-			await writeToFile(outputPath, result, options.outputFormat);
-			if (options.json) outputJson({
-				path: outputPath,
-				count: result.length
-			});
-			else logger$4.info(`Successfully pulled ${result.length} data points to ${outputPath}`);
-		} else if (options.json) outputJson(result);
-		else printToConsole(result, options.outputFormat ?? "json");
-	} catch (error) {
-		if (options.json) outputJsonError(error);
-		logger$4.error(`Failed to pull dataset: ${error instanceof Error ? error.message : String(error)}`);
-		process.exit(1);
-	}
+const handleDatasetsPull = async (client, outputPath, opts) => {
+	requireSingleIdentifier(opts);
+	const result = await pullAllData(client, opts.name ? { name: opts.name } : { id: opts.id }, opts.batchSize ?? DEFAULT_DATASET_PULL_BATCH_SIZE, opts.offset ?? 0, opts.limit);
+	if (outputPath) {
+		await writeToFile(outputPath, result, opts.outputFormat);
+		if (opts.json) outputJson({
+			path: outputPath,
+			count: result.length
+		});
+		else logger$2.info(`Successfully pulled ${result.length} data points to ${outputPath}`);
+	} else if (opts.json) outputJson(result);
+	else printToConsole(result, opts.outputFormat ?? "json");
 };
 /**
 * Handle datasets create command.
 */
-const handleDatasetsCreate = async (name, paths, options) => {
-	const client = new LaminarClient({
-		projectApiKey: options.projectApiKey,
-		baseUrl: options.baseUrl,
-		port: options.port
+const handleDatasetsCreate = async (client, name, paths, opts) => {
+	const data = await loadFromPaths(paths, opts.recursive);
+	if (data.length === 0) throw new Error("No data to push");
+	logger$2.info(`Pushing ${data.length} data points to dataset '${name}'...`);
+	await client.datasets.push({
+		points: data,
+		name,
+		batchSize: opts.batchSize ?? DEFAULT_DATASET_PUSH_BATCH_SIZE,
+		createDataset: true
 	});
-	try {
-		const data = await loadFromPaths(paths, options.recursive);
-		if (data.length === 0) {
-			if (options.json) outputJsonError("No data to push");
-			logger$4.error("No data to push. Skipping");
-			process.exit(1);
+	logger$2.info(`Successfully pushed ${data.length} data points to dataset '${name}'`);
+	logger$2.info(`Pulling data from dataset '${name}'...`);
+	const result = await pullAllData(client, { name }, opts.batchSize ?? DEFAULT_DATASET_PULL_BATCH_SIZE, 0, void 0);
+	await writeToFile(opts.outputFile, result, opts.outputFormat);
+	if (opts.json) outputJson({
+		name,
+		path: opts.outputFile,
+		count: result.length
+	});
+	else logger$2.info(`Successfully created dataset '${name}' and saved ${result.length} datapoints to ${opts.outputFile}`);
+};
+//#endregion
+//#region src/utils/trace-note.ts
+const NOTE_METADATA_KEY = "rollout.note";
+/**
+* Normalize a user-supplied trace id (UUID or 32-char OTel hex, optionally
+* 0x-prefixed) to the dashed UUID form used by the SQL endpoint. Throws on
+* anything else so a typo fails loudly instead of querying nothing.
+*/
+const normalizeTraceId = (traceId) => {
+	const id = traceId.trim().toLowerCase().replace(/^0x/, "");
+	if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(id)) return id;
+	if (/^[0-9a-f]{32}$/.test(id)) return id.replace(/^([0-9a-f]{8})([0-9a-f]{4})([0-9a-f]{4})([0-9a-f]{4})([0-9a-f]{12})$/, "$1-$2-$3-$4-$5");
+	throw new Error(`Invalid trace id "${traceId}". Expected a UUID or a 32-char OTel hex trace id.`);
+};
+/**
+* Extract the note from a trace's `metadata` column as returned by the SQL
+* endpoint (a JSON string; tolerate an already-parsed object too). Missing /
+* malformed metadata reads as "no note".
+*/
+const readNoteFromMetadata = (metadata) => {
+	let parsed = metadata;
+	if (typeof metadata === "string") {
+		if (metadata === "") return "";
+		try {
+			parsed = JSON.parse(metadata);
+		} catch {
+			return "";
 		}
-		logger$4.info(`Pushing ${data.length} data points to dataset '${name}'...`);
-		await client.datasets.push({
-			points: data,
-			name,
-			batchSize: options.batchSize ?? DEFAULT_DATASET_PUSH_BATCH_SIZE,
-			createDataset: true
-		});
-		logger$4.info(`Successfully pushed ${data.length} data points to dataset '${name}'`);
-	} catch (error) {
-		if (options.json) outputJsonError(error);
-		logger$4.error(`Failed to create dataset: ${error instanceof Error ? error.message : String(error)}`);
-		process.exit(1);
-	}
-	logger$4.info(`Pulling data from dataset '${name}'...`);
-	try {
-		const result = await pullAllData(client, { name }, options.batchSize ?? DEFAULT_DATASET_PULL_BATCH_SIZE, 0, void 0);
-		await writeToFile(options.outputFile, result, options.outputFormat);
-		if (options.json) outputJson({
-			name,
-			path: options.outputFile,
-			count: result.length
-		});
-		else logger$4.info(`Successfully created dataset '${name}' and saved ${result.length} datapoints to ${options.outputFile}`);
-	} catch (error) {
-		if (options.json) outputJsonError(error);
-		logger$4.error(`Failed to pull dataset after creation: ${error instanceof Error ? error.message : String(error)}`);
-		process.exit(1);
 	}
+	if (typeof parsed !== "object" || parsed === null) return "";
+	const note = parsed[NOTE_METADATA_KEY];
+	return typeof note === "string" ? note : "";
 };
 //#endregion
-//#region src/cache-server.ts
-const DEFAULT_START_PORT = 35667;
+//#region src/commands/debug/index.ts
+const logger$1 = initializeLogger();
 /**
-* Finds an available port starting from the given port number
+* Upsert the display name of a debug session. Update-only on the backend: a
+* session id unknown to the project 404s rather than creating a ghost session.
+*
+* Pure handler: the command wrapper (`withProjectClient`) resolves a user-token
+* {@link LaminarClient} (routes to `/v1/cli/*` with the resolved project) and
+* owns the error envelope.
 */
-async function findAvailablePort(startPort) {
-	return new Promise((resolve, reject) => {
-		const server = http.createServer();
-		server.listen(startPort, () => {
-			const port = server.address().port;
-			server.close(() => resolve(port));
-		});
-		server.on("error", (err) => {
-			if (err.code === "EADDRINUSE") resolve(findAvailablePort(startPort + 1));
-			else reject(err);
-		});
+const handleDebugSessionSetName = async (client, sessionId, name, opts) => {
+	await client.rolloutSessions.setName({
+		sessionId,
+		name
 	});
-}
+	if (opts.json) {
+		outputJson({
+			sessionId,
+			name
+		});
+		return;
+	}
+	logger$1.info(`Set name of session ${sessionId} to "${name}".`);
+};
 /**
-* Parses request body as JSON
+* Print a per-trace summary of a debug session: every trace whose metadata
+* groups it to the session (`rollout.session_id`), oldest first, with the
+* agent-authored note (`rollout.note`) attached to each.
+*
+* Pure handler: the command wrapper (`withProjectClient`) resolves a user-token
+* {@link LaminarClient} (routes to `/v1/cli/*` with the resolved project) and
+* owns the error envelope.
 */
-function parseBody(req) {
-	return new Promise((resolve, reject) => {
-		let body = "";
-		req.on("data", (chunk) => {
-			body += chunk.toString();
-		});
-		req.on("end", () => {
-			try {
-				resolve(body ? JSON.parse(body) : {});
-			} catch (err) {
-				reject(/* @__PURE__ */ new Error(`Invalid JSON: ${err instanceof Error ? err.message : String(err)}`));
-			}
-		});
-		req.on("error", reject);
+const handleDebugSessionSummary = async (client, sessionId, opts) => {
+	const traces = (await client.sql.query("SELECT id, formatDateTime(end_time, '%Y-%m-%dT%H:%i:%S.%fZ') AS end_time, metadata FROM traces WHERE simpleJSONExtractString(metadata, 'rollout.session_id') = {session_id:String} ORDER BY start_time", { session_id: sessionId })).map((row) => ({
+		note: readNoteFromMetadata(row.metadata),
+		traceId: String(row.id ?? ""),
+		endTime: String(row.end_time ?? "")
+	}));
+	if (opts.json) {
+		outputJson(traces);
+		return;
+	}
+	if (traces.length === 0) {
+		console.log(`No traces found for session ${sessionId}.`);
+		return;
+	}
+	const blocks = traces.map((trace) => {
+		const tag = `<trace id="${trace.traceId}" end-time="${trace.endTime}"/>`;
+		return trace.note ? `${trace.note}\n${tag}` : tag;
 	});
+	console.log(blocks.join("\n\n"));
+};
+//#endregion
+//#region src/utils/colors.ts
+function enabledFor(stream) {
+	if ("NO_COLOR" in process.env) return false;
+	if ("FORCE_COLOR" in process.env && process.env.FORCE_COLOR !== "0") return true;
+	return Boolean(stream.isTTY);
 }
-/**
-* Starts a local cache server for storing and retrieving cached LLM responses
-* during rollout debugging sessions.
-*
-* @param startPort - Optional starting port number (defaults to 35667)
-* @returns Server information including port, server instance, cache, and metadata setter
-*/
-async function startCacheServer(startPort = DEFAULT_START_PORT) {
-	const cache = /* @__PURE__ */ new Map();
-	let metadata = {
-		pathToCount: {},
-		overrides: void 0
-	};
-	const server = http.createServer((req, res) => {
-		(async () => {
-			res.setHeader("Access-Control-Allow-Origin", "*");
-			res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
-			res.setHeader("Access-Control-Allow-Headers", "Content-Type");
-			if (req.method === "OPTIONS") {
-				res.writeHead(200);
-				res.end();
-				return;
-			}
-			if (req.method === "GET" && req.url === "/health") {
-				res.writeHead(200, { "Content-Type": "application/json" });
-				res.end(JSON.stringify({ status: "ok" }));
-				return;
-			}
-			if (req.method === "POST" && req.url === "/cached") {
-				try {
-					const { path, index } = await parseBody(req);
-					if (typeof path !== "string" || typeof index !== "number") {
-						res.writeHead(400, { "Content-Type": "application/json" });
-						res.end(JSON.stringify({ error: "Invalid request: path (string) and index (number) required" }));
-						return;
-					}
-					const cacheKey = `${index}:${path}`;
-					const response = {
-						span: cache.get(cacheKey),
-						pathToCount: metadata.pathToCount,
-						overrides: metadata.overrides
-					};
-					res.writeHead(200, { "Content-Type": "application/json" });
-					res.end(JSON.stringify(response));
-				} catch (err) {
-					res.writeHead(400, { "Content-Type": "application/json" });
-					res.end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
-				}
-				return;
-			}
-			res.writeHead(404, { "Content-Type": "application/json" });
-			res.end(JSON.stringify({ error: "Not found" }));
-		})().catch((error) => {
-			if (!res.headersSent) {
-				res.writeHead(500, { "Content-Type": "application/json" });
-				res.end(JSON.stringify({ error: error instanceof Error ? error.message : "Internal server error" }));
-			}
-		});
+const pc = (0, picocolors.createColors)(enabledFor(process.stderr));
+const pcOut = (0, picocolors.createColors)(enabledFor(process.stdout));
+const stderrColorEnabled = enabledFor(process.stderr);
+const orange = (text) => stderrColorEnabled ? `\x1b[38;2;208;117;78m${text}\x1b[39m` : text;
+//#endregion
+//#region src/commands/login/index.ts
+async function handleLogin(options) {
+	const issuer = pick$1(options.frontendUrl, process.env.LMNR_FRONTEND_URL, DEFAULT_FRONTEND_URL$1);
+	const da = await initiateDevice(issuer, CLI_SCOPE);
+	const completeUri = da.verification_uri_complete ?? da.verification_uri;
+	process.stderr.write(`\nOpen this URL in your browser to authorize:\n  ${pc.cyan(completeUri)}\n`);
+	if (da.user_code) process.stderr.write(`Code: ${pc.bold(pc.cyan(da.user_code))}\n\n`);
+	if (!options.noBrowser) try {
+		await (0, open.default)(completeUri);
+	} catch {}
+	process.stderr.write(pc.dim("Waiting for authorization...\n"));
+	const token = await pollDevice(issuer, da.device_code, {
+		intervalSeconds: da.interval,
+		timeoutSeconds: da.expires_in
 	});
-	const port = await findAvailablePort(startPort);
-	return new Promise((resolve, reject) => {
-		server.listen(port, () => {
-			resolve({
-				port,
-				server,
-				cache,
-				setMetadata: (newMetadata) => {
-					metadata = newMetadata;
-				}
-			});
-		});
-		server.on("error", reject);
+	const sessionToken = token.access_token;
+	const jwt = await mintAccessJwt(issuer, sessionToken);
+	const session = await fetchSession(issuer, sessionToken);
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	await writeCredentials({
+		version: 1,
+		issuer,
+		sessionToken,
+		accessToken: jwt,
+		accessTokenExpiresAt: decodeJwtExp(jwt) ?? now,
+		sessionExpiresAt: typeof token.expires_in === "number" ? new Date(Date.now() + token.expires_in * 1e3).toISOString() : void 0,
+		userEmail: session.email || void 0,
+		userId: session.id,
+		createdAt: now,
+		lastUsedAt: now
 	});
+	return {
+		userId: session.id,
+		userEmail: session.email || null,
+		projectId: parseProjectFromMetadata(token.metadata)
+	};
+}
+function pick$1(...candidates) {
+	for (const c of candidates) if (c && c.length > 0) return c;
+	return "";
 }
 //#endregion
-//#region src/sse-client.ts
-const HEARTBEAT_INTERVAL = 5e3;
-const MAX_MISSED_HEARTBEATS = 3;
-/**
-* SSE client for rollout debugging sessions
-* Connects to the Laminar backend and listens for run events
-*/
-var SSEClient = class extends events.EventEmitter {
-	constructor(options) {
-		super();
-		this.lastHeartbeat = Date.now();
-		this.isShutdown = false;
-		this.client = options.client;
-		this.sessionId = options.sessionId;
-		this.params = options.params;
-		this.name = options.name;
-	}
-	/**
-	* Connects to the SSE endpoint
-	*/
-	async connectAndListen() {
-		if (this.isShutdown) return;
-		this.abortController = new AbortController();
-		this.lastHeartbeat = Date.now();
-		try {
-			const response = await this.client.rolloutSessions.connect({
-				sessionId: this.sessionId,
-				params: this.params,
-				signal: this.abortController.signal,
-				name: this.name
-			});
-			this.emit("connected");
-			this.startHeartbeatCheck();
-			await this.parseSSEStream(response.body);
-		} catch (error) {
-			if (error.name === "AbortError") return;
-			this.emit("error", error);
-			if (!this.isShutdown) this.scheduleReconnect();
-		}
-	}
-	/**
-	* Parses SSE stream and emits events
-	*/
-	async parseSSEStream(body) {
-		const reader = body.getReader();
-		const decoder = new TextDecoder();
-		const parser = (0, eventsource_parser.createParser)({ onEvent: (event) => {
-			this.processSSEEvent(event);
-		} });
-		try {
-			while (true) {
-				const { done, value } = await reader.read();
-				if (done) break;
-				const chunk = decoder.decode(value, { stream: true });
-				parser.feed(chunk);
-			}
-		} finally {
-			reader.releaseLock();
-		}
-		if (!this.isShutdown) this.scheduleReconnect();
-	}
-	/**
-	* Processes a parsed SSE event
-	*/
-	processSSEEvent(event) {
-		if (!event.data) return;
-		try {
-			if (event.event === "heartbeat") {
-				this.lastHeartbeat = Date.now();
-				this.emit("heartbeat");
-			} else if (event.event === "run") {
-				const runEvent = {
-					event_type: "run",
-					data: JSON.parse(event.data)
-				};
-				this.emit("run", runEvent);
-			} else if (event.event === "handshake") {
-				const handshakeEvent = {
-					event_type: "handshake",
-					data: JSON.parse(event.data)
-				};
-				this.emit("handshake", handshakeEvent);
-			} else if (event.event === "stop") this.emit("stop");
-		} catch (error) {
-			this.emit("error", /* @__PURE__ */ new Error(`Failed to parse SSE event data: ${error}`));
-		}
-	}
-	/**
-	* Starts checking for missed heartbeats
-	*/
-	startHeartbeatCheck() {
-		this.stopHeartbeatCheck();
-		this.heartbeatCheckTimer = setInterval(() => {
-			if (Date.now() - this.lastHeartbeat > HEARTBEAT_INTERVAL * MAX_MISSED_HEARTBEATS) {
-				this.emit("heartbeat_timeout");
-				this.reconnect();
-			}
-		}, HEARTBEAT_INTERVAL);
-	}
-	/**
-	* Stops heartbeat checking
-	*/
-	stopHeartbeatCheck() {
-		if (this.heartbeatCheckTimer) {
-			clearInterval(this.heartbeatCheckTimer);
-			this.heartbeatCheckTimer = void 0;
-		}
-	}
-	/**
-	* Schedules a reconnection attempt
-	*/
-	scheduleReconnect() {
-		if (this.reconnectTimer || this.isShutdown) return;
-		this.emit("reconnecting");
-		this.reconnectTimer = setTimeout(() => {
-			this.reconnectTimer = void 0;
-			this.reconnect();
-		}, 1e3);
-	}
-	/**
-	* Reconnects to the SSE endpoint
-	*/
-	reconnect() {
-		this.disconnect(true);
-		this.connectAndListen().catch((error) => {
-			this.emit("error", error);
-		});
-	}
-	/**
-	* Disconnects from the SSE endpoint
-	*/
-	disconnect(stopReconnect = true) {
-		if (this.abortController) {
-			this.abortController.abort();
-			this.abortController = void 0;
-		}
-		this.stopHeartbeatCheck();
-		if (stopReconnect && this.reconnectTimer) {
-			clearTimeout(this.reconnectTimer);
-			this.reconnectTimer = void 0;
-		}
-	}
-	/**
-	* Updates the function metadata (params, name) and reconnects
-	*/
-	updateMetadata(params, name) {
-		this.params = params;
-		this.name = name;
-		this.reconnect();
-	}
-	/**
-	* Shuts down the SSE client gracefully
-	*/
-	shutdown() {
-		this.isShutdown = true;
-		this.disconnect(true);
-		this.emit("shutdown");
-		this.removeAllListeners();
-	}
-};
+//#region src/commands/logout/index.ts
 /**
-* Creates an SSE client (does not auto-connect)
-* Call client.connect() after registering event listeners
+* Best-effort server-side session revoke via POST /api/auth/sign-out with the
+* session token as Bearer. Logout MUST complete locally even if the server is
+* unreachable — the user expects "log me out" to remove the file. On any
+* failure we log to stderr and continue.
 */
-function createSSEClient(options) {
-	return new SSEClient(options);
+async function revokeSession(creds) {
+	if (!creds.sessionToken || creds.sessionToken.length === 0) return;
+	const url = `${trimSlash$2(creds.issuer)}/api/auth/sign-out`;
+	try {
+		const res = await fetch(url, {
+			method: "POST",
+			headers: {
+				authorization: `Bearer ${creds.sessionToken}`,
+				"content-type": "application/json"
+			},
+			body: "{}"
+		});
+		if (!res.ok) process.stderr.write(`warning: session revoke at ${url} returned ${res.status}; local credentials still removed.
+`);
+	} catch (e) {
+		const msg = e instanceof Error ? e.message : String(e);
+		process.stderr.write(`warning: session revoke at ${url} failed (${msg}); local credentials still removed.\n`);
+	}
+}
+async function handleLogout() {
+	const creds = await readCredentials();
+	if (!creds) {
+		process.stderr.write("Already logged out.\n");
+		return;
+	}
+	const label = creds.userEmail ?? creds.userId;
+	await deleteCredentials();
+	await revokeSession(creds);
+	process.stderr.write(`Logged out of ${label}. Removed ${credentialsPath()}.\n`);
+}
+function trimSlash$2(url) {
+	return url.replace(/\/+$/, "");
 }
 //#endregion
-//#region src/subprocess/executor.ts
-const logger$3 = initializeLogger();
+//#region src/commands/project/index.ts
 /**
-* Track and kill the currently running subprocess
+* List the projects the signed-in user can access (discovery — no project
+* scope). Pure handler: the `withUserToken` wrapper resolves the user-token
+* client and owns the error envelope.
 */
-var SubprocessManager = class {
-	constructor() {
-		this.currentProcess = null;
-	}
-	/**
-	* Execute a subprocess and track it
-	*/
-	async execute(options) {
-		const { command, args, config } = options;
-		const child = (0, child_process.spawn)(command, args, { stdio: [
-			"pipe",
-			"pipe",
-			"pipe"
-		] });
-		this.currentProcess = child;
-		return new Promise((resolve, reject) => {
-			const result = void 0;
-			let hasError = false;
-			readline.createInterface({
-				input: child.stdout,
-				crlfDelay: Infinity
-			}).on("line", (line) => {
-				if (line.startsWith("__LMNR_WORKER__:")) try {
-					const messageJson = line.substring(16);
-					const message = JSON.parse(messageJson);
-					switch (message.type) {
-						case "log":
-							logger$3[message.level](message.message);
-							break;
-						case "error":
-							hasError = true;
-							logger$3.error(`Worker error: ${message.error}`);
-							if (message.stack) logger$3.error(message.stack);
-							break;
-					}
-				} catch {
-					logger$3.debug("Failed to parse worker protocol message. Printing raw line");
-					console.log(line.substring(16));
-				}
-				else console.log(line);
-			});
-			child.stderr.on("data", (data) => {
-				process.stderr.write(data);
-			});
-			child.on("exit", (code, signal) => {
-				if (this.currentProcess?.pid === child.pid) this.currentProcess = null;
-				if (signal) reject(/* @__PURE__ */ new Error(`Worker terminated by signal: ${signal}`));
-				else if (code === 0) resolve(result);
-				else {
-					if (!hasError) logger$3.error(`Worker exited with code ${code}`);
-					reject(/* @__PURE__ */ new Error(`Worker exited with code ${code}`));
-				}
-			});
-			child.on("error", (error) => {
-				this.currentProcess = null;
-				reject(/* @__PURE__ */ new Error(`Failed to spawn worker: ${error.message}`));
-			});
-			child.stdin?.write(JSON.stringify(config) + "\n");
-			child.stdin?.end();
-		});
-	}
-	/**
-	* Kill the currently running subprocess
-	* @returns true if a process was killed, false if no process was running
-	*/
-	kill() {
-		if (this.currentProcess) {
-			const processToKill = this.currentProcess;
-			this.currentProcess.kill("SIGTERM");
-			setTimeout(() => {
-				if (processToKill && processToKill.exitCode === null) {
-					logger$3.warn("Child process did not terminate, using SIGKILL");
-					processToKill.kill("SIGKILL");
-				}
-			}, 5e3);
-			return true;
-		}
-		return false;
-	}
-	/**
-	* Check if a subprocess is currently running
-	*/
-	isRunning() {
-		return this.currentProcess !== null;
-	}
+const handleProjectsList = async (client, opts) => {
+	const projects = await client.cli.listProjects();
+	const linked = (await readProjectLink())?.projectId;
+	if (opts.json) {
+		outputJson(projects.map((p) => ({
+			...p,
+			linked: p.id === linked
+		})));
+		return;
+	}
+	if (projects.length === 0) {
+		console.log("No projects found. Create one in the dashboard, then run `lmnr-cli setup`.");
+		return;
+	}
+	const columns = [
+		"",
+		"Workspace",
+		"Project",
+		"Project ID"
+	];
+	const rows = projects.map((p) => [
+		p.id === linked ? "●" : "",
+		p.workspaceName,
+		p.name,
+		p.id
+	]);
+	console.log(renderTable(columns, rows));
+	console.log(linked ? "\n● = linked to this directory (lmnr-cli setup). Override per-command with --project-id.\n" : "\nNot linked here. Run `lmnr-cli setup` in your project directory, or pass --project-id.\n");
 };
 //#endregion
-//#region src/worker-registry.ts
-/**
-* Default workers mapped by file extension
-*/
-const DEFAULT_WORKERS = {
-	".ts": {
-		command: "node",
-		args: []
-	},
-	".cts": {
-		command: "node",
-		args: []
-	},
-	".mts": {
-		command: "node",
-		args: []
-	},
-	".tsx": {
-		command: "node",
-		args: []
-	},
-	".jsx": {
-		command: "node",
-		args: []
-	},
-	".js": {
-		command: "node",
-		args: []
-	},
-	".mjs": {
-		command: "node",
-		args: []
-	},
-	".cjs": {
-		command: "node",
-		args: []
-	},
-	".py": {
-		command: "python3",
-		args: ["-m", "lmnr.cli.worker"]
+//#region src/auth/project-id.ts
+function trimSlash$1(url) {
+	return url.replace(/\/+$/, "");
+}
+async function probeProjectKey(projectApiKey, baseUrl = DEFAULT_BASE_URL$1, port) {
+	const url = new URL(trimSlash$1(baseUrl));
+	if (port) url.port = String(port);
+	url.pathname = "/v1/project";
+	let res;
+	try {
+		res = await fetch(url.toString(), {
+			method: "GET",
+			headers: {
+				Authorization: `Bearer ${projectApiKey}`,
+				Accept: "application/json"
+			}
+		});
+	} catch {
+		return { status: "unverifiable" };
+	}
+	if (res.status === 401) return { status: "invalid" };
+	if (!res.ok) return { status: "unverifiable" };
+	const body = await res.json().catch(() => null);
+	return body?.projectId ? {
+		status: "ok",
+		projectId: body.projectId
+	} : { status: "unverifiable" };
+}
+//#endregion
+//#region src/utils/env-file.ts
+const execFileAsync = (0, node_util.promisify)(node_child_process.execFile);
+const DEFAULT_VAR_NAME = "LMNR_PROJECT_API_KEY";
+const CANDIDATE_FILES = [".env.local", ".env"];
+/**
+* Write/replace `<varName>=<value>` in the .env file at `envPath`.
+*
+* Semantics:
+* - If the file does not exist: create it with mode 0o600 and a single line.
+* - If the file exists:
+*   - Replace an existing `^<varName>\s*=.*` line in place (preserves comments,
+*     ordering, and other keys).
+*   - Otherwise append the line (with a leading newline if the file does not
+*     end in one).
+*   - DO NOT change the file mode on existing files — the user may have set
+*     a deliberate mode and changing it surprises them.
+* - Writes are atomic: write to `<envPath>.tmp`, then rename.
+*/
+async function writeEnvFile(envPath, value, varName = DEFAULT_VAR_NAME) {
+	if (!await fileExists(envPath)) {
+		await atomicWrite(envPath, `${varName}=${value}\n`, 384);
+		return {
+			path: envPath,
+			created: true,
+			replaced: false
+		};
 	}
-};
+	const original = await (0, node_fs_promises.readFile)(envPath, "utf-8");
+	const regex = new RegExp(`^${escapeRegex(varName)}\\s*=.*$`, "m");
+	let next;
+	let replaced = false;
+	if (regex.test(original)) {
+		next = original.replace(regex, `${varName}=${value}`);
+		replaced = true;
+	} else next = `${original.endsWith("\n") || original.length === 0 ? original : `${original}\n`}${varName}=${value}\n`;
+	const existingMode = (await (0, node_fs_promises.stat)(envPath)).mode & 511;
+	await atomicWrite(envPath, next, existingMode);
+	return {
+		path: envPath,
+		created: false,
+		replaced
+	};
+}
+/**
+* Read a single env var's value from a .env file. Returns null when the file
+* is missing, the var is absent, or its value is empty/whitespace.
+*/
+async function readEnvVar(envPath, varName = DEFAULT_VAR_NAME) {
+	if (!await fileExists(envPath)) return null;
+	const original = await (0, node_fs_promises.readFile)(envPath, "utf-8");
+	const regex = new RegExp(`^${escapeRegex(varName)}\\s*=(.*)$`, "m");
+	const match = original.match(regex);
+	if (!match) return null;
+	const value = match[1].trim().replace(/^["']|["']$/g, "");
+	return value.length > 0 ? value : null;
+}
 /**
-* Get the worker command for a given file path or module.
-* Resolves the TypeScript worker dynamically from @lmnr-ai/lmnr package.
+* Find an already-configured key, checking `process.env` → `.env.local` → `.env`
+* (first match wins, mirroring Next.js precedence). `process.env` comes first
+* because an exported var is what actually runs, regardless of language.
 */
-function getWorkerCommand(filePath, options) {
-	if (options?.pythonModule) return {
-		command: "python3",
-		args: ["-m", "lmnr.cli.worker"]
+async function findEnvKey(cwd, varName = DEFAULT_VAR_NAME) {
+	const fromProcess = process.env[varName]?.trim();
+	if (fromProcess) return {
+		value: fromProcess,
+		source: { type: "process-env" }
 	};
-	if (!filePath) throw new Error("Either filePath or pythonModule must be provided");
-	const ext = path.extname(filePath);
-	if (!DEFAULT_WORKERS[ext]) throw new Error(`Unsupported file extension: ${ext}. Supported extensions: ${Object.keys(DEFAULT_WORKERS).join(", ")}`);
-	const worker = DEFAULT_WORKERS[ext];
-	if ([
-		".ts",
-		".tsx",
-		".js",
-		".mjs",
-		".cjs",
-		".mts",
-		".cts",
-		".jsx"
-	].includes(ext)) try {
-		const workerPath = require.resolve("@lmnr-ai/lmnr/dist/cli/worker/index.cjs");
-		return {
-			command: worker.command,
-			args: [workerPath]
+	for (const name of CANDIDATE_FILES) {
+		const path = (0, node_path.resolve)(cwd, name);
+		const value = await readEnvVar(path, varName);
+		if (value) return {
+			value,
+			source: {
+				type: "file",
+				path
+			}
 		};
-	} catch (error) {
-		throw new Error(`Failed to resolve TypeScript/JavaScript worker from @lmnr-ai/lmnr package. Make sure @lmnr-ai/lmnr is installed. Error: ${error instanceof Error ? error.message : String(error)}`);
 	}
-	return worker;
+	return null;
 }
-//#endregion
-//#region src/commands/dev/metadata.ts
-const logger$2 = initializeLogger();
-const TS_JS_EXTENSIONS = [
-	".ts",
-	".tsx",
-	".js",
-	".mjs",
-	".cjs",
-	".jsx",
-	".mts",
-	".cts"
-];
-const EXTENSIONS_TO_DISCOVER_METADATA = [...TS_JS_EXTENSIONS, ".py"];
 /**
-* Protocol prefix for metadata discovery responses
-* This allows us to safely parse JSON even if there are other log statements in stdout
+* LMNR_* config keys the CLI hydrates from a project `.env.local` / `.env`.
+* Curated on purpose — we do NOT slurp the whole file, so unrelated app secrets
+* (model API keys, etc.) never enter the CLI process. Notable exclusions:
+*  - `LMNR_GRPC_PORT`: the CLI is REST-only (no gRPC), so it has no use for it.
+*  - `LMNR_LOG_LEVEL`: loggers are built at module-import time (before
+*    `loadLocalEnv` runs), so hydrating it here would silently have no effect.
+*  - `LMNR_PROJECT_ID`: the project comes from `--project-id` or
+*    `.lmnr/project.json` only; `resolveAuth` ignores the env var, so loading
+*    it here would just contradict that.
 */
-const METADATA_PROTOCOL_PREFIX = "LMNR_METADATA:";
-const logLmnrPackageNotFoundAndExit = () => {
-	logger$2.error("@lmnr-ai/lmnr package not found or outdated. For JS/TS projects, please install the latest version of @lmnr-ai/lmnr in your project: npm install @lmnr-ai/lmnr\nYou might need to run `lmnr-cli` from the root of your project");
-	process.exit(1);
-};
+const AUTOLOADED_ENV_KEYS = [
+	"LMNR_BASE_URL",
+	"LMNR_HTTP_PORT",
+	"LMNR_FRONTEND_URL"
+];
 /**
-* Discovers function metadata for TypeScript and JavaScript files by:
-* 1. Extracting TypeScript metadata (params with types from source - TS only)
-* 2. Building and loading the module with esbuild
-* 3. Selecting the appropriate function
-* 4. Matching metadata by span name
+* Hydrate `process.env` from `.env.local` / `.env` in `cwd` for the curated
+* {@link AUTOLOADED_ENV_KEYS}, WITHOUT overriding values already present in the
+* environment (a real exported var / Claude Code `settings.json` env always
+* wins — `findEnvKey` checks `process.env` first and we skip those).
 *
-* For JavaScript files, TypeScript metadata extraction fails gracefully, but runtime
-* parameter extraction via regex still works (param names without types).
-*/
-const discoverTypeScriptMetadata = async (filePath, options) => {
-	let extractRolloutFunctions;
-	let buildFile;
-	let loadModule;
-	let selectRolloutFunction;
-	try {
-		const lmnrPackage = "@lmnr-ai/lmnr";
-		const tsParserPath = require.resolve(`${lmnrPackage}/dist/cli/worker/ts-parser.cjs`);
-		const buildModulePath = require.resolve(`${lmnrPackage}/dist/cli/worker/build.cjs`);
-		delete require.cache[tsParserPath];
-		delete require.cache[buildModulePath];
-		extractRolloutFunctions = require(tsParserPath).extractRolloutFunctions;
-		const buildModule = require(buildModulePath);
-		buildFile = buildModule.buildFile;
-		loadModule = buildModule.loadModule;
-		selectRolloutFunction = buildModule.selectRolloutFunction;
-		if (!extractRolloutFunctions || !buildFile || !loadModule || !selectRolloutFunction) {
-			logger$2.error("Missing exports from @lmnr-ai/lmnr modules. This may indicate an outdated package version.");
-			logLmnrPackageNotFoundAndExit();
-		}
-	} catch (error) {
-		if (error.code === "MODULE_NOT_FOUND") logLmnrPackageNotFoundAndExit();
-		logger$2.error(`Unexpected error loading @lmnr-ai/lmnr modules: ${error.message}`);
-		throw error;
+* Why this exists: Claude Code and many other runners do NOT inject a project
+* `.env` into a spawned subprocess's environment, so self-hosters who put
+* `LMNR_BASE_URL` / `LMNR_HTTP_PORT` in `.env` previously had to export them or
+* pass flags on every call. cwd-only, no upward directory walk (mirrors
+* dotenv's default) — the CLI must be invoked from the dir holding the `.env`.
+*/
+async function loadLocalEnv(cwd, keys = AUTOLOADED_ENV_KEYS) {
+	for (const key of keys) {
+		const found = await findEnvKey(cwd, key);
+		if (found?.source.type === "file") process.env[key] = found.value;
 	}
-	let paramsMetadata;
+}
+/**
+* Pick the file to write a freshly-minted key into:
+*  - rewrite in place if the key already lives in a file,
+*  - else prefer an existing `.env.local` (its presence proves the project opted
+*    into the gitignored-secret convention) — but never CREATE one, since Python
+*    loaders ignore it,
+*  - else `.env` (the default every ecosystem loads).
+*/
+async function resolveEnvWriteTarget(cwd, existing) {
+	if (existing?.source.type === "file") return existing.source.path;
+	const local = (0, node_path.resolve)(cwd, ".env.local");
+	if (await fileExists(local)) return local;
+	return (0, node_path.resolve)(cwd, ".env");
+}
+/**
+* Whether `path` is gitignored. Returns null when it can't be determined (not a
+* git repo / git absent) so callers can stay silent rather than warn wrongly.
+*/
+async function isPathGitIgnored(path) {
 	try {
-		paramsMetadata = extractRolloutFunctions(filePath);
-		logger$2.debug(`Extracted TypeScript metadata for ${paramsMetadata?.size} functions`);
-	} catch (error) {
-		logger$2.warn("Failed to extract TypeScript metadata, falling back to runtime parsing: " + (error instanceof Error ? error.message : String(error)));
+		await execFileAsync("git", [
+			"check-ignore",
+			"-q",
+			path
+		]);
+		return true;
+	} catch (err) {
+		return err.code === 1 ? false : null;
 	}
-	const moduleText = await buildFile(filePath, {
-		externalPackages: options.externalPackages,
-		dynamicImportsToSkip: options.dynamicImportsToSkip
-	});
-	loadModule({
-		filename: filePath,
-		moduleText
-	});
-	const selectedFunction = selectRolloutFunction(options.function);
-	if (paramsMetadata) {
-		logger$2.debug(`Available TS metadata keys: ${Array.from(paramsMetadata.keys()).join(", ")}`);
-		logger$2.debug(`Looking for span name: ${selectedFunction.name} (runtime key: ${selectedFunction.exportName})`);
-		let foundMetadata = null;
-		for (const [exportName, metadata] of paramsMetadata.entries()) {
-			logger$2.debug(`Checking ${exportName}: span name = ${metadata.name}, export name = ${exportName}`);
-			if (metadata.name === selectedFunction.name) {
-				foundMetadata = metadata;
-				logger$2.debug(`Match. Export name: ${exportName}, span name: ${metadata.name}`);
-				break;
-			}
-		}
-		if (foundMetadata) {
-			selectedFunction.params = foundMetadata.params;
-			logger$2.debug(`Using TypeScript metadata for span: ${selectedFunction.name}`);
-		} else logger$2.info(`No TypeScript metadata found for span name: ${selectedFunction.name}`);
+}
+async function fileExists(path) {
+	try {
+		await (0, node_fs_promises.access)(path);
+		return true;
+	} catch {
+		return false;
 	}
-	return {
-		functionName: selectedFunction.name,
-		params: selectedFunction.params || []
-	};
-};
+}
+async function atomicWrite(path, contents, mode) {
+	const tmp = `${path}.tmp`;
+	await (0, node_fs_promises.writeFile)(tmp, contents, mode === void 0 ? void 0 : { mode });
+	await (0, node_fs_promises.rename)(tmp, path);
+}
+function escapeRegex(raw) {
+	return raw.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//#endregion
+//#region src/skill/laminar-skill.ts
+const SKILL_REPO = "lmnr-ai/lmnr-skills";
+const SKILL_REF = "main";
+const SKILL_NAME = "laminar";
 /**
-* Helper to execute subprocess commands
+* giget source for the pinned skill subdir: `github:<owner>/<repo>/<subdir>#<ref>`.
+* giget resolves this against codeload.github.com, gunzips, untars, strips the
+* `repo-<ref>/` prefix, and extracts only the subdir — all the mechanics we'd
+* otherwise hand-roll.
 */
-const execCommand = async (command, args) => new Promise((resolve, reject) => {
-	const { spawn } = require("child_process");
-	const child = spawn(command, args);
-	let stdout = "";
-	let stderr = "";
-	child.stdout.on("data", (data) => {
-		stdout += data.toString();
-	});
-	child.stderr.on("data", (data) => {
-		stderr += data.toString();
-	});
-	child.on("close", (code) => {
-		if (code === 0) resolve({
-			stdout,
-			stderr
-		});
-		else reject(/* @__PURE__ */ new Error(`Command failed with code ${code}: ${stderr}`));
-	});
-	child.on("error", (error) => {
-		reject(error);
-	});
-});
+function skillSource() {
+	return `github:${SKILL_REPO}/skills/${SKILL_NAME}#${SKILL_REF}`;
+}
+//#endregion
+//#region src/skill/fetch-skill.ts
 /**
-* Extracts JSON metadata from stdout that may contain other log statements
-* Looks for lines matching the protocol prefix and parses the JSON payload
+* Download the pinned Laminar skill subtree into `dir` using giget.
+*
+* giget owns every quirk we'd otherwise hand-roll: the codeload tarball URL,
+* gunzip, untar, stripping the `repo-<ref>/` leading segment, subdir filtering,
+* and ref pinning. `force` overwrites `dir` so reruns are idempotent.
 *
-* @param stdout - Raw stdout output that may contain logs and metadata
-* @returns Parsed JSON object
-* @throws Error if no valid metadata line is found or JSON parsing fails
+* We deliberately do NOT pass `preferOffline`: giget caches the tarball keyed by
+* REF name, and SKILL_REF is a moving branch (`main` / a feature branch), so
+* `preferOffline` would reuse a stale cached tarball forever — reinstalling
+* files that were since deleted upstream. Without it, giget revalidates via the
+* stored etag and re-downloads when the branch moved.
+*
+* Throws on network / resolve / extract errors — callers (skill install is
+* best-effort) catch and skip.
 */
-const extractMetadataFromStdout = (stdout) => {
-	const prefixPositions = [];
-	let searchStart = 0;
-	while (true) {
-		const pos = stdout.indexOf(METADATA_PROTOCOL_PREFIX, searchStart);
-		if (pos === -1) break;
-		prefixPositions.push(pos);
-		searchStart = pos + 14;
-	}
-	if (prefixPositions.length === 0) try {
-		return JSON.parse(stdout.trim());
-	} catch {
-		throw new Error("No metadata found in output. Please make sure you are running the latest version of `lmnr` python package.");
-	}
-	let lastValidJson = null;
-	for (const pos of prefixPositions) {
-		const startPos = pos + 14;
-		const jsonText = stdout.slice(startPos).trim();
-		const nextNewline = stdout.indexOf("\n", startPos);
-		if (nextNewline !== -1) {
-			const lineText = stdout.slice(startPos, nextNewline).trim();
-			try {
-				lastValidJson = JSON.parse(lineText);
-				continue;
-			} catch {}
-		}
-		try {
-			let depth = 0;
-			let inString = false;
-			let escapeNext = false;
-			let firstChar = -1;
-			for (let i = 0; i < jsonText.length; i++) {
-				const char = jsonText[i];
-				if (escapeNext) {
-					escapeNext = false;
-					continue;
-				}
-				if (char === "\\" && inString) {
-					escapeNext = true;
-					continue;
-				}
-				if (char === "\"") {
-					inString = !inString;
-					continue;
-				}
-				if (inString) continue;
-				if (char === "{" || char === "[") {
-					if (firstChar === -1) firstChar = i;
-					depth++;
-				} else if (char === "}" || char === "]") {
-					depth--;
-					if (depth === 0 && firstChar !== -1) {
-						const candidate = jsonText.slice(0, i + 1);
-						lastValidJson = JSON.parse(candidate);
-						break;
-					}
-				}
-			}
-			if (depth !== 0 || firstChar === -1) lastValidJson = JSON.parse(jsonText);
-		} catch {
-			continue;
-		}
-	}
-	if (lastValidJson === null) throw new Error("No valid metadata JSON found in output. Please make sure you are running the latest version of `lmnr` python package.");
-	return lastValidJson;
-};
+async function downloadSkill(dir) {
+	await (0, giget.downloadTemplate)(skillSource(), {
+		dir,
+		force: true
+	});
+}
+//#endregion
+//#region src/utils/install-skill.ts
+const AGENT_DIRS = [
+	".claude",
+	".cursor",
+	".codex",
+	".agents"
+];
+const DEFAULT_AGENT_DIRS = [".claude", ".agents"];
 /**
-* Discovers function metadata for Python files/modules by calling the lmnr Python CLI
+* Fetch the pinned Laminar skill (`SKILL_NAME`) from the lmnr-skills repo and
+* write its full tree into every present agent dir under `cwd`
+* (`<dir>/skills/<SKILL_NAME>/SKILL.md`, `.../references/*.md`, ...). If none
+* are present, default to BOTH `.claude/` and `.agents/`. Idempotent —
+* overwrites on rerun.
+*
+* We download ONCE into a temp staging dir (one network hit) and copy it into
+* each agent dir. Skill install is the last, best-effort step of `setup`: a
+* download failure MUST NOT break setup — on error we log a warning and return
+* `{ written: [], defaulted: false, skipped: true }`.
+*
+* For .cursor/.codex the skills layout is not guaranteed to match CC; we write
+* the CC-guaranteed `skills/<SKILL_NAME>/` shape there too rather than
+* inventing a path that silently loads nothing.
 */
-const discoverPythonMetadata = async (filePathOrModule, options) => {
-	logger$2.debug(`Discovering Python metadata for ${filePathOrModule}`);
-	const args = ["discover"];
-	if (options.pythonModule) args.push("--module", options.pythonModule);
-	else args.push("--file", filePathOrModule);
-	if (options.function) args.push("--function", options.function);
+async function installSkill(cwd = process.cwd()) {
+	const staging = await (0, node_fs_promises.mkdtemp)((0, node_path.join)((0, node_os.tmpdir)(), "lmnr-skill-"));
 	try {
-		const response = extractMetadataFromStdout((await execCommand("lmnr", args)).stdout);
+		try {
+			await downloadSkill(staging);
+		} catch (err) {
+			process.stderr.write(`Warning: could not fetch the Laminar skill (${skillSource()}): ${describeError$1(err)}; skipping skill install.\n`);
+			return {
+				written: [],
+				defaulted: false,
+				skipped: true
+			};
+		}
+		const relFiles = (await (0, node_fs_promises.readdir)(staging, {
+			recursive: true,
+			withFileTypes: true
+		})).filter((d) => d.isFile()).map((d) => (0, node_path.relative)(staging, (0, node_path.join)(d.parentPath, d.name)));
+		const present = [];
+		for (const dir of AGENT_DIRS) if (await dirExists((0, node_path.join)(cwd, dir))) present.push(dir);
+		const targets = present.length > 0 ? present : DEFAULT_AGENT_DIRS;
+		const written = [];
+		for (const dir of targets) {
+			const skillRoot = (0, node_path.join)(cwd, dir, "skills", SKILL_NAME);
+			await (0, node_fs_promises.rm)(skillRoot, {
+				recursive: true,
+				force: true
+			});
+			await (0, node_fs_promises.mkdir)(skillRoot, { recursive: true });
+			await (0, node_fs_promises.cp)(staging, skillRoot, { recursive: true });
+			for (const rel of relFiles) written.push((0, node_path.join)(skillRoot, rel));
+		}
 		return {
-			functionName: response.name,
-			params: response.params || []
+			written,
+			defaulted: present.length === 0,
+			skipped: false
 		};
-	} catch (error) {
-		const errorMessage = error instanceof Error ? error.message : String(error);
-		logger$2.error(`Error while loading Python file/module: ${errorMessage}`);
-		if (errorMessage.toLowerCase().includes("command not found") || errorMessage.includes("spawn lmnr ENOENT")) logger$2.info(`HINT: Make sure latest version of \`lmnr\` python package is installed. \`pip install --upgrade lmnr\`, or if you are running this command from a virtual environment, make sure to activate it. For \`uv\` users, rerun the command with \`uv run\`, e.g. "uv run npx lmnr-cli dev ${filePathOrModule}"`);
-		throw error;
+	} finally {
+		await (0, node_fs_promises.rm)(staging, {
+			recursive: true,
+			force: true
+		});
 	}
-};
-/**
-* Generic metadata discovery dispatcher that routes to language-specific implementations
-*/
-const discoverFunctionMetadata = async (filePathOrModule, options) => {
-	if (options.pythonModule) return await discoverPythonMetadata(filePathOrModule, options);
-	const ext = path.extname(filePathOrModule);
-	if (TS_JS_EXTENSIONS.includes(ext)) return await discoverTypeScriptMetadata(filePathOrModule, options);
-	if (ext === ".py") return await discoverPythonMetadata(filePathOrModule, options);
-	logger$2.warn(`No metadata discovery available for ${ext} files`);
-	return {
-		functionName: options.function || path.basename(filePathOrModule, ext),
-		params: []
-	};
-};
-//#endregion
-//#region src/commands/dev/index.ts
-const logger$1 = initializeLogger();
-function newUUID() {
-	if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") return crypto.randomUUID();
-	return (0, uuid.v4)();
 }
-function getFrontendUrl(baseUrl, frontendPort) {
-	let url = baseUrl ?? "https://api.lmnr.ai";
-	if (url === "https://api.lmnr.ai") url = "https://www.laminar.sh";
-	url = url.replace(/\/$/, "");
-	if (/localhost|127\.0\.0\.1/.test(url)) {
-		const port = frontendPort ?? url.match(/:\d{1,5}$/g)?.[0]?.slice(1) ?? 5667;
-		url = url.replace(/:\d{1,5}$/g, "");
-		return `${url}:${port}`;
+async function dirExists(path) {
+	try {
+		await (0, node_fs_promises.access)(path);
+		return true;
+	} catch {
+		return false;
 	}
-	return url;
 }
+function describeError$1(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+//#endregion
+//#region src/commands/setup/index.ts
+const DEFAULT_FRONTEND_URL = "https://www.laminar.sh";
+const DEFAULT_BASE_URL = "https://api.lmnr.ai";
+const EXIT_NO_ACCESS = 4;
+const EXIT_LOGIN_FAILED = 6;
+const EXIT_NO_PROJECT = 7;
+const EXIT_ENV_WRITE_FAILED = 8;
+const EXIT_SETUP_KEY_FAILED = 9;
+const EXIT_LIST_PROJECTS_FAILED = 10;
+const EXIT_KEY_PROBE_FAILED = 11;
+const EXIT_KEY_MISMATCH = 12;
 /**
-* Parses request arguments, attempting JSON parse for strings
+* Directory-scoped onboarding (SPEC decision tree):
+*  - log in if needed (browser picks/creates the project; its id rides back on
+*    the device-token metadata, see parseProjectFromMetadata),
+*  - resolve a project for this directory (`.lmnr/project.json`), enforcing
+*    access,
+*  - mint a project API key only when one isn't already configured for this
+*    project (checked across process.env → .env.local → .env), then write it to
+*    an existing .env.local or else .env,
+*  - install the Laminar skill into present agent dirs,
+*  - print a summary.
+*
+* The minted key goes ONLY into the project's env file, never into
+* credentials.json (which stores user-scoped BetterAuth tokens).
 */
-const tryParseArg = (arg) => {
-	if (typeof arg === "string") try {
-		return JSON.parse(arg);
-	} catch {
-		return arg;
+async function handleSetup(options) {
+	const writeEnv = options.writeEnv !== false;
+	const frontendUrl = pick(options.frontendUrl, process.env.LMNR_FRONTEND_URL, DEFAULT_FRONTEND_URL);
+	const baseUrl = pick(options.baseUrl, process.env.LMNR_BASE_URL, DEFAULT_BASE_URL);
+	const isJson = options.json === true;
+	if (!isJson) process.stderr.write(`\n${orange("Laminar CLI")} ${pc.dim(`v${version$1}`)}\n\n`);
+	const cwd = process.cwd();
+	const existingKey = await findEnvKey(cwd);
+	let creds = await safeReadCredentials();
+	let link = await readProjectLink();
+	if (!creds) {
+		let login;
+		try {
+			login = await handleLogin({
+				frontendUrl,
+				noBrowser: options.noBrowser
+			});
+		} catch (err) {
+			emitError(isJson, "login_failed", describeError(err));
+			process.exit(EXIT_LOGIN_FAILED);
+		}
+		creds = await safeReadCredentials();
+		if (!creds) {
+			emitError(isJson, "login_failed", "credentials missing after login");
+			process.exit(EXIT_LOGIN_FAILED);
+		}
+		const issuer = creds.issuer || frontendUrl;
+		const userBaseUrl = baseUrl;
+		if (link) await assertAccess(creds, userBaseUrl, link.projectId, isJson);
+		else if (login.projectId) link = await writeLink(issuer, userBaseUrl, login.projectId, isJson);
+		else link = await resolveProjectViaCli(creds, userBaseUrl, issuer, isJson, options);
+	} else {
+		const userBaseUrl = baseUrl;
+		const issuer = creds.issuer || frontendUrl;
+		if (link) await assertAccess(creds, userBaseUrl, link.projectId, isJson);
+		else link = await resolveProjectViaCli(creds, userBaseUrl, issuer, isJson, options);
+	}
+	if (!isJson) {
+		process.stderr.write(`${pc.green("✓")} Logged in as ${creds.userEmail ?? "<unknown>"}\n`);
+		process.stderr.write(`${pc.green("✓")} Project: ${link.projectName ?? link.projectId}` + (link.workspaceName ? pc.dim(` (${link.workspaceName})`) : "") + "\n");
+	}
+	if (!creds || !link.projectId) {
+		emitError(isJson, "setup_invariant", "missing credentials or project after resolution");
+		process.exit(EXIT_NO_PROJECT);
+	}
+	const issuer = creds.issuer || frontendUrl;
+	const userBaseUrl = baseUrl;
+	let apiKey = null;
+	let envPath = null;
+	let keyMeta = null;
+	let needMint = true;
+	if (existingKey) {
+		const probe = await probeProjectKey(existingKey.value, userBaseUrl, envHttpPort());
+		const where = existingKey.source.type === "process-env" ? "your environment" : (0, node_path.relative)(cwd, existingKey.source.path);
+		if (probe.status === "unverifiable") {
+			emitError(isJson, "key_probe_failed", `Couldn't verify the existing Project API Key in ${where} (network or server error). Check your connection and re-run.`);
+			process.exit(EXIT_KEY_PROBE_FAILED);
+		} else if (probe.status === "ok" && probe.projectId === link.projectId) {
+			needMint = false;
+			if (!isJson) process.stderr.write(`${pc.green("✓")} Project API Key already set in ${where}\n`);
+		} else if (probe.status === "ok") {
+			emitError(isJson, "key_mismatch", `The Project API Key in ${where} belongs to a different project (${probe.projectId}), not the one linked here (${link.projectId}). Remove or update it, then re-run.`);
+			process.exit(EXIT_KEY_MISMATCH);
+		} else if (!isJson) process.stderr.write(`${pc.yellow("⚠")} Existing Project API Key in ${where} is invalid or revoked, minting a new one\n`);
+	}
+	if (needMint) {
+		try {
+			keyMeta = await mintSetupKey(issuer, creds.sessionToken, link.projectId);
+		} catch (err) {
+			emitError(isJson, "setup_key_failed", describeError(err));
+			process.exit(EXIT_SETUP_KEY_FAILED);
+		}
+		apiKey = keyMeta.apiKey;
+		if (!link.projectName && keyMeta.projectName) link.projectName = keyMeta.projectName;
+		if (!link.workspaceName && keyMeta.workspaceName) link.workspaceName = keyMeta.workspaceName;
+		if (!link.workspaceId && keyMeta.workspaceId) link.workspaceId = keyMeta.workspaceId;
+		if (writeEnv) {
+			const target = await resolveEnvWriteTarget(cwd, existingKey);
+			try {
+				const result = await writeEnvFile(target, apiKey);
+				envPath = result.path;
+				if (!isJson) {
+					const rel = (0, node_path.relative)(cwd, result.path);
+					const verb = result.created ? "Created" : result.replaced ? "Updated LMNR_PROJECT_API_KEY in" : "Added LMNR_PROJECT_API_KEY to";
+					process.stderr.write(`${pc.green("✓")} ${verb} ${rel}\n`);
+					if (await isPathGitIgnored(result.path) === false) process.stderr.write(`${pc.yellow("⚠")} ${rel} isn't gitignored; add it so the key isn't committed\n`);
+				}
+			} catch (err) {
+				process.stderr.write(`\n${pc.red("ERROR")}: failed to write ${target}: ${describeError(err)}\n` + pc.dim("Your API key (set it manually):") + `\n  LMNR_PROJECT_API_KEY=${apiKey}\n\n`);
+				if (isJson) process.stdout.write(JSON.stringify({
+					error: "env_write_failed",
+					apiKey,
+					projectId: link.projectId,
+					message: describeError(err)
+				}) + "\n");
+				process.exit(EXIT_ENV_WRITE_FAILED);
+			}
+		}
 	}
-	return arg;
-};
+	let skillsInstalled = [];
+	try {
+		const skillResult = await installSkill(process.cwd());
+		skillsInstalled = skillResult.written;
+		if (!isJson) {
+			if (skillResult.skipped) process.stderr.write(pc.dim("  Laminar skill install skipped\n"));
+			else if (skillResult.written.length > 0) {
+				const note = skillResult.defaulted ? pc.dim(" (no agent dir found; defaulted to .claude and .agents)") : "";
+				process.stderr.write(`${pc.green("✓")} Installed Laminar skill${note}\n`);
+			}
+		}
+	} catch (err) {
+		if (!isJson) process.stderr.write(`${pc.yellow("Warning")}: could not install Laminar skill (${describeError(err)}).\n`);
+	}
+	const frontendLink = `${trimSlash(issuer)}/project/${link.projectId}/traces`;
+	const result = {
+		projectId: link.projectId,
+		projectName: link.projectName ?? null,
+		workspaceId: link.workspaceId ?? null,
+		workspaceName: link.workspaceName ?? null,
+		apiKey,
+		envFileUpdated: envPath,
+		skillsInstalled,
+		frontendUrl: frontendLink,
+		userEmail: creds.userEmail ?? null
+	};
+	if (isJson) process.stdout.write(JSON.stringify(result) + "\n");
+	else process.stdout.write(`
+Next steps:
+  1. Instrument your project with Laminar using the installed skill or the docs:
+     ${pcOut.cyan("https://laminar.sh/docs/tracing/integrations/overview")}\n  2. Run your project.
+  3. Verify instrumentation:
+     ${pcOut.green("lmnr-cli sql query \"SELECT * FROM traces ORDER BY start_time DESC LIMIT 1\" --json")}\n  4. View your traces in the browser:
+     ${pcOut.cyan(frontendLink)}\n`);
+}
 /**
-* Handles a run event from the backend
+* Resolve a project via the CLI (logged-in, no link). 0 projects routes to the
+* browser create flow (gap A): we re-run the device flow, which lands on the
+* /device picker → first-project create UI, and the new project's id rides back
+* on the device-token metadata. >1 prompts a CLI choice; ==1 auto-selects.
 */
-const handleRunEvent = async (event, sessionId, filePathOrModule, client, cacheServerPort, cache, setMetadata, options, subprocessManager) => {
-	logger$1.debug("Received run event");
-	const { trace_id, path_to_count, args: rawArgs, overrides } = event.data;
-	const parsedArgs = Array.isArray(rawArgs) ? rawArgs.map(tryParseArg) : Object.fromEntries(Object.entries(rawArgs).map(([key, value]) => [key, tryParseArg(value)]));
-	cache.clear();
-	setMetadata({
-		pathToCount: {},
-		overrides
-	});
+async function resolveProjectViaCli(creds, userBaseUrl, issuer, isJson, options) {
+	let projects;
 	try {
-		if (!trace_id || trace_id.trim() === "") logger$1.info("No spans in cache, starting fresh");
-		else {
-			const paths = Object.keys(path_to_count || {});
-			if (paths.length === 0) logger$1.info("No spans to cache, starting fresh");
-			else {
-				const query = `
-          SELECT name, input, output, attributes, path
-          FROM spans
-          WHERE trace_id = {traceId:UUID}
-            AND path IN {paths:String[]}
-          ORDER BY start_time ASC
-        `;
-				logger$1.debug(`Querying spans from trace ${trace_id}...`);
-				const spans = await client.sql.query(query, {
-					traceId: trace_id,
-					paths
-				});
-				logger$1.debug(`Received ${spans.length} spans from backend`);
-				const spansByPath = {};
-				for (const span of spans) {
-					const path$2 = span.path;
-					if (!spansByPath[path$2]) spansByPath[path$2] = [];
-					spansByPath[path$2].push(span);
-				}
-				for (const [path$3, pathSpans] of Object.entries(spansByPath)) {
-					const maxCount = path_to_count?.[path$3] || 0;
-					const spansToCache = pathSpans.slice(0, maxCount);
-					spansToCache.forEach((span, index) => {
-						let parsedInput;
-						let parsedOutput;
-						let parsedAttributes;
-						try {
-							parsedInput = typeof span.input === "string" ? JSON.parse(span.input) : span.input;
-						} catch {
-							parsedInput = span.input;
-						}
-						try {
-							parsedOutput = typeof span.output === "string" ? span.output : JSON.stringify(span.output);
-						} catch {
-							parsedOutput = String(span.output);
-						}
-						try {
-							parsedAttributes = typeof span.attributes === "string" ? JSON.parse(span.attributes) : span.attributes;
-						} catch {
-							parsedAttributes = {};
-						}
-						const cachedSpan = {
-							name: span.name,
-							input: parsedInput,
-							output: parsedOutput,
-							attributes: parsedAttributes
-						};
-						const cacheKey = `${index}:${path$3}`;
-						cache.set(cacheKey, cachedSpan);
-					});
-					logger$1.info(`Cached ${spansToCache.length} spans for path: ${path$3}`);
-				}
-				setMetadata({
-					pathToCount: path_to_count || {},
-					overrides
-				});
-			}
+		projects = await listProjects(creds, userBaseUrl);
+	} catch (err) {
+		emitError(isJson, "list_projects_failed", describeError(err));
+		process.exit(EXIT_LIST_PROJECTS_FAILED);
+	}
+	if (projects.length === 0) {
+		if (isJson) {
+			emitError(isJson, "no_projects", `No projects found. Run \`lmnr-cli setup\` interactively (it opens the browser to create your first project) or create one at ${trimSlash(issuer)}/onboarding.`);
+			process.exit(EXIT_NO_PROJECT);
 		}
-		const baseUrl = options.baseUrl ?? process.env.LMNR_BASE_URL ?? "https://api.lmnr.ai";
-		const httpPort = options.port ?? (baseUrl.match(/:\d{1,5}$/g) ? parseInt(baseUrl.match(/:\d{1,5}$/g)[0].slice(1)) : 443);
-		const grpcPort = options.grpcPort ?? 8443;
-		const env = {
-			LMNR_ROLLOUT_SESSION_ID: sessionId,
-			LMNR_ROLLOUT_STATE_SERVER_ADDRESS: `http://localhost:${cacheServerPort}`
-		};
-		const workerConfig = {
-			filePath: options.pythonModule ? void 0 : filePathOrModule,
-			modulePath: options.pythonModule,
-			functionName: options.function,
-			args: parsedArgs,
-			env,
-			cacheServerPort,
-			baseUrl,
-			projectApiKey: options.projectApiKey,
-			httpPort,
-			grpcPort,
-			externalPackages: options.externalPackages,
-			dynamicImportsToSkip: options.dynamicImportsToSkip
-		};
-		const workerCommand = options.command ? {
-			command: options.command,
-			args: options.commandArgs ?? []
-		} : getWorkerCommand(options.pythonModule ? void 0 : filePathOrModule, options);
+		process.stderr.write("\nYou have no projects yet. Opening the browser to create your first one...\n");
+		let login;
 		try {
-			await client.rolloutSessions.setStatus({
-				sessionId,
-				status: "RUNNING"
+			login = await handleLogin({
+				frontendUrl: issuer,
+				noBrowser: options.noBrowser
 			});
-		} catch (error) {
-			logger$1.error(`Error setting debugger session status: ${error instanceof Error ? error.message : error}`);
+		} catch (err) {
+			emitError(isJson, "login_failed", describeError(err));
+			process.exit(EXIT_LOGIN_FAILED);
 		}
-		await subprocessManager.execute({
-			command: workerCommand.command,
-			args: workerCommand.args,
-			config: workerConfig
-		});
-		try {
-			await client.rolloutSessions.setStatus({
-				sessionId,
-				status: "FINISHED"
-			});
-		} catch (error) {
-			logger$1.error(`Error setting debugger session status: ${error instanceof Error ? error.message : error}`);
+		if (!login.projectId) {
+			emitError(isJson, "no_projects", `No project was created. Create one at ${trimSlash(issuer)}/onboarding then re-run setup.`);
+			process.exit(EXIT_NO_PROJECT);
 		}
-	} catch (error) {
-		logger$1.error(`Error handling run event: ${error instanceof Error ? error.message : error}`);
-		if (error instanceof Error && error.stack) logger$1.error(error.stack);
-		try {
-			await client.rolloutSessions.setStatus({
-				sessionId,
-				status: "FINISHED"
-			});
-		} catch (error) {
-			logger$1.error(`Error setting debugger session status: ${error instanceof Error ? error.message : error}`);
+		return writeLink(issuer, userBaseUrl, login.projectId, isJson);
+	}
+	let chosen;
+	if (options.projectId) {
+		const match = projects.find((p) => p.id === options.projectId);
+		if (!match) {
+			emitError(isJson, "no_access", `You don't have access to project ${options.projectId}. Accessible: ` + projects.map((p) => `${p.id} (${p.workspaceName}/${p.name})`).join(", "));
+			process.exit(EXIT_NO_ACCESS);
+		}
+		chosen = match;
+	} else if (projects.length === 1) chosen = projects[0];
+	else {
+		if (isJson) {
+			emitError(isJson, "project_ambiguous", `Multiple projects: pass --project-id <id>, or run setup interactively. ` + projects.map((p) => `${p.id} (${p.workspaceName}/${p.name})`).join(", "));
+			process.exit(EXIT_NO_PROJECT);
 		}
+		chosen = await promptProjectChoice(projects);
 	}
-};
-/**
-* Main dev command handler
-*/
-async function runDev(filePath, options = {}) {
-	const isPythonModule = !!options.pythonModule;
-	const filePathOrModule = filePath || options.pythonModule;
-	let didLogHandshake = false;
-	const sessionId = newUUID();
-	const client = new LaminarClient({
-		baseUrl: options.baseUrl,
-		projectApiKey: options.projectApiKey,
-		port: options.port
+	const linkPath = await writeProjectLink({
+		projectId: chosen.id,
+		projectName: chosen.name,
+		workspaceId: chosen.workspaceId,
+		workspaceName: chosen.workspaceName
 	});
-	logger$1.debug("Starting cache server...");
-	const { port: cacheServerPort, server: cacheServer, cache, setMetadata } = await startCacheServer();
-	logger$1.debug(`Cache server started on port ${cacheServerPort}`);
-	const subprocessManager = new SubprocessManager();
-	let functionName = options.function;
-	let params = [];
+	if (!isJson) process.stderr.write(`${pc.green("✓")} Linked ${linkPath}\n`);
+	return {
+		projectId: chosen.id,
+		projectName: chosen.name,
+		workspaceId: chosen.workspaceId,
+		workspaceName: chosen.workspaceName
+	};
+}
+/** Write `.lmnr/project.json`, enriching display details from listProjects when possible. */
+async function writeLink(issuer, userBaseUrl, projectId, isJson) {
+	let link = { projectId };
 	try {
-		if (isPythonModule || filePath && EXTENSIONS_TO_DISCOVER_METADATA.includes(path.extname(filePath))) {
-			logger$1.debug("Discovering entrypoint functions...");
-			const metadata = await discoverFunctionMetadata(filePathOrModule, options);
-			functionName = metadata.functionName;
-			params = metadata.params;
-			logger$1.info(`Serving function: ${functionName}`);
-			logger$1.debug(`Function parameters: ${JSON.stringify(params, null, 2)}`);
-		} else if (filePath) {
-			functionName = options.function || path.basename(filePath, path.extname(filePath));
-			logger$1.warn(`Metadata discovery not available for ${path.extname(filePath)} files`);
+		const creds = await safeReadCredentials();
+		if (creds) {
+			const match = (await listProjects(creds, userBaseUrl)).find((p) => p.id === projectId);
+			if (match) link = {
+				projectId,
+				projectName: match.name,
+				workspaceId: match.workspaceId,
+				workspaceName: match.workspaceName
+			};
 		}
-	} catch (error) {
-		logger$1.error("Failed to discover entrypoint functions: " + (error instanceof Error ? error.message : String(error)));
-		cacheServer.close();
-		throw error;
+	} catch {}
+	try {
+		const linkPath = await writeProjectLink(link);
+		if (!isJson) process.stderr.write(`${pc.green("✓")} Linked ${linkPath}\n`);
+	} catch (err) {
+		if (!isJson) process.stderr.write(`${pc.yellow("Warning")}: could not write .lmnr/project.json (${describeError(err)}). CLI commands will need --project-id ${projectId}.\n`);
 	}
-	logger$1.debug("Setting up file watcher...");
-	const watcher = chokidar.default.watch(".", {
-		ignored: (path$4) => {
-			const ignoredDirs = [
-				"node_modules",
-				".git",
-				"dist",
-				"build",
-				".next",
-				"coverage",
-				".turbo",
-				"tmp",
-				"temp",
-				"venv",
-				".venv",
-				"virtualenv",
-				".virtualenv",
-				"__pycache__",
-				".pytest_cache",
-				".ruff_cache",
-				".mypy_cache",
-				".cache",
-				".DS_Store"
-			];
-			if (path$4.split(/[/\\]/).some((segment) => ignoredDirs.includes(segment))) return true;
-			if (path$4.endsWith(".log") || path$4.endsWith(".map")) return true;
-			return false;
-		},
-		persistent: true,
-		ignoreInitial: true,
-		awaitWriteFinish: {
-			stabilityThreshold: 100,
-			pollInterval: 100
+	return link;
+}
+/**
+* Access check: the user must be a member of `projectId`. Calls
+* GET /v1/cli/projects (user JWT) and asserts the id is present; aborts
+* otherwise (SPEC: "You don't have access to the project in this directory").
+*/
+async function assertAccess(creds, userBaseUrl, projectId, isJson) {
+	let projects;
+	try {
+		projects = await listProjects(creds, userBaseUrl);
+	} catch (err) {
+		emitError(isJson, "list_projects_failed", describeError(err));
+		process.exit(EXIT_LIST_PROJECTS_FAILED);
+	}
+	if (!projects.some((p) => p.id === projectId)) {
+		emitError(isJson, "no_access", "You don't have access to the project in this directory");
+		process.exit(EXIT_NO_ACCESS);
+	}
+}
+/** List the projects the user can access (user-JWT-authed discovery). */
+async function listProjects(creds, baseUrl) {
+	const updated = await refreshIfNeeded(creds);
+	return new LaminarClient({
+		baseUrl,
+		port: envHttpPort(),
+		auth: {
+			type: "userToken",
+			token: updated.accessToken,
+			projectId: ""
 		}
-	});
-	logger$1.debug("Setting up SSE client...");
-	let sseClient = null;
+	}).cli.listProjects();
+}
+async function safeReadCredentials() {
 	try {
-		sseClient = createSSEClient({
-			client,
-			sessionId,
-			params,
-			name: functionName ?? ""
-		});
-		let currentRunPromise = null;
-		let stopRequested = false;
-		sseClient.on("heartbeat", () => {
-			logger$1.debug("Heartbeat received");
-		});
-		sseClient.on("run", (event) => {
-			if (currentRunPromise !== null) {
-				logger$1.warn("Already processing a run event, skipping new run");
-				return;
-			}
-			currentRunPromise = (async () => {
-				try {
-					stopRequested = false;
-					if (reloadScheduled) {
-						logger$1.info("Reloading function metadata before run...");
-						if (isPythonModule || filePath && EXTENSIONS_TO_DISCOVER_METADATA.includes(path.extname(filePath))) try {
-							const metadata = await discoverFunctionMetadata(filePathOrModule, options);
-							if (stopRequested) {
-								logger$1.info("Run cancelled during metadata discovery");
-								return;
-							}
-							logger$1.debug(`Updated function metadata: ${metadata.functionName}`);
-							logger$1.debug(`Updated parameters: ${JSON.stringify(metadata.params, null, 2)}`);
-							if (sseClient) {
-								sseClient.updateMetadata(metadata.params, metadata.functionName);
-								logger$1.debug("Notified backend of metadata changes");
-							}
-							reloadScheduled = false;
-						} catch (error) {
-							logger$1.error("Failed to update function metadata: " + (error instanceof Error ? error.message : String(error)));
-							if (error instanceof Error && error.stack) logger$1.debug(`Stack trace: ${error.stack}`);
-							return;
-						}
-						else reloadScheduled = false;
-					}
-					if (stopRequested) {
-						logger$1.info("Run cancelled before execution");
-						return;
-					}
-					await handleRunEvent(event, sessionId, filePathOrModule, client, cacheServerPort, cache, setMetadata, options, subprocessManager);
-				} catch (error) {
-					logger$1.error("Unhandled error in run event handler: " + (error instanceof Error ? error.message : String(error)));
-				} finally {
-					currentRunPromise = null;
-				}
-			})();
-		});
-		sseClient.on("handshake", (event) => {
-			const projectId = event.data.project_id;
-			const sessionId = event.data.session_id;
-			const frontendUrl = getFrontendUrl(options.baseUrl, options.frontendPort);
-			if (!didLogHandshake) logger$1.info(`View your session at ${frontendUrl}/project/${projectId}/debugger-sessions/${sessionId}`);
-			didLogHandshake = true;
-		});
-		sseClient.on("error", (error) => {
-			logger$1.warn(`Error connecting to backend: ${error.message}`);
-		});
-		sseClient.on("reconnecting", () => {
-			logger$1.info("Reconnecting to backend...");
-		});
-		sseClient.on("heartbeat_timeout", () => {
-			logger$1.debug("Heartbeat timeout, reconnecting...");
-		});
-		sseClient.on("stop", () => {
-			logger$1.debug("Stop event received");
-			stopRequested = true;
-			if (subprocessManager.kill()) logger$1.info("Current run cancelled");
-		});
-		let reloadTimeout = null;
-		let reloadScheduled = false;
-		watcher.on("change", (changedPath) => {
-			logger$1.info(`File changed: ${changedPath}, scheduling reload...`);
-			if (reloadTimeout) clearTimeout(reloadTimeout);
-			reloadTimeout = setTimeout(() => {
-				logger$1.debug("Marking reload as scheduled for next run...");
-				reloadTimeout = null;
-				reloadScheduled = true;
-			}, 100);
-		});
-		const shutdown = () => {
-			logger$1.debug("Shutting down...");
-			if (reloadTimeout) {
-				clearTimeout(reloadTimeout);
-				reloadTimeout = null;
-			}
-			reloadScheduled = false;
-			logger$1.debug("Closing file watcher...");
-			watcher.close().catch((error) => {
-				logger$1.error(`Failed to close file watcher: ${error instanceof Error ? error.message : error}`);
-			});
-			subprocessManager.kill();
-			logger$1.debug("Deleting debugger session...");
-			client.rolloutSessions.delete({ sessionId }).then(() => {
-				if (sseClient) sseClient.shutdown();
-				cacheServer.close(() => {
-					logger$1.debug("Cache server closed");
-				});
-				process.exit(0);
-			}).catch((error) => {
-				logger$1.warn(`Failed to delete debugger session: ${error instanceof Error ? error.message : error}`);
-				process.exit(1);
-			});
-		};
-		process.on("SIGINT", shutdown);
-		process.on("SIGTERM", shutdown);
-		process.stdin.resume();
-		logger$1.debug("Connecting to backend...");
-		await sseClient.connectAndListen();
-	} catch (error) {
-		logger$1.error("Failed to start dev command: " + (error instanceof Error ? error.message : String(error)));
-		try {
-			await client.rolloutSessions.delete({ sessionId });
-		} catch {}
-		await watcher.close();
-		cacheServer.close(() => {
-			process.exit(1);
-		});
+		return await readCredentials();
+	} catch {
+		return null;
 	}
 }
-//#endregion
-//#region src/commands/sql/index.ts
-const logger = initializeLogger();
-const handleSqlQuery = async (query, options) => {
-	const client = new LaminarClient({
-		projectApiKey: options.projectApiKey,
-		baseUrl: options.baseUrl,
-		port: options.port
+/** POST /api/cli/api-key with the session bearer for an explicit project. */
+async function mintSetupKey(issuer, sessionToken, projectId) {
+	const url = `${trimSlash(issuer)}/api/cli/api-key`;
+	const res = await fetch(url, {
+		method: "POST",
+		headers: {
+			authorization: `Bearer ${sessionToken}`,
+			"content-type": "application/json"
+		},
+		body: JSON.stringify({
+			deviceName: (0, node_os.hostname)(),
+			projectId
+		})
+	});
+	if (res.ok) return await res.json();
+	const body = await res.json().catch(() => ({}));
+	throw new Error(body.error ?? `api-key request failed (${res.status})`);
+}
+async function promptProjectChoice(projects) {
+	process.stderr.write("\nMultiple projects available. Choose one:\n");
+	projects.forEach((p, i) => {
+		process.stderr.write(`  ${i + 1}) ${p.workspaceName} / ${p.name}\n`);
+	});
+	const rl = (0, node_readline_promises.createInterface)({
+		input: process.stdin,
+		output: process.stderr
 	});
 	try {
-		const rows = await client.sql.query(query);
-		if (options.json) {
-			outputJson(rows);
-			return;
+		while (true) {
+			const answer = (await rl.question(`Select [1-${projects.length}]: `)).trim();
+			const idx = Number.parseInt(answer, 10);
+			if (Number.isInteger(idx) && idx >= 1 && idx <= projects.length) return projects[idx - 1];
+			process.stderr.write(`${pc.red("Invalid selection.")}\n`);
 		}
-		if (rows.length === 0) {
-			console.log("No rows returned.");
-			return;
-		}
-		const columns = Object.keys(rows[0]);
-		const tableRows = rows.map((row) => columns.map((col) => String(row[col] ?? "")));
-		console.log(renderTable(columns, tableRows));
-		console.log(`\n${rows.length} row(s)\n`);
-	} catch (error) {
-		if (options.json) outputJsonError(error);
-		logger.error(`Query failed: ${error instanceof Error ? error.message : String(error)}`);
-		process.exit(1);
+	} finally {
+		rl.close();
 	}
+}
+function pick(...candidates) {
+	for (const c of candidates) if (c && c.length > 0) return c;
+	return "";
+}
+function trimSlash(url) {
+	return url.replace(/\/+$/, "");
+}
+function describeError(err) {
+	if (err instanceof Error) return err.message;
+	return String(err);
+}
+function emitError(json, code, detail) {
+	if (json) process.stdout.write(JSON.stringify({
+		error: code,
+		detail
+	}) + "\n");
+	else process.stderr.write(`\n${pc.red(`ERROR (${code})`)}: ${detail}\n`);
+}
+//#endregion
+//#region src/commands/sql/index.ts
+/**
+* Run a SQL query against the project's data and print the rows. Pure handler:
+* the command wrapper (`withProjectClient`) resolves the client and owns the
+* error envelope (`--json` → structured error + exit, otherwise log + exit).
+*/
+const handleSqlQuery = async (client, query, opts) => {
+	const rows = await client.sql.query(query);
+	if (opts.json) {
+		outputJson(rows);
+		return;
+	}
+	if (rows.length === 0) {
+		console.log("No rows returned.");
+		return;
+	}
+	const columns = Object.keys(rows[0]);
+	const tableRows = rows.map((row) => columns.map((col) => String(row[col] ?? "")));
+	console.log(renderTable(columns, tableRows));
+	console.log(`\n${rows.length} row(s)\n`);
 };
 //#endregion
 //#region src/commands/sql/schema.ts
@@ -2591,44 +2942,60 @@ Available tables:
     data (String), target (String), metadata (String)
 `;
 //#endregion
+//#region src/commands/trace/index.ts
+const logger = initializeLogger();
+const NOTE_SEPARATOR = "\n\n";
+/**
+* Append a free-text note to an existing trace. Stored under the
+* `rollout.note` trace-metadata key via the post-factum metadata patch
+* endpoint. The patch endpoint is last-write-wins per key, so the current
+* note is read back first (via the SQL endpoint) and the new text is pushed
+* as `existing + "\n\n" + note`. The note may contain markdown /
+* span-reference links.
+*
+* Pure handler: the command wrapper (`withProjectClient`) resolves a user-token
+* {@link LaminarClient} (routes to `/v1/cli/*` with the resolved project) and
+* owns the error envelope (`--json` → structured error + exit, else log + exit).
+*
+* The read-modify-write is not transactional: the patch lands via the async
+* ingestion queue, so a second append issued within ~a second of the first
+* can read the pre-patch note and drop the first append. Fine for the
+* intended cadence (one note per investigation step), not for concurrent
+* writers.
+*
+* TODO: revisit — make the append atomic server-side (e.g. an append mode on
+* the metadata patch endpoint that concatenates within the Postgres UPDATE,
+* which already serializes on the trace row lock).
+*/
+const handleTraceAppendNote = async (client, traceId, note, opts) => {
+	const id = normalizeTraceId(traceId);
+	const rows = await client.sql.query("SELECT metadata FROM traces WHERE id = {trace_id:UUID} LIMIT 1", { trace_id: id });
+	if (rows.length === 0) throw new Error(`Trace ${id} not found. If the run just finished, the trace may not be flushed yet. Retry in a few seconds.`);
+	const existing = readNoteFromMetadata(rows[0].metadata);
+	const updated = existing ? `${existing}${NOTE_SEPARATOR}${note}` : note;
+	await client.traces.pushMetadata(id, { [NOTE_METADATA_KEY]: updated }, { failOnNotFound: true });
+	if (opts.json) {
+		outputJson({
+			traceId: id,
+			note: updated
+		});
+		return;
+	}
+	logger.info(`Appended note to trace ${id}.`);
+};
+//#endregion
 //#region src/index.ts
 async function main() {
+	await loadLocalEnv(process.cwd());
 	const program = new commander.Command();
 	program.name("lmnr-cli").description("CLI for the Laminar agent observability platform").version(version$1, "-v, --version", "display version number");
-	program.command("dev").description("Start a debugging session").argument("[file]", "Path to file containing the entrypoint function(s). Either `file` or `-m` must be provided.").option("-m, --python-module <module>", "Python module path (e.g., src.myfile). Either `file` or `-m` must be provided.").option("--function <name>", "Specific function to serve (if multiple entrypoint functions found)").option("--project-api-key <key>", "Project API key. If not provided, reads from LMNR_PROJECT_API_KEY env variable").option("--base-url <url>", "Base URL for the Laminar API. Defaults to https://api.lmnr.ai or LMNR_BASE_URL env variable").option("--port <port>", "Port for the Laminar API. Defaults to 443", (val) => parseInt(val, 10)).option("--grpc-port <port>", "Port for the Laminar gRPC backend. Defaults to 8443", (val) => parseInt(val, 10)).option("--frontend-port <port>", "Port for the Laminar frontend. Defaults to 5667", (val) => parseInt(val, 10)).option("--external-packages <packages...>", "[ADVANCED] List of packages to pass as external to esbuild. This will not link the packages directly into the dev file, but will instead require them at runtime. Read more: https://esbuild.github.io/api/#external").option("--dynamic-imports-to-skip <modules...>", "[ADVANCED] List of module names to skip when encountered as dynamic imports. These dynamic imports will resolve to an empty module to prevent build failures. This is meant to skip the imports that are not used in the entrypoint function itself.").option("--command <command>", "[ADVANCED] Custom command to run the worker (e.g., python3, node)").option("--command-args <args...>", "[ADVANCED] Arguments for the custom command").action(async (file, options) => {
-		if (!file && !options.pythonModule) {
-			console.error("Error: Must provide either a file path or --python-module (-m) flag");
-			process.exit(1);
-		}
-		if (file && options.pythonModule) {
-			console.error("Error: Cannot specify both file path and --python-module (-m) flag");
-			process.exit(1);
-		}
-		await runDev(file, options);
-	}).addHelpText("after", `
-Examples:
-  $ lmnr-cli dev agent.ts                    # TypeScript file
-  $ lmnr-cli dev agent.py                    # Python file (script mode)
-  $ lmnr-cli dev -m src.agent                # Python module (module mode)
-  $ lmnr-cli dev agent.ts --function myAgent # Specific function
-`);
-	const datasetsCmd = program.command("dataset").description("Manage datasets").option("--project-api-key <key>", "Project API key. If not provided, reads from LMNR_PROJECT_API_KEY env variable").option("--base-url <url>", "Base URL for the Laminar API. Defaults to https://api.lmnr.ai or LMNR_BASE_URL env variable").option("--port <port>", "Port for the Laminar API. Defaults to 443", (val) => parseInt(val, 10)).option("--json", "Output structured JSON to stdout");
-	datasetsCmd.command("list").description("List all datasets").action(async (_options, cmd) => {
-		await handleDatasetsList(cmd.optsWithGlobals());
-	});
-	datasetsCmd.command("push").description("Push datapoints to an existing dataset").argument("<paths...>", "Paths to files or directories containing data to push").option("-n, --name <name>", "Name of the dataset (either name or id must be provided)").option("--id <id>", "ID of the dataset (either name or id must be provided)").option("-r, --recursive", "Recursively read files in directories", false).option("--batch-size <size>", "Batch size for pushing data", (val) => parseInt(val, 10), 100).action(async (paths, _options, cmd) => {
-		await handleDatasetsPush(paths, cmd.optsWithGlobals());
-	});
-	datasetsCmd.command("pull").description("Pull data from a dataset").argument("[output-path]", "Path to save the data. If not provided, prints to console").option("-n, --name <name>", "Name of the dataset (either name or id must be provided)").option("--id <id>", "ID of the dataset (either name or id must be provided)").option("--output-format <format>", "Output format (json, csv, jsonl). Inferred from file extension if not provided").option("--batch-size <size>", "Batch size for pulling data", (val) => parseInt(val, 10), 100).option("--limit <limit>", "Limit number of datapoints to pull", (val) => parseInt(val, 10)).option("--offset <offset>", "Offset for pagination", (val) => parseInt(val, 10), 0).action(async (outputPath, _options, cmd) => {
-		await handleDatasetsPull(outputPath, cmd.optsWithGlobals());
-	});
-	datasetsCmd.command("create").description("Create a dataset from input files").argument("<name>", "Name of the dataset to create").argument("<paths...>", "Paths to files or directories containing data to push").requiredOption("-o, --output-file <file>", "Path to save the pulled data").option("--output-format <format>", "Output format (json, csv, jsonl). Inferred from file extension if not provided").option("-r, --recursive", "Recursively read files in directories", false).option("--batch-size <size>", "Batch size for pushing/pulling data", (val) => parseInt(val, 10), 100).action(async (name, paths, _options, cmd) => {
-		await handleDatasetsCreate(name, paths, cmd.optsWithGlobals());
-	});
-	const sqlCmd = program.command("sql").description("Run SQL queries against your Laminar project data").option("--project-api-key <key>", "Project API key. If not provided, reads from LMNR_PROJECT_API_KEY env variable").option("--base-url <url>", "Base URL for the Laminar API. Defaults to https://api.lmnr.ai or LMNR_BASE_URL env variable").option("--port <port>", "Port for the Laminar API. Defaults to 443", (val) => parseInt(val, 10)).option("--json", "Output structured JSON to stdout");
-	sqlCmd.command("query").description("Execute a SQL query").argument("<query>", "SQL query string").action(async (query, _options, cmd) => {
-		await handleSqlQuery(query, cmd.optsWithGlobals());
-	}).addHelpText("after", SQL_SCHEMA_HELP + `
+	const datasetsCmd = program.command("dataset").description("Manage datasets").option("--project-id <id>", "Target project id. Defaults to the linked .lmnr/project.json. Run `lmnr-cli login` first.").option("--base-url <url>", "Base URL for the Laminar API. Defaults to https://api.lmnr.ai or LMNR_BASE_URL env variable").option("--port <port>", "Port for the Laminar API. Defaults to 443", (val) => parseInt(val, 10)).option("--json", "Output structured JSON to stdout");
+	datasetsCmd.command("list").description("List all datasets").action(withProjectClient(handleDatasetsList));
+	datasetsCmd.command("push").description("Push datapoints to an existing dataset").argument("<paths...>", "Paths to files or directories containing data to push").option("-n, --name <name>", "Name of the dataset (either name or id must be provided)").option("--id <id>", "ID of the dataset (either name or id must be provided)").option("-r, --recursive", "Recursively read files in directories", false).option("--batch-size <size>", "Batch size for pushing data", (val) => parseInt(val, 10), 100).action(withProjectClient(handleDatasetsPush));
+	datasetsCmd.command("pull").description("Pull data from a dataset").argument("[output-path]", "Path to save the data. If not provided, prints to console").option("-n, --name <name>", "Name of the dataset (either name or id must be provided)").option("--id <id>", "ID of the dataset (either name or id must be provided)").option("--output-format <format>", "Output format (json, csv, jsonl). Inferred from file extension if not provided").option("--batch-size <size>", "Batch size for pulling data", (val) => parseInt(val, 10), 100).option("--limit <limit>", "Limit number of datapoints to pull", (val) => parseInt(val, 10)).option("--offset <offset>", "Offset for pagination", (val) => parseInt(val, 10), 0).action(withProjectClient(handleDatasetsPull));
+	datasetsCmd.command("create").description("Create a dataset from input files").argument("<name>", "Name of the dataset to create").argument("<paths...>", "Paths to files or directories containing data to push").requiredOption("-o, --output-file <file>", "Path to save the pulled data").option("--output-format <format>", "Output format (json, csv, jsonl). Inferred from file extension if not provided").option("-r, --recursive", "Recursively read files in directories", false).option("--batch-size <size>", "Batch size for pushing/pulling data", (val) => parseInt(val, 10), 100).action(withProjectClient(handleDatasetsCreate));
+	const sqlCmd = program.command("sql").description("Run SQL queries against your Laminar project data").option("--project-id <id>", "Target project id. Defaults to the linked .lmnr/project.json. Run `lmnr-cli login` first.").option("--base-url <url>", "Base URL for the Laminar API. Defaults to https://api.lmnr.ai or LMNR_BASE_URL env variable").option("--port <port>", "Port for the Laminar API. Defaults to 443", (val) => parseInt(val, 10)).option("--json", "Output structured JSON to stdout");
+	sqlCmd.command("query").description("Execute a SQL query").argument("<query>", "SQL query string").action(withProjectClient(handleSqlQuery)).addHelpText("after", SQL_SCHEMA_HELP + `
 Examples:
   $ lmnr-cli sql query "SELECT * FROM spans LIMIT 10"
   $ lmnr-cli sql query "SELECT id, total_cost, status FROM traces LIMIT 20"
@@ -2637,32 +3004,77 @@ Examples:
 	sqlCmd.command("schema").description("Show available tables and their columns").action(() => {
 		process.stdout.write(SQL_SCHEMA_HELP);
 	});
+	program.command("project").description("Work with Laminar projects").command("list").description("List the projects you can access (● = linked to this directory)").option("--base-url <url>", "Base URL for the Laminar API. Defaults to the logged-in session or LMNR_BASE_URL").option("--port <port>", "Port for the Laminar API. Defaults to 443", (val) => parseInt(val, 10)).option("--json", "Output structured JSON to stdout").action(withUserToken(handleProjectsList));
+	program.command("login").description("Authenticate the CLI via OAuth Device Flow").option("--frontend-url <url>", "Frontend URL (issuer). Defaults to https://www.laminar.sh or LMNR_FRONTEND_URL env variable").option("--no-browser", "Do not open the verification URL in a browser").action(async (options) => {
+		const result = await handleLogin(options);
+		process.stderr.write(`${pc.green("✓")} Logged in as ${result.userEmail ?? "<unknown>"}.\n`);
+		process.stderr.write(pc.dim("Client: lmnr-cli. Tokens stored at ~/.config/lmnr/credentials.json (mode 0600).\n"));
+		process.stderr.write(pc.dim("Run `lmnr-cli setup` in a project directory to link it and write its API key.\n"));
+	});
+	program.command("logout").description("Log out and remove the stored credentials").action(async () => {
+		await handleLogout();
+	});
+	program.command("setup").description("One-shot onboarding: login, select a project, write its key to .env, link .lmnr, and install the Laminar agent skill").option("--write-env", "Write LMNR_PROJECT_API_KEY to ./.env (default)", true).option("--no-write-env", "Do not write to ./.env").option("--project-id <id>", "Project to link when you can access more than one (disambiguates the project_ambiguous case in --json mode)").option("--json", "Emit a machine-readable JSON line on stdout").option("--no-browser", "Do not auto-open the device-flow URL").option("--frontend-url <url>", "Frontend URL (issuer). Defaults to LMNR_FRONTEND_URL or https://www.laminar.sh").option("--base-url <url>", "Base URL for the Laminar API. Defaults to LMNR_BASE_URL or https://api.lmnr.ai").action(async (options) => {
+		await handleSetup(options);
+	});
+	program.command("trace").description("Inspect and operate on traces").option("--project-id <id>", "Target project id. Defaults to the linked .lmnr/project.json. Run `lmnr-cli login` first.").option("--base-url <url>", "Base URL for the Laminar API. Defaults to https://api.lmnr.ai or LMNR_BASE_URL env variable").option("--port <port>", "Port for the Laminar API. Defaults to 443", (val) => parseInt(val, 10)).option("--json", "Output structured JSON to stdout").command("append-note").description("Append a free-text note to a trace (stored in trace metadata)").argument("<trace-id>", "Trace ID (UUID or 32-char OTel hex trace id)").argument("<note>", "Note text (may contain markdown)").action(withProjectClient(handleTraceAppendNote)).addHelpText("after", `
+Notes accumulate: each call appends a new paragraph to the trace's existing
+note rather than overwriting it.
+
+Examples:
+  $ lmnr-cli trace append-note <trace-id> "Reproduced the timeout on the search tool."
+`);
+	const debugSessionCmd = program.command("debug").description("Operate on debug sessions").option("--project-id <id>", "Target project id. Defaults to the linked .lmnr/project.json. Run `lmnr-cli login` first.").option("--base-url <url>", "Base URL for the Laminar API. Defaults to https://api.lmnr.ai or LMNR_BASE_URL env variable").option("--port <port>", "Port for the Laminar API. Defaults to 443", (val) => parseInt(val, 10)).option("--json", "Output structured JSON to stdout").addHelpText("after", `
+Learn more about debugging features at https://laminar.sh/docs/platform/debugger
+`).command("session").description("Manage debug sessions").addHelpText("after", `
+Learn more about debugging features at https://laminar.sh/docs/platform/debugger
+`);
+	debugSessionCmd.command("set-name").description("Set the display name of a debug session").argument("<session-id>", "Debug session ID").argument("<name>", "Session display name").action(withProjectClient(handleDebugSessionSetName)).addHelpText("after", `
+Examples:
+  $ lmnr-cli debug session set-name <session-id> "Fix report length + search tool"
+`);
+	debugSessionCmd.command("summary").description("Print every trace in a debug session with its note, oldest first").argument("<session-id>", "Debug session ID").action(withProjectClient(handleDebugSessionSummary)).addHelpText("after", `
+Output is one block per trace (oldest first), the trace's note followed by a
+self-closing tag carrying the trace id and end time:
+
+  {note}
+  <trace id="{trace-id}" end-time="{end-time}"/>
+
+With --json, prints an array of {"note", "traceId", "endTime"} objects.
+
+Examples:
+  $ lmnr-cli debug session summary <session-id>
+  $ lmnr-cli debug session summary <session-id> --json
+`);
 	program.addHelpText("after", `
 Authentication:
-  Most commands require a project API key. Provide it in one of two ways:
-    1. Environment variable: export LMNR_PROJECT_API_KEY=<your-key>
-    2. CLI flag:             --project-api-key <your-key>
-  Get your key at https://www.laminar.sh (Settings > Project API Keys).
+  Run \`lmnr-cli setup\` to login, link this directory, write a project API key to
+  ./.env, and install the Laminar skill 
+  \`lmnr-cli login\` authenticates as a user. Every project command
+  (sql / dataset / project / trace / debug) runs on that user session and
+  targets a project via --project-id or the linked .lmnr/project.json.
 
 Examples:
-  lmnr-cli dev agent.ts                                    # Debugger TypeScript entrypoint
-  lmnr-cli dev agent.py                                    # Debugger Python script mode
-  lmnr-cli dev -m src.agent                                # Debugger Python module mode
+  lmnr-cli setup                                           # Logs in and prepares directory
+  lmnr-cli login                                           # Authenticate (user)
+  lmnr-cli project list                                    # Projects you can access
+  lmnr-cli logout                                          # Log out
   lmnr-cli dataset list --json                             # List all datasets
   lmnr-cli dataset push data.jsonl -n my-dataset --json    # Push data to a dataset
   lmnr-cli dataset pull output.jsonl -n my-dataset --json  # Pull data from a dataset
   lmnr-cli sql query "SELECT * FROM spans LIMIT 10" --json # Query spans
-  lmnr-cli sql query "SELECT t.id, s.name FROM traces t JOIN spans s ON t.id = s.trace_id" --json
   lmnr-cli sql schema                                      # Show available tables
+  lmnr-cli trace append-note <trace-id> "note text"        # Append a note to a trace
+  lmnr-cli debug session set-name <session-id> "title"     # Rename a debug session
+  lmnr-cli debug session summary <session-id>              # Notes for each trace in a session
 
 For more information about the Laminar platfrom:
   Documentation: https://laminar.sh/docs
-  Dashboard:     https://www.laminar.sh
 `);
 	await program.parseAsync();
 }
 main().catch((err) => {
-	console.error(err instanceof Error ? err.message : err);
+	console.error(errorMessage(err));
 	process.exit(1);
 });
 //#endregion