@modelprofile.com/authswitch 2.1.2

package/ts/classes.cli.ts

@@ -0,0 +1,479 @@
+import * as plugins from './plugins.js';
+import { commitinfo } from './00_commitinfo_data.js';
+import { CodexHarness } from './classes.codexharness.js';
+import { OpenCodeHarness } from './classes.opencodeharness.js';
+import { ClaudeCodeHarness } from './classes.claudecodeharness.js';
+import { AuthSwitchTui } from './classes.tui.js';
+import { AglAuthSwitchCoordinator, AuthSwitchOperations, type TAuthSwitchCoordinator, type TAuthSwitchMutation } from './classes.operations.js';
+import { AccountListRenderer, readAccountList } from './classes.accountlist.js';
+import { duration, orderedUsageWindows, until } from './accounts.js';
+import { defaultPreusePrompt, PreuseError, validatePreuseOptions } from './preuse.js';
+import type { CodexSwitcher } from './classes.codexswitcher.js';
+import type { IAuthHarness, IHarnessAccount, IHarnessOutcome, IHarnessState, IHarnessPreuseResult } from './interfaces.harness.js';
+import { bold, dim, green, orange, plainText, red } from './formatting.js';
+
+const canPrompt = (): boolean =>
+  process.stdin.isTTY === true && process.stdout.isTTY === true && !process.env.CI;
+const COMMANDS = ['login', 'stash', 'list', 'ls', 'use', 'preuse', 'current', 'drop', 'rm', 'doctor'];
+
+/** Harness-independent command routing and interactive account management. */
+export class AuthSwitchCli {
+  private readonly harnesses = new Map<string, IAuthHarness>();
+  private console?: plugins.smartconsole.SmartConsole;
+  private running = false;
+  private readonly operations: AuthSwitchOperations;
+  private get out(): plugins.smartconsole.SmartConsole { return this.console ??= new plugins.smartconsole.SmartConsole(); }
+
+  constructor(harnessesArg?: IAuthHarness[] | CodexSwitcher, coordinatorArg?: TAuthSwitchCoordinator) {
+    const coordinator = new AglAuthSwitchCoordinator();
+    this.operations = new AuthSwitchOperations(coordinatorArg ?? (harnessesArg === undefined ? request => coordinator.coordinate(request) : undefined));
+    harnessesArg ??= [new CodexHarness(), new OpenCodeHarness(), new ClaudeCodeHarness()];
+    // Preserve the published single-Codex constructor at the composition boundary.
+    const harnesses = Array.isArray(harnessesArg) ? harnessesArg : [new CodexHarness(harnessesArg)];
+    for (const harness of harnesses) {
+      if (!/^[a-z][a-z0-9-]*$/.test(harness.id) || COMMANDS.includes(harness.id) || harness.id === 'help') {
+        throw new Error(`invalid harness name "${plainText(harness.id)}"`);
+      }
+      if (this.harnesses.has(harness.id)) throw new Error(`duplicate harness "${harness.id}"`);
+      this.harnesses.set(harness.id, harness);
+    }
+  }
+
+  private usage(): string {
+    return `${bold('authswitch')} ${dim(`v${commitinfo.version}`)}
+Manage saved accounts across harnesses.
+
+${bold('Usage')}
+  authswitch                         open the interactive guide
+  authswitch list                    list all accounts with live subscription, usage and resets
+  authswitch <harness> list           list accounts for one harness
+  authswitch list --json             print all account information as JSON
+  authswitch <harness> preuse <account> [--prompt <text>] [--model <id>]
+                                    send one prompt through that account without switching
+  authswitch <harness> stash [account/provider] [--keep]
+                                    save one active login; --keep leaves it active
+  authswitch <harness> use [account]   activate a saved account; prompts when omitted
+  authswitch <harness> current        show the active account
+  authswitch <harness> login [provider]
+                                    sign in and save a new account without switching
+  authswitch <harness> drop <account>  remove a saved account
+  authswitch <harness> doctor         diagnose the harness
+
+${bold('Harnesses')}
+  ${[...this.harnesses.values()].map((harnessArg) => `${harnessArg.id} (${harnessArg.label})`).join(', ') || 'none registered'}
+  Unqualified commands use the sole harness, or ask you to choose one.
+
+${bold('Options')}
+  -h, --help                         show this help
+  -v, --version                      show the version
+  -i, --interactive                  open the guided account manager
+  --tui                             open the terminal management dashboard
+  --json                            JSON output for list / ls only
+
+Preuse consumes the selected account's quota. Its default prompt is:
+  "${defaultPreusePrompt}"
+
+${bold('Environment')}
+  AUTHSWITCH_HOME   root directory for saved accounts (default ~/.authswitch)
+  NO_COLOR          disable coloured output
+  Other credential locations and executables are configured by each harness.
+`;
+  }
+
+  public async run(argvArg: string[]): Promise<number> {
+    if (this.running) throw new Error('This CLI is already running.');
+    this.running = true;
+    const args = [...argvArg];
+    try {
+      // Parse command values before global flags: a prompt may itself contain a flag.
+      if (args[0] === 'preuse' || (this.harnesses.has(args[0]) && args[1] === 'preuse')) {
+        const qualified = args[0] !== 'preuse';
+        return await this.commandPreuse(qualified ? this.harnesses.get(args[0]) : undefined, args.slice(qualified ? 2 : 1));
+      }
+      const jsonFlags = args.filter(value => value === '--json');
+      const json = jsonFlags.length === 1;
+      if (jsonFlags.length > 1) { process.stderr.write('Use --json only once.\n'); return 2; }
+      if (json) {
+        args.splice(args.indexOf('--json'), 1);
+        const route = [...args];
+        if (this.harnesses.has(route[0])) route.shift();
+        if (route.length !== 1 || !['list', 'ls'].includes(route[0])) {
+          process.stderr.write('--json requires list or ls, optionally qualified by a harness.\n');
+          return 2;
+        }
+      }
+      if (['-h', '--help', 'help'].includes(args[0]) || (args.length === 0 && !canPrompt())) {
+        process.stdout.write(`${this.usage()}\n`);
+        return 0;
+      }
+      if (['-v', '--version'].includes(args[0])) {
+        process.stdout.write(`${commitinfo.version}\n`);
+        return 0;
+      }
+      const modes = args.filter(value => ['-i', '--interactive', '--tui'].includes(value));
+      if (modes.length) {
+        const rest = args.filter(value => !['-i', '--interactive', '--tui'].includes(value));
+        if (modes.length !== 1 || rest.length > 1 || (rest.length === 1 && !this.harnesses.has(rest[0]))) {
+          process.stderr.write('Choose one interactive mode, optionally qualified by a harness; do not combine it with a command.\n');
+          return 2;
+        }
+        if (!canPrompt()) { process.stderr.write('Interactive mode requires a terminal outside CI.\n'); return 2; }
+        const harness = rest.length ? this.harnesses.get(rest[0]) : undefined;
+        if (modes[0] === '--tui') return await this.runTui(harness);
+        return await this.runInteractive(harness);
+      }
+      if (args.length === 0) return await this.runInteractive();
+      const first = args.shift()!;
+      let harness = this.harnesses.get(first);
+      const command = harness ? args.shift() ?? 'list' : first;
+      if (!harness && !COMMANDS.includes(command)) {
+        process.stderr.write(`${red('unknown harness or command')} "${plainText(first)}"\n\n${this.usage()}\n`);
+        return 2;
+      }
+      if (['list', 'ls'].includes(command)) {
+        if (args.length) { process.stderr.write('list accepts only --json; optionally put a harness before list.\n'); return 2; }
+        return await this.commandList(harness ? [harness] : [...this.harnesses.values()], json);
+      }
+      if (!harness) {
+        harness = await this.selectHarness();
+        if (!harness) return canPrompt() ? 0 : 2;
+      }
+      switch (command) {
+        case 'login':
+          if (args.length > 1 || args[0]?.startsWith('-')) { process.stderr.write('login accepts an optional provider ID.\n'); return 2; }
+          return await this.commandLogin(harness, args[0]);
+        case 'stash': {
+          const references = args.filter(value => value !== '--keep');
+          if (references.length > 1 || references.some(value => value.startsWith('-'))) { process.stderr.write('stash accepts one active account or provider and --keep.\n'); return 2; }
+          const account = await this.selectActive(harness, references[0]);
+          return account ? this.reportOutcome(await this.mutate(harness, { harnessId: harness.id, action: 'save', keepActive: args.includes('--keep'), accountId: account.id })) : 1;
+        }
+        case 'use': return await this.commandUse(harness, args[0]);
+        case 'current': this.printCurrent(harness, await harness.readState()); return 0;
+        case 'drop':
+        case 'rm': {
+          if (!args[0]) {
+            process.stderr.write(`${red('drop needs an account')}: authswitch ${harness.id} drop <account>\n`);
+            return 2;
+          }
+          const id = await this.resolveAccount(harness, args[0]);
+          return id === null ? 1 : this.reportOutcome(await harness.removeAccount(id));
+        }
+        case 'doctor': return this.reportOutcome(await harness.diagnose());
+        default:
+          process.stderr.write(`${red('unknown command')} "${plainText(command)}"\n\n${this.usage()}\n`);
+          return 2;
+      }
+    } catch (errorArg) {
+      process.stderr.write(`${red('error')} ${errorArg instanceof Error ? errorArg.message : String(errorArg)}\n`);
+      return 1;
+    } finally {
+      const console = this.console; this.console = undefined;
+      try { await console?.dispose(); } finally { this.running = false; }
+    }
+  }
+
+  private async runTui(harnessArg?: IAuthHarness): Promise<number> {
+    return new AuthSwitchTui([...this.harnesses.values()], this.out, this.operations).run(harnessArg);
+  }
+
+  private mutate(harness: IAuthHarness, mutation: TAuthSwitchMutation): Promise<IHarnessOutcome> {
+    return this.operations.run(harness, mutation, canPrompt() ? async message => await this.out.prompts.ask({
+      name: 'waitForIdle', type: 'confirm', message, default: false,
+    }) === true : undefined);
+  }
+
+  private async commandLogin(harness: IAuthHarness, providerId?: string): Promise<number> {
+    if (!harness.beginLogin) { process.stderr.write(`${plainText(harness.label)} does not support a hosted login flow. ${harness.loginHint}\n`); return 2; }
+    const providers = harness.loginProviders ?? [];
+    let provider = providers.find(item => item.providerId === providerId) ?? (!providerId && providers.length === 1 ? providers[0] : undefined);
+    if (!provider && !providerId && canPrompt()) {
+      const selected = await this.out.prompts.ask({ name: 'loginProvider', type: 'list', message: 'Which provider would you like to log in to?', choices: providers.map(item => ({ name: item.label, value: item.providerId })) });
+      provider = providers.find(item => item.providerId === selected);
+    }
+    if (!provider || !provider.flows.length) { process.stderr.write('Choose a supported provider: ' + providers.map(item => item.providerId).join(', ') + '\n'); return 2; }
+    let handle: Awaited<ReturnType<NonNullable<IAuthHarness['beginLogin']>>> | undefined;
+    let cancelled = false;
+    const cancel = () => { cancelled = true; void handle?.cancel().catch(() => undefined); };
+    process.on('SIGINT', cancel); process.on('SIGTERM', cancel);
+    try {
+      handle = await harness.beginLogin({ providerId: provider.providerId, flow: provider.flows.includes('device') ? 'device' : provider.flows[0] });
+      if (cancelled) await handle.cancel();
+      else if (handle.prompt.flow === 'device') {
+        process.stdout.write(`Open ${plainText(handle.prompt.verificationUrl)}\nCode: ${plainText(handle.prompt.userCode)}\nWaiting for login. Press Ctrl+C to cancel.\n`);
+      } else process.stdout.write(`Open ${plainText(handle.prompt.authUrl)}\nWaiting for login. Press Ctrl+C to cancel.\n`);
+      return this.reportOutcome((await handle.completion).outcome);
+    } finally {
+      process.removeListener('SIGINT', cancel); process.removeListener('SIGTERM', cancel);
+      await handle?.close();
+    }
+  }
+
+  private async commandPreuse(harnessArg: IAuthHarness | undefined, argsArg: string[]): Promise<number> {
+    let reference: string | undefined;
+    let prompt = defaultPreusePrompt;
+    let model: string | undefined;
+    const flags = new Set<string>();
+    try {
+      for (let index = 0; index < argsArg.length; index++) {
+        const argument = argsArg[index];
+        if (argument.startsWith('--prompt=') || argument.startsWith('--model=') || argument === '--prompt' || argument === '--model') {
+          const separator = argument.indexOf('=');
+          const flag = separator < 0 ? argument : argument.slice(0, separator);
+          if (flags.has(flag)) throw new PreuseError(`Use ${flag} only once.`);
+          flags.add(flag);
+          const value = separator < 0 ? argsArg[++index] : argument.slice(separator + 1);
+          if (value === undefined) throw new PreuseError(`${flag} requires a value.`);
+          if (flag === '--prompt') prompt = value; else model = value;
+        } else if (argument.startsWith('-') || reference !== undefined) {
+          throw new PreuseError('Usage: authswitch [harness] preuse <account> [--prompt <text>] [--model <id>]');
+        } else reference = argument;
+      }
+      validatePreuseOptions({ prompt, model });
+      if (!reference && !canPrompt()) throw new PreuseError('preuse requires an account outside an interactive terminal.');
+    } catch (error) {
+      process.stderr.write(`${error instanceof PreuseError ? error.message : 'Invalid preuse arguments.'}\n`);
+      return 2;
+    }
+    const harness = harnessArg ?? await this.selectHarness();
+    if (!harness) return canPrompt() ? 0 : 2;
+    if (!harness.preuseAccount) { process.stderr.write(`Preuse is not supported by ${plainText(harness.label)}.\n`); return 2; }
+    const state = await harness.readState();
+    let account: IHarnessAccount | undefined;
+    if (reference) {
+      const matches = state.accounts.filter(item => item.id === reference || item.label === reference);
+      if (matches.length > 1) { process.stderr.write('That account reference is ambiguous; use an exact account ID.\n'); return 1; }
+      account = matches[0];
+      if (!account) {
+        const id = await this.resolveAccount(harness, reference);
+        if (id === null) return 1;
+        account = state.accounts.find(item => item.id === id);
+      }
+    } else {
+      const answer = await this.out.prompts.ask({
+        name: 'preuseAccount', type: 'list', message: `Which ${harness.label} account should receive the preuse prompt? This consumes quota.`,
+        choices: [...state.accounts.map(item => ({ name: plainText(item.label), value: item.id })), { name: 'Back', value: '' }],
+      });
+      if (!answer) return 0;
+      account = state.accounts.find(item => item.id === answer);
+    }
+    if (!account) { process.stderr.write('The selected account is no longer available.\n'); return 1; }
+    const controller = new AbortController();
+    const cancel = () => controller.abort();
+    process.once('SIGINT', cancel);
+    process.once('SIGTERM', cancel);
+    try {
+      let result: IHarnessPreuseResult;
+      try {
+        process.stdout.write(`Preusing ${plainText(account.label)} (${plainText(harness.label)})…\n`);
+        result = await harness.preuseAccount(account.id, { prompt, model, signal: controller.signal });
+      } catch (error) {
+        process.stderr.write(`${error instanceof PreuseError ? error.message : 'Preuse failed. Tokens may already have been consumed; check account status before trying again.'}\n`);
+        return controller.signal.aborted ? 130 : 1;
+      }
+      // Once inference completes, status or presentation failures must not report it as failed.
+      try {
+        process.stdout.write(`Prompt completed with ${plainText(result.model)}. Tokens: ${result.inputTokens ?? 'unreported'} input, ${result.outputTokens ?? 'unreported'} output, ${result.totalTokens ?? 'unreported'} total.\n`);
+        if (controller.signal.aborted) return 0;
+        const windows = orderedUsageWindows((await harness.readAccountStatus(account.id)).summary?.usageWindows);
+        if (windows?.length) {
+          const now = Date.now();
+          process.stdout.write('Reset schedule reported after the prompt:\n');
+          if ((process.stdout.columns ?? 100) < 40) {
+            for (const window of windows) process.stdout.write(`${plainText(window.label)} (${duration(window.durationSeconds)})\n  Used: ${window.usedPercent}%\n  Reset in: ${until(window.resetAt, now)}\n`);
+          } else await this.out.table(windows, { columns: [
+            { key: 'window', title: 'Window', value: row => `${plainText(row.label)} (${duration(row.durationSeconds)})` },
+            { key: 'usage', title: 'Used', value: row => `${row.usedPercent}%` },
+            { key: 'reset', title: 'Reset in', value: row => until(row.resetAt, now) },
+          ], overflow: 'wrap' });
+        } else process.stdout.write('Reset schedule could not be verified; the completed prompt will not be repeated.\n');
+      } catch {
+        process.stderr.write('Prompt completed, but its reset schedule could not be verified or displayed. The prompt will not be repeated.\n');
+      }
+      return 0;
+    } finally {
+      process.removeListener('SIGINT', cancel);
+      process.removeListener('SIGTERM', cancel);
+    }
+  }
+
+  private async selectHarness(): Promise<IAuthHarness | undefined> {
+    if (this.harnesses.size === 1) return this.harnesses.values().next().value;
+    if (this.harnesses.size === 0 || !canPrompt()) {
+      process.stderr.write(`${red('a harness is required')}: ${[...this.harnesses.keys()].join(', ') || 'none registered'}\n`);
+      return undefined;
+    }
+    const answer = await this.out.prompts.ask({
+      name: 'harness', type: 'list', message: 'Which harness would you like to manage?', default: [...this.harnesses.keys()][0],
+      choices: [...this.harnesses.values()].map((harnessArg) => ({ name: harnessArg.label, value: harnessArg.id })).concat([{ name: 'Exit', value: '' }]),
+    });
+    return this.harnesses.get(answer);
+  }
+
+  private async runInteractive(preferredArg?: IAuthHarness): Promise<number> {
+    process.stdout.write(`${bold('authswitch')} ${dim(`v${commitinfo.version}`)}\nUse the arrow keys and Enter to choose.\n`);
+    while (true) {
+      const harness = preferredArg ?? await this.selectHarness();
+      preferredArg = undefined;
+      if (!harness) return this.harnesses.size === 0 ? 2 : 0;
+      this.printCurrent(harness, await harness.readState());
+      const offered = await this.offerToSave(harness);
+      if (offered === 'failed') return 1;
+      const code = await this.runHarnessGuide(harness);
+      if (code !== null) return code;
+    }
+  }
+
+  /** Offer a verified save before presenting the switch picker; declining never switches. */
+  private async offerToSave(harnessArg: IAuthHarness): Promise<'ready' | 'declined' | 'failed'> {
+    const state = await harnessArg.readState();
+    if (state.saveUnavailableReason) return 'ready';
+    for (const current of state.accounts.filter(account => account.isActive && !account.isStashed)) {
+      const answer = await this.out.prompts.ask({
+        name: 'saveCurrent', type: 'confirm',
+        message: `${plainText(current.label)}${current.slotId ? ` (${plainText(current.slotId)})` : ''} is not saved in ${harnessArg.label}. Save this login before switching?`, default: true,
+      });
+      if (answer !== true) return 'declined';
+      if (this.reportOutcome(await this.mutate(harnessArg, { harnessId: harnessArg.id, action: 'save', keepActive: true, accountId: current.id })) !== 0) return 'failed';
+    }
+    return 'ready';
+  }
+
+  private async runHarnessGuide(harnessArg: IAuthHarness): Promise<number | null> {
+    while (true) {
+      const state = await harnessArg.readState();
+      this.printCurrent(harnessArg, state);
+      const current = state.accounts.find(account => account.isActive && !account.isStashed) ?? state.accounts.find(account => account.isActive);
+      const hasStashes = state.accounts.some((accountArg) => accountArg.isStashed);
+      if (!hasStashes) process.stdout.write(`${dim('No saved accounts yet. Choose "Save the current login" to get started.')}\n`);
+      const action = await this.out.prompts.ask({
+        name: 'action', type: 'list', message: `What would you like to do in ${harnessArg.label}?`,
+        default: current && !current.isStashed || !hasStashes ? 'stash' : 'use',
+        choices: [
+          { name: 'Switch to a saved account', value: 'use' },
+          { name: 'Save the current login', value: 'stash' },
+          ...(harnessArg.beginLogin ? [{ name: 'Log in and save another account', value: 'login' }] : []),
+          { name: 'List accounts, subscription, usage and resets', value: 'list' },
+          { name: harnessArg.diagnosticsLabel, value: 'doctor' },
+          { name: 'Remove a saved account', value: 'drop' },
+          ...(this.harnesses.size > 1 ? [{ name: 'Choose another harness', value: 'harness' }] : []),
+          { name: 'Exit', value: 'exit' },
+        ],
+      });
+      let code = 0;
+      switch (action) {
+        case 'login': code = await this.commandLogin(harnessArg); break;
+        case 'use': code = await this.commandUse(harnessArg, undefined, true); break;
+        case 'stash': {
+          if (state.saveUnavailableReason) { process.stdout.write(`${state.saveUnavailableReason}\n`); break; }
+          const active = await this.selectActive(harnessArg);
+          if (!active) break;
+          const mode = await this.out.prompts.ask({
+            name: 'stashMode', type: 'list', message: `How would you like to save ${plainText(active.label)}?`, default: 'keep',
+            choices: [
+              { name: 'Save and keep this account active', value: 'keep' },
+              { name: 'Save and clear the active login so I can log in to another account', value: 'clear' },
+              { name: 'Back', value: 'back' },
+            ],
+          });
+          if (mode === 'keep' || mode === 'clear') code = this.reportOutcome(await this.mutate(harnessArg, { harnessId: harnessArg.id, action: 'save', keepActive: mode === 'keep', accountId: active.id }));
+          break;
+        }
+        case 'list': code = await this.commandList([harnessArg]); break;
+        case 'doctor': code = this.reportOutcome(await harnessArg.diagnose()); break;
+        case 'drop': {
+          const id = await this.promptForAccount(harnessArg, `Which saved ${harnessArg.label} account should be removed?`, true, true);
+          if (!id) break;
+          const confirmation = await this.out.prompts.ask({
+            name: 'confirmDrop', type: 'confirm', message: `Remove the saved login for ${plainText(id)}? The active login stays as it is.`, default: false,
+          });
+          if (confirmation === true) code = this.reportOutcome(await harnessArg.removeAccount(id));
+          break;
+        }
+        case 'harness': return null;
+        case 'exit': return 0;
+        default: throw new Error('no interactive action was selected');
+      }
+      if (code !== 0) return code;
+    }
+  }
+
+  private printCurrent(harnessArg: IAuthHarness, stateArg: IHarnessState): void {
+    process.stdout.write(`\n${bold(`Current ${harnessArg.label} account`)}\n`);
+    const active = stateArg.accounts.filter(account => account.isActive);
+    if (active.length) {
+      for (const current of active) process.stdout.write(`${bold(plainText(current.label))}${current.slotId ? ` (${plainText(current.slotId)})` : ''} ${current.isStashed ? green('(saved)') : orange('(not saved)')}\n`);
+    } else {
+      process.stdout.write(`${dim('no account is currently active')}\n`);
+    }
+    if (stateArg.saveUnavailableReason) process.stdout.write(`${dim(stateArg.saveUnavailableReason)}\n`);
+  }
+
+  private async selectActive(harness: IAuthHarness, reference?: string): Promise<IHarnessAccount | undefined> {
+    const state = await harness.readState();
+    if (state.saveUnavailableReason) { process.stderr.write(`${plainText(state.saveUnavailableReason)}\n`); return undefined; }
+    const accounts = state.accounts.filter(account => account.isActive && (!reference || account.id === reference || account.label === reference || account.slotId === reference));
+    if (accounts.length === 1) return accounts[0];
+    if (!accounts.length) { process.stderr.write('No matching active login to save.\n'); return undefined; }
+    if (!canPrompt()) { process.stderr.write(`Several logins are active. Use authswitch ${harness.id} stash <account/provider> [--keep].\n`); return undefined; }
+    const id = await this.out.prompts.ask({ name: 'activeAccount', type: 'list', message: 'Which active login should be saved?', choices: accounts.map(account => ({ name: `${plainText(account.label)}${account.slotId ? ` (${plainText(account.slotId)})` : ''}`, value: account.id })) });
+    return accounts.find(account => account.id === id);
+  }
+
+  private reportOutcome(outcomeArg: IHarnessOutcome): number {
+    for (const line of outcomeArg.lines) process.stdout.write(`${line.trimEnd()}\n`);
+    for (const problem of outcomeArg.problems) process.stderr.write(`${red('incomplete')} ${problem}\n`);
+    return outcomeArg.problems.length === 0 ? 0 : 1;
+  }
+
+  private async commandList(harnessesArg: IAuthHarness[], jsonArg = false): Promise<number> {
+    const list = await readAccountList(harnessesArg);
+    if (jsonArg) process.stdout.write(`${JSON.stringify(list, null, 2)}\n`);
+    else await new AccountListRenderer(this.out).render(list);
+    return list.complete ? 0 : 1;
+  }
+
+  private printAccount(accountArg: IHarnessAccount): void {
+    const saved = accountArg.isStashed ? 'saved' : 'not saved';
+    process.stdout.write(`${accountArg.isActive ? green('*') : ' '} ${bold(plainText(accountArg.label))} ${dim(`(${saved})`)}\n`);
+    if (accountArg.savedAt) process.stdout.write(`  ${dim('Saved: ' + plainText(accountArg.savedAt))}\n`);
+    for (const detail of accountArg.details) process.stdout.write(`  ${detail}\n`);
+  }
+
+  private async resolveAccount(harnessArg: IAuthHarness, referenceArg: string): Promise<string | null> {
+    const resolved = await harnessArg.resolveAccount(referenceArg);
+    if ('id' in resolved) return resolved.id;
+    process.stderr.write(resolved.candidates.length === 0
+      ? `${red('no stashed account matches')} "${plainText(referenceArg)}" in ${harnessArg.label}\n`
+      : `${red('ambiguous account')} "${plainText(referenceArg)}" matches: ${resolved.candidates.map(plainText).join(', ')}\n`);
+    return null;
+  }
+
+  private async commandUse(harnessArg: IAuthHarness, referenceArg?: string, allowBackArg = false): Promise<number> {
+    let id: string | null = null;
+    if (referenceArg) {
+      id = await this.resolveAccount(harnessArg, referenceArg);
+      if (id === null) return 1;
+    }
+    if (canPrompt()) {
+      const offered = await this.offerToSave(harnessArg);
+      if (offered !== 'ready') return offered === 'failed' ? 1 : 0;
+    }
+    id ??= await this.promptForAccount(harnessArg, `Which ${harnessArg.label} account should be active?`, allowBackArg);
+    if (id === null) return allowBackArg ? 0 : 1;
+    return this.reportOutcome(await this.mutate(harnessArg, { harnessId: harnessArg.id, action: 'switch', accountId: id }));
+  }
+
+  private async promptForAccount(harnessArg: IAuthHarness, messageArg: string, allowBackArg: boolean, includeIncompleteArg = false): Promise<string | null> {
+    const accounts = (await harnessArg.readState()).accounts.filter((accountArg) => accountArg.isStashed || (includeIncompleteArg && accountArg.savedAt !== null));
+    if (accounts.length === 0) { process.stderr.write(`${red('no stashed accounts')} - run \`authswitch ${harnessArg.id} stash\` first\n`); return null; }
+    if (!canPrompt()) { process.stderr.write(`${red('an account is required')} without an interactive terminal: authswitch ${harnessArg.id} use <account>\n`); return null; }
+    const answer = await this.out.prompts.ask({
+      name: 'account', type: 'list', message: messageArg,
+      default: accounts.find((accountArg) => accountArg.isActive)?.id ?? accounts[0].id,
+      choices: [...accounts.map((accountArg) => ({ name: `${plainText(accountArg.label)}${accountArg.slotId ? ` (${plainText(accountArg.slotId)})` : ''}${accountArg.isActive ? ' (active)' : ''}`, value: accountArg.id })),
+        ...(allowBackArg ? [{ name: 'Back', value: null }] : [])],
+    });
+    return typeof answer === 'string' ? answer : null;
+  }
+}