@functional-systems/lambdadb-cli 0.1.7-dev.23 → 0.1.7-dev.25

package/src/account.ts

@@ -0,0 +1,351 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, writeFile, rename, rm, open } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { configPath, endpoint, fileIdentity, timeoutMs, type Options } from './config.js';
+import { CredentialVault, credentialReference, type CredentialReference } from './credentials.js';
+import { authorizeAccount } from './device-auth.js';
+import { InputError, ManagementError } from './errors.js';
+import type { Output } from './output.js';
+
+export type AccountOptions = Options & { apiUrl?: string; browser?: boolean; signal?: AbortSignal };
+export type Account = CredentialReference & {
+  apiUrl: string;
+  consoleUrl: string;
+  memberId: string;
+  email: string;
+  expiresAt: string;
+};
+export const accountVault = () => new CredentialVault(undefined, process.platform, 'account');
+export const accountPath = async (options: Options) =>
+  `${await fileIdentity(configPath(options))}.account.json`;
+export const accountTarget = (a: Account) => ({ ...a, endpoint: a.apiUrl, project: 'account' });
+
+export async function readOptional(path: string): Promise<string | undefined> {
+  try {
+    return await readFile(path, 'utf8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw new InputError(`Cannot read ${path}. Check file permissions.`);
+  }
+}
+export async function writeMetadata(path: string, value: unknown, before: string | undefined) {
+  const destination = await fileIdentity(path);
+  if ((await readOptional(path)) !== before)
+    throw new InputError(`Configuration changed: ${path}. Retry after reviewing it.`);
+  const temp = `${destination}.${randomUUID()}.tmp`;
+  try {
+    await mkdir(dirname(destination), { recursive: true, mode: 0o700 });
+    await writeFile(temp, JSON.stringify(value, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+    await rename(temp, destination);
+  } finally {
+    await rm(temp, { force: true }).catch(() => {});
+  }
+}
+export async function withManagementLock<T>(options: Options, action: () => Promise<T>): Promise<T> {
+  const path = `${await fileIdentity(configPath(options))}.management.lock`;
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  let handle;
+  try {
+    handle = await open(path, 'wx', 0o600);
+  } catch {
+    throw new InputError(
+      `Another management operation may be running. After confirming it has stopped, remove ${path} and retry.`,
+    );
+  }
+  try {
+    await handle.writeFile(String(process.pid));
+    return await action();
+  } finally {
+    await handle.close();
+    await rm(path, { force: true });
+  }
+}
+function parseAccount(text: string): Account {
+  let a: Account;
+  try {
+    a = JSON.parse(text);
+    credentialReference(a.credentialStore, a.credentialId);
+    if (
+      Object.keys(a).some(
+        (k) =>
+          ![
+            'apiUrl',
+            'consoleUrl',
+            'memberId',
+            'email',
+            'expiresAt',
+            'credentialStore',
+            'credentialId',
+          ].includes(k),
+      ) ||
+      typeof a.memberId !== 'string' ||
+      !/^[0-9a-f-]{36}$/.test(a.memberId) ||
+      typeof a.email !== 'string' ||
+      typeof a.expiresAt !== 'string' ||
+      !Number.isFinite(Date.parse(a.expiresAt))
+    )
+      throw new Error();
+    if (endpoint(a.apiUrl) !== a.apiUrl || endpoint(a.consoleUrl) !== a.consoleUrl) throw new Error();
+  } catch {
+    throw new InputError(
+      'Invalid account metadata. Never store tokens in configuration; restore the file or run login.',
+    );
+  }
+  return a;
+}
+export async function loadAccount(options: AccountOptions): Promise<Account> {
+  const text = await readOptional(await accountPath(options));
+  if (!text)
+    throw new InputError(
+      'Run lambdadb login first. Project-key environment setup remains available without account login.',
+    );
+  const a = parseAccount(text);
+  if (options.apiUrl && endpoint(options.apiUrl) !== a.apiUrl)
+    throw new InputError(
+      'This login belongs to a different API origin. Run login with --api-url for that server.',
+    );
+  if (Date.parse(a.expiresAt) <= Date.now())
+    throw new InputError(
+      'CLI login expired. Run lambdadb login again; existing project connections are preserved.',
+    );
+  return a;
+}
+
+export async function accountRequest(
+  account: Account,
+  token: string,
+  path: string,
+  method = 'GET',
+  body?: object,
+  org?: string,
+  signal?: AbortSignal,
+  requestTimeoutMs = 30_000,
+): Promise<Record<string, unknown>> {
+  let response: Response | undefined;
+  let value: Record<string, unknown>;
+  try {
+    response = await fetch(`${account.apiUrl}/auth/cli/${path}`, {
+      method,
+      redirect: 'error',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json',
+        ...(org ? { 'X-Organization-ID': org } : {}),
+      },
+      ...(body ? { body: JSON.stringify(body) } : {}),
+      signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(requestTimeoutMs)]) : AbortSignal.timeout(requestTimeoutMs),
+    });
+    if (response.status === 204) return {};
+    const reader = response.body?.getReader();
+    if (!reader) throw new Error();
+    const chunks: Uint8Array[] = [];
+    let size = 0;
+    try {
+      for (;;) {
+        const next = await reader.read();
+        if (next.done) break;
+        size += next.value.length;
+        if (size > 2_000_000) throw new Error();
+        chunks.push(next.value);
+      }
+    } finally {
+      await reader.cancel().catch(() => {});
+    }
+    value = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error();
+  } catch {
+    // A rejection remains definite without a JSON body. A connect conflict may
+    // represent an already claimed issuance, whose result cannot be recovered.
+    const status = response?.status;
+    if (status !== undefined && status >= 400 && status < 500 && status !== 408 &&
+      !(path === 'connect' && status === 409)) {
+      throw new ManagementError('management_request_failed', status);
+    }
+    throw new ManagementError(
+      method === 'GET' ? 'management_unavailable' : 'write_outcome_unknown',
+      status,
+    );
+  }
+  if (!response.ok) {
+    const known = [
+      'login_required',
+      'access_denied',
+      'project_limit_reached',
+      'issuance_unconfirmed',
+      'project_not_ready_or_forbidden',
+      'project_request_rejected',
+    ];
+    const code =
+      method !== 'GET' && (response.status >= 500 || response.status === 408) && value.error !== 'issuance_unconfirmed'
+        ? 'write_outcome_unknown'
+        : typeof value.error === 'string' && known.includes(value.error)
+          ? value.error
+          : 'management_request_failed';
+    // Only a small allowlist of non-secret fields may reach diagnostics.
+    const details: Record<string, unknown> = {};
+    if (typeof value.invitation_id === 'string' && /^[0-9a-f-]{36}$/.test(value.invitation_id)) {
+      details.invitation_id = value.invitation_id;
+      details.invitation_url = `${account.consoleUrl}/invites/${value.invitation_id}`;
+    }
+    if (code === 'project_limit_reached')
+      details.organization = parseOrganization(value.organization, account);
+    throw new ManagementError(code, response.status, details);
+  }
+  return value;
+}
+export type Organization = {
+  id: string;
+  name: string;
+  role: string;
+  plan: string;
+  max_projects: number;
+  projects_count: number;
+  billing_url: string;
+  can_upgrade: boolean;
+};
+export function parseOrganization(value: unknown, a: Account): Organization {
+  const v = value as Organization;
+  if (
+    !v ||
+    typeof v.id !== 'string' ||
+    !/^[0-9a-f-]{36}$/.test(v.id) ||
+    typeof v.name !== 'string' ||
+    !['owner', 'admin', 'member'].includes(v.role) ||
+    typeof v.plan !== 'string' ||
+    !Number.isInteger(v.max_projects) ||
+    v.max_projects < 0 ||
+    !Number.isInteger(v.projects_count) ||
+    v.projects_count < 0
+  )
+    throw new InputError('Invalid Organization response. Check server compatibility.');
+  return {
+    id: v.id,
+    name: v.name,
+    role: v.role,
+    plan: v.plan,
+    max_projects: v.max_projects,
+    projects_count: v.projects_count,
+    billing_url: `${a.consoleUrl}/organization/billing/open?org_id=${encodeURIComponent(v.id)}`,
+    can_upgrade: v.role === 'owner',
+  };
+}
+export async function management(options: AccountOptions, output: Output) {
+  const requestTimeoutMs = timeoutMs(options);
+  const account = await loadAccount(options);
+  let token: string;
+  try {
+    token = await accountVault().read(accountTarget(account));
+  } catch {
+    throw new InputError(
+      'Cannot read the CLI account session. Unlock the recorded OS store or run login explicitly. No account credential is forwarded to MCP.',
+    );
+  }
+  output.protect(token);
+  return {
+    account,
+    request: (path: string, method = 'GET', body?: object, org?: string) =>
+      accountRequest(account, token, path, method, body, org, options.signal, requestTimeoutMs),
+  };
+}
+export async function login(options: AccountOptions, output: Output, vault = accountVault()) {
+  const requestTimeoutMs = timeoutMs(options);
+  return withManagementLock(options, async () => {
+    const path = await accountPath(options),
+      before = await readOptional(path);
+    let previousOrigin: string | undefined;
+    if (before) {
+      try {
+        previousOrigin = parseAccount(before).apiUrl;
+      } catch {
+        /* Explicit login can replace malformed non-secret metadata. */
+      }
+    }
+    const apiUrl = endpoint(options.apiUrl ?? previousOrigin ?? 'https://api.lambdadb.ai');
+    const store = await vault.select(options.credentialStore ?? 'auto');
+    output.diagnostic(
+      `Account session: ${store}; non-secret metadata: ${path}. Login lasts up to seven days. Project credentials are separate.`,
+    );
+    if (store === 'keyutils')
+      output.diagnostic(
+        'Kernel credentials can expire or disappear after reboot. Run login again explicitly if unavailable.',
+      );
+    const cancellation = new AbortController();
+    const cancel = () => cancellation.abort();
+    process.once('SIGINT', cancel);
+    process.once('SIGTERM', cancel);
+    try {
+      const granted = await authorizeAccount(
+        apiUrl,
+        options.browser !== false,
+        output,
+        options.signal ? AbortSignal.any([options.signal, cancellation.signal]) : cancellation.signal,
+        requestTimeoutMs,
+      );
+      const account: Account = {
+        apiUrl,
+        consoleUrl: granted.consoleUrl,
+        memberId: granted.memberId,
+        email: granted.email,
+        expiresAt: granted.expiresAt,
+        credentialStore: store,
+        credentialId: randomUUID(),
+      };
+      try {
+        await vault.save(accountTarget(account), granted.token);
+        await writeMetadata(path, account, before);
+      } catch (error) {
+        await accountRequest(account, granted.token, 'logout', 'POST', {}, undefined, options.signal, requestTimeoutMs).catch(() =>
+          output.diagnostic('Server-session cleanup could not be confirmed; it expires within seven days.'),
+        );
+        await vault.remove(accountTarget(account)).catch(() => {});
+        throw error;
+      }
+      if (before) {
+        // Retire only a parseable previous account slot after the replacement is durable.
+        try {
+          const old = parseAccount(before);
+          const token = await vault.read(accountTarget(old));
+          output.protect(token);
+          await revokeAccount(old, token, options);
+          await vault.remove(accountTarget(old));
+        } catch {
+          output.diagnostic(
+            'Previous login cleanup could not be confirmed. It expires within seven days; project keys are unaffected.',
+          );
+        }
+      }
+      return account;
+    } finally {
+      process.removeListener('SIGINT', cancel);
+      process.removeListener('SIGTERM', cancel);
+    }
+  });
+}
+export async function logout(options: AccountOptions, output: Output, vault = accountVault()) {
+  timeoutMs(options);
+  return withManagementLock(options, async () => {
+    const path = await accountPath(options),
+      before = await readOptional(path);
+    if (!before) return;
+    // Expired sessions may still be removed locally, without opening a browser.
+    const account = parseAccount(before);
+    if (options.apiUrl && endpoint(options.apiUrl) !== account.apiUrl)
+      throw new InputError('The account belongs to another API origin.');
+    const token = await vault.read(accountTarget(account));
+    output.protect(token);
+    await revokeAccount(account, token, options);
+    await vault.remove(accountTarget(account));
+    if ((await readOptional(path)) !== before)
+      throw new InputError('Account metadata changed. Review it before removing it.');
+    await rm(await fileIdentity(path));
+  });
+}
+
+async function revokeAccount(account: Account, token: string, options: AccountOptions): Promise<void> {
+  try {
+    await accountRequest(account, token, 'logout', 'POST', {}, undefined, options.signal, timeoutMs(options));
+  } catch (error) {
+    // An expired or already revoked session is safe to remove locally.
+    if (!(error instanceof ManagementError && error.status === 401)) throw error;
+  }
+}

package/src/agent-config.ts

@@ -1,9 +1,10 @@
 import { applyEdits, modify, parse as parseJson, type ParseError } from 'jsonc-parser';
 import { parse as parseToml } from 'smol-toml';
-import type { Settings } from './config.js';
+import type { SelectedSettings } from './config.js';
+import { credentialReference } from './credentials.js';
 import { InputError } from './errors.js';
 
-export type McpLaunch = { command: string; args: string[]; apiKeyEnv: string };
+export type McpLaunch = { command: string; args: string[]; apiKeyEnv?: string; runtimeEnv?: string[] };
 type Server = { command: string | string[]; args?: string[]; env_vars?: string[];
   env?: Record<string, string>; environment?: Record<string, string>; type?: string };
 type ServerFactory = (launch: McpLaunch) => Server;
@@ -11,10 +12,13 @@ type JsonMapPath = readonly string[] | ((value: Record<string, unknown>) => read
 const begin = '# BEGIN lambdadb init';
 const end = '# END lambdadb init';
 
-export function mcpLaunch(selected: Required<Settings>, writeTools: boolean, cliVersion: string): McpLaunch {
-  return { command: 'npx', apiKeyEnv: selected.apiKeyEnv,
+export function mcpLaunch(selected: SelectedSettings, writeTools: boolean, cliVersion: string): McpLaunch {
+  const stored = selected.credentialStore ? credentialReference(selected.credentialStore, selected.credentialId) : undefined;
+  return { command: 'npx', apiKeyEnv: selected.credentialStore ? undefined : selected.apiKeyEnv,
+    runtimeEnv: selected.credentialStore === 'secret-service' ? ['DBUS_SESSION_BUS_ADDRESS', 'XDG_RUNTIME_DIR'] : [],
     args: ['-y', `@functional-systems/lambdadb-cli@${cliVersion}`, 'mcp',
-      '--endpoint', selected.endpoint, '--project', selected.project, '--api-key-env', selected.apiKeyEnv,
+      '--endpoint', selected.endpoint, '--project', selected.project,
+      ...(stored ? ['--credential-store', stored.credentialStore, '--credential-id', stored.credentialId] : ['--api-key-env', selected.apiKeyEnv]),
       ...(writeTools ? ['--write-tools'] : [])] };
 }
 
@@ -30,9 +34,11 @@ function managedServer(value: unknown, createServer: ServerFactory): boolean {
   const a = Array.isArray(value.command) ? value.command.slice(1) : value.args;
   if (command !== 'npx' || !Array.isArray(a)) return false;
   if (a.some(v => typeof v !== 'string') || !/^@functional-systems\/lambdadb-cli@[\w.+-]+$/.test(a[1] ?? '')
-    || a[0] !== '-y' || a[2] !== 'mcp' || a[3] !== '--endpoint' || a[5] !== '--project'
-    || a[7] !== '--api-key-env' || ![9, 10].includes(a.length) || (a.length === 10 && a[9] !== '--write-tools')) return false;
-  const expected = createServer({ command: 'npx', args: a, apiKeyEnv: a[8] });
+    || a[0] !== '-y' || a[2] !== 'mcp' || a[3] !== '--endpoint' || a[5] !== '--project') return false;
+  const stored = a[7] === '--credential-store' && ['keychain', 'windows', 'secret-service', 'keyutils'].includes(a[8]) && a[9] === '--credential-id';
+  const length = stored ? 11 : 9;
+  if ((!stored && a[7] !== '--api-key-env') || ![length, length + 1].includes(a.length) || (a.length > length && a[length] !== '--write-tools')) return false;
+  const expected = createServer({ command: 'npx', args: a, apiKeyEnv: stored ? undefined : a[8], runtimeEnv: stored && a[8] === 'secret-service' ? ['DBUS_SESSION_BUS_ADDRESS', 'XDG_RUNTIME_DIR'] : [] });
   return Object.keys(value).length === Object.keys(expected).length
     && Object.entries(expected).every(([key, item]) => JSON.stringify(value[key]) === JSON.stringify(item));
 }

package/src/agents.ts

@@ -17,18 +17,18 @@ export type AgentAdapter = {
   instructions: string;
 };
 
-const codexServer = ({ command, args, apiKeyEnv }: McpLaunch) => ({ command, args, env_vars: [apiKeyEnv] });
+const codexServer = ({ command, args, apiKeyEnv, runtimeEnv }: McpLaunch) => ({ command, args, env_vars: apiKeyEnv ? [apiKeyEnv] : runtimeEnv ?? [] });
 const claudeServer = ({ command, args, apiKeyEnv }: McpLaunch) => ({
-  type: 'stdio', command, args, env: { [apiKeyEnv]: `\${${apiKeyEnv}}` },
+  type: 'stdio', command, args, env: apiKeyEnv ? { [apiKeyEnv]: `\${${apiKeyEnv}}` } : {},
 });
 const cursorServer = ({ command, args, apiKeyEnv }: McpLaunch) => ({
-  type: 'stdio', command, args, env: { [apiKeyEnv]: `\${env:${apiKeyEnv}}` },
+  type: 'stdio', command, args, env: apiKeyEnv ? { [apiKeyEnv]: `\${env:${apiKeyEnv}}` } : {},
 });
 const geminiServer = ({ command, args, apiKeyEnv }: McpLaunch) => ({
-  command, args, env: { [apiKeyEnv]: `\${${apiKeyEnv}}` },
+  command, args, env: apiKeyEnv ? { [apiKeyEnv]: `\${${apiKeyEnv}}` } : {},
 });
 const opencodeServer = ({ command, args, apiKeyEnv }: McpLaunch) => ({
-  type: 'local', command: [command, ...args], environment: { [apiKeyEnv]: `{env:${apiKeyEnv}}` },
+  type: 'local', command: [command, ...args], environment: apiKeyEnv ? { [apiKeyEnv]: `{env:${apiKeyEnv}}` } : {},
 });
 
 function vscodeUserDirectory({ cwd, home, env, platform = process.platform }: AgentContext): string {
@@ -164,7 +164,7 @@ export const agentAdapters = [
     detectionDirectories: context => [copilotDirectory(context), join(context.cwd, '.github', 'mcp.json')],
     paths: copilotPaths,
     configure: (path, text, launch) => strictJsonConfig(path, text, launch, claudeServer, copilotMapPath),
-    instructions: 'GitHub Copilot CLI: restart from the environment holding the selected key, trust the repository, then check /mcp and run /skills reload. Project MCP settings override user settings.',
+    instructions: 'GitHub Copilot CLI: restart with the configured credential source available, trust the repository, then check /mcp and run /skills reload. Project MCP settings override user settings.',
   },
   {
     id: 'kiro', executable: ['kiro', 'kiro-cli'],
@@ -174,7 +174,7 @@ export const agentAdapters = [
       return { mcp: join(directory, 'settings', 'mcp.json'), skill: join(directory, 'skills', 'lambdadb', 'SKILL.md') };
     },
     configure: (path, text, launch) => jsonConfig(path, text, launch, geminiServer),
-    instructions: 'Kiro IDE/CLI: restart from the environment holding the selected key and check /mcp. Approve the selected variable in Mcp Approved Env Vars when prompted. Custom agents must include the MCP JSON and skill resources; init does not alter agent permissions or definitions.',
+    instructions: 'Kiro IDE/CLI: restart with the configured credential source available and check /mcp. For environment mode, approve the selected variable in Mcp Approved Env Vars when prompted. Custom agents must include the MCP JSON and skill resources; init does not alter agent permissions or definitions.',
   },
   {
     id: 'cline', executable: [], scopes: ['user'],
@@ -184,7 +184,7 @@ export const agentAdapters = [
         skill: join(context.home, '.cline', 'skills', 'lambdadb', 'SKILL.md') };
     },
     configure: (path, text, launch) => strictJsonConfig(path, text, launch, cursorServer),
-    instructions: 'Cline VS Code extension: reload VS Code from the environment holding the selected key and check MCP Servers and the Skills menu. Init targets the default stable VS Code profile, not Cline CLI or other editors/profiles. No tools are auto-approved.',
+    instructions: 'Cline VS Code extension: reload VS Code with the configured credential source available and check MCP Servers and the Skills menu. Init targets the default stable VS Code profile, not Cline CLI or other editors/profiles. No tools are auto-approved.',
   },
 ] as const satisfies readonly AgentAdapter[];
 

package/src/cli.ts

@@ -1,15 +1,18 @@
 #!/usr/bin/env node
 import { Command, CommanderError, Option } from 'commander';
 import { readFileSync } from 'node:fs';
-import { integer, name, resolveConfig, saveSettings, type Options } from './config.js';
+import { integer, name, resolveConfig, saveSettings, settings, type Options } from './config.js';
 import { createInput, parseRef, queryInput, readJson, readJsonl, updateInput } from './input.js';
 import { importDocuments, planBatches } from './import-workflow.js';
-import { definitelyRejected, describeError, InputError, isInputError } from './errors.js';
+import { definitelyRejected, describeError, InputError, ManagementError, isInputError } from './errors.js';
 import { Output, type Envelope } from './output.js';
 import { checkConnection, runtime } from './runtime.js';
+import { CredentialVault, credentialReference } from './credentials.js';
 import { initialize } from './init.js';
 import { serveMcp } from './mcp.js';
 import { agentNames } from './agents.js';
+import { login, logout, management } from './account.js';
+import { organizations, projects, createProject, useProject } from './projects.js';
 
 const output = new Output();
 output.protect(process.env.LAMBDADB_API_KEY);
@@ -23,11 +26,14 @@ const program = new Command()
   .description('Project-scoped LambdaDB CLI. Only init prompts; all other commands are non-interactive.')
   .version(JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version)
   .option('--json', 'Emit one versioned JSON result on stdout; diagnostics stay on stderr')
+  .option('--api-url <url>', 'Account API origin (login reuses the saved origin, otherwise https://api.lambdadb.ai)')
   .option('--endpoint <url>', 'API origin (overrides LAMBDADB_ENDPOINT and saved configuration)')
   .option('--project <name>', 'Existing project (overrides LAMBDADB_PROJECT and saved configuration)')
   .option('--api-key-env <name>', 'Environment variable holding the key; never pass a key as an argument')
+  .option('--credential-store <store>', 'OS credential backend: auto, keychain, windows, secret-service or keyutils (init --connect selects auto)')
+  .option('--credential-id <uuid>', 'Non-secret saved credential reference (normally generated by init)')
   .option('--config <path>', 'Configuration path (overrides LAMBDADB_CONFIG)')
-  .option('--timeout-ms <ms>', 'Total network budget, 1–3600000 ms (default 30000)')
+  .option('--timeout-ms <ms>', 'Data API: total command budget; account/project API: per HTTP request, 1–3600000 ms (default 30000)')
   .showSuggestionAfterError(false)
   .exitOverride()
   .configureOutput({ writeErr: () => {} })
@@ -73,18 +79,42 @@ program.command('configure')
   });
 
 program.command('init')
-  .description('Connect an existing project and install agent MCP configuration and a usage skill')
+  .description('Connect through Console or existing credentials, then install agent MCP configuration and a usage skill')
+  .option('--connect', 'Select or create a project through account login; reuse saved project keys when available')
+  .option('--no-browser', 'Print the verification URL without opening a local browser (for SSH)')
   .option('--non-interactive', 'Require explicit agent/scope choices; never prompt')
   .option('--agents <names>', `Comma-separated ${agentNames} subset, or none`)
   .option('--scope <scope>', 'Agent configuration scope: project (current directory) or user')
   .option('--write-tools', 'Explicitly enable MCP write tools (default: read-only)')
-  .addHelpText('after', '\nObtain endpoint, project and a project API key manually from https://console.lambdadb.ai.\nExport the key securely before running init; no key value is saved.\nAutomation example:\n  lambdadb init --non-interactive --agents codex,claude,cursor --scope project --endpoint https://api.lambdadb.ai --project my-project --json')
+  .addHelpText('after', '\nBrowser setup: lambdadb init --connect (add --no-browser for SSH).\nThe browser handles signup/login and CLI approval. Select or create the project in your terminal.\nBrowser setup saves the project key only in an OS credential store. Account sessions and project keys are stored separately in the OS store; configuration files contain no secrets.\nManual/CI setup: obtain a project key in Console and export it securely; init saves only the environment-variable name.\nAutomation example:\n  lambdadb init --non-interactive --agents codex,claude,cursor --scope project --endpoint https://api.lambdadb.ai --project my-project --json')
   .action(async (_opts, cmd: Command) => {
     const data = await initialize(cmd.optsWithGlobals(), output);
     target = { endpoint: data.settings.endpoint, project: data.settings.project };
     result(data, 'Initialization complete. Authentication and collection-list access verified; search readiness is not verified.');
   });
 
+program.command('login').description('Authorize account management in a browser and save a separate OS session')
+  .option('--no-browser', 'Print a URL usable on another device without opening a browser')
+  .action(async (_opts, cmd: Command) => result(await login(cmd.optsWithGlobals(), output), 'Account login saved. Project connections and agent settings are unchanged.'));
+program.command('logout').description('Revoke the saved account session and remove it locally; keep project connections')
+  .action(async (_opts, cmd: Command) => { await logout(cmd.optsWithGlobals(), output); result({ loggedOut: true, projectKeysRevoked: false }, 'Account logged out. Project keys and agent connections are unchanged.'); });
+program.command('orgs').description('Manage account Organizations').command('list')
+  .action(async (_opts, cmd: Command) => result({ organizations: await organizations(cmd.optsWithGlobals(), output) }, 'Accessible Organizations.'));
+const projectCommands = program.command('projects').description('List, create and select projects using the saved account session');
+projectCommands.command('list').requiredOption('--org <uuid>', 'Organization ID')
+  .action(async (opts, cmd: Command) => result({ projects: await projects(cmd.optsWithGlobals(), opts.org, output) }, 'Projects in the selected Organization.'));
+projectCommands.command('regions').description('List available regions before project creation')
+  .action(async (_opts, cmd: Command) => { const api = await management(cmd.optsWithGlobals(), output); result(await api.request('regions'), 'Project regions.'); });
+projectCommands.command('create').option('--org <uuid>', 'Existing Organization ID').option('--default-org', 'Explicitly prepare the default Organization on submission')
+  .requiredOption('--name <name>', 'Project name').requiredOption('--region <region>', 'Region from projects regions')
+  .action(async (opts, cmd: Command) => {
+    const created = await createProject(cmd.optsWithGlobals(), opts, output);
+    result(created, 'Project requested. Check projects list for ACTIVE status; creation does not establish search readiness.');
+  });
+projectCommands.command('use').requiredOption('--org <uuid>', 'Organization ID').requiredOption('--project-id <uuid>', 'Project ID')
+  .option('--issue-key', 'Explicitly issue a new project key, including replacement of a saved connection')
+  .action(async (opts, cmd: Command) => result(await useProject(cmd.optsWithGlobals(), opts.org, opts.projectId, !!opts.issueKey, output), 'CLI project selected. Agent configurations are unchanged.'));
+
 program.command('mcp')
   .description('Launch the existing stdio MCP package with runtime credential forwarding (used by init)')
   .option('--write-tools', 'Explicitly enable MCP write tools (default: read-only)')
@@ -99,6 +129,16 @@ program.command('mcp')
     process.exitCode = await serveMcp(config, !!opts.writeTools);
   });
 
+program.command('credentials').description('Manage local OS credential references').command('remove')
+  .description('Delete this connection’s local OS credential; keep metadata and do not revoke the server key')
+  .action(async (_opts, cmd: Command) => {
+    const selected = await settings(cmd.optsWithGlobals());
+    if (!selected.credentialStore || !selected.credentialId) throw new InputError('This connection uses an environment variable. Unset it in your shell or secret manager; revoke the project key separately in Console.');
+    await new CredentialVault().remove({ ...selected, ...credentialReference(selected.credentialStore, selected.credentialId) });
+    result({ credentialStore: selected.credentialStore, credentialKeyId: selected.credentialKeyId, credentialKeyName: selected.credentialKeyName, serverKeyRevoked: false },
+      'Local credential removed. Connection references remain. Revoke the project key in Console if you no longer need it.');
+  });
+
 program.command('doctor')
   .description('Check configuration, authentication and project collection-list access')
   .action(async (_opts, cmd: Command) => connected(cmd, async ({ client, options }) => {
@@ -247,7 +287,7 @@ try {
     output.json ||= process.argv.includes('--json');
     const failure = error instanceof CommanderError
       ? new InputError('Invalid or incomplete command. Run lambdadb --help or the command-specific --help.') : error;
-    const unknownWrite = mutationStarted && !definitelyRejected(failure);
+    const unknownWrite = (mutationStarted && !definitelyRejected(failure)) || (failure instanceof ManagementError && ['write_outcome_unknown', 'issuance_unconfirmed'].includes(failure.code));
     const exitCode = isInputError(failure) ? 2 : unknownWrite ? 5 : 3;
     if (commandName === 'mcp') {
       const safe = describeError(failure);

package/src/config.ts

@@ -1,13 +1,19 @@
 import { homedir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { lstat, mkdir, readFile, realpath, rename, rm, writeFile } from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
+import { CredentialVault, credentialReference, type CredentialReference } from './credentials.js';
 import { InputError } from './errors.js';
 
-export type Settings = { endpoint?: string; project?: string; apiKeyEnv?: string };
-export type Config = Required<Settings> & { apiKey: string; timeoutMs: number };
+export type Settings = { endpoint?: string; project?: string; apiKeyEnv?: string; credentialKeyId?: string; credentialKeyName?: string } & Partial<CredentialReference>;
+export type SelectedSettings = Required<Pick<Settings, 'endpoint' | 'project' | 'apiKeyEnv'>> & Partial<CredentialReference> & Pick<Settings, 'credentialKeyId' | 'credentialKeyName'>;
+export type Config = SelectedSettings & { apiKey: string; timeoutMs: number };
 export type Options = Settings & { config?: string; timeoutMs?: string };
 
+export function timeoutMs(options: Options): number {
+  return integer(options.timeoutMs ?? process.env.LAMBDADB_TIMEOUT_MS ?? '30000', 'Timeout', 1, 3600000);
+}
+
 export function configPath(options: Options): string {
   return resolve(options.config ?? process.env.LAMBDADB_CONFIG
     ?? join(process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config'), 'lambdadb', 'config.json'));
@@ -53,20 +59,32 @@ export async function loadSettings(path: string, explicitlySelected = false): Pr
   try {
     const value = JSON.parse(text);
     if (!value || typeof value !== 'object' || Array.isArray(value)
-      || Object.keys(value).some(k => !['endpoint', 'project', 'apiKeyEnv'].includes(k))
+      || Object.keys(value).some(k => !['endpoint', 'project', 'apiKeyEnv', 'credentialStore', 'credentialId', 'credentialKeyId', 'credentialKeyName'].includes(k))
       || Object.values(value).some(v => typeof v !== 'string')) throw new Error();
+    for (const key of ['credentialKeyId', 'credentialKeyName']) {
+      if (value[key] !== undefined && (!value.credentialStore || !/^[a-zA-Z0-9_-]{1,128}$/.test(value[key]))) throw new Error();
+    }
+    if (value.credentialStore !== undefined || value.credentialId !== undefined) credentialReference(value.credentialStore, value.credentialId);
     return value;
-  } catch { throw new InputError('Configuration must be a JSON object with only endpoint, project and apiKeyEnv strings. Never store an API key in it.'); }
+  } catch { throw new InputError('Configuration must be a JSON object with endpoint, project, apiKeyEnv and optional credentialStore/credentialId/credentialKeyId/credentialKeyName strings. Never store an API key in it.'); }
 }
 
-export async function settings(options: Options, creating = false): Promise<Required<Settings>> {
+export async function settings(options: Options, creating = false): Promise<SelectedSettings> {
   const saved = await loadSettings(configPath(options), !creating && !!(options.config ?? process.env.LAMBDADB_CONFIG));
   const selectedEndpoint = options.endpoint ?? process.env.LAMBDADB_ENDPOINT ?? saved.endpoint;
   const project = options.project ?? process.env.LAMBDADB_PROJECT ?? saved.project;
   if (!selectedEndpoint || !project) throw new InputError('Endpoint and project are required. Run configure or set LAMBDADB_ENDPOINT and LAMBDADB_PROJECT.');
   // Project names are encoded as a single SDK URL segment, with no implicit playground fallback.
   if (!/^[a-zA-Z0-9_-]+$/.test(project)) throw new InputError('Project must contain only letters, digits, underscores or hyphens.');
+  const stored = options.credentialStore || options.credentialId ? credentialReference(options.credentialStore, options.credentialId) :
+    saved.credentialStore ? credentialReference(saved.credentialStore, saved.credentialId) : undefined;
+  const previousIdentity = stored?.credentialId === saved.credentialId ? saved : {};
+  const identity = {
+    ...(options.credentialKeyId ?? previousIdentity.credentialKeyId ? { credentialKeyId: options.credentialKeyId ?? previousIdentity.credentialKeyId } : {}),
+    ...(options.credentialKeyName ?? previousIdentity.credentialKeyName ? { credentialKeyName: options.credentialKeyName ?? previousIdentity.credentialKeyName } : {}),
+  };
   return {
+    ...(stored && (options.credentialStore || !(options.apiKeyEnv ?? process.env.LAMBDADB_API_KEY_ENV)) ? { ...stored, ...identity } : {}),
     endpoint: endpoint(selectedEndpoint), project,
     apiKeyEnv: environmentName(options.apiKeyEnv ?? process.env.LAMBDADB_API_KEY_ENV ?? saved.apiKeyEnv ?? 'LAMBDADB_API_KEY'),
   };
@@ -74,15 +92,17 @@ export async function settings(options: Options, creating = false): Promise<Requ
 
 export async function resolveConfig(options: Options, creating = false): Promise<Config> {
   const selected = await settings(options, creating);
-  const apiKey = process.env[selected.apiKeyEnv];
+  const apiKey = selected.credentialStore && selected.credentialId
+    ? await new CredentialVault().read({ ...selected, ...credentialReference(selected.credentialStore, selected.credentialId) })
+    : process.env[selected.apiKeyEnv];
   if (!apiKey || !apiKey.trim() || /[\r\n]/.test(apiKey)) throw new InputError('The selected API-key environment variable is missing or invalid. Supply it through your shell or CI secret manager.');
   return {
     ...selected, apiKey,
-    timeoutMs: integer(options.timeoutMs ?? process.env.LAMBDADB_TIMEOUT_MS ?? '30000', 'Timeout', 1, 3600000),
+    timeoutMs: timeoutMs(options),
   };
 }
 
-export async function saveSettings(options: Options): Promise<{ path: string; settings: Required<Settings> }> {
+export async function saveSettings(options: Options): Promise<{ path: string; settings: SelectedSettings }> {
   const value = await settings(options, true);
   const path = configPath(options);
   const temp = `${path}.${randomUUID()}.tmp`;
@@ -94,3 +114,16 @@ export async function saveSettings(options: Options): Promise<{ path: string; se
   finally { await rm(temp, { force: true }).catch(() => {}); }
   return { path, settings: value };
 }
+
+export async function fileIdentity(path: string): Promise<string> {
+  try { return await realpath(path); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw new InputError(`Cannot resolve configuration path: ${path}.`);
+    const info = await lstat(path).catch(error => {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+      throw new InputError(`Cannot resolve configuration path: ${path}.`);
+    });
+    if (info?.isSymbolicLink()) throw new InputError(`Configuration symbolic link has a missing target: ${path}. Restore its target before rerunning init.`);
+    return join(await fileIdentity(dirname(path)), basename(path));
+  }
+}