lmnr-cli 0.1.10 → 0.1.11

package/dist/index.cjs

@@ -31,6 +31,9 @@ let pino = require("pino");
 let pino$3 = __toESM(pino, 1);
 pino = __toESM(pino);
 let pino_pretty = require("pino-pretty");
+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");
@@ -38,11 +41,18 @@ let fs_promises = require("fs/promises");
 fs_promises = __toESM(fs_promises);
 let cli_table3 = require("cli-table3");
 cli_table3 = __toESM(cli_table3);
+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 package.json
-var version$1 = "0.1.10";
+var version$1 = "0.1.11";
 //#endregion
 //#region ../../node_modules/.pnpm/dotenv@17.4.2/node_modules/dotenv/lib/main.js
 var require_main = /* @__PURE__ */ __commonJSMin(((exports, module) => {
@@ -348,22 +358,28 @@ function _v4(options, buf, offset) {
 //#endregion
 //#region ../client/dist/index.mjs
 var import_main = require_main();
-var version = "0.8.27";
+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) {
@@ -372,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 = {
@@ -397,6 +413,33 @@ 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";
@@ -458,8 +501,8 @@ 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.
@@ -467,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()
 		});
@@ -482,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()
 		});
@@ -511,7 +554,7 @@ var DatasetsResource = class extends BaseResource {
 			const batchNum = Math.floor(i / batchSize) + 1;
 			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({
@@ -549,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()
 		});
@@ -560,8 +603,8 @@ var DatasetsResource = class extends BaseResource {
 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.
@@ -735,8 +778,8 @@ var EvalsResource = class extends BaseResource {
 * 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
@@ -793,9 +836,29 @@ var EvaluatorsResource = class extends BaseResource {
 	}
 };
 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);
 	}
 	/**
 	* Idempotently register (upsert) a debug session on the backend, keyed on the
@@ -806,7 +869,7 @@ var RolloutSessionsResource = class extends BaseResource {
 	* caller can build the debugger URL; null if the body can't be parsed.
 	*/
 	async register({ sessionId, name }) {
-		const response = await fetch(`${this.baseHttpUrl}/v1/rollouts/${sessionId}`, {
+		const response = await fetch(`${this.baseHttpUrl}${this.apiPrefix}/rollouts/${sessionId}`, {
 			method: "POST",
 			headers: this.headers(),
 			body: JSON.stringify({ name })
@@ -826,15 +889,73 @@ var RolloutSessionsResource = class extends BaseResource {
 	* stays the SDK's job via {@link register}.
 	*/
 	async setName({ sessionId, name }) {
-		const response = await fetch(`${this.baseHttpUrl}/v1/rollouts/${sessionId}/name`, {
+		const response = await fetch(`${this.baseHttpUrl}${this.apiPrefix}/rollouts/${sessionId}/name`, {
 			method: "PATCH",
 			headers: this.headers(),
 			body: JSON.stringify({ name })
 		});
 		if (!response.ok) await this.handleError(response);
 	}
+	/**
+	* 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}/v1/rollouts/${sessionId}`, {
+		const response = await fetch(`${this.baseHttpUrl}${this.apiPrefix}/rollouts/${sessionId}`, {
 			method: "DELETE",
 			headers: this.headers()
 		});
@@ -842,11 +963,11 @@ var RolloutSessionsResource = class extends BaseResource {
 	}
 };
 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({
@@ -861,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
@@ -917,8 +1038,8 @@ var TagsResource = class extends BaseResource {
 const logger$5 = initializeLogger$1();
 var TracesResource = class extends BaseResource {
 	/** Resource for post-factum operations on existing traces. */
-	constructor(baseHttpUrl, projectApiKey) {
-		super(baseHttpUrl, projectApiKey);
+	constructor(baseHttpUrl, auth) {
+		super(baseHttpUrl, auth);
 	}
 	/**
 	* Push a metadata patch to an existing trace.
@@ -973,7 +1094,7 @@ var TracesResource = class extends BaseResource {
 	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 + "/v1/traces/metadata";
+		const url = this.baseHttpUrl + this.apiPrefix + "/traces/metadata";
 		const response = await fetch(url, {
 			method: "POST",
 			headers: this.headers(),
@@ -991,25 +1112,49 @@ var TracesResource = class extends BaseResource {
 		if (!response.ok) await this.handleError(response);
 	}
 };
-var LaminarClient = class {
-	constructor({ baseUrl, projectApiKey, port } = {}) {
+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);
 		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.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);
-		this._traces = new TracesResource(this.baseUrl, this.projectApiKey);
+		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;
 	}
@@ -1044,8 +1189,458 @@ function initializeLogger(options) {
 	}));
 }
 //#endregion
-//#region src/utils/file.ts
+//#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: 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";
+/**
+* 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.
+*/
+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");
+}
+/**
+* Read the credentials file. Returns null when missing or not the current flat
+* v1 shape (treated as "not logged in" — `lmnr-cli login` overwrites).
+*/
+async function readCredentials() {
+	const path = credentialsPath();
+	let raw;
+	try {
+		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();
+}
+/**
+* Poll BetterAuth's native token endpoint until the user approves. Returns the
+* full token response (whose `access_token` is the durable session token).
+*/
+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);
+	}
+}
+/**
+* Mint a fresh 15m EdDSA JWT from a session token. Throws DeviceFlowError
+* "invalid_grant" on 401 (session expired/revoked).
+*/
+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 ?? ""
+	};
+}
+/**
+* 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`.
+*/
+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.
 */
@@ -1066,7 +1661,7 @@ const collectFiles = async (paths, recursive = false) => {
 	for (const filepath of paths) try {
 		const stats = await fs_promises.stat(filepath);
 		if (stats.isFile()) if (isSupportedFile(filepath)) collectedFiles.push(filepath);
-		else logger$4.warn(`Skipping unsupported file type: ${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) {
@@ -1080,7 +1675,7 @@ const collectFiles = async (paths, recursive = false) => {
 			}
 		}
 	} catch (error) {
-		logger$4.warn(`Path does not exist or is not accessible: ${filepath}. Error: ${errorMessage(error)}`);
+		logger$3.warn(`Path does not exist or is not accessible: ${filepath}. Error: ${errorMessage(error)}`);
 	}
 	return collectedFiles;
 };
@@ -1102,7 +1697,7 @@ const tryParseJson = (content) => {
 	try {
 		return JSON.parse(content);
 	} catch (error) {
-		logger$4.debug(`Error parsing JSON: ${errorMessage(error)}`);
+		logger$3.debug(`Error parsing JSON: ${errorMessage(error)}`);
 		return content;
 	}
 };
@@ -1130,7 +1725,7 @@ async function readJsonlFile(filepath) {
 /**
 * Read a single file and return its contents.
 */
-async function readFile(filepath) {
+async function readFile$1(filepath) {
 	const ext = path.extname(filepath).toLowerCase();
 	if (ext === ".json") return readJsonFile(filepath);
 	else if (ext === ".csv") return readCsvFile(filepath);
@@ -1143,17 +1738,17 @@ async function readFile(filepath) {
 const loadFromPaths = async (paths, recursive = false) => {
 	const files = await collectFiles(paths, recursive);
 	if (files.length === 0) {
-		logger$4.warn("No supported files found in the specified paths");
+		logger$3.warn("No supported files found in the specified paths");
 		return [];
 	}
-	logger$4.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$4.info(`Read ${data.length} record(s) from ${file}`);
+		logger$3.info(`Read ${data.length} record(s) from ${file}`);
 	} catch (error) {
-		logger$4.error(`Error reading file ${file}: ${errorMessage(error)}`);
+		logger$3.error(`Error reading file ${file}: ${errorMessage(error)}`);
 		throw error;
 	}
 	return result;
@@ -1193,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$4.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);
@@ -1218,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$4.error("No data to print");
+			logger$3.error("No data to print");
 			return;
 		}
 		console.log(formatCsv(data));
@@ -1226,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: errorMessage(error) }));
-	process.exit(exitCode);
-}
-//#endregion
 //#region src/utils/table.ts
 const DEFAULT_TERMINAL_WIDTH = 80;
 const PADDING_RIGHT = 2;
@@ -1305,9 +1883,14 @@ function renderTable(head, rows) {
 }
 //#endregion
 //#region src/commands/dataset/index.ts
-const logger$3 = 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.
 */
@@ -1332,171 +1915,95 @@ 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$3.error(`Failed to list datasets: ${errorMessage(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$3.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$3.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$3.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$3.info(`Pushed ${data.length} data points to dataset ${options.name || options.id}`);
-	} catch (error) {
-		if (options.json) outputJsonError(error);
-		logger$3.error(`Failed to push dataset: ${errorMessage(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$3.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$3.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$3.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$3.error(`Failed to pull dataset: ${errorMessage(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$3.error("No data to push. Skipping");
-			process.exit(1);
-		}
-		logger$3.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$3.info(`Successfully pushed ${data.length} data points to dataset '${name}'`);
-	} catch (error) {
-		if (options.json) outputJsonError(error);
-		logger$3.error(`Failed to create dataset: ${errorMessage(error)}`);
-		process.exit(1);
-	}
-	logger$3.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$3.info(`Successfully created dataset '${name}' and saved ${result.length} datapoints to ${options.outputFile}`);
-	} catch (error) {
-		if (options.json) outputJsonError(error);
-		logger$3.error("Failed to pull dataset after creation: " + errorMessage(error));
-		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
@@ -1533,112 +2040,860 @@ const readNoteFromMetadata = (metadata) => {
 };
 //#endregion
 //#region src/commands/debug/index.ts
-const logger$2 = initializeLogger();
+const logger$1 = initializeLogger();
 /**
 * 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.
 */
-const handleDebugSessionSetName = async (sessionId, name, options) => {
-	const client = new LaminarClient({
-		projectApiKey: options.projectApiKey,
-		baseUrl: options.baseUrl,
-		port: options.port
+const handleDebugSessionSetName = async (client, sessionId, name, opts) => {
+	await client.rolloutSessions.setName({
+		sessionId,
+		name
 	});
-	try {
-		await client.rolloutSessions.setName({
+	if (opts.json) {
+		outputJson({
 			sessionId,
 			name
 		});
-		if (options.json) {
-			outputJson({
-				sessionId,
-				name
-			});
-			return;
-		}
-		logger$2.info(`Set name of session ${sessionId} to "${name}".`);
-	} catch (error) {
-		if (options.json) outputJsonError(error);
-		logger$2.error(`Failed to set session name: ${errorMessage(error)}`);
-		process.exit(1);
+		return;
 	}
+	logger$1.info(`Set name of session ${sessionId} to "${name}".`);
 };
-const SUMMARY_PAGE_SIZE = 1e3;
 /**
 * 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.
+*/
+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);
+}
+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 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/commands/logout/index.ts
+/**
+* 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.
+*/
+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/commands/project/index.ts
+/**
+* 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.
+*/
+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/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;
+}
+/**
+* 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.
+*/
+async function findEnvKey(cwd, varName = DEFAULT_VAR_NAME) {
+	const fromProcess = process.env[varName]?.trim();
+	if (fromProcess) return {
+		value: fromProcess,
+		source: { type: "process-env" }
+	};
+	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
+			}
+		};
+	}
+	return null;
+}
+/**
+* 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 AUTOLOADED_ENV_KEYS = [
+	"LMNR_BASE_URL",
+	"LMNR_HTTP_PORT",
+	"LMNR_FRONTEND_URL"
+];
+/**
+* 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).
+*
+* 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;
+	}
+}
+/**
+* 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 {
+		await execFileAsync("git", [
+			"check-ignore",
+			"-q",
+			path
+		]);
+		return true;
+	} catch (err) {
+		return err.code === 1 ? false : null;
+	}
+}
+async function fileExists(path) {
+	try {
+		await (0, node_fs_promises.access)(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+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";
+/**
+* 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.
+*/
+function skillSource() {
+	return `github:${SKILL_REPO}/skills/${SKILL_NAME}#${SKILL_REF}`;
+}
+//#endregion
+//#region src/skill/fetch-skill.ts
+/**
+* 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.
+*
+* 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 handleDebugSessionSummary = async (sessionId, options) => {
-	const client = new LaminarClient({
-		projectApiKey: options.projectApiKey,
-		baseUrl: options.baseUrl,
-		port: options.port
+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"];
+/**
+* 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.
+*/
+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 traces = [];
-		let offset = 0;
-		for (;;) {
-			const rows = 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 LIMIT {limit:UInt32} OFFSET {offset:UInt32}", {
-				session_id: sessionId,
-				limit: SUMMARY_PAGE_SIZE,
-				offset
+		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
 			});
-			for (const row of rows) traces.push({
-				note: readNoteFromMetadata(row.metadata),
-				traceId: String(row.id ?? ""),
-				endTime: String(row.end_time ?? "")
+			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 {
+			written,
+			defaulted: present.length === 0,
+			skipped: false
+		};
+	} finally {
+		await (0, node_fs_promises.rm)(staging, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+async function dirExists(path) {
+	try {
+		await (0, node_fs_promises.access)(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+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;
+/**
+* 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).
+*/
+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
 			});
-			if (rows.length < SUMMARY_PAGE_SIZE) break;
-			offset += SUMMARY_PAGE_SIZE;
+		} catch (err) {
+			emitError(isJson, "login_failed", describeError(err));
+			process.exit(EXIT_LOGIN_FAILED);
 		}
-		if (options.json) {
-			outputJson(traces);
-			return;
+		creds = await safeReadCredentials();
+		if (!creds) {
+			emitError(isJson, "login_failed", "credentials missing after login");
+			process.exit(EXIT_LOGIN_FAILED);
 		}
-		if (traces.length === 0) {
-			console.log(`No traces found for session ${sessionId}.`);
-			return;
+		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);
+			}
 		}
-		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"));
-	} catch (error) {
-		if (options.json) outputJsonError(error);
-		logger$2.error(`Failed to summarize session: ${errorMessage(error)}`);
-		process.exit(1);
 	}
-};
-//#endregion
-//#region src/commands/sql/index.ts
-const logger$1 = initializeLogger();
-const handleSqlQuery = async (query, options) => {
-	const client = new LaminarClient({
-		projectApiKey: options.projectApiKey,
-		baseUrl: options.baseUrl,
-		port: options.port
+	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`);
+}
+/**
+* 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.
+*/
+async function resolveProjectViaCli(creds, userBaseUrl, issuer, isJson, options) {
+	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.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);
+		}
+		process.stderr.write("\nYou have no projects yet. Opening the browser to create your first one...\n");
+		let login;
+		try {
+			login = await handleLogin({
+				frontendUrl: issuer,
+				noBrowser: options.noBrowser
+			});
+		} catch (err) {
+			emitError(isJson, "login_failed", describeError(err));
+			process.exit(EXIT_LOGIN_FAILED);
+		}
+		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);
+		}
+		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);
+	}
+	const linkPath = await writeProjectLink({
+		projectId: chosen.id,
+		projectName: chosen.name,
+		workspaceId: chosen.workspaceId,
+		workspaceName: chosen.workspaceName
 	});
+	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 {
-		const rows = await client.sql.query(query);
-		if (options.json) {
-			outputJson(rows);
-			return;
+		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
+			};
 		}
-		if (rows.length === 0) {
-			console.log("No rows returned.");
-			return;
+	} 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`);
+	}
+	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: ""
 		}
-		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$1.error(`Query failed: ${errorMessage(error)}`);
-		process.exit(1);
+	}).cli.listProjects();
+}
+async function safeReadCredentials() {
+	try {
+		return await readCredentials();
+	} catch {
+		return null;
+	}
+}
+/** 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 {
+		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`);
+		}
+	} 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
@@ -1698,6 +2953,10 @@ const NOTE_SEPARATOR = "\n\n";
 * 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
@@ -1708,55 +2967,35 @@ const NOTE_SEPARATOR = "\n\n";
 * the metadata patch endpoint that concatenates within the Postgres UPDATE,
 * which already serializes on the trace row lock).
 */
-const handleTraceAppendNote = async (traceId, note, options) => {
-	const client = new LaminarClient({
-		projectApiKey: options.projectApiKey,
-		baseUrl: options.baseUrl,
-		port: options.port
-	});
-	try {
-		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 (options.json) {
-			outputJson({
-				traceId: id,
-				note: updated
-			});
-			return;
-		}
-		logger.info(`Appended note to trace ${id}.`);
-	} catch (error) {
-		if (options.json) outputJsonError(error);
-		logger.error(`Failed to append trace note: ${errorMessage(error)}`);
-		process.exit(1);
+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");
-	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"
@@ -1765,29 +3004,36 @@ Examples:
 	sqlCmd.command("schema").description("Show available tables and their columns").action(() => {
 		process.stdout.write(SQL_SCHEMA_HELP);
 	});
-	program.command("trace").description("Operate on existing traces").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").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(async (traceId, note, _options, cmd) => {
-		await handleTraceAppendNote(traceId, note, cmd.optsWithGlobals());
-	}).addHelpText("after", `
+	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-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").addHelpText("after", `
+	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(async (sessionId, name, _options, cmd) => {
-		await handleDebugSessionSetName(sessionId, name, cmd.optsWithGlobals());
-	}).addHelpText("after", `
+	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(async (sessionId, _options, cmd) => {
-		await handleDebugSessionSummary(sessionId, cmd.optsWithGlobals());
-	}).addHelpText("after", `
+	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:
 
@@ -1802,17 +3048,21 @@ Examples:
 `);
 	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 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
@@ -1820,7 +3070,6 @@ Examples:
 
 For more information about the Laminar platfrom:
   Documentation: https://laminar.sh/docs
-  Dashboard:     https://www.laminar.sh
 `);
 	await program.parseAsync();
 }