@bctrl/cli 0.1.6 → 0.1.8

package/dist/commands/space/index.js

@@ -1,80 +1,83 @@
 import { Command } from 'commander';
-import { readJsonFile } from '../shared/io.js';
-import { outputFlags, requestOperationAndPrint } from '../shared/operation.js';
+import { buildOperationInput, outputFlags, requestOperationAndPrint } from '../shared/operation.js';
 import { addOutputFlags } from '../shared/output.js';
 import { CliError } from '../../runtime/errors.js';
 import { createSpaceListCommand } from './list.js';
 export function createSpaceCommand(factory) {
     const command = new Command('space').description('Manage BCTRL spaces');
     command.addCommand(createSpaceListCommand(factory));
-    command.addCommand(addOutputFlags(new Command('get').description('View a space').argument('<spaceId>')).action(async (spaceId, options) => {
-        await requestOperationAndPrint(factory, 'spaces.get', {
+    command.addCommand(addOutputFlags(new Command('get')
+        .description('View a space')
+        .argument('<spaceId>')
+        .option('--params <json>', 'Path/query parameters as a JSON object (inline, @file, or - for stdin)')).action(async (spaceId, options) => {
+        await requestOperationAndPrint(factory, 'spaces.get', await buildOperationInput('spaces.get', options, {
             pathParams: { spaceId },
             output: outputFlags(options),
-        });
+        }));
     }));
     command.addCommand(addOutputFlags(new Command('create')
         .description('Create a space')
         .option('--name <name>', 'Space name')
         .option('--subaccount-id <id>', 'Subaccount id')
-        .option('--input <path>', 'Read JSON request body from file, or - for stdin')).action(async (options) => {
-        await requestOperationAndPrint(factory, 'spaces.create', {
-            body: typeof options.input === 'string'
-                ? (await readJsonFile(options.input))
-                : {
-                    name: options.name,
-                    subaccountId: options.subaccountId,
-                },
+        .option('--params <json>', 'Path/query parameters as a JSON object (inline, @file, or - for stdin)')
+        .option('--body <json>', 'Request body as JSON (inline, @file, or - for stdin)')).action(async (options) => {
+        await requestOperationAndPrint(factory, 'spaces.create', await buildOperationInput('spaces.create', options, {
+            body: {
+                name: options.name,
+            },
+            actingSubaccountId: options.subaccountId,
             output: outputFlags(options),
-        });
+        }));
     }));
     command.addCommand(addOutputFlags(new Command('patch')
         .description('Edit a space')
         .argument('<spaceId>')
         .option('--name <name>', 'Space name')
-        .option('--input <path>', 'Read JSON request body from file, or - for stdin')).action(async (spaceId, options) => {
-        await requestOperationAndPrint(factory, 'spaces.update', {
+        .option('--params <json>', 'Path/query parameters as a JSON object (inline, @file, or - for stdin)')
+        .option('--body <json>', 'Request body as JSON (inline, @file, or - for stdin)')).action(async (spaceId, options) => {
+        await requestOperationAndPrint(factory, 'spaces.update', await buildOperationInput('spaces.update', options, {
             pathParams: { spaceId },
-            body: typeof options.input === 'string'
-                ? (await readJsonFile(options.input))
-                : { name: options.name },
+            body: { name: options.name },
             output: outputFlags(options),
-        });
+        }));
     }));
     command.addCommand(addOutputFlags(new Command('delete')
         .description('Delete a space')
         .argument('<spaceId>')
-        .option('-y, --yes', 'Confirm deletion')).action(async (spaceId, options) => {
+        .option('-y, --yes', 'Confirm deletion')
+        .option('--params <json>', 'Path/query parameters as a JSON object (inline, @file, or - for stdin)')).action(async (spaceId, options) => {
         if (options.yes !== true) {
             throw new CliError('Refusing to delete without --yes');
         }
-        await requestOperationAndPrint(factory, 'spaces.delete', {
+        await requestOperationAndPrint(factory, 'spaces.delete', await buildOperationInput('spaces.delete', options, {
             pathParams: { spaceId },
             output: outputFlags(options),
-        });
+        }));
     }));
     command.addCommand(createSpaceEnvironmentCommand(factory));
     return command;
 }
 function createSpaceEnvironmentCommand(factory) {
     const command = new Command('env').description('Manage a space environment');
-    command.addCommand(addOutputFlags(new Command('get').description('Get a space environment').argument('<spaceId>')).action(async (spaceId, options) => {
-        await requestOperationAndPrint(factory, 'spaces.environment.get', {
+    command.addCommand(addOutputFlags(new Command('get')
+        .description('Get a space environment')
+        .argument('<spaceId>')
+        .option('--params <json>', 'Path/query parameters as a JSON object (inline, @file, or - for stdin)')).action(async (spaceId, options) => {
+        await requestOperationAndPrint(factory, 'spaces.environment.get', await buildOperationInput('spaces.environment.get', options, {
             pathParams: { spaceId },
             output: outputFlags(options),
-        });
+        }));
     }));
     command.addCommand(addOutputFlags(new Command('patch')
         .description('Update a space environment')
         .argument('<spaceId>')
-        .option('--input <path>', 'Read JSON request body from file, or - for stdin')).action(async (spaceId, options) => {
-        await requestOperationAndPrint(factory, 'spaces.environment.update', {
+        .option('--params <json>', 'Path/query parameters as a JSON object (inline, @file, or - for stdin)')
+        .option('--body <json>', 'Request body as JSON (inline, @file, or - for stdin)')).action(async (spaceId, options) => {
+        await requestOperationAndPrint(factory, 'spaces.environment.update', await buildOperationInput('spaces.environment.update', options, {
             pathParams: { spaceId },
-            body: typeof options.input === 'string'
-                ? (await readJsonFile(options.input))
-                : {},
+            body: {},
             output: outputFlags(options),
-        });
+        }));
     }));
     return command;
 }

package/dist/commands/space/list.js

@@ -1,17 +1,18 @@
 import { Command } from 'commander';
-import { addPaginationFlags, outputFlags, requestOperationAndPrint } from '../shared/operation.js';
+import { addPaginationFlags, buildOperationInput, outputFlags, requestOperationAndPrint, } from '../shared/operation.js';
 import { addOutputFlags } from '../shared/output.js';
 export function createSpaceListCommand(factory) {
     return addOutputFlags(addPaginationFlags(new Command('list')
         .description('List spaces')
-        .option('--subaccount <id>', 'Filter by subaccount id'))).action(async (options) => {
-        await requestOperationAndPrint(factory, 'spaces.list', {
+        .option('--subaccount <id>', 'Filter by subaccount id')
+        .option('--params <json>', 'Path/query parameters as a JSON object (inline, @file, or - for stdin)'))).action(async (options) => {
+        await requestOperationAndPrint(factory, 'spaces.list', await buildOperationInput('spaces.list', options, {
             query: {
-                subaccountId: options.subaccount,
                 limit: options.limit,
                 cursor: options.cursor,
             },
+            actingSubaccountId: options.subaccount,
             output: outputFlags(options),
-        });
+        }));
     });
 }

package/dist/commands/subaccount/index.js

@@ -2,7 +2,7 @@ import { Command } from 'commander';
 import { readJsonFile } from '../shared/io.js';
 import { parsePositiveInteger } from '../shared/options.js';
 import { addOutputFlags } from '../shared/output.js';
-import { addPaginationFlags, createOperationJsonBodyCommand, createOperationListCommand, createOperationViewCommand, outputFlags, requestOperationAndPrint, } from '../shared/operation.js';
+import { addPaginationFlags, buildOperationInput, createOperationJsonBodyCommand, createOperationListCommand, createOperationViewCommand, outputFlags, requestOperationAndPrint, } from '../shared/operation.js';
 export function createSubaccountCommand(factory) {
     const command = new Command('subaccount').description('Manage subaccounts');
     command.addCommand(createOperationListCommand(factory, {
@@ -37,11 +37,12 @@ export function createSubaccountCommand(factory) {
     command.addCommand(addOutputFlags(new Command('archive')
         .description('Archive a subaccount')
         .argument('<subaccountId>')
-        .requiredOption('-y, --yes', 'Confirm archive')).action(async (subaccountId, options) => {
-        await requestOperationAndPrint(factory, 'subaccounts.archive', {
+        .requiredOption('-y, --yes', 'Confirm archive')
+        .option('--params <json>', 'Path/query parameters as a JSON object (inline, @file, or - for stdin)')).action(async (subaccountId, options) => {
+        await requestOperationAndPrint(factory, 'subaccounts.archive', await buildOperationInput('subaccounts.archive', options, {
             pathParams: { subaccountId },
             output: outputFlags(options),
-        });
+        }));
     }));
     command.addCommand(createSubaccountUsageCommand(factory));
     return command;
@@ -55,12 +56,8 @@ function createSubaccountWriteCommand(factory, name, operationId, argNames = [])
         configure: (cmd) => cmd
             .option('--name <name>', 'Subaccount name')
             .option('--external-id <id>', 'External id')
-            .option('--metadata-file <path>', 'Metadata JSON file')
-            .option('--input <path>', 'Read full JSON request body from file, or - for stdin'),
+            .option('--metadata-file <path>', 'Metadata JSON file'),
         body: async (_args, options) => {
-            if (typeof options.input === 'string') {
-                return (await readJsonFile(options.input));
-            }
             return {
                 name: options.name,
                 externalId: options.externalId,
@@ -76,18 +73,19 @@ function createSubaccountUsageCommand(factory) {
         .description('Show subaccount usage')
         .argument('[id]')
         .option('-L, --limit <number>', 'Maximum number of usage records to return', parsePositiveInteger)
-        .option('--cursor <cursor>', 'Pagination cursor')).action(async (id, options) => {
+        .option('--cursor <cursor>', 'Pagination cursor')
+        .option('--params <json>', 'Path/query parameters as a JSON object (inline, @file, or - for stdin)')).action(async (id, options) => {
         if (id) {
-            await requestOperationAndPrint(factory, 'subaccounts.get', {
+            await requestOperationAndPrint(factory, 'subaccounts.get', await buildOperationInput('subaccounts.get', options, {
                 pathParams: { subaccountId: id },
                 query: { include: ['usage'] },
                 output: outputFlags(options),
-            });
+            }));
             return;
         }
-        await requestOperationAndPrint(factory, 'subaccounts.usage.list', {
+        await requestOperationAndPrint(factory, 'subaccounts.usage.list', await buildOperationInput('subaccounts.usage.list', options, {
             query: { limit: options.limit, cursor: options.cursor },
             output: outputFlags(options),
-        });
+        }));
     });
 }

package/dist/commands/usage/index.js

@@ -1,13 +1,17 @@
 import { Command } from 'commander';
 import { addOutputFlags } from '../shared/output.js';
-import { outputFlags, requestOperationAndPrint } from '../shared/operation.js';
+import { buildOperationInput, outputFlags, requestOperationAndPrint } from '../shared/operation.js';
 export function createUsageCommand(factory) {
     const command = addOutputFlags(new Command('usage').description('Get organization usage'));
-    command.action(async (options) => {
-        await requestOperationAndPrint(factory, 'usage.get', { output: outputFlags(options) });
+    command
+        .option('--params <json>', 'Path/query parameters as a JSON object (inline, @file, or - for stdin)')
+        .action(async (options) => {
+        await requestOperationAndPrint(factory, 'usage.get', await buildOperationInput('usage.get', options, { output: outputFlags(options) }));
     });
-    command.addCommand(addOutputFlags(new Command('get').description('Get organization usage')).action(async (options) => {
-        await requestOperationAndPrint(factory, 'usage.get', { output: outputFlags(options) });
+    command.addCommand(addOutputFlags(new Command('get').description('Get organization usage'))
+        .option('--params <json>', 'Path/query parameters as a JSON object (inline, @file, or - for stdin)')
+        .action(async (options) => {
+        await requestOperationAndPrint(factory, 'usage.get', await buildOperationInput('usage.get', options, { output: outputFlags(options) }));
     }));
     return command;
 }

package/dist/commands/vault/index.js

@@ -1,9 +1,9 @@
 import { Command } from 'commander';
 import { CliError } from '../../runtime/errors.js';
-import { readJsonFile, readText } from '../shared/io.js';
+import { readText } from '../shared/io.js';
 import { parsePositiveInteger } from '../shared/options.js';
 import { addOutputFlags } from '../shared/output.js';
-import { createOperationDeleteCommand, createOperationJsonBodyCommand, createOperationListCommand, createOperationViewCommand, outputFlags, requestOperationAndPrint, } from '../shared/operation.js';
+import { buildOperationInput, createOperationDeleteCommand, createOperationJsonBodyCommand, createOperationListCommand, createOperationViewCommand, outputFlags, requestOperationAndPrint, } from '../shared/operation.js';
 export function createVaultCommand(factory) {
     const command = new Command('vault').description('Manage vault secrets and TOTP codes');
     command.addCommand(createOperationListCommand(factory, {
@@ -42,14 +42,15 @@ function createVaultReadCommand(factory) {
     return addOutputFlags(new Command('read')
         .description('Read a vault secret value')
         .argument('<key>')
-        .option('--reveal', 'Allow printing a secret to an interactive terminal')).action(async (key, options) => {
+        .option('--reveal', 'Allow printing a secret to an interactive terminal')
+        .option('--params <json>', 'Path/query parameters as a JSON object (inline, @file, or - for stdin)')).action(async (key, options) => {
         if (factory.io.isStdoutTTY() && options.reveal !== true) {
             throw new CliError('Refusing to print a secret to a terminal without --reveal');
         }
-        await requestOperationAndPrint(factory, 'vault.secrets.value', {
+        await requestOperationAndPrint(factory, 'vault.secrets.value', await buildOperationInput('vault.secrets.value', options, {
             pathParams: { key },
             output: outputFlags(options),
-        });
+        }));
     });
 }
 function createVaultSetCommand(factory) {
@@ -68,12 +69,8 @@ function createVaultSetCommand(factory) {
             .option('--totp-secret <secret>', 'TOTP seed')
             .option('--label <label>', 'Display label')
             .option('--origin <origin...>', 'Allowed origin')
-            .option('--origin-pattern <pattern...>', 'Allowed origin pattern')
-            .option('--input <path>', 'Read full JSON request body from file, or - for stdin'),
+            .option('--origin-pattern <pattern...>', 'Allowed origin pattern'),
         body: async (args, options) => {
-            if (typeof options.input === 'string') {
-                return (await readJsonFile(options.input));
-            }
             const password = typeof options.passwordFromFile === 'string'
                 ? (await readText(options.passwordFromFile)).trimEnd()
                 : options.password;
@@ -97,7 +94,7 @@ function createVaultSetCommand(factory) {
             }
             if (type === 'value') {
                 if (typeof value !== 'string') {
-                    throw new CliError('Vault value secrets require --value, --value-from-file, or --input');
+                    throw new CliError('Vault value secrets require --value, --value-from-file, or --body');
                 }
                 return {
                     ...common,
@@ -106,7 +103,7 @@ function createVaultSetCommand(factory) {
                 };
             }
             if (typeof options.username !== 'string' || typeof password !== 'string') {
-                throw new CliError('Vault login secrets require --username and --password, --password-from-file, or --input');
+                throw new CliError('Vault login secrets require --username and --password, --password-from-file, or --body');
             }
             return {
                 ...common,
@@ -137,12 +134,8 @@ function createVaultPatchCommand(factory) {
             .option('--origin <origin...>', 'Allowed origin')
             .option('--clear-origins', 'Remove origins')
             .option('--origin-pattern <pattern...>', 'Allowed origin pattern')
-            .option('--clear-origin-patterns', 'Remove origin patterns')
-            .option('--input <path>', 'Read full JSON request body from file, or - for stdin'),
+            .option('--clear-origin-patterns', 'Remove origin patterns'),
         body: async (_args, options) => {
-            if (typeof options.input === 'string') {
-                return (await readJsonFile(options.input));
-            }
             const password = typeof options.passwordFromFile === 'string'
                 ? (await readText(options.passwordFromFile)).trimEnd()
                 : options.password;
@@ -159,7 +152,7 @@ function createVaultPatchCommand(factory) {
                 originPatterns: options.clearOriginPatterns === true ? null : options.originPattern,
             };
             if (!Object.values(body).some((value) => value !== undefined)) {
-                throw new CliError('Vault patch requires at least one field or --input');
+                throw new CliError('Vault patch requires at least one field or --body');
             }
             return body;
         },
@@ -168,10 +161,11 @@ function createVaultPatchCommand(factory) {
 function createVaultTotpCommand(factory) {
     return addOutputFlags(new Command('totp')
         .description('Generate the current TOTP code for a vault secret')
-        .argument('<key>')).action(async (key, options) => {
-        await requestOperationAndPrint(factory, 'vault.secrets.totp', {
+        .argument('<key>')
+        .option('--params <json>', 'Path/query parameters as a JSON object (inline, @file, or - for stdin)')).action(async (key, options) => {
+        await requestOperationAndPrint(factory, 'vault.secrets.totp', await buildOperationInput('vault.secrets.totp', options, {
             pathParams: { key },
             output: outputFlags(options),
-        });
+        }));
     });
 }

package/dist/config/auth-store.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { type SecretBackend } from './secret-store.js';
 export declare const StoredWhoamiSchema: z.ZodObject<{
     email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     scope: z.ZodEnum<{
@@ -7,14 +8,33 @@ export declare const StoredWhoamiSchema: z.ZodObject<{
     }>;
     organizationId: z.ZodString;
     subaccountId: z.ZodNullable<z.ZodString>;
-    defaultSpaceId: z.ZodString;
+    defaultSpaceId: z.ZodNullable<z.ZodString>;
+    effectiveScope: z.ZodObject<{
+        scope: z.ZodEnum<{
+            organization: "organization";
+            subaccount: "subaccount";
+        }>;
+        organizationId: z.ZodString;
+        subaccountId: z.ZodNullable<z.ZodString>;
+        defaultSpaceId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
     keyId: z.ZodString;
     plan: z.ZodString;
 }, z.core.$strict>;
 export type StoredWhoami = z.infer<typeof StoredWhoamiSchema>;
-export declare const StoredAuthSchema: z.ZodObject<{
+/** How the stored credential was obtained. `device` is reserved for the device-login flow. */
+export declare const AuthMethodSchema: z.ZodEnum<{
+    "api-key": "api-key";
+    device: "device";
+}>;
+export type AuthMethod = z.infer<typeof AuthMethodSchema>;
+/**
+ * On-disk credential metadata. This file NEVER contains the secret — the token
+ * lives in the OS keychain (or a separate 0600 secret file when keychain is
+ * unavailable). See secret-store.ts.
+ */
+export declare const StoredAuthMetadataSchema: z.ZodObject<{
     apiBaseUrl: z.ZodString;
-    token: z.ZodString;
     whoami: z.ZodObject<{
         email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         scope: z.ZodEnum<{
@@ -23,15 +43,61 @@ export declare const StoredAuthSchema: z.ZodObject<{
         }>;
         organizationId: z.ZodString;
         subaccountId: z.ZodNullable<z.ZodString>;
-        defaultSpaceId: z.ZodString;
+        defaultSpaceId: z.ZodNullable<z.ZodString>;
+        effectiveScope: z.ZodObject<{
+            scope: z.ZodEnum<{
+                organization: "organization";
+                subaccount: "subaccount";
+            }>;
+            organizationId: z.ZodString;
+            subaccountId: z.ZodNullable<z.ZodString>;
+            defaultSpaceId: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>;
         keyId: z.ZodString;
         plan: z.ZodString;
     }, z.core.$strict>;
+    method: z.ZodEnum<{
+        "api-key": "api-key";
+        device: "device";
+    }>;
+    backend: z.ZodEnum<{
+        keychain: "keychain";
+        file: "file";
+    }>;
     createdAt: z.ZodString;
     validatedAt: z.ZodString;
 }, z.core.$strict>;
-export type StoredAuth = z.infer<typeof StoredAuthSchema>;
-export declare function getAuthFilePath(env?: NodeJS.ProcessEnv): string;
-export declare function readStoredAuth(env?: NodeJS.ProcessEnv): Promise<StoredAuth | null>;
-export declare function writeStoredAuth(auth: StoredAuth, env?: NodeJS.ProcessEnv): Promise<string>;
-export declare function deleteStoredAuth(env?: NodeJS.ProcessEnv): Promise<boolean>;
+export type StoredAuthMetadata = z.infer<typeof StoredAuthMetadataSchema>;
+/** Metadata + the resolved secret, assembled in memory only. */
+export type StoredCredential = StoredAuthMetadata & {
+    token: string;
+};
+export declare function normalizeApiBaseUrl(url: string): string;
+export declare function readStoredMetadata(env?: NodeJS.ProcessEnv): Promise<StoredAuthMetadata | null>;
+/**
+ * Resolve the full stored credential (metadata + secret) for the given active
+ * API base URL. Returns null when there is no metadata, when it is for a
+ * different base URL, or when the secret is missing (e.g. the keychain entry was
+ * deleted out from under a stale metadata file) — all of which mean "logged out".
+ */
+export declare function loadCredential(env?: NodeJS.ProcessEnv, activeApiBaseUrl?: string): Promise<StoredCredential | null>;
+export type SaveCredentialResult = {
+    path: string;
+    backend: SecretBackend;
+    keychainFallback: boolean;
+};
+export declare function saveCredential(input: {
+    apiBaseUrl: string;
+    token: string;
+    whoami: StoredWhoami;
+    method: AuthMethod;
+    createdAt: string;
+    validatedAt: string;
+}, env?: NodeJS.ProcessEnv): Promise<SaveCredentialResult>;
+/**
+ * Remove a stored credential. Deletes the secret from BOTH backends keyed by the
+ * (normalized) API base URL — independent of whether the metadata file exists,
+ * so a corrupt/missing metadata file can never orphan the secret — then removes
+ * the metadata file. Returns whether anything was removed.
+ */
+export declare function clearCredential(env: NodeJS.ProcessEnv | undefined, apiBaseUrl: string): Promise<boolean>;

package/dist/config/auth-store.js

@@ -1,61 +1,164 @@
-import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
-import { homedir } from 'node:os';
 import { z } from 'zod';
-const DEFAULT_AUTH_FILE_NAME = 'auth.json';
+import { getMetadataFilePath } from './paths.js';
+import { deleteSecretAllBackends, resolveSecretStore, } from './secret-store.js';
+const StoredEffectiveScopeSchema = z
+    .object({
+    scope: z.enum(['organization', 'subaccount']),
+    organizationId: z.string().min(1),
+    subaccountId: z.string().min(1).nullable(),
+    defaultSpaceId: z.string().min(1).nullable(),
+})
+    .strict();
 export const StoredWhoamiSchema = z
     .object({
     email: z.string().email().nullable().optional(),
     scope: z.enum(['organization', 'subaccount']),
     organizationId: z.string().min(1),
     subaccountId: z.string().min(1).nullable(),
-    defaultSpaceId: z.string().min(1),
+    defaultSpaceId: z.string().min(1).nullable(),
+    effectiveScope: StoredEffectiveScopeSchema,
     keyId: z.string().min(1),
     plan: z.string().min(1),
 })
     .strict();
-export const StoredAuthSchema = z
+/** How the stored credential was obtained. `device` is reserved for the device-login flow. */
+export const AuthMethodSchema = z.enum(['api-key', 'device']);
+/**
+ * On-disk credential metadata. This file NEVER contains the secret — the token
+ * lives in the OS keychain (or a separate 0600 secret file when keychain is
+ * unavailable). See secret-store.ts.
+ */
+export const StoredAuthMetadataSchema = z
     .object({
     apiBaseUrl: z.string().url(),
-    token: z.string().min(1),
     whoami: StoredWhoamiSchema,
+    method: AuthMethodSchema,
+    backend: z.enum(['keychain', 'file']),
     createdAt: z.string().datetime(),
     validatedAt: z.string().datetime(),
 })
     .strict();
-export function getAuthFilePath(env = process.env) {
-    if (env.BCTRL_AUTH_FILE?.trim()) {
-        return env.BCTRL_AUTH_FILE.trim();
-    }
-    const configDir = env.BCTRL_CONFIG_DIR?.trim() ??
-        (env.XDG_CONFIG_HOME?.trim()
-            ? join(env.XDG_CONFIG_HOME.trim(), 'bctrl')
-            : join(homedir(), '.config', 'bctrl'));
-    return join(configDir, DEFAULT_AUTH_FILE_NAME);
+const AUTH_WRITE_MARKER_FILE_NAME = 'auth.write';
+const AUTH_WRITE_WAIT_TIMEOUT_MS = 2000;
+const AUTH_WRITE_WAIT_INTERVAL_MS = 100;
+const AUTH_WRITE_STALE_MS = 30000;
+export function normalizeApiBaseUrl(url) {
+    return url.replace(/\/+$/, '');
 }
-export async function readStoredAuth(env = process.env) {
-    const path = getAuthFilePath(env);
+export async function readStoredMetadata(env = process.env) {
+    const path = getMetadataFilePath(env);
     try {
-        const text = await readFile(path, 'utf8');
-        return StoredAuthSchema.parse(JSON.parse(text));
+        const parsed = StoredAuthMetadataSchema.safeParse(JSON.parse(await readFile(path, 'utf8')));
+        // A schema mismatch means a legacy/corrupt metadata file (e.g. a pre-keychain
+        // auth.json that embedded a token). Treat it as "logged out" rather than
+        // throwing, so the CLI degrades to re-login instead of erroring on startup.
+        return parsed.success ? parsed.data : null;
     }
     catch (error) {
         if (isFileNotFound(error))
             return null;
+        if (error instanceof SyntaxError)
+            return null;
         const reason = error instanceof Error ? error.message : String(error);
-        throw new Error(`Failed to read BCTRL auth file at ${path}: ${reason}`);
+        throw new Error(`Failed to read BCTRL auth metadata at ${path}: ${reason}`);
     }
 }
-export async function writeStoredAuth(auth, env = process.env) {
-    const path = getAuthFilePath(env);
+/**
+ * Resolve the full stored credential (metadata + secret) for the given active
+ * API base URL. Returns null when there is no metadata, when it is for a
+ * different base URL, or when the secret is missing (e.g. the keychain entry was
+ * deleted out from under a stale metadata file) — all of which mean "logged out".
+ */
+export async function loadCredential(env = process.env, activeApiBaseUrl) {
+    const meta = await readStoredMetadataAfterPendingWrite(env);
+    if (!meta)
+        return null;
+    if (activeApiBaseUrl &&
+        normalizeApiBaseUrl(meta.apiBaseUrl) !== normalizeApiBaseUrl(activeApiBaseUrl)) {
+        return null;
+    }
+    const { store } = resolveSecretStore(env);
+    const token = await store.get(normalizeApiBaseUrl(meta.apiBaseUrl));
+    if (!token)
+        return null;
+    return { ...meta, token };
+}
+export async function saveCredential(input, env = process.env) {
+    await markCredentialWriteStarted(env);
+    const { store, keychainFallback } = resolveSecretStore(env);
+    try {
+        await store.set(normalizeApiBaseUrl(input.apiBaseUrl), input.token);
+        const metadata = {
+            apiBaseUrl: input.apiBaseUrl,
+            whoami: input.whoami,
+            method: input.method,
+            backend: store.backend,
+            createdAt: input.createdAt,
+            validatedAt: input.validatedAt,
+        };
+        const path = getMetadataFilePath(env);
+        await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+        await writeFile(path, `${JSON.stringify(metadata, null, 2)}\n`, { mode: 0o600 });
+        return { path, backend: store.backend, keychainFallback };
+    }
+    finally {
+        await clearCredentialWriteMarker(env);
+    }
+}
+/**
+ * Remove a stored credential. Deletes the secret from BOTH backends keyed by the
+ * (normalized) API base URL — independent of whether the metadata file exists,
+ * so a corrupt/missing metadata file can never orphan the secret — then removes
+ * the metadata file. Returns whether anything was removed.
+ */
+export async function clearCredential(env = process.env, apiBaseUrl) {
+    const secretRemoved = await deleteSecretAllBackends(normalizeApiBaseUrl(apiBaseUrl), env);
+    let metadataRemoved = false;
+    try {
+        await rm(getMetadataFilePath(env));
+        metadataRemoved = true;
+    }
+    catch (error) {
+        if (!isFileNotFound(error))
+            throw error;
+    }
+    return secretRemoved || metadataRemoved;
+}
+function getAuthWriteMarkerPath(env = process.env) {
+    return join(dirname(getMetadataFilePath(env)), AUTH_WRITE_MARKER_FILE_NAME);
+}
+async function markCredentialWriteStarted(env) {
+    const path = getAuthWriteMarkerPath(env);
     await mkdir(dirname(path), { recursive: true, mode: 0o700 });
-    await writeFile(path, `${JSON.stringify(auth, null, 2)}\n`, { mode: 0o600 });
-    return path;
+    await writeFile(path, new Date().toISOString(), { mode: 0o600 });
+}
+async function clearCredentialWriteMarker(env) {
+    try {
+        await rm(getAuthWriteMarkerPath(env));
+    }
+    catch (error) {
+        if (!isFileNotFound(error))
+            throw error;
+    }
 }
-export async function deleteStoredAuth(env = process.env) {
+async function readStoredMetadataAfterPendingWrite(env) {
+    const startedAt = Date.now();
+    for (;;) {
+        const meta = await readStoredMetadata(env);
+        if (meta)
+            return meta;
+        if (!(await isCredentialWriteInProgress(env)) || Date.now() - startedAt >= AUTH_WRITE_WAIT_TIMEOUT_MS) {
+            return null;
+        }
+        await sleep(AUTH_WRITE_WAIT_INTERVAL_MS);
+    }
+}
+async function isCredentialWriteInProgress(env) {
     try {
-        await rm(getAuthFilePath(env));
-        return true;
+        const marker = await stat(getAuthWriteMarkerPath(env));
+        return Date.now() - marker.mtimeMs < AUTH_WRITE_STALE_MS;
     }
     catch (error) {
         if (isFileNotFound(error))
@@ -63,6 +166,9 @@ export async function deleteStoredAuth(env = process.env) {
         throw error;
     }
 }
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function isFileNotFound(error) {
     return (typeof error === 'object' &&
         error !== null &&