@relesio/cli 0.2.6 → 0.3.0

package/README.md

@@ -34,13 +34,22 @@ bun link
 
 ## Quick Start
 
-1. **Authenticate** with your API token:
+1. **Authenticate** via browser (recommended):
 
    ```bash
-   relesio auth login --token rls_your_token_here
+   relesio auth login
    ```
 
-   Or use the `RELESIO_API_TOKEN` environment variable.
+   The CLI prints a short code, opens your browser to `relesio.com/device`, and waits
+   for you to approve. Once approved, a named API key is stored automatically.
+
+   For headless / CI environments, pass an API key directly:
+
+   ```bash
+   relesio auth login --token rls_your_token_here
+   # or set the environment variable
+   export RELESIO_API_TOKEN=rls_your_token_here
+   ```
 
 2. **Upload** a built frontend:
 
@@ -58,12 +67,12 @@ bun link
 
 ### Authentication
 
-| Command               | Description              |
-| --------------------- | ------------------------ |
-| `relesio auth login`  | Authenticate with token  |
-| `relesio auth status` | Show current auth state  |
-| `relesio auth logout` | Clear stored credentials |
-| `relesio whoami`      | Show current user info   |
+| Command               | Description                                      |
+| --------------------- | ------------------------------------------------ |
+| `relesio auth login`  | Authenticate via browser (device flow) or token  |
+| `relesio auth status` | Show current auth state                          |
+| `relesio auth logout` | Clear stored credentials                         |
+| `relesio whoami`      | Show current user info                           |
 
 ### Organizations & Projects
 
@@ -90,17 +99,30 @@ bun link
 ### Authentication
 
 ```bash
-# Interactive login (prompts for token)
+# Browser-based login (recommended — opens relesio.com/device)
 relesio auth login
 
-# With token flag
+# Headless / CI: pass an API key directly
 relesio auth login --token rls_...
 
-# Via environment variable
+# Or export the token as an environment variable
 export RELESIO_API_TOKEN=rls_...
 relesio auth status
 ```
 
+**Device flow steps:**
+
+1. Run `relesio auth login` — a short code is printed in the terminal.
+2. Your browser opens automatically to `https://relesio.com/device`.
+3. Enter the code (or confirm the pre-filled one), then click **Approve**.
+4. The CLI detects the approval, creates a named `rls_*` API key
+   (`CLI - <hostname> - <date>`), and stores it locally.
+5. All subsequent commands use the stored key automatically.
+
+If the browser cannot open (headless server), the URL and code are printed —
+navigate to the URL manually and enter the code. The CLI keeps polling until
+you approve, deny, or the 30-minute code expires.
+
 ### Upload
 
 ```bash
@@ -140,12 +162,12 @@ relesio rollback my-app --env production --yes
 
 ### Environment Variables
 
-| Variable           | Description                             | Default                    |
-| ------------------ | --------------------------------------- | -------------------------- |
-| `RELESIO_API_TOKEN`| API token (starts with `rls_`)          | —                          |
-| `RELESIO_API_URL`  | API base URL                            | `https://api.relesio.com`  |
-| `RELESIO_ORG_ID`   | Override active organization            | —                          |
-| `DEBUG`            | Enable debug output                     | —                          |
+| Variable            | Description                                                     | Default                   |
+| ------------------- | --------------------------------------------------------------- | ------------------------- |
+| `RELESIO_API_TOKEN` | API key (`rls_*`). Bypasses device flow — required for CI/CD.  | —                         |
+| `RELESIO_API_URL`   | Override the API base URL                                       | `https://api.relesio.com` |
+| `RELESIO_ORG_ID`    | Override active organization ID                                 | —                         |
+| `DEBUG`             | Enable verbose debug output                                     | —                         |
 
 ### Organization Context
 

package/dist/commands/auth/__tests__/login.test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Device Authorization Flow — Unit Tests
+ *
+ * Tests the CLI login command's device flow logic including:
+ * - Device code request
+ * - Polling loop with RFC 8628 error handling
+ * - API key exchange
+ * - Org selection after authentication
+ * - Backward-compatible --token login
+ * - Integration tests calling the actual exported functions
+ */
+export {};

package/dist/commands/auth/__tests__/login.test.js

@@ -0,0 +1,450 @@
+/**
+ * Device Authorization Flow — Unit Tests
+ *
+ * Tests the CLI login command's device flow logic including:
+ * - Device code request
+ * - Polling loop with RFC 8628 error handling
+ * - API key exchange
+ * - Org selection after authentication
+ * - Backward-compatible --token login
+ * - Integration tests calling the actual exported functions
+ */
+import { describe, it, expect, beforeEach, afterEach, mock, spyOn } from "bun:test";
+import os from "node:os";
+// Prevent the `open` package from opening real browser tabs during tests.
+mock.module("open", () => ({ default: mock(() => Promise.resolve()) }));
+import { DEVICE_ERROR, saveAuthAndSelectOrg, loginWithToken, loginWithDeviceFlow, deriveFrontendUrl } from "../login.js";
+import { ConfigManager } from "../../../lib/config/manager.js";
+import { RelesioAPIClient } from "../../../lib/api/client.js";
+// --------------- Helpers ---------------
+function makeDeviceCodeResponse(overrides) {
+    return {
+        device_code: "dev_abc123",
+        user_code: "ABCD-1234",
+        verification_uri: "https://relesio.com/device",
+        verification_uri_complete: "https://relesio.com/device?user_code=ABCD-1234",
+        expires_in: 1800,
+        interval: 5,
+        ...overrides
+    };
+}
+function makeErrorResponse(error, description) {
+    return { error, error_description: description };
+}
+function makeFetchResponse(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "Content-Type": "application/json" }
+    });
+}
+function makeMeResponse(overrides) {
+    return {
+        message: "ok",
+        data: {
+            userId: "user_123",
+            email: "user@example.com",
+            name: "Test User",
+            activeOrganizationId: "org_123",
+            activeOrganizationName: "Test Org",
+            activeOrganizationSlug: "test-org",
+            organizations: [
+                {
+                    id: "org_123",
+                    name: "Test Org",
+                    slug: "test-org",
+                    role: "OWNER"
+                }
+            ],
+            apiKey: {
+                id: "key_1",
+                name: "CLI - host - 2026-03-01",
+                metadata: null
+            },
+            ...(overrides?.organizations !== undefined
+                ? { organizations: overrides.organizations }
+                : {}),
+            ...(overrides?.activeOrganizationId !== undefined
+                ? { activeOrganizationId: overrides.activeOrganizationId }
+                : {})
+        }
+    };
+}
+// --------------- Unit Tests ---------------
+describe("Device Authorization Flow", () => {
+    describe("RFC 8628 Error Codes", () => {
+        it("should define all required error codes", () => {
+            expect(DEVICE_ERROR.PENDING).toBe("authorization_pending");
+            expect(DEVICE_ERROR.SLOW_DOWN).toBe("slow_down");
+            expect(DEVICE_ERROR.DENIED).toBe("access_denied");
+            expect(DEVICE_ERROR.EXPIRED).toBe("expired_token");
+        });
+    });
+    describe("Device Code Request", () => {
+        it("should parse device code response correctly", () => {
+            const response = makeDeviceCodeResponse();
+            expect(response.device_code).toBe("dev_abc123");
+            expect(response.user_code).toBe("ABCD-1234");
+            expect(response.verification_uri).toBe("https://relesio.com/device");
+            expect(response.verification_uri_complete).toContain("user_code=ABCD-1234");
+            expect(response.expires_in).toBe(1800);
+            expect(response.interval).toBe(5);
+        });
+        it("should use default interval of 5 when not provided", () => {
+            const response = makeDeviceCodeResponse({
+                interval: undefined
+            });
+            const pollingIntervalMs = (response.interval ?? 5) * 1000;
+            expect(pollingIntervalMs).toBe(5000);
+        });
+        it("should use default expires_in of 1800 when not provided", () => {
+            const response = makeDeviceCodeResponse({
+                expires_in: undefined
+            });
+            const expiresIn = response.expires_in ?? 1800;
+            expect(expiresIn).toBe(1800);
+        });
+    });
+    describe("Polling Logic", () => {
+        it("should continue polling on authorization_pending", () => {
+            const errorBody = makeErrorResponse(DEVICE_ERROR.PENDING);
+            const shouldContinue = errorBody.error === DEVICE_ERROR.PENDING;
+            expect(shouldContinue).toBe(true);
+        });
+        it("should add 5 seconds to interval on slow_down (RFC 8628 §3.5)", () => {
+            let currentInterval = 5000;
+            const errorBody = makeErrorResponse(DEVICE_ERROR.SLOW_DOWN);
+            if (errorBody.error === DEVICE_ERROR.SLOW_DOWN) {
+                currentInterval += 5000;
+            }
+            expect(currentInterval).toBe(10000);
+        });
+        it("should add 5s cumulatively on repeated slow_down", () => {
+            let currentInterval = 5000;
+            for (let i = 0; i < 3; i++) {
+                currentInterval += 5000;
+            }
+            expect(currentInterval).toBe(20000);
+        });
+        it("should exit with code 1 on access_denied", () => {
+            const errorBody = makeErrorResponse(DEVICE_ERROR.DENIED);
+            const shouldExit = errorBody.error === DEVICE_ERROR.DENIED;
+            expect(shouldExit).toBe(true);
+        });
+        it("should exit with code 1 on expired_token", () => {
+            const errorBody = makeErrorResponse(DEVICE_ERROR.EXPIRED);
+            const shouldExit = errorBody.error === DEVICE_ERROR.EXPIRED;
+            expect(shouldExit).toBe(true);
+        });
+        it("should enforce client-side deadline with 30s buffer", () => {
+            const expiresIn = 1800;
+            const now = Date.now();
+            const deadline = now + (expiresIn + 30) * 1000;
+            expect(deadline - now).toBe(1830 * 1000);
+        });
+        it("should apply minimum 60s floor to expires_in to guard against malformed server responses", () => {
+            // Mirrors the production code: Math.max(deviceCodeData.expires_in ?? 1800, 60)
+            const applyExpiresFloor = (v) => Math.max(v ?? 1800, 60);
+            expect(applyExpiresFloor(0)).toBe(60);
+            expect(applyExpiresFloor(30)).toBe(60);
+            expect(applyExpiresFloor(undefined)).toBe(1800);
+            expect(applyExpiresFloor(1800)).toBe(1800);
+        });
+        it("should not sleep before the first poll (immediate first check)", () => {
+            let isFirstPoll = true;
+            const sleepCalls = [];
+            const mockSleep = (ms) => {
+                sleepCalls.push(ms);
+            };
+            if (!isFirstPoll) {
+                mockSleep(5000);
+            }
+            isFirstPoll = false;
+            if (!isFirstPoll) {
+                mockSleep(5000);
+            }
+            expect(sleepCalls).toHaveLength(1);
+            expect(sleepCalls[0]).toBe(5000);
+        });
+    });
+    describe("API Key Exchange", () => {
+        it("should generate correct key name with hostname and date", () => {
+            const hostname = os.hostname();
+            const date = new Date().toISOString().slice(0, 10);
+            const keyName = `CLI - ${hostname} - ${date}`;
+            expect(keyName).toContain("CLI - ");
+            expect(keyName).toContain(hostname);
+            expect(keyName).toMatch(/\d{4}-\d{2}-\d{2}$/);
+        });
+        it("should send Bearer token in Authorization header for key exchange", () => {
+            const accessToken = "test_access_token_xyz";
+            const headers = {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${accessToken}`
+            };
+            expect(headers.Authorization).toBe(`Bearer ${accessToken}`);
+        });
+    });
+    describe("Browser Open", () => {
+        it("should open the derived dashboard URL with user_code appended", () => {
+            const apiBaseUrl = "https://api.relesio.com";
+            const userCode = "ABCD-1234";
+            const frontendBase = deriveFrontendUrl(apiBaseUrl);
+            const browserUri = `${frontendBase}/device?user_code=${userCode}`;
+            expect(browserUri).toBe("https://relesio.com/device?user_code=ABCD-1234");
+        });
+        it("should derive localhost:3000 browser URL when API is on localhost", () => {
+            const apiBaseUrl = "http://localhost:8787";
+            const userCode = "WXYZ-5678";
+            const frontendBase = deriveFrontendUrl(apiBaseUrl);
+            const browserUri = `${frontendBase}/device?user_code=${userCode}`;
+            expect(browserUri).toBe("http://localhost:3000/device?user_code=WXYZ-5678");
+        });
+    });
+    describe("deriveFrontendUrl", () => {
+        it("maps api.relesio.com to relesio.com", () => {
+            expect(deriveFrontendUrl("https://api.relesio.com")).toBe("https://relesio.com");
+        });
+        it("maps api-stage.relesio.com to stage.relesio.com", () => {
+            expect(deriveFrontendUrl("https://api-stage.relesio.com")).toBe("https://stage.relesio.com");
+        });
+        it("maps localhost:8787 to localhost:3000 preserving protocol", () => {
+            expect(deriveFrontendUrl("http://localhost:8787")).toBe("http://localhost:3000");
+        });
+        it("maps 127.0.0.1 to localhost:3000 preserving protocol", () => {
+            expect(deriveFrontendUrl("http://127.0.0.1:8787")).toBe("http://localhost:3000");
+        });
+        it("passes through unknown API hosts unchanged", () => {
+            expect(deriveFrontendUrl("https://custom.api.example.com")).toBe("https://custom.api.example.com");
+        });
+        it("returns the input unchanged when URL is invalid", () => {
+            expect(deriveFrontendUrl("not-a-valid-url")).toBe("not-a-valid-url");
+        });
+    });
+});
+// --------------- Integration Tests: saveAuthAndSelectOrg ---------------
+describe("saveAuthAndSelectOrg (integration)", () => {
+    let saveSpy;
+    let originalFetch;
+    beforeEach(() => {
+        originalFetch = globalThis.fetch;
+        saveSpy = spyOn(ConfigManager, "save").mockImplementation(() => { });
+    });
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+        saveSpy.mockRestore();
+    });
+    it("stores activeOrganizationId directly when already set in response", async () => {
+        const meData = makeMeResponse().data;
+        await saveAuthAndSelectOrg("rls_test_key", meData);
+        expect(saveSpy).toHaveBeenCalledTimes(1);
+        const savedArgs = saveSpy.mock.calls[0][0];
+        expect(savedArgs.apiToken).toBe("rls_test_key");
+        expect(savedArgs.activeOrganizationId).toBe("org_123");
+        expect(savedArgs.userEmail).toBe("user@example.com");
+    });
+    it("auto-selects the only org when activeOrganizationId is null", async () => {
+        const meData = {
+            ...makeMeResponse().data,
+            activeOrganizationId: null,
+            activeOrganizationName: null,
+            activeOrganizationSlug: null,
+            organizations: [
+                {
+                    id: "org_solo",
+                    name: "Solo Org",
+                    slug: "solo-org",
+                    role: "OWNER"
+                }
+            ]
+        };
+        await saveAuthAndSelectOrg("rls_solo_key", meData);
+        const saved = saveSpy.mock.calls[0][0];
+        expect(saved.activeOrganizationId).toBe("org_solo");
+        expect(saved.activeOrganizationName).toBe("Solo Org");
+        expect(saved.activeOrganizationSlug).toBe("solo-org");
+        // Legacy fields kept in sync
+        expect(saved.currentOrgId).toBe("org_solo");
+    });
+    it("saves with null org when organizations array is empty", async () => {
+        const meData = {
+            ...makeMeResponse().data,
+            activeOrganizationId: null,
+            activeOrganizationName: null,
+            activeOrganizationSlug: null,
+            organizations: []
+        };
+        await saveAuthAndSelectOrg("rls_no_org", meData);
+        const saved = saveSpy.mock.calls[0][0];
+        expect(saved.activeOrganizationId).toBeNull();
+        expect(saved.apiToken).toBe("rls_no_org");
+    });
+    it("stored config has matching legacy fields (currentOrgId = activeOrganizationId)", async () => {
+        const meData = makeMeResponse().data;
+        await saveAuthAndSelectOrg("rls_compat_key", meData);
+        const saved = saveSpy.mock.calls[0][0];
+        expect(saved.currentOrgId).toBe(saved.activeOrganizationId);
+        expect(saved.currentOrgName).toBe(saved.activeOrganizationName);
+    });
+});
+// --------------- Integration Tests: loginWithToken ---------------
+describe("loginWithToken (integration)", () => {
+    let saveSpy;
+    let clientGetSpy;
+    beforeEach(() => {
+        saveSpy = spyOn(ConfigManager, "save").mockImplementation(() => { });
+    });
+    afterEach(() => {
+        saveSpy.mockRestore();
+        clientGetSpy?.mockRestore();
+    });
+    it("validates token against /v1/api-token/me and saves config on success", async () => {
+        // RelesioAPIClient uses undici internally, so spy on the prototype method
+        clientGetSpy = spyOn(RelesioAPIClient.prototype, "get").mockResolvedValue(makeMeResponse());
+        await loginWithToken("rls_valid_token", "https://api.relesio.com");
+        expect(clientGetSpy).toHaveBeenCalledWith("/v1/api-token/me", expect.objectContaining({
+            headers: { "x-api-key": "rls_valid_token" }
+        }));
+        expect(saveSpy).toHaveBeenCalledTimes(1);
+        const saved = saveSpy.mock.calls[0][0];
+        expect(saved.apiToken).toBe("rls_valid_token");
+        expect(saved.userEmail).toBe("user@example.com");
+        expect(saved.activeOrganizationId).toBe("org_123");
+    });
+    it("throws on non-ok response from /v1/api-token/me", async () => {
+        clientGetSpy = spyOn(RelesioAPIClient.prototype, "get").mockRejectedValue(new Error("Unauthorized"));
+        await expect(loginWithToken("rls_bad_token", "https://api.relesio.com")).rejects.toThrow("Unauthorized");
+        expect(saveSpy).not.toHaveBeenCalled();
+    });
+});
+// --------------- Integration Tests: loginWithDeviceFlow ---------------
+//
+// loginWithDeviceFlow uses globalThis.fetch for the device code endpoints (raw RFC 8628 calls)
+// and RelesioAPIClient (undici) for /v1/api-token/me. We mock both separately.
+describe("loginWithDeviceFlow (integration)", () => {
+    let originalFetch;
+    let saveSpy;
+    let exitSpy;
+    let clientGetSpy;
+    beforeEach(() => {
+        originalFetch = globalThis.fetch;
+        saveSpy = spyOn(ConfigManager, "save").mockImplementation(() => { });
+        // Intercept process.exit to prevent it from terminating the test process
+        exitSpy = spyOn(process, "exit").mockImplementation((() => {
+            throw new Error("process.exit called");
+        }));
+    });
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+        saveSpy.mockRestore();
+        exitSpy.mockRestore();
+        clientGetSpy?.mockRestore();
+    });
+    it("completes full flow: pending×2 → approval → key exchange → /me → saves config", async () => {
+        let pollCount = 0;
+        // /api/auth/device/* calls go through globalThis.fetch (raw fetch in login.ts)
+        globalThis.fetch = mock((url) => {
+            const urlStr = typeof url === "string" ? url : url.toString();
+            if (urlStr.includes("/api/auth/device/code")) {
+                return Promise.resolve(makeFetchResponse(200, makeDeviceCodeResponse({ interval: 0 })));
+            }
+            if (urlStr.includes("/api/auth/device/token")) {
+                pollCount++;
+                if (pollCount <= 2) {
+                    return Promise.resolve(makeFetchResponse(400, makeErrorResponse(DEVICE_ERROR.PENDING)));
+                }
+                return Promise.resolve(makeFetchResponse(200, {
+                    access_token: "at_xyz789",
+                    token_type: "Bearer"
+                }));
+            }
+            if (urlStr.includes("/api/auth/api-key/create")) {
+                return Promise.resolve(makeFetchResponse(200, {
+                    key: "rls_device_key",
+                    id: "key_1",
+                    name: "CLI - host"
+                }));
+            }
+            return Promise.resolve(makeFetchResponse(404, { error: "unexpected url in test" }));
+        });
+        // /v1/api-token/me goes through RelesioAPIClient (undici) — spy on the prototype
+        clientGetSpy = spyOn(RelesioAPIClient.prototype, "get").mockResolvedValue(makeMeResponse());
+        await loginWithDeviceFlow("https://api.relesio.com");
+        // Polling ran at least 3 times (2 pending + 1 success)
+        expect(pollCount).toBeGreaterThanOrEqual(3);
+        // ConfigManager.save was called with the rls_* key from key exchange
+        expect(saveSpy).toHaveBeenCalledTimes(1);
+        const saved = saveSpy.mock.calls[0][0];
+        expect(saved.apiToken).toBe("rls_device_key");
+        expect(saved.userEmail).toBe("user@example.com");
+        expect(saved.activeOrganizationId).toBe("org_123");
+    });
+    it("exits with code 1 when device request is denied", async () => {
+        globalThis.fetch = mock((url) => {
+            const urlStr = typeof url === "string" ? url : url.toString();
+            if (urlStr.includes("/api/auth/device/code")) {
+                return Promise.resolve(makeFetchResponse(200, makeDeviceCodeResponse({ interval: 0 })));
+            }
+            return Promise.resolve(makeFetchResponse(400, makeErrorResponse(DEVICE_ERROR.DENIED)));
+        });
+        await expect(loginWithDeviceFlow("https://api.relesio.com")).rejects.toThrow("process.exit called");
+        expect(exitSpy).toHaveBeenCalledWith(1);
+        expect(saveSpy).not.toHaveBeenCalled();
+    });
+    it("exits with code 1 when device code expires", async () => {
+        globalThis.fetch = mock((url) => {
+            const urlStr = typeof url === "string" ? url : url.toString();
+            if (urlStr.includes("/api/auth/device/code")) {
+                return Promise.resolve(makeFetchResponse(200, makeDeviceCodeResponse({ interval: 0 })));
+            }
+            return Promise.resolve(makeFetchResponse(400, makeErrorResponse(DEVICE_ERROR.EXPIRED)));
+        });
+        await expect(loginWithDeviceFlow("https://api.relesio.com")).rejects.toThrow("process.exit called");
+        expect(exitSpy).toHaveBeenCalledWith(1);
+        expect(saveSpy).not.toHaveBeenCalled();
+    });
+    it("exits with code 1 when key exchange fails (401) after device approval", async () => {
+        globalThis.fetch = mock((url) => {
+            const urlStr = typeof url === "string" ? url : url.toString();
+            if (urlStr.includes("/api/auth/device/code")) {
+                return Promise.resolve(makeFetchResponse(200, makeDeviceCodeResponse({ interval: 0 })));
+            }
+            if (urlStr.includes("/api/auth/device/token")) {
+                return Promise.resolve(makeFetchResponse(200, {
+                    access_token: "at_short_lived",
+                    token_type: "Bearer"
+                }));
+            }
+            // /api/auth/api-key/create → 401
+            return Promise.resolve(makeFetchResponse(401, { error: "Unauthorized" }));
+        });
+        await expect(loginWithDeviceFlow("https://api.relesio.com")).rejects.toThrow("process.exit called");
+        expect(exitSpy).toHaveBeenCalledWith(1);
+        expect(saveSpy).not.toHaveBeenCalled();
+    });
+    it("throws on /device/code endpoint server error", async () => {
+        globalThis.fetch = mock(() => Promise.resolve(makeFetchResponse(500, { error: "Server error" })));
+        await expect(loginWithDeviceFlow("https://api.relesio.com")).rejects.toThrow();
+        expect(saveSpy).not.toHaveBeenCalled();
+    });
+});
+// --------------- Backward Compatibility ---------------
+describe("Backward Compatibility", () => {
+    it("should prefer --token flag when provided", () => {
+        const options = { token: "rls_explicit_token" };
+        const envToken = undefined;
+        const token = options.token || envToken;
+        expect(token).toBe("rls_explicit_token");
+    });
+    it("should fall back to RELESIO_API_TOKEN env var", () => {
+        const options = { token: undefined };
+        const envToken = "rls_env_token";
+        const token = options.token || envToken;
+        expect(token).toBe("rls_env_token");
+    });
+    it("should trigger device flow when no token provided", () => {
+        const options = { token: undefined };
+        const envToken = undefined;
+        const token = options.token || envToken;
+        expect(token).toBeFalsy();
+    });
+});

package/dist/commands/auth/login.d.ts

@@ -1,2 +1,79 @@
 import { Command } from "commander";
+export interface ApiKeyMeResponse {
+    message: string;
+    data: {
+        userId: string;
+        email: string;
+        name: string | null;
+        activeOrganizationId: string | null;
+        activeOrganizationName: string | null;
+        activeOrganizationSlug: string | null;
+        organizations: Array<{
+            id: string;
+            name: string;
+            slug: string;
+            role: string;
+        }>;
+        apiKey: {
+            id: string;
+            name: string | null;
+            metadata: Record<string, unknown> | null;
+        };
+    };
+}
+export interface DeviceCodeResponse {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete?: string;
+    expires_in: number;
+    interval: number;
+}
+export interface DeviceTokenSuccessResponse {
+    access_token: string;
+    token_type: string;
+}
+export interface DeviceTokenErrorResponse {
+    error: string;
+    error_description?: string;
+}
+export interface ApiKeyCreateResponse {
+    key: string;
+    id: string;
+    name: string | null;
+}
+/** RFC 8628 §3.5 error codes */
+export declare const DEVICE_ERROR: {
+    readonly PENDING: "authorization_pending";
+    readonly SLOW_DOWN: "slow_down";
+    readonly DENIED: "access_denied";
+    readonly EXPIRED: "expired_token";
+};
 export declare const loginCommand: Command;
+/** Exported for unit testing — not part of the public CLI API. */
+export declare function loginWithToken(token: string, apiBaseUrl: string): Promise<void>;
+/** Exported for unit testing — not part of the public CLI API. */
+export declare function loginWithDeviceFlow(apiBaseUrl: string): Promise<void>;
+export interface ResolvedOrg {
+    activeOrganizationId: string | null;
+    activeOrganizationName: string | null;
+    activeOrganizationSlug: string | null;
+}
+/**
+ * Org-selection logic applied after both device flow and --token login.
+ * Implements the logic from Technical Notes §9.
+ *
+ * Returns the resolved org values so the caller can display them without a
+ * second disk read. Exported for unit testing — not part of the public CLI API.
+ */
+export declare function saveAuthAndSelectOrg(apiToken: string, data: ApiKeyMeResponse["data"]): Promise<ResolvedOrg>;
+/**
+ * Maps an API base URL to its corresponding dashboard (frontend) URL.
+ *
+ * Used by the device flow to derive the correct dashboard domain from
+ * RELESIO_API_URL, independent of what FRONTEND_URL the API server is
+ * configured with.
+ *
+ * Exported for unit testing — not part of the public CLI API.
+ */
+export declare function deriveFrontendUrl(apiBaseUrl: string): string;