@kairon/cli 0.1.0

package/README.md

@@ -0,0 +1,212 @@
+# `@kairon/cli` — Kairon from a terminal
+
+The second programmatic door (PRD-57, ADR-0054 §7). It is an **MCP client**, not a
+second API: every command goes through `POST /mcp` on a real Kairon, so a CLI call
+and an agent call are the same call — the same `channel_action` ledger row with
+`source: 'mcp'`, the same daily caps, the same [[Limit Override]]s. MCP is the door
+for a *model*; this is the door for a *script*.
+
+Nothing here has its own surface to keep in sync. Commands are generated from the
+server's `tools/list`, so the CLI cannot drift from the tools.
+
+## Install
+
+```bash
+npm i -g @kairon/cli     # then: kairon login
+npx @kairon/cli whoami   # or run it once, installing nothing
+```
+
+Needs Node ≥ 22.23.1. Working on the CLI itself:
+
+```bash
+pnpm --filter @kairon/cli build     # dist/index.js, the `kairon` binary
+pnpm --filter @kairon/cli kairon -- whoami   # run from source with tsx
+pnpm --filter @kairon/cli test
+```
+
+### Releasing
+
+`.github/workflows/release-cli.yml` publishes on a `cli-v*` tag, and refuses if the tag
+disagrees with `package.json`. The token lives in the `NPM_TOKEN` repository secret and
+nowhere else — never in a committed `.npmrc`, which would put it in every clone and
+every fork.
+
+```bash
+pnpm --filter @kairon/cli exec npm version minor   # bump, and mirror it in src/version.ts
+git tag cli-v0.2.0 && git push origin cli-v0.2.0
+```
+
+`version.ts` is checked against `package.json` by a spec, because `kairon --version` and
+the MCP client handshake both report the constant: if they drift, every bug report cites
+a version that does not exist. Run the workflow manually (`workflow_dispatch`) to
+rehearse a release — it builds, tests and packs without publishing.
+
+## Commands
+
+There is **no command list in this package.** A tool's name is its command: split on
+the first `_`, kebab-case the rest.
+
+```
+list_add                → kairon list add
+campaign_run_get        → kairon campaign run-get
+search_sales_navigator  → kairon search sales-navigator
+```
+
+That absence is the design, and `no-command-table.spec.ts` is there to keep it —
+it greps these sources for tool-name-shaped literals and fails on any of them. A
+table would be a second definition of the surface, and a second definition drifts:
+add a tool server-side, forget the entry, and a command silently doesn't exist.
+
+Flags come from the tool's JSON Schema. Scalars are `--flag`; nested objects are dot
+paths; arrays and unions take JSON, because there is no honest flat spelling for
+"an array of either a memberId or a url". `--json` passes the whole input.
+
+```bash
+kairon chat list --unread                                  # scalar
+kairon signal search --signal posted_with_keyword \
+  --config.keyword "platform migration"                    # nested
+kairon list add --asset leads --id list_… \
+  --items '[{"url":"https://linkedin.com/in/ada"}]'        # array as JSON
+kairon list create --json '{"asset":"leads","name":"Q3"}'  # the escape hatch
+```
+
+Input is checked against the cached schema **before** any network call, so a typo
+costs nothing and names itself:
+
+```
+$ kairon list list --aset leads
+Unknown option "--aset" for "kairon list list".
+
+  Did you mean --asset?
+```
+
+`tools/list` is cached per server URL under `~/.kairon/tools/`, so `--help` works
+offline — and before you have ever logged in. `--refresh` re-fetches; there is no
+TTL, because a tool set changes on deploy, not on a schedule.
+
+## Output
+
+The result is JSON on **stdout**; everything a human reads is on **stderr**. So this
+works with no flags:
+
+```bash
+kairon campaign stats --id camp_… | jq '.funnel'
+```
+
+A failed tool exits non-zero, writes **nothing** to stdout, and leads with the
+`AppException` code — the stable thing to branch on (ADR-0004):
+
+```
+$ kairon list get --asset leads --id list_01… ; echo "exit=$?"
+kairon list get failed: COMMON_NOT_FOUND
+{
+  "code": "COMMON_NOT_FOUND",
+  "params": { "resource": "lead_list" },
+  "detail": "No lead list list_01… in this org"
+}
+exit=1
+```
+
+One rough edge, verified live and **not** the CLI's to fix: a *malformed* id (bad
+prefix, wrong shape) escapes the API as a raw `TypeID` error rather than an
+`AppException`, so it arrives as `unknown_error` with prose instead of a code. It is
+legible, but it is not the contract. Tracked as KAI-430 — it affects every MCP
+caller, not just this one.
+
+## Auth
+
+`kairon login` runs OAuth 2.1 authorization code + PKCE with Dynamic Client
+Registration against the same authorization server the Claude connector uses. There
+is no API key, and that is a decision, not a gap (ADR-0017 §2).
+
+```bash
+kairon login                                  # production
+kairon login --server http://localhost:3055   # a local API
+kairon whoami
+kairon logout
+```
+
+Credentials live in `~/.kairon/config.json` at mode `0600`, keyed by server, so a
+dev login never disturbs the production one. Access tokens (30d) refresh silently;
+when the refresh token (90d) finally dies you get one sentence and the command to
+run, not a stack trace.
+
+**Headless** — CI, cron, a container:
+
+```bash
+KAIRON_TOKEN=<access token> kairon whoami     # no ~/.kairon needed at all
+```
+
+| Variable | What it does |
+|---|---|
+| `KAIRON_API_URL` | Default server; `--server` beats it, production is the fallback |
+| `KAIRON_TOKEN` | Use this access token and ignore stored credentials entirely |
+| `KAIRON_CONFIG_DIR` | Where credentials live (default `~/.kairon`) |
+
+Two things the server does **not** offer, which shape the client:
+
+- **No JWKS.** Access tokens are opaque and introspected server-side, so the CLI
+  cannot validate one locally — it finds out on the call.
+- **No revocation endpoint.** `kairon logout` deletes the local credentials; the
+  access token stays valid on the server until it expires. The command says so
+  rather than implying a revocation that didn't happen.
+
+## Signing in against a local Kairon
+
+**Point `BETTER_AUTH_URL` at the web origin, not the bare API port.** Otherwise no
+MCP client can authenticate locally — this CLI or the Claude connector — and the
+symptom is silent: sign-in appears to succeed and the authorize endpoint bounces
+back to the login page forever.
+
+The cause is an origin split that only exists in dev. The web app reaches the API
+through Vite's proxy on its *own* origin (`auth-client.ts` sets no `baseURL`), so
+Better Auth's session cookie is host-only on `https://<worktree>.kairon.localhost`.
+A `BETTER_AUTH_URL` of `http://localhost:<port>` then advertises
+`authorization_endpoint` on a **different origin**, which that cookie never reaches.
+Production has no such split — `app.heykairon.com` serves the SPA and the API
+together — so the one-origin shape is also the truthful local rehearsal.
+
+`vite.config.ts` proxies `/mcp` and `/.well-known/*` for exactly this reason. With
+that in place:
+
+```bash
+BETTER_AUTH_URL=https://<worktree>.kairon.localhost pnpm dev
+NODE_EXTRA_CA_CERTS=~/.portless/ca.pem \
+  kairon login --server https://<worktree>.kairon.localhost
+```
+
+`NODE_EXTRA_CA_CERTS` is needed because portless serves its own certificate, which
+Node does not trust by default. Two gotchas worth knowing:
+
+- Changing `BETTER_AUTH_URL`'s **scheme** invalidates any existing browser session.
+  Better Auth derives the cookie *name* from it (`better-auth.session_token` over
+  http, `__Secure-better-auth.session_token` over https), so the old cookie is not
+  so much rejected as never looked for. Sign in again.
+- The whole flow was verified end to end this way on 2026-07-25 against real Better
+  Auth: DCR, PKCE authorize, code exchange (a refresh token *is* issued for
+  `offline_access`, with the 30-day access-token TTL from ADR-0017), silent refresh,
+  `whoami`, and `logout`.
+
+## Tests
+
+`src/testing/fake-kairon.ts` is a real HTTP server speaking the same wire protocol
+the API does — discovery, DCR, `authorize`, `token`, `GET /mcp/me`, and an actual
+stateless MCP endpoint. The specs drive the whole browser round trip over sockets,
+including a fake "browser" that follows the 302 into the CLI's loopback listener.
+
+That is deliberate. A mocked `fetch` would pass while being wrong in every way that
+actually bites: a redirect that never fires, a `code_verifier` that hashes to
+something else, a loopback port the browser can't reach, an MCP handshake the SDK
+rejects. The fake is strict exactly where the client could be wrong — PKCE
+verification, exact redirect-URI matching, `state`, bearer checks. Its tool schemas
+are copied from a real `tools/list`, so flag derivation meets the shapes it will
+actually meet: a nested object, an enum, an array of a union.
+
+The command surface was also driven against a **real local Kairon** (2026-07-26):
+32 tools discovered and cached, `list create` → `list list` → `list delete` round
+trip, `| jq` with no flags, `COMMON_NOT_FOUND` surfaced with exit 1 and an empty
+stdout, and a typo refused before any connection. Rendering the *production*
+catalogue's help is what caught the one real bug in this slice: `--help` listed
+`--annualRevenue.currency` and two siblings as **required**, because a leaf inside
+an optional object was being read as required on its own. Nested requiredness now
+depends on every ancestor.

package/dist/args.js

@@ -0,0 +1,80 @@
+import { CliError } from './errors.js';
+/**
+ * A ~40-line argv parser instead of a dependency.
+ *
+ * Slice 2 (KAI-415) generates commands from the server's `tools/list`, so the
+ * flags this has to accept are not known at build time — they're whatever the
+ * MCP input schemas say. A parser that hands back a plain `flags` bag is a
+ * better fit for that than a library whose model is "declare your options up
+ * front", and it keeps the CLI's dependency list at exactly one (the MCP SDK).
+ *
+ * Accepts `--flag value`, `--flag=value`, `--bool`, and `--no-bool`. A bare `--`
+ * ends flag parsing, so a value that looks like a flag can still be passed.
+ */
+export function parseArgs(argv) {
+    const positionals = [];
+    const flags = {};
+    let command;
+    let literal = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === undefined)
+            continue;
+        if (literal || !arg.startsWith('-')) {
+            if (command === undefined && !literal)
+                command = arg;
+            else
+                positionals.push(arg);
+            continue;
+        }
+        if (arg === '--') {
+            literal = true;
+            continue;
+        }
+        // `-h` / `-v` are the only short flags; everything else is long-form, because
+        // generated tool flags come from schema keys and those are words, not letters.
+        if (!arg.startsWith('--')) {
+            const short = arg.slice(1);
+            if (short === 'h')
+                flags.help = true;
+            else if (short === 'v')
+                flags.version = true;
+            else
+                throw new CliError(`Unknown option "${arg}".`, 'kairon --help');
+            continue;
+        }
+        const body = arg.slice(2);
+        if (body.length === 0)
+            throw new CliError('Empty option "--".', 'kairon --help');
+        const eq = body.indexOf('=');
+        if (eq !== -1) {
+            flags[body.slice(0, eq)] = body.slice(eq + 1);
+            continue;
+        }
+        if (body.startsWith('no-')) {
+            flags[body.slice(3)] = false;
+            continue;
+        }
+        // A following token is this flag's value unless it is itself a flag, which
+        // makes `--server` with nothing after it an error rather than a silent `true`.
+        const next = argv[i + 1];
+        if (next !== undefined && !next.startsWith('-')) {
+            flags[body] = next;
+            i += 1;
+        }
+        else {
+            flags[body] = true;
+        }
+    }
+    return { command, positionals, flags };
+}
+/** Read a flag that must carry a string value, so `--server` alone fails loudly. */
+export function stringFlag(flags, name) {
+    const value = flags[name];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new CliError(`--${name} needs a value.`, `kairon --${name} <value>`);
+    }
+    return value;
+}

package/dist/browser.js

@@ -0,0 +1,33 @@
+import { spawn } from 'node:child_process';
+/**
+ * Open a URL in the user's browser, best-effort.
+ *
+ * Best-effort is the whole design: `login` prints the URL before calling this and
+ * keeps waiting on the loopback listener either way, so a headless box, an SSH
+ * session, or a locked-down desktop degrades to "paste this link" instead of
+ * hanging on a browser that was never going to appear. Nothing here is awaited or
+ * checked for that reason.
+ */
+export function openBrowser(url) {
+    const [command, args] = process.platform === 'darwin'
+        ? ['open', [url]]
+        : process.platform === 'win32'
+            ? // `start` is a cmd builtin, and its first quoted argument is the window
+                // title — hence the empty string, or a URL with spaces becomes the title
+                // and nothing opens.
+                ['cmd', ['/c', 'start', '', url]]
+            : ['xdg-open', [url]];
+    try {
+        const child = spawn(command, args, {
+            stdio: 'ignore',
+            detached: true,
+        });
+        child.on('error', () => {
+            /* No browser on this machine. The printed URL is the fallback. */
+        });
+        child.unref();
+    }
+    catch {
+        /* Same. */
+    }
+}

package/dist/catalogue.js

@@ -0,0 +1,99 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { connectMcp } from './client.js';
+import { configDir } from './config.js';
+import { resolveAccessToken } from './session.js';
+/**
+ * Where one server's catalogue is cached.
+ *
+ * Keyed by server URL, so a dev Kairon and production never answer for each other —
+ * they legitimately have different tool sets mid-refactor, and a shared cache would
+ * make `--help` lie about whichever you used last. The URL is percent-encoded into a
+ * single filename rather than split into directories: it keeps `~/.kairon/tools/`
+ * flat and greppable, and the encoding is reversible if anyone needs to know what a
+ * file is for.
+ */
+export function cataloguePath(server, env = process.env) {
+    return join(configDir(env), 'tools', `${encodeURIComponent(server)}.json`);
+}
+/**
+ * The tool catalogue for a server (MR57).
+ *
+ * Cache-first, because `--help` is the command a user runs most and it should not
+ * need a network — or a login. `--refresh` re-fetches, and so does a cache miss.
+ *
+ * The cache never expires on a timer. A tool set changes on deploy, not on a
+ * schedule, so a TTL would only ever be wrong in one of two directions: too short
+ * and every help is a round trip, too long and `--refresh` is the real fix anyway.
+ * Making staleness the user's explicit call is both simpler and more honest than a
+ * number pretending to know how often we ship.
+ */
+export async function loadCatalogue(server, opts = {}) {
+    const env = opts.env ?? process.env;
+    if (!opts.refresh) {
+        const cached = await readCatalogue(server, env);
+        if (cached)
+            return cached;
+    }
+    const tools = await fetchCatalogue(server, env);
+    await writeCatalogue(server, tools, env);
+    return tools;
+}
+/** The cached catalogue, or undefined when absent, unreadable, or for another server. */
+export async function readCatalogue(server, env = process.env) {
+    let raw;
+    try {
+        raw = await readFile(cataloguePath(server, env), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        // A cache holds nothing that cannot be re-fetched, so anything unexpected —
+        // a truncated file, a future version, a different server — degrades to a miss
+        // rather than an error the user has to clear by hand.
+        if (parsed.version !== 1 || parsed.server !== server || !Array.isArray(parsed.tools)) {
+            return undefined;
+        }
+        return parsed.tools;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function fetchCatalogue(server, env) {
+    const token = await resolveAccessToken(server, env);
+    const client = await connectMcp(server, token);
+    try {
+        const { tools } = await client.listTools();
+        return tools.map((tool) => ({
+            name: tool.name,
+            ...(typeof tool.title === 'string' ? { title: tool.title } : {}),
+            ...(typeof tool.description === 'string' ? { description: tool.description } : {}),
+            ...(tool.inputSchema ? { inputSchema: tool.inputSchema } : {}),
+        }));
+    }
+    finally {
+        await client.close();
+    }
+}
+/**
+ * Persist the catalogue. Written to a temp file and renamed, like the credential
+ * file: two `kairon` processes racing must leave a whole cache behind, not a
+ * half-written one that every later `--help` then treats as a miss.
+ */
+async function writeCatalogue(server, tools, env) {
+    const path = cataloguePath(server, env);
+    const file = { version: 1, server, fetchedAt: new Date().toISOString(), tools };
+    try {
+        await mkdir(join(configDir(env), 'tools'), { recursive: true, mode: 0o700 });
+        const tmp = `${path}.${process.pid}.tmp`;
+        await writeFile(tmp, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
+        await rename(tmp, path);
+    }
+    catch {
+        // A cache that cannot be written (read-only home, full disk) must not fail the
+        // command the user actually asked for — they lose offline help, nothing else.
+    }
+}

package/dist/client.js

@@ -0,0 +1,45 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { CliError } from './errors.js';
+import { CLI_NAME, CLI_VERSION } from './version.js';
+/**
+ * Connect to a Kairon MCP server as a real MCP client (ADR-0017).
+ *
+ * The bearer rides as a plain header rather than through the SDK's `authProvider`
+ * hook: this CLI already owns the whole OAuth lifecycle in `oauth/` and refreshes
+ * *before* the call in `session.ts`, so handing the SDK a second, partial notion
+ * of auth would give the same token two owners.
+ *
+ * The door is stateless, so there is no session to keep alive between commands —
+ * each command connects, asks, and closes.
+ */
+export async function connectMcp(server, accessToken) {
+    const transport = new StreamableHTTPClientTransport(new URL(`${server}/mcp`), {
+        requestInit: { headers: { Authorization: `Bearer ${accessToken}` } },
+    });
+    const client = new Client({ name: CLI_NAME, version: CLI_VERSION });
+    try {
+        await client.connect(transport);
+    }
+    catch (error) {
+        throw asReadableConnectError(error, server);
+    }
+    return client;
+}
+/**
+ * Turn a transport-level failure into something worth reading.
+ *
+ * The SDK reports HTTP failures as `Error: ... HTTP 403 ...`, which tells a user
+ * nothing about the two states they can actually resolve: a token that has gone
+ * stale, and an account with no LinkedIn seat connected yet.
+ */
+export function asReadableConnectError(error, server) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes('401')) {
+        return new CliError(`${server} rejected your credentials.`, `kairon login --server ${server}`);
+    }
+    if (message.includes('403')) {
+        return new CliError(`${server} accepted your login but refused the request. Either no LinkedIn account is connected, or the subscription is inactive.`, 'Connect an account in the Kairon web app, then try again.');
+    }
+    return new CliError(`Could not reach the Kairon MCP server at ${server}/mcp: ${message}`);
+}

package/dist/commands/call.js

@@ -0,0 +1,96 @@
+import { connectMcp } from '../client.js';
+import { CliError } from '../errors.js';
+import { buildInput, validateInput } from '../flags.js';
+import { displayName } from '../naming.js';
+import { resolveAccessToken } from '../session.js';
+/**
+ * A tool error the server returned — the CLI's own failure mode for MR56.
+ *
+ * Separate from {@link CliError} because it is not the CLI's fault and carries a
+ * machine `code` the caller may script against (ADR-0004). `index.ts` prints the
+ * code first and exits non-zero.
+ */
+export class ToolFailed extends Error {
+    command;
+    code;
+    payload;
+    constructor(command, 
+    /** The `AppException` code, e.g. `COMMON_NOT_FOUND`. `unknown_error` if absent. */
+    code, 
+    /** The whole error payload, printed as JSON so a script can read it. */
+    payload, detail) {
+        super(detail ?? code);
+        this.command = command;
+        this.code = code;
+        this.payload = payload;
+        this.name = 'ToolFailed';
+    }
+}
+/**
+ * Run one generated command (MR54, MR55, MR56).
+ *
+ * The stream split is the contract: **the result is the only thing on stdout**, so
+ * `kairon list list --asset leads | jq '.items'` works with no flags and no
+ * `--quiet`. Anything a human wants to read — progress, warnings, errors — goes to
+ * stderr, where a pipe never sees it. This is why nothing here writes a friendly
+ * line to `out`, however tempting: one stray `Fetching…` and every downstream `jq`
+ * breaks.
+ *
+ * Validation happens before `connectMcp`, so a typo'd flag costs nothing and names
+ * itself rather than becoming a 422 after a round trip and an OAuth refresh.
+ */
+export async function callTool(server, tool, flags, out = process.stdout, env = process.env) {
+    const command = displayName(tool.name);
+    const input = buildInput(flags, tool.inputSchema, command);
+    validateInput(input, tool.inputSchema, command);
+    const token = await resolveAccessToken(server, env);
+    const client = await connectMcp(server, token);
+    let result;
+    try {
+        result = await client.callTool({ name: tool.name, arguments: input });
+    }
+    finally {
+        await client.close();
+    }
+    const payload = readPayload(result);
+    if (result.isError) {
+        const error = (payload ?? {});
+        throw new ToolFailed(command, typeof error.code === 'string' ? error.code : 'unknown_error', payload, typeof error.detail === 'string' ? error.detail : undefined);
+    }
+    out.write(`${JSON.stringify(payload ?? null, null, 2)}\n`);
+    return payload;
+}
+/**
+ * The tool's own JSON out of the MCP envelope.
+ *
+ * `structuredContent` is preferred when the server sends it (it is already the
+ * object), and the text block is parsed otherwise — our door serialises the result
+ * with `JSON.stringify` (tool-catalogue.ts), so it round-trips. A tool that answers
+ * with genuinely non-JSON text still prints, as text, rather than becoming an error:
+ * printing what the server said beats inventing a failure it did not report.
+ */
+export function readPayload(result) {
+    const envelope = (result ?? {});
+    if (envelope.structuredContent !== undefined)
+        return envelope.structuredContent;
+    const blocks = Array.isArray(envelope.content) ? envelope.content : [];
+    const text = blocks
+        .filter((block) => {
+        const candidate = block;
+        return candidate.type === 'text' && typeof candidate.text === 'string';
+    })
+        .map((block) => block.text)
+        .join('\n');
+    if (text.length === 0)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+/** Raised when a `group verb` pair matches no tool, with the nearest group named. */
+export function unknownCommand(command, groups) {
+    return new CliError(`Unknown command "kairon ${command}".`, groups.length > 0 ? 'kairon --help' : 'kairon login, then kairon --help');
+}

package/dist/commands/login.js

@@ -0,0 +1,77 @@
+import { openBrowser } from '../browser.js';
+import { configPath, saveCredentials } from '../config.js';
+import { CliError } from '../errors.js';
+import { discoverAuthServer, scopesToRequest } from '../oauth/discovery.js';
+import { startLoopback } from '../oauth/loopback.js';
+import { createPkcePair, createState } from '../oauth/pkce.js';
+import { registerClient } from '../oauth/register.js';
+import { authorizeUrl, exchangeCode } from '../oauth/tokens.js';
+/** How long to wait for the human to finish in the browser before giving up. */
+const LOGIN_TIMEOUT_MS = 5 * 60_000;
+/**
+ * `kairon login` — OAuth 2.1 authorization code + PKCE on a loopback redirect (MR47).
+ *
+ * The order below is not interchangeable. The port must be bound before dynamic
+ * client registration, because the redirect URI we register has to be the one the
+ * browser will actually be sent to; and the listener must be waiting before the
+ * browser opens, because on a fast machine the redirect can arrive before an
+ * `await` that came later would have run.
+ */
+export async function login(server, out = process.stdout) {
+    const metadata = await discoverAuthServer(server);
+    const scope = scopesToRequest(metadata);
+    const state = createState();
+    const pkce = createPkcePair();
+    const listener = await startLoopback(state);
+    try {
+        const clientId = await registerClient(metadata, listener.redirectUri, scope);
+        const url = authorizeUrl(metadata, {
+            clientId,
+            redirectUri: listener.redirectUri,
+            challenge: pkce.challenge,
+            state,
+            scope,
+        });
+        out.write(`Opening your browser to sign in to ${server}\n`);
+        out.write(`If it does not open, paste this into your browser:\n\n${url}\n\n`);
+        openBrowser(url);
+        const code = await withTimeout(listener.waitForCode(), LOGIN_TIMEOUT_MS);
+        const credentials = await exchangeCode(metadata, {
+            code,
+            verifier: pkce.verifier,
+            clientId,
+            redirectUri: listener.redirectUri,
+        });
+        await saveCredentials(server, credentials);
+        out.write(`Signed in to ${server}. Credentials saved to ${configPath()}\n`);
+        if (!credentials.refreshToken) {
+            // Worth saying out loud: without a refresh token the user gets sent back
+            // through the browser when the access token expires, and silently
+            // discovering that in a month is worse than one line now.
+            out.write('Note: the server issued no refresh token, so you will need to sign in again when this one expires.\n');
+        }
+        return credentials;
+    }
+    finally {
+        // Always give the port back, including on Ctrl-C partway through: a leaked
+        // listener would hold a port for the life of the process for nothing.
+        listener.close();
+    }
+}
+function withTimeout(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new CliError('Timed out waiting for the browser sign-in.', 'kairon login'));
+        }, ms);
+        // `unref` so a finished login exits immediately instead of idling until the
+        // timeout fires.
+        timer.unref?.();
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error instanceof Error ? error : new Error(String(error)));
+        });
+    });
+}

package/dist/commands/logout.js

@@ -0,0 +1,21 @@
+import { clearCredentials } from '../config.js';
+/**
+ * `kairon logout` — remove the stored credentials for one server (MR48).
+ *
+ * Local only, and the message says so, because this deployment publishes no
+ * revocation endpoint (see `oauth/discovery.ts`): the access token stays valid on
+ * the server until it expires. Printing a bare "Logged out" would imply a
+ * server-side revocation that did not happen, which is the kind of small lie that
+ * matters on a shared machine.
+ */
+export async function logout(server, out = process.stdout) {
+    const removed = await clearCredentials(server);
+    if (removed) {
+        out.write(`Removed stored credentials for ${server}.\n`);
+        out.write('The access token stays valid on the server until it expires.\n');
+    }
+    else {
+        out.write(`No stored credentials for ${server}.\n`);
+    }
+    return removed;
+}