@2kw/ai 5.2.0-dev.6 → 5.2.0

package/dist/commands/auth.js

@@ -1,64 +1,340 @@
 import { Command } from "commander";
 import chalk from "chalk";
-import { store, resolveConfig, isJsonOutput, getActiveContextName, getActiveContext, getContextCount, setContext, setActiveContext, deleteContext, DEFAULT_BASE_URL, } from "../lib/config.js";
+import { store, resolveConfig, isJsonOutput, getActiveContextName, getActiveContext, getContextCount, setContext, setActiveContext, deleteContext, defaultAuthUrlFor, DEFAULT_BASE_URL, } from "../lib/config.js";
 import { getClient, runAction } from "../lib/client.js";
+import { classifyAuthFailure } from "../lib/errors.js";
+import { CLI_CLIENT_ID, getSessionInfo, listOrganizations, pollDeviceToken, requestDeviceCode, revokeSession, setActiveOrganization, } from "../lib/auth-service.js";
+import { DeviceApprovalError, runDevicePolling, selectOrganization, SessionExpiredError, } from "../lib/auth-session.js";
+import { withSpinner } from "../lib/output.js";
+import { maskApiKey } from "../lib/redact.js";
 import { createInterface } from "node:readline/promises";
-export function makeAuthCommand() {
+// Human-readable, actionable line per failure kind for the non-JSON output.
+const FAILURE_HINTS = {
+    UNAUTHORIZED: 'Key rejected. Run "2kw auth login" to re-authenticate.',
+    FORBIDDEN: "Key is valid but lacks access. Check the key's organization in the 2kw UI.",
+    UNREACHABLE: "Could not reach the host. Check the base URL and your connection.",
+    UNKNOWN: 'Validation failed. Run "2kw auth login" and, if it persists, check the base URL.',
+};
+/**
+ * Group an 8-character device user code as XXXX-XXXX.
+ *
+ * Purely presentational: the code is read off a terminal and typed into a
+ * browser, and a grouped one survives that trip with fewer mistakes. Anything
+ * that is not exactly 8 characters (a service configured for another length,
+ * or a code that already carries its own separator) is shown untouched.
+ */
+export function formatUserCode(code) {
+    return code.length === 8 ? `${code.slice(0, 4)}-${code.slice(4)}` : code;
+}
+/** Trailing slashes make `${authUrl}/api/auth/...` double up — drop them once, here. */
+function stripTrailingSlash(url) {
+    return url.replace(/\/+$/, "");
+}
+/**
+ * Open the approval page in the user's browser, and shrug if that is not
+ * possible.
+ *
+ * `open` is imported dynamically so a headless box never pays for it, and every
+ * failure is swallowed: over SSH or in a container there is no browser to open,
+ * which is precisely the situation the device grant exists for — the URL and
+ * code are already on screen.
+ */
+async function tryOpenBrowser(url) {
+    try {
+        const { default: open } = await import("open");
+        await open(url);
+    }
+    catch {
+        // No browser, no display, no default handler. The printed URL still works.
+    }
+}
+/**
+ * The browser login, end to end: ask for a device code, wait for the user to
+ * approve it, then record who they are and which organization they act as.
+ *
+ * A refused or expired approval is reported and swallowed (exit code 1, no
+ * context written) because it is the user's answer, not a fault. Everything
+ * else — an unreachable auth service, a rejected client id — propagates to
+ * `runAction`, which renders it once and machine-readably under `--json`.
+ *
+ * By design this is an interactive surface: it prints a code, opens a browser,
+ * and may ask which organization to use. Its own outcomes are therefore prose
+ * even under `--json` — a device approval that was denied is a conversation,
+ * not a payload. Faults still leave through handleError and are rendered as
+ * JSON there.
+ */
+export async function deviceFlowLogin(target, deps = {}) {
+    const { requestCode = requestDeviceCode, poll = pollDeviceToken, runPolling = runDevicePolling, sessionInfo = getSessionInfo, listOrgs = listOrganizations, chooseOrg = selectOrganization, setActiveOrg = setActiveOrganization, revoke = revokeSession, openBrowser = tryOpenBrowser, saveContext = setContext, activateContext = setActiveContext, } = deps;
+    const { contextName, baseUrl, authUrl } = target;
+    const device = await requestCode(authUrl, CLI_CLIENT_ID);
+    console.log("");
+    console.log(`Open ${chalk.cyan(device.verification_uri_complete)}`);
+    console.log(`and confirm the code ${chalk.bold(formatUserCode(device.user_code))}`);
+    console.log("");
+    await openBrowser(device.verification_uri_complete);
+    let sessionToken;
+    try {
+        sessionToken = await withSpinner("Waiting for approval in the browser...", () => runPolling({
+            poll: () => poll(authUrl, CLI_CLIENT_ID, device.device_code),
+            intervalSec: device.interval,
+            expiresInSec: device.expires_in,
+        }));
+    }
+    catch (err) {
+        // The user's own answer — say it plainly and stop. Anything else (a refused
+        // client id, a network that never came back) is a fault, and belongs to
+        // handleError, which is what puts it in front of a --json consumer.
+        if (!(err instanceof DeviceApprovalError))
+            throw err;
+        console.error(chalk.red(err.message));
+        process.exitCode = 1;
+        return;
+    }
+    const { email } = await sessionInfo(authUrl, sessionToken);
+    // Everything from here to the successful write is guarded: until the session
+    // token reaches the config store, a failure leaves it live server-side with
+    // nothing on this machine able to use it — an account with no organization at
+    // all being the case that guarantees it, a refused set-active or a read-only
+    // store the ones that merely make it likely. Revoking is best-effort: the
+    // failure that got us here is the one worth reporting, not a failed cleanup.
+    let org;
+    try {
+        org = await chooseOrg(await listOrgs(authUrl, sessionToken));
+        await setActiveOrg(authUrl, sessionToken, org.id);
+        // A whole entry, not a patch: this context may have held an API key, and a
+        // leftover one would silently outrank the session on the next command.
+        saveContext(contextName, {
+            baseUrl,
+            authUrl,
+            sessionToken,
+            organizationId: org.id,
+        });
+    }
+    catch (err) {
+        try {
+            await revoke(authUrl, sessionToken);
+        }
+        catch {
+            // Nothing to do; the session expires on its own.
+        }
+        throw err;
+    }
+    // Outside the guard on purpose: the session is on disk now, so a failure to
+    // mark the context active still leaves a credential the user can reach.
+    activateContext(contextName);
+    console.log(chalk.green(`Logged in as ${email}`));
+    console.log(chalk.dim(`  — organization: ${org.name}`));
+    console.log(chalk.dim(`Config stored at: ${store.path}`));
+}
+/**
+ * The pre-device-flow login: take an API key from the flag or the terminal and
+ * store it. Still the path for CI-style credentials and for anyone whose
+ * machine cannot run the browser flow.
+ */
+async function manualLogin(opts) {
+    let apiKey = opts.apiKey;
+    let baseUrl = opts.baseUrl;
+    const contextName = getActiveContextName();
+    const currentCtx = getActiveContext();
+    if (!apiKey || !baseUrl) {
+        const rl = createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        try {
+            if (!baseUrl) {
+                const defaultUrl = currentCtx?.baseUrl ?? DEFAULT_BASE_URL;
+                baseUrl = await rl.question(`Base URL [${defaultUrl}]: `);
+                if (!baseUrl)
+                    baseUrl = defaultUrl;
+            }
+            if (!apiKey) {
+                apiKey = await rl.question("API Key (sk_...): ");
+            }
+        }
+        finally {
+            rl.close();
+        }
+    }
+    if (!apiKey) {
+        console.error(chalk.red("API key is required."));
+        process.exit(1);
+    }
+    setContext(contextName, { apiKey, baseUrl });
+    setActiveContext(contextName);
+    console.log(chalk.green("Credentials saved successfully."));
+    console.log(chalk.dim(`Config stored at: ${store.path}`));
+}
+/**
+ * Sign out: drop the local credentials, then tell the auth service.
+ *
+ * That order is deliberate. `revokeSession` has no timeout, so an auth host
+ * that black-holes the request would hang the command with the credentials
+ * still on disk — while the user, having read "Credentials cleared", believes
+ * they are signed out. Clearing first makes the local half unconditional and
+ * leaves the network call as what it is: best-effort, and the only part that
+ * can fail. A host that refuses the connection fails fast either way.
+ *
+ * The token and URL are copied out first because the store no longer holds
+ * them by the time they are used.
+ */
+export async function performLogout(deps = {}) {
+    const { revoke = revokeSession } = deps;
+    const contextName = getActiveContextName();
+    const ctx = getActiveContext();
+    const sessionToken = ctx?.sessionToken;
+    const authUrl = ctx?.authUrl;
+    if (getContextCount() <= 1) {
+        // Last context — clear it by resetting the store
+        store.store = { activeContext: "default", contexts: {} };
+    }
+    else {
+        deleteContext(contextName);
+        console.log(chalk.dim(`Removed context "${contextName}". Switched to "${getActiveContextName()}".`));
+    }
+    console.log(chalk.green("Credentials cleared."));
+    // The wording claims only what happened — better-auth answers 200 whether or
+    // not the bearer resolved to a session, so "revoked" would be a guess. A
+    // session that was already dead is not a failed logout either.
+    if (sessionToken && authUrl) {
+        try {
+            await revoke(authUrl, sessionToken);
+            console.log(chalk.dim("Sign-out sent to the auth service."));
+        }
+        catch {
+            console.log(chalk.yellow("Could not revoke the server-side session (already expired?)."));
+        }
+    }
+}
+/** The credential check both status paths run: cheap, and it needs real auth. */
+async function countModels(command) {
+    const client = getClient(command);
+    const { data } = await client.GET("/v1/models");
+    return data?.data?.length ?? 0;
+}
+/** `auth status` for a browser-session context. */
+export async function sessionStatus(config, view, deps) {
+    const { json, contextName, multiContext } = view;
+    const { countModels: probe, sessionInfo = getSessionInfo } = deps;
+    // Best-effort identity: better-auth answers 200 with a null body for a dead
+    // session, which auth-service turns into an error — so any failure here means
+    // "no user to name", never a reason to stop.
+    let email;
+    try {
+        email = (await sessionInfo(config.authUrl, config.sessionToken)).email;
+    }
+    catch {
+        email = undefined;
+    }
+    const identity = {
+        ...(multiContext ? { context: contextName } : {}),
+        baseUrl: config.baseUrl,
+        authType: "session",
+        ...(email ? { email } : {}),
+        ...(config.organizationId ? { organizationId: config.organizationId } : {}),
+        authUrl: config.authUrl,
+    };
+    const printIdentityLines = () => {
+        if (multiContext) {
+            console.log(`  Context: ${contextName}`);
+        }
+        console.log(`  Base URL:  ${config.baseUrl}`);
+        console.log(`  Auth:      browser session (${config.authUrl})`);
+        if (email) {
+            console.log(`  User:      ${email}`);
+        }
+        if (config.organizationId) {
+            console.log(`  Org:       ${config.organizationId}`);
+        }
+    };
+    try {
+        const modelCount = await probe();
+        if (json) {
+            console.log(JSON.stringify({ authenticated: true, ...identity, modelCount }));
+        }
+        else {
+            console.log(chalk.green("Authenticated"));
+            printIdentityLines();
+            console.log(`  Models:    ${modelCount} available`);
+        }
+    }
+    catch (err) {
+        // A dead session already has its own rendering in handleError — catching it
+        // here would print the diagnosis twice, once as a guess.
+        if (err instanceof SessionExpiredError)
+            throw err;
+        // The same classification the human hint is chosen by, reported instead of
+        // kept — a --json caller should not have to string-match a hint it cannot
+        // even see to learn that the host was unreachable. Same key as the API-key
+        // branch below, so one consumer handles both auth types.
+        const failureKind = classifyAuthFailure(err);
+        process.exitCode = 1;
+        if (json) {
+            console.log(JSON.stringify({
+                authenticated: false,
+                ...identity,
+                failureKind,
+                error: "Failed to validate credentials",
+            }));
+        }
+        else {
+            console.log(chalk.yellow("Credentials configured but validation failed."));
+            printIdentityLines();
+            // A host that never answered says nothing about the session, so do not
+            // send the user off to re-login over what is probably a dropped network.
+            const hint = failureKind === "UNREACHABLE"
+                ? FAILURE_HINTS.UNREACHABLE
+                : 'Session may have expired — run "2kw auth login".';
+            console.log(chalk.dim(`  ${hint}`));
+        }
+    }
+}
+/**
+ * @param deviceDeps forwarded to {@link deviceFlowLogin} — a seam for tests
+ *   that need to prove the browser flow was NOT entered.
+ */
+export function makeAuthCommand(deviceDeps = {}) {
     const cmd = new Command("auth").description("Manage authentication");
     cmd
         .command("login")
-        .description("Configure API credentials")
-        .option("--api-key <key>", "API key")
+        .description("Sign in through the browser (or with an API key)")
+        .option("--api-key <key>", "Save an API key instead of signing in through the browser")
+        .option("--manual", "Prompt for an API key instead of signing in through the browser")
         .option("--base-url <url>", "Base URL")
-        .action(async (opts) => {
-        let apiKey = opts.apiKey;
-        let baseUrl = opts.baseUrl;
-        const contextName = getActiveContextName();
-        const currentCtx = getActiveContext();
-        if (!apiKey || !baseUrl) {
-            const rl = createInterface({
-                input: process.stdin,
-                output: process.stdout,
-            });
-            try {
-                if (!baseUrl) {
-                    const defaultUrl = currentCtx?.baseUrl ?? DEFAULT_BASE_URL;
-                    baseUrl = await rl.question(`Base URL [${defaultUrl}]: `);
-                    if (!baseUrl)
-                        baseUrl = defaultUrl;
-                }
-                if (!apiKey) {
-                    apiKey = await rl.question("API Key (sk_...): ");
-                }
-            }
-            finally {
-                rl.close();
+        .option("--auth-url <url>", "Auth service URL (defaults to the one matching the base URL)")
+        .action(async (_opts, command) => {
+        // Merged, not own: the root program declares --api-key and --base-url as
+        // global options, and commander binds a flag to the first command that
+        // declares it while parsing — the root. This subcommand's own opts are
+        // therefore structurally EMPTY for exactly the two flags it documents, so
+        // `auth login --api-key sk_x` used to fall through to the browser flow.
+        //
+        // Reading them merged conflates the two spellings, and that is the
+        // intended behaviour: at the root, --api-key means "authenticate this one
+        // invocation", but combined with `auth login` the user has supplied a key
+        // AND asked to sign in, and saving it is the only reading that does
+        // anything at all.
+        const opts = command.optsWithGlobals();
+        await runAction(command, async () => {
+            if (opts.apiKey || opts.manual) {
+                await manualLogin(opts);
+                return;
             }
-        }
-        if (!apiKey) {
-            console.error(chalk.red("API key is required."));
-            process.exit(1);
-        }
-        setContext(contextName, { apiKey, baseUrl });
-        setActiveContext(contextName);
-        console.log(chalk.green("Credentials saved successfully."));
-        console.log(chalk.dim(`Config stored at: ${store.path}`));
+            const contextName = getActiveContextName();
+            const currentCtx = getActiveContext();
+            const baseUrl = opts.baseUrl ?? currentCtx?.baseUrl ?? DEFAULT_BASE_URL;
+            const authUrl = stripTrailingSlash(opts.authUrl ?? currentCtx?.authUrl ?? defaultAuthUrlFor(baseUrl));
+            // Which service is about to be handed the login is not obvious once it
+            // is derived from the base URL, so say it before opening a browser.
+            console.log(chalk.dim(`Auth service: ${authUrl} (override with --auth-url)`));
+            await deviceFlowLogin({ contextName, baseUrl, authUrl }, deviceDeps);
+        });
     });
     cmd
         .command("logout")
         .description("Clear stored credentials")
-        .action(() => {
-        const contextName = getActiveContextName();
-        const count = getContextCount();
-        if (count <= 1) {
-            // Last context — clear it by resetting the store
-            store.store = { activeContext: "default", contexts: {} };
-        }
-        else {
-            deleteContext(contextName);
-            console.log(chalk.dim(`Removed context "${contextName}". Switched to "${getActiveContextName()}".`));
-        }
-        console.log(chalk.green("Credentials cleared."));
+        .action(async (_opts, command) => {
+        await runAction(command, () => performLogout());
     });
     cmd
         .command("status")
@@ -71,6 +347,8 @@ export function makeAuthCommand() {
                 config = resolveConfig(command);
             }
             catch {
+                // No credentials configured at all — distinct from a rejected key.
+                process.exitCode = 1;
                 if (json) {
                     console.log(JSON.stringify({ authenticated: false }));
                 }
@@ -80,15 +358,20 @@ export function makeAuthCommand() {
                 }
                 return;
             }
-            const { apiKey, baseUrl } = config;
-            const keyPreview = apiKey.slice(0, 7) + "..." + apiKey.slice(-4);
             const multiContext = getContextCount() > 1;
             const contextName = getActiveContextName();
+            if (config.kind === "session") {
+                await sessionStatus(config, { json, contextName, multiContext }, { countModels: () => countModels(command) });
+                return;
+            }
+            const { apiKey, baseUrl } = config;
+            // The shared mask, not a local slice: on a key of 11 characters or
+            // fewer the two slices overlap and print it in full — every one of
+            // these four uses, --json included.
+            const keyPreview = maskApiKey(apiKey);
             // Try to validate by listing models (lightweight call)
             try {
-                const client = getClient(command);
-                const { data } = await client.GET("/v1/models");
-                const modelCount = data?.data?.length ?? 0;
+                const modelCount = await countModels(command);
                 if (json) {
                     console.log(JSON.stringify({
                         authenticated: true,
@@ -108,13 +391,19 @@ export function makeAuthCommand() {
                     console.log(`  Models:    ${modelCount} available`);
                 }
             }
-            catch {
+            catch (err) {
+                // Credentials are present but the check failed. Surface WHY, so
+                // callers stop guessing among a bad key, missing permissions, and an
+                // unreachable host.
+                const failureKind = classifyAuthFailure(err);
+                process.exitCode = 1;
                 if (json) {
                     console.log(JSON.stringify({
                         authenticated: false,
                         ...(multiContext ? { context: contextName } : {}),
                         baseUrl,
                         apiKeyPreview: keyPreview,
+                        failureKind,
                         error: "Failed to validate credentials",
                     }));
                 }
@@ -125,6 +414,7 @@ export function makeAuthCommand() {
                     }
                     console.log(`  Base URL:  ${baseUrl}`);
                     console.log(`  API Key:   ${keyPreview}`);
+                    console.log(chalk.yellow(`  ${FAILURE_HINTS[failureKind]}`));
                 }
             }
         });

package/dist/commands/config.d.ts

@@ -1,3 +1,19 @@
 import { Command } from "commander";
+declare const ALLOWED_KEYS: readonly ["apiKey", "baseUrl"];
+type ConfigKey = (typeof ALLOWED_KEYS)[number];
+/**
+ * Write one config key onto the active context.
+ *
+ * Setting `apiKey` also tears down any browser session on that context.
+ * Resolution checks `sessionToken` before `apiKey` (see
+ * resolveConfigFromSources), so a key stored alongside a live session would be
+ * shadowed forever — the user would have set a credential that never gets used
+ * and never gets mentioned. Clearing the session makes the write mean what it
+ * says. Reported back so the caller can say it out loud.
+ */
+export declare function applyConfigSet(key: ConfigKey, value: string): {
+    clearedSession: boolean;
+};
 export declare function makeConfigCommand(): Command;
+export {};
 //# sourceMappingURL=config.d.ts.map

package/dist/commands/config.js

@@ -1,6 +1,7 @@
 import { Command } from "commander";
 import chalk from "chalk";
 import { store, isJsonOutput, getActiveContext, getActiveContextName, getContextCount, setContext, DEFAULT_BASE_URL, } from "../lib/config.js";
+import { maskApiKey } from "../lib/redact.js";
 const ALLOWED_KEYS = ["apiKey", "baseUrl"];
 const KEY_ALIASES = {
     "api-key": "apiKey",
@@ -16,6 +17,36 @@ function validateKey(key) {
     }
     return normalized;
 }
+/**
+ * Write one config key onto the active context.
+ *
+ * Setting `apiKey` also tears down any browser session on that context.
+ * Resolution checks `sessionToken` before `apiKey` (see
+ * resolveConfigFromSources), so a key stored alongside a live session would be
+ * shadowed forever — the user would have set a credential that never gets used
+ * and never gets mentioned. Clearing the session makes the write mean what it
+ * says. Reported back so the caller can say it out loud.
+ */
+export function applyConfigSet(key, value) {
+    const contextName = getActiveContextName();
+    const entry = { ...(getActiveContext() ?? { apiKey: "", baseUrl: DEFAULT_BASE_URL }) };
+    if (key === "apiKey") {
+        const clearedSession = Boolean(entry.sessionToken);
+        entry.apiKey = value;
+        // All five together: a leftover authUrl or cached JWT describes a session
+        // that no longer exists here.
+        entry.sessionToken = undefined;
+        entry.authUrl = undefined;
+        entry.organizationId = undefined;
+        entry.cachedJwt = undefined;
+        entry.cachedJwtExp = undefined;
+        setContext(contextName, entry);
+        return { clearedSession };
+    }
+    entry[key] = value;
+    setContext(contextName, entry);
+    return { clearedSession: false };
+}
 export function makeConfigCommand() {
     const cmd = new Command("config").description("Manage CLI configuration");
     cmd
@@ -25,19 +56,22 @@ export function makeConfigCommand() {
         .argument("<value>", "Config value")
         .action((key, value, _opts, command) => {
         const validKey = validateKey(key);
-        // Update the active context
-        const contextName = getActiveContextName();
-        const ctx = getActiveContext() ?? {
-            apiKey: "",
-            baseUrl: DEFAULT_BASE_URL,
-        };
-        ctx[validKey] = value;
-        setContext(contextName, ctx);
+        const { clearedSession } = applyConfigSet(validKey, value);
+        // Never echo the key back, in either mode: `config set apiKey` is exactly
+        // the command whose output ends up in a CI log.
+        const shown = validKey === "apiKey" ? maskApiKey(value) : value;
         if (isJsonOutput(command)) {
-            console.log(JSON.stringify({ key: validKey, value }));
+            console.log(JSON.stringify({
+                key: validKey,
+                value: shown,
+                ...(clearedSession ? { clearedSession: true } : {}),
+            }));
         }
         else {
-            console.log(chalk.green(`Set ${validKey} = ${validKey === "apiKey" ? "****" : value}`));
+            console.log(chalk.green(`Set ${validKey} = ${shown}`));
+            if (clearedSession) {
+                console.log(chalk.dim("Cleared the browser session on this context."));
+            }
         }
     });
     cmd
@@ -47,12 +81,13 @@ export function makeConfigCommand() {
         .action((key, _opts, command) => {
         const validKey = validateKey(key);
         const ctx = getActiveContext();
-        const value = ctx?.[validKey];
+        const raw = ctx?.[validKey];
+        const value = raw && validKey === "apiKey" ? maskApiKey(raw) : raw;
         if (isJsonOutput(command)) {
             console.log(JSON.stringify({ key: validKey, value: value ?? null }));
         }
         else if (value) {
-            console.log(validKey === "apiKey" ? "****" : value);
+            console.log(value);
         }
         else {
             console.log(chalk.dim("(not set)"));
@@ -63,8 +98,10 @@ export function makeConfigCommand() {
         .description("Show all configuration values")
         .action((_opts, command) => {
         const ctx = getActiveContext();
+        // Masked at the source, so neither branch below can grow a path that
+        // prints the raw key — and `--json` is the branch that ends up in a log.
         const values = {
-            apiKey: ctx?.apiKey,
+            apiKey: ctx?.apiKey ? maskApiKey(ctx.apiKey) : undefined,
             baseUrl: ctx?.baseUrl,
         };
         if (isJsonOutput(command)) {
@@ -72,15 +109,11 @@ export function makeConfigCommand() {
         }
         else {
             for (const [key, value] of Object.entries(values)) {
-                const display = !value
-                    ? chalk.dim("(not set)")
-                    : key === "apiKey"
-                        ? value.slice(0, 7) + "..." + value.slice(-4)
-                        : value;
+                const display = value ?? chalk.dim("(not set)");
                 console.log(`${chalk.cyan(key)}: ${display}`);
             }
             if (getContextCount() > 1) {
-                console.log(chalk.dim(`\nContext: ${getActiveContextName()} (use "backbone context list" to see all)`));
+                console.log(chalk.dim(`\nContext: ${getActiveContextName()} (use "2kw context list" to see all)`));
             }
             console.log(chalk.dim(`\nConfig file: ${store.path}`));
         }

package/dist/commands/context.d.ts

@@ -1,3 +1,28 @@
 import { Command } from "commander";
+import { updateContext } from "../lib/config.js";
+import { listOrganizations, setActiveOrganization } from "../lib/auth-service.js";
+import { selectOrganization, type Asker } from "../lib/auth-session.js";
+/** Injection points for {@link performSetOrg}; all default to the real thing. */
+export interface SetOrgDeps {
+    listOrgs?: typeof listOrganizations;
+    chooseOrg?: typeof selectOrganization;
+    setActiveOrg?: typeof setActiveOrganization;
+    /** Store writer; defaults to {@link updateContext}. */
+    persist?: typeof updateContext;
+    /** Question function for the picker; defaults to reading a line from stdin. */
+    ask?: Asker;
+}
+/**
+ * Point the active session context at a different organization.
+ *
+ * The switch is server-side state (the session's active organization), so the
+ * local write that follows is not a cache but the record of what the server was
+ * told. A cached JWT minted for the previous organization would still be
+ * accepted by the API, silently answering as the old org, so it is dropped in
+ * the same write.
+ *
+ * @param orgArg an organization id or slug; omitted means "prompt".
+ */
+export declare function performSetOrg(orgArg: string | undefined, deps?: SetOrgDeps): Promise<void>;
 export declare function makeContextCommand(): Command;
 //# sourceMappingURL=context.d.ts.map