From 79542d00df23d3b7ee6d03e72d972ba98dc3353e Mon Sep 17 00:00:00 2001
From: Scott Lovegrove <scott@ferretlabs.com>
Date: Fri, 22 May 2026 22:44:38 +0100
Subject: [PATCH 1/3] feat(auth): add account list/use Commander attachers

Adds attachAccountListCommand + attachAccountUseCommand under the /auth
subpath, giving consumers `account list` / `account use <ref>` for
multi-account management. They consume TokenStore.list() / setDefault(),
which were required since 0.12.0 but had no consumer inside cli-core.

Mirrors the existing attachStatusCommand / attachLogoutCommand patterns:
optional renderText/renderJson overrides with sensible defaults, json
envelope { accounts, default } with ndjson one-object-per-line streaming,
and the logout-style success envelope (ndjson silent) for `use`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/auth/account.test.ts | 346 +++++++++++++++++++++++++++++++++++++++
 src/auth/account.ts      | 149 +++++++++++++++++
 src/auth/index.ts        |   6 +
 3 files changed, 501 insertions(+)
 create mode 100644 src/auth/account.test.ts
 create mode 100644 src/auth/account.ts

diff --git a/src/auth/account.test.ts b/src/auth/account.test.ts
new file mode 100644
index 0000000..1c5a2c6
--- /dev/null
+++ b/src/auth/account.test.ts
@@ -0,0 +1,346 @@
+import { Command } from 'commander'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { CliError } from '../errors.js'
+import { formatJson, formatNdjson } from '../json.js'
+import {
+    type AttachAccountListCommandOptions,
+    type AttachAccountUseCommandOptions,
+    attachAccountListCommand,
+    attachAccountUseCommand,
+} from './account.js'
+import type { TokenStore } from './types.js'
+
+type Account = { id: string; label?: string; email: string }
+
+const a1: Account = { id: '1', label: 'Alice', email: 'alice@b' }
+const a2: Account = { id: '2', label: 'Bob', email: 'bob@b' }
+
+type Entry = { account: Account; isDefault: boolean }
+const bothAccounts: Entry[] = [
+    { account: a1, isDefault: true },
+    { account: a2, isDefault: false },
+]
+
+function buildStore(entries: Entry[] = bothAccounts): {
+    store: TokenStore<Account>
+    listSpy: ReturnType<typeof vi.fn>
+    setDefaultSpy: ReturnType<typeof vi.fn>
+} {
+    const listSpy = vi.fn(async () => entries)
+    const setDefaultSpy = vi.fn(async () => {})
+    const store: TokenStore<Account> = {
+        active: vi.fn(async () => null),
+        set: vi.fn(),
+        clear: vi.fn(),
+        list: listSpy,
+        setDefault: setDefaultSpy,
+    }
+    return { store, listSpy, setDefaultSpy }
+}
+
+function buildList(
+    overrides: Partial<AttachAccountListCommandOptions<Account>> = {},
+    store?: TokenStore<Account>,
+): { program: Command; command: Command } {
+    const resolvedStore = store ?? buildStore().store
+    const program = new Command()
+    program.exitOverride()
+    const account = program.command('account')
+    const command = attachAccountListCommand<Account>(account, {
+        store: resolvedStore,
+        ...overrides,
+    })
+    return { program, command }
+}
+
+function buildUse(
+    overrides: Partial<AttachAccountUseCommandOptions<Account>> = {},
+    store?: TokenStore<Account>,
+): { program: Command; command: Command } {
+    const resolvedStore = store ?? buildStore().store
+    const program = new Command()
+    program.exitOverride()
+    const account = program.command('account')
+    const command = attachAccountUseCommand<Account>(account, {
+        store: resolvedStore,
+        ...overrides,
+    })
+    return { program, command }
+}
+
+describe('attachAccountListCommand', () => {
+    let logSpy: ReturnType<typeof vi.spyOn>
+
+    beforeEach(() => {
+        logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    })
+
+    afterEach(() => {
+        logSpy.mockRestore()
+    })
+
+    it('renders default human lines with a (default) marker only on the default entry', async () => {
+        const { program } = buildList()
+
+        await program.parseAsync(['node', 'cli', 'account', 'list'])
+
+        const emitted = logSpy.mock.calls.map((call: unknown[]) => call[0])
+        expect(emitted).toEqual(['Alice (id:1) (default)', 'Bob (id:2)'])
+    })
+
+    it('emits a custom renderText string', async () => {
+        const renderText = vi.fn(() => 'one line')
+        const { program } = buildList({ renderText })
+
+        await program.parseAsync(['node', 'cli', 'account', 'list'])
+
+        expect(renderText).toHaveBeenCalledWith({
+            accounts: bothAccounts,
+            default: '1',
+            view: { json: false, ndjson: false },
+            flags: {},
+        })
+        expect(logSpy).toHaveBeenCalledWith('one line')
+    })
+
+    it('emits each line when renderText returns an array', async () => {
+        const renderText = vi.fn(() => ['line 1', 'line 2', 'line 3'])
+        const { program } = buildList({ renderText })
+
+        await program.parseAsync(['node', 'cli', 'account', 'list'])
+
+        const emitted = logSpy.mock.calls.map((call: unknown[]) => call[0]).join('\n')
+        expect(emitted).toBe('line 1\nline 2\nline 3')
+    })
+
+    it('emits the default envelope under --json', async () => {
+        const { program } = buildList()
+
+        await program.parseAsync(['node', 'cli', 'account', 'list', '--json'])
+
+        expect(logSpy).toHaveBeenCalledWith(
+            formatJson({
+                accounts: [
+                    { account: a1, isDefault: true },
+                    { account: a2, isDefault: false },
+                ],
+                default: '1',
+            }),
+        )
+    })
+
+    it('invokes renderJson per account under --json and keeps the envelope default', async () => {
+        const renderJson = vi.fn(
+            ({ account, isDefault }: { account: Account; isDefault: boolean }) => ({
+                name: account.label,
+                isDefault,
+            }),
+        )
+        const { program } = buildList({ renderJson })
+
+        await program.parseAsync(['node', 'cli', 'account', 'list', '--json'])
+
+        expect(renderJson).toHaveBeenCalledTimes(2)
+        expect(renderJson).toHaveBeenNthCalledWith(1, { account: a1, isDefault: true, flags: {} })
+        expect(renderJson).toHaveBeenNthCalledWith(2, { account: a2, isDefault: false, flags: {} })
+        expect(logSpy).toHaveBeenCalledWith(
+            formatJson({
+                accounts: [
+                    { name: 'Alice', isDefault: true },
+                    { name: 'Bob', isDefault: false },
+                ],
+                default: '1',
+            }),
+        )
+    })
+
+    it('streams one object per account under --ndjson with no envelope', async () => {
+        const { program } = buildList()
+
+        await program.parseAsync(['node', 'cli', 'account', 'list', '--ndjson'])
+
+        expect(logSpy).toHaveBeenCalledWith(
+            formatNdjson([
+                { account: a1, isDefault: true },
+                { account: a2, isDefault: false },
+            ]),
+        )
+    })
+
+    it('does not invoke renderJson in human mode', async () => {
+        const renderJson = vi.fn(() => ({ x: 1 }))
+        const { program } = buildList({ renderJson })
+
+        await program.parseAsync(['node', 'cli', 'account', 'list'])
+
+        expect(renderJson).not.toHaveBeenCalled()
+    })
+
+    it('emits an empty envelope under --json when no accounts are stored', async () => {
+        const { program } = buildList({}, buildStore([]).store)
+
+        await program.parseAsync(['node', 'cli', 'account', 'list', '--json'])
+
+        expect(logSpy).toHaveBeenCalledWith(formatJson({ accounts: [], default: null }))
+    })
+
+    it('emits nothing under --ndjson when no accounts are stored', async () => {
+        const { program } = buildList({}, buildStore([]).store)
+
+        await program.parseAsync(['node', 'cli', 'account', 'list', '--ndjson'])
+
+        expect(logSpy).not.toHaveBeenCalled()
+    })
+
+    it('emits the default empty-state message in human mode when no accounts are stored', async () => {
+        const { program } = buildList({}, buildStore([]).store)
+
+        await program.parseAsync(['node', 'cli', 'account', 'list'])
+
+        expect(logSpy).toHaveBeenCalledWith('No accounts stored.')
+    })
+
+    it('reports default null when no entry is marked default', async () => {
+        const store = buildStore([
+            { account: a1, isDefault: false },
+            { account: a2, isDefault: false },
+        ]).store
+        const { program } = buildList({}, store)
+
+        await program.parseAsync(['node', 'cli', 'account', 'list', '--json'])
+
+        expect(logSpy).toHaveBeenCalledWith(
+            formatJson({
+                accounts: [
+                    { account: a1, isDefault: false },
+                    { account: a2, isDefault: false },
+                ],
+                default: null,
+            }),
+        )
+    })
+
+    it('exposes consumer-attached options in flags but strips --json / --ndjson', async () => {
+        const renderText = vi.fn(() => 'ok')
+        const { program, command } = buildList({ renderText })
+        command.option('--full', 'Show extended fields')
+
+        await program.parseAsync(['node', 'cli', 'account', 'list', '--full'])
+
+        expect(renderText).toHaveBeenCalledWith({
+            accounts: bothAccounts,
+            default: '1',
+            view: { json: false, ndjson: false },
+            flags: { full: true },
+        })
+    })
+
+    it('returns the new Command so the consumer can chain', () => {
+        const { command } = buildList()
+
+        expect(command.name()).toBe('list')
+    })
+})
+
+describe('attachAccountUseCommand', () => {
+    let logSpy: ReturnType<typeof vi.spyOn>
+
+    beforeEach(() => {
+        logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    })
+
+    afterEach(() => {
+        logSpy.mockRestore()
+    })
+
+    it('calls setDefault and prints the success line in human mode', async () => {
+        const built = buildStore()
+        const { program } = buildUse({}, built.store)
+
+        await program.parseAsync(['node', 'cli', 'account', 'use', 'alice@b'])
+
+        expect(built.setDefaultSpy).toHaveBeenCalledWith('alice@b')
+        expect(logSpy).toHaveBeenCalledWith('✓ Default account set to alice@b')
+    })
+
+    it('emits the success envelope under --json', async () => {
+        const { program } = buildUse()
+
+        await program.parseAsync(['node', 'cli', 'account', 'use', 'alice@b', '--json'])
+
+        expect(logSpy).toHaveBeenCalledWith(formatJson({ ok: true, default: 'alice@b' }))
+    })
+
+    it('is silent under --ndjson but still calls setDefault', async () => {
+        const built = buildStore()
+        const { program } = buildUse({}, built.store)
+
+        await program.parseAsync(['node', 'cli', 'account', 'use', 'alice@b', '--ndjson'])
+
+        expect(built.setDefaultSpy).toHaveBeenCalledWith('alice@b')
+        expect(logSpy).not.toHaveBeenCalled()
+    })
+
+    it('echoes the raw user-supplied ref, not a resolved id', async () => {
+        const { program } = buildUse()
+
+        await program.parseAsync(['node', 'cli', 'account', 'use', 'alice@b', '--json'])
+
+        expect(logSpy).toHaveBeenCalledWith(formatJson({ ok: true, default: 'alice@b' }))
+    })
+
+    it('propagates ACCOUNT_NOT_FOUND from setDefault and prints nothing', async () => {
+        const thrown = new CliError('ACCOUNT_NOT_FOUND', 'No stored account matches "ghost".')
+        const built = buildStore()
+        built.setDefaultSpy.mockRejectedValueOnce(thrown)
+        const { program } = buildUse({}, built.store)
+
+        await expect(program.parseAsync(['node', 'cli', 'account', 'use', 'ghost'])).rejects.toBe(
+            thrown,
+        )
+        expect(logSpy).not.toHaveBeenCalled()
+    })
+
+    it('awaits onDefaultSet after the success line', async () => {
+        const order: string[] = []
+        const built = buildStore()
+        built.setDefaultSpy.mockImplementationOnce(async () => {
+            order.push('setDefault')
+        })
+        const onDefaultSet = vi.fn(async () => {
+            await Promise.resolve()
+            order.push('onDefaultSet')
+        })
+        const { program } = buildUse({ onDefaultSet }, built.store)
+
+        await program.parseAsync(['node', 'cli', 'account', 'use', 'alice@b'])
+
+        expect(onDefaultSet).toHaveBeenCalledWith({
+            ref: 'alice@b',
+            view: { json: false, ndjson: false },
+            flags: {},
+        })
+        expect(order).toEqual(['setDefault', 'onDefaultSet'])
+    })
+
+    it('exposes consumer-attached options in flags but strips --json / --ndjson', async () => {
+        const onDefaultSet = vi.fn()
+        const { program, command } = buildUse({ onDefaultSet })
+        command.option('--full', 'Extra')
+
+        await program.parseAsync(['node', 'cli', 'account', 'use', 'alice@b', '--full'])
+
+        expect(onDefaultSet).toHaveBeenCalledWith({
+            ref: 'alice@b',
+            view: { json: false, ndjson: false },
+            flags: { full: true },
+        })
+    })
+
+    it('returns the new Command so the consumer can chain', () => {
+        const { command } = buildUse()
+
+        expect(command.name()).toBe('use')
+    })
+})
diff --git a/src/auth/account.ts b/src/auth/account.ts
new file mode 100644
index 0000000..76a7a6a
--- /dev/null
+++ b/src/auth/account.ts
@@ -0,0 +1,149 @@
+import type { Command } from 'commander'
+import { formatJson, formatNdjson } from '../json.js'
+import type { ViewOptions } from '../options.js'
+import type { AccountRef, AuthAccount, TokenStore } from './types.js'
+
+export type AttachAccountListContext<TAccount extends AuthAccount> = {
+    /** Every stored account with its default marker, in store order. */
+    accounts: ReadonlyArray<{ account: TAccount; isDefault: boolean }>
+    /** The default account's ref (its `id`), or `null` when nothing is stored. */
+    default: AccountRef | null
+    /** `--json` / `--ndjson` flag values, both present (defaulted to `false`). */
+    view: Required<ViewOptions>
+    /** Consumer-attached options. The registrar flags (`--json`, `--ndjson`) are stripped. */
+    flags: Record<string, unknown>
+}
+
+export type AttachAccountListCommandOptions<TAccount extends AuthAccount = AuthAccount> = {
+    store: TokenStore<TAccount>
+    description?: string
+    /**
+     * Human-mode renderer over the full list. May return a single string or an
+     * array of lines; lines are joined with `\n` on output. Defaults to one
+     * line per account (`<label ?? id> (id:<id>)`, plus ` (default)` on the
+     * default entry) and an empty-state message when nothing is stored.
+     */
+    renderText?(ctx: AttachAccountListContext<TAccount>): string | readonly string[]
+    /**
+     * Per-account machine payload, invoked once per entry. The returned value
+     * becomes one element of the `--json` `accounts` array and one `--ndjson`
+     * line, so the per-account shape stays identical across both modes.
+     * Defaults to `{ account, isDefault }`. Only invoked under `--json` / `--ndjson`.
+     */
+    renderJson?(ctx: {
+        account: TAccount
+        isDefault: boolean
+        flags: Record<string, unknown>
+    }): unknown
+}
+
+export type AttachAccountUseCommandOptions<TAccount extends AuthAccount = AuthAccount> = {
+    store: TokenStore<TAccount>
+    description?: string
+    /**
+     * Fires after `store.setDefault` resolves. `ref` is the raw user-supplied
+     * positional argument. Use for CLI-specific follow-ups (e.g. dropping a
+     * cached client bound to the previous default). Awaited.
+     */
+    onDefaultSet?(ctx: {
+        ref: AccountRef
+        view: Required<ViewOptions>
+        flags: Record<string, unknown>
+    }): void | Promise<void>
+}
+
+function defaultListText<TAccount extends AuthAccount>(
+    ctx: AttachAccountListContext<TAccount>,
+): string[] {
+    if (ctx.accounts.length === 0) return ['No accounts stored.']
+    return ctx.accounts.map(({ account, isDefault }) => {
+        const name = account.label ?? account.id
+        return `${name} (id:${account.id})${isDefault ? ' (default)' : ''}`
+    })
+}
+
+/**
+ * Attach `list` as a subcommand of `parent` (typically an `account` group).
+ * Reads `store.list()` and renders every stored account with its default
+ * marker. `--json` emits a `{ accounts, default }` envelope where `default` is
+ * the default entry's `account.id` (or `null`); `--ndjson` streams one
+ * per-account object per line (no envelope, no `default` field — that is
+ * envelope-level metadata available only via `--json`). Returns the new
+ * `Command` so the consumer can chain.
+ *
+ * Note: `default` is derived from `account.id` (the contract's stable index
+ * key). A store whose ref-matching rule is not id-based should override the
+ * surfaced ref via `renderJson` if it needs a different value echoed.
+ */
+export function attachAccountListCommand<TAccount extends AuthAccount = AuthAccount>(
+    parent: Command,
+    options: AttachAccountListCommandOptions<TAccount>,
+): Command {
+    return parent
+        .command('list')
+        .description(options.description ?? 'List stored accounts')
+        .option('--json', 'Emit machine-readable JSON output')
+        .option('--ndjson', 'Emit machine-readable NDJSON output')
+        .action(async (cmd: Record<string, unknown>) => {
+            const { json, ndjson, ...flags } = cmd
+            const view: Required<ViewOptions> = {
+                json: Boolean(json),
+                ndjson: Boolean(ndjson),
+            }
+            const accounts = await options.store.list()
+            const defaultRef: AccountRef | null =
+                accounts.find((entry) => entry.isDefault)?.account.id ?? null
+            if (view.json || view.ndjson) {
+                const payloads = accounts.map(({ account, isDefault }) =>
+                    options.renderJson
+                        ? options.renderJson({ account, isDefault, flags })
+                        : { account, isDefault },
+                )
+                if (view.json) {
+                    console.log(formatJson({ accounts: payloads, default: defaultRef }))
+                } else if (payloads.length > 0) {
+                    console.log(formatNdjson(payloads))
+                }
+                return
+            }
+            const text = options.renderText
+                ? options.renderText({ accounts, default: defaultRef, view, flags })
+                : defaultListText({ accounts, default: defaultRef, view, flags })
+            const lines = typeof text === 'string' ? [text] : text
+            for (const line of lines) console.log(line)
+        })
+}
+
+/**
+ * Attach `use <ref>` as a subcommand of `parent` (typically an `account`
+ * group). Calls `store.setDefault(ref)` and emits the success envelope
+ * (`✓ Default account set to <ref>` in plain, `{ ok: true, default: <ref> }`
+ * under `--json`, silent under `--ndjson`). `setDefault`'s
+ * `CliError('ACCOUNT_NOT_FOUND', …)` on a ref miss propagates unchanged.
+ * Returns the new `Command` so the consumer can chain.
+ */
+export function attachAccountUseCommand<TAccount extends AuthAccount = AuthAccount>(
+    parent: Command,
+    options: AttachAccountUseCommandOptions<TAccount>,
+): Command {
+    return parent
+        .command('use')
+        .description(options.description ?? 'Set the default account')
+        .argument('<ref>', 'Account reference to set as default')
+        .option('--json', 'Emit machine-readable JSON output')
+        .option('--ndjson', 'Emit machine-readable NDJSON output')
+        .action(async (ref: string, cmd: Record<string, unknown>) => {
+            const { json, ndjson, ...flags } = cmd
+            const view: Required<ViewOptions> = {
+                json: Boolean(json),
+                ndjson: Boolean(ndjson),
+            }
+            await options.store.setDefault(ref)
+            if (view.json) {
+                console.log(formatJson({ ok: true, default: ref }))
+            } else if (!view.ndjson) {
+                console.log(`✓ Default account set to ${ref}`)
+            }
+            await options.onDefaultSet?.({ ref, view, flags })
+        })
+}
diff --git a/src/auth/index.ts b/src/auth/index.ts
index 9da95d0..8193d1d 100644
--- a/src/auth/index.ts
+++ b/src/auth/index.ts
@@ -1,4 +1,10 @@
 export type { AuthErrorCode } from './errors.js'
+export { attachAccountListCommand, attachAccountUseCommand } from './account.js'
+export type {
+    AttachAccountListCommandOptions,
+    AttachAccountListContext,
+    AttachAccountUseCommandOptions,
+} from './account.js'
 export { runOAuthFlow } from './flow.js'
 export type { RunOAuthFlowOptions, RunOAuthFlowResult } from './flow.js'
 export { attachLoginCommand } from './login.js'

From daa9b9f13f2faac33abd7cd50646d867294009db Mon Sep 17 00:00:00 2001
From: Scott Lovegrove <scott@ferretlabs.com>
Date: Fri, 22 May 2026 23:04:05 +0100
Subject: [PATCH 2/3] fix(auth): address account attacher review feedback

- Document the new exports in README (What's in it + Account selection
  usage block) per the AGENTS.md README-maintenance rule.
- account list --ndjson now streams one object per account instead of
  buffering a joined string, matching the documented streaming contract.
- account use --json now emits the resolved default account.id (re-read
  from list() after setDefault) so it round-trips against account list
  --json; the human line still echoes the raw ref.
- Adopt the shared emitView helper for the json/human branches.
- Add an --ndjson + custom renderJson test; replace the redundant
  raw-ref test with one asserting the canonical-vs-requested distinction.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md                | 58 ++++++++++++++++++++-------
 src/auth/account.test.ts | 85 ++++++++++++++++++++++++++--------------
 src/auth/account.ts      | 69 +++++++++++++++++++-------------
 3 files changed, 142 insertions(+), 70 deletions(-)

diff --git a/README.md b/README.md
index 87f9935..0aed89e 100644
--- a/README.md
+++ b/README.md
@@ -12,20 +12,20 @@ npm install @doist/cli-core
 
 ## What's in it
 
-| Module               | Key exports                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `auth` (subpath)     | `attachLoginCommand`, `attachLogoutCommand`, `attachStatusCommand`, `attachTokenViewCommand`, `runOAuthFlow`, `refreshAccessToken`, `createPkceProvider`, `createDcrProvider`, `createSecureStore`, `createKeyringTokenStore`, `migrateLegacyAuth`, `persistBundle`, `bundleFromExchange`, PKCE helpers, `AuthProvider` / `TokenStore` / `TokenBundle` / `ActiveBundleSnapshot` / `RefreshInput` / `AccountRef` / `SecureStore` / `UserRecordStore` types, `AttachLogoutRevokeContext` | OAuth runtime plus the Commander attachers for `<cli> [auth] login` / `logout` / `status` / `token`. `attachLogoutCommand` accepts an optional `revokeToken` hook for best-effort server-side token revocation. Ships the standard public-client PKCE flow (`createPkceProvider`), the RFC 7591 Dynamic Client Registration flow (`createDcrProvider`), a thin cross-platform OS-keyring wrapper (`createSecureStore`), and a multi-account keyring-backed `TokenStore` (`createKeyringTokenStore`) that stores secrets in the OS credential manager and degrades to plaintext in the consumer's config when the keyring is unavailable (WSL/headless Linux/containers). The store contract supports an optional `setBundle(account, bundle)` write method (required on `KeyringTokenStore`) so consumers that need refresh-token persistence can opt in via `TokenBundle`; `active()` stays narrow (access token + account only) so callers that don't need refresh state don't pay extra keyring IPC. `AuthProvider` and `TokenStore` remain the escape hatches for fully bespoke backends (device code, magic-link, …). `logout` / `status` / `token` always attach `--user <ref>` and thread the parsed ref to `store.active(ref)` (and `store.clear(ref)` on `logout`). `commander` (when using the attachers), `open` (browser launch), `@napi-rs/keyring` (when using `createSecureStore` or the keyring `TokenStore`), and `oauth4webapi` (when a consumer opts into silent refresh or uses `createDcrProvider`) are optional peer/optional deps. |
-| `commands` (subpath) | `registerChangelogCommand`, `registerUpdateCommand` (+ semver helpers)                                                                                                                                                                                                                                                                                                                                                                                                                 | Commander wiring for cli-core's standard commands (e.g. `<cli> changelog`, `<cli> update`, `<cli> update switch`). **Requires** `commander` as an optional peer-dep.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `config`             | `getConfigPath`, `readConfig`, `readConfigStrict`, `writeConfig`, `updateConfig`, `CoreConfig`, `UpdateChannel`                                                                                                                                                                                                                                                                                                                                                                        | Read / write a per-CLI JSON config file with typed error codes; `CoreConfig` is the shape of fields cli-core itself owns (extend it for per-CLI fields).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `empty`              | `printEmpty`                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Print an empty-state message gated on `--json` / `--ndjson` so machine consumers never see human strings on stdout.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `errors`             | `CliError`                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Typed CLI error class with `code` and exit-code mapping.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `global-args`        | `parseGlobalArgs`, `stripUserFlag`, `createGlobalArgsStore`, `createAccessibleGate`, `createSpinnerGate`, `getProgressJsonlPath`, `isProgressJsonlEnabled`                                                                                                                                                                                                                                                                                                                             | Parse well-known global flags (`--json`, `--ndjson`, `--quiet`, `--verbose`, `--accessible`, `--no-spinner`, `--progress-jsonl`, `--user <ref>`) and derive predicates from them. `stripUserFlag` removes `--user` tokens from argv so the cleaned array can be forwarded to Commander when the flag has no root-program attachment.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `json`               | `formatJson`, `formatNdjson`                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Stable JSON / newline-delimited JSON formatting for stdout.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `markdown` (subpath) | `preloadMarkdown`, `renderMarkdown`, `TerminalRendererOptions`                                                                                                                                                                                                                                                                                                                                                                                                                         | Lazy-init terminal markdown renderer. **Requires** `marked` and `marked-terminal-renderer` as peer-deps — install only if your CLI uses this subpath.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `options`            | `ViewOptions`                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Type contract for `{ json?, ndjson? }` per-command options that machine-output gates derive from.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `spinner`            | `createSpinner`                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Loading spinner factory wrapping `yocto-spinner` with disable gates.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `terminal`           | `isCI`, `isStderrTTY`, `isStdinTTY`, `isStdoutTTY`                                                                                                                                                                                                                                                                                                                                                                                                                                     | TTY / CI detection helpers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `testing` (subpath)  | `describeEmptyMachineOutput`                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Vitest helpers reusable by consuming CLIs (e.g. parametrised empty-state suite covering `--json` / `--ndjson` / human modes).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Module               | Key exports                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `auth` (subpath)     | `attachLoginCommand`, `attachLogoutCommand`, `attachStatusCommand`, `attachTokenViewCommand`, `attachAccountListCommand`, `attachAccountUseCommand`, `runOAuthFlow`, `refreshAccessToken`, `createPkceProvider`, `createDcrProvider`, `createSecureStore`, `createKeyringTokenStore`, `migrateLegacyAuth`, `persistBundle`, `bundleFromExchange`, PKCE helpers, `AuthProvider` / `TokenStore` / `TokenBundle` / `ActiveBundleSnapshot` / `RefreshInput` / `AccountRef` / `SecureStore` / `UserRecordStore` types, `AttachLogoutRevokeContext` / `AttachAccountListContext` | OAuth runtime plus the Commander attachers for `<cli> [auth] login` / `logout` / `status` / `token` and `<cli> account list` / `use`. `attachLogoutCommand` accepts an optional `revokeToken` hook for best-effort server-side token revocation. Ships the standard public-client PKCE flow (`createPkceProvider`), the RFC 7591 Dynamic Client Registration flow (`createDcrProvider`), a thin cross-platform OS-keyring wrapper (`createSecureStore`), and a multi-account keyring-backed `TokenStore` (`createKeyringTokenStore`) that stores secrets in the OS credential manager and degrades to plaintext in the consumer's config when the keyring is unavailable (WSL/headless Linux/containers). The store contract supports an optional `setBundle(account, bundle)` write method (required on `KeyringTokenStore`) so consumers that need refresh-token persistence can opt in via `TokenBundle`; `active()` stays narrow (access token + account only) so callers that don't need refresh state don't pay extra keyring IPC. `AuthProvider` and `TokenStore` remain the escape hatches for fully bespoke backends (device code, magic-link, …). `logout` / `status` / `token` always attach `--user <ref>` and thread the parsed ref to `store.active(ref)` (and `store.clear(ref)` on `logout`). `commander` (when using the attachers), `open` (browser launch), `@napi-rs/keyring` (when using `createSecureStore` or the keyring `TokenStore`), and `oauth4webapi` (when a consumer opts into silent refresh or uses `createDcrProvider`) are optional peer/optional deps. |
+| `commands` (subpath) | `registerChangelogCommand`, `registerUpdateCommand` (+ semver helpers)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Commander wiring for cli-core's standard commands (e.g. `<cli> changelog`, `<cli> update`, `<cli> update switch`). **Requires** `commander` as an optional peer-dep.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `config`             | `getConfigPath`, `readConfig`, `readConfigStrict`, `writeConfig`, `updateConfig`, `CoreConfig`, `UpdateChannel`                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Read / write a per-CLI JSON config file with typed error codes; `CoreConfig` is the shape of fields cli-core itself owns (extend it for per-CLI fields).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `empty`              | `printEmpty`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Print an empty-state message gated on `--json` / `--ndjson` so machine consumers never see human strings on stdout.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `errors`             | `CliError`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Typed CLI error class with `code` and exit-code mapping.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `global-args`        | `parseGlobalArgs`, `stripUserFlag`, `createGlobalArgsStore`, `createAccessibleGate`, `createSpinnerGate`, `getProgressJsonlPath`, `isProgressJsonlEnabled`                                                                                                                                                                                                                                                                                                                                                                                                                 | Parse well-known global flags (`--json`, `--ndjson`, `--quiet`, `--verbose`, `--accessible`, `--no-spinner`, `--progress-jsonl`, `--user <ref>`) and derive predicates from them. `stripUserFlag` removes `--user` tokens from argv so the cleaned array can be forwarded to Commander when the flag has no root-program attachment.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `json`               | `formatJson`, `formatNdjson`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Stable JSON / newline-delimited JSON formatting for stdout.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `markdown` (subpath) | `preloadMarkdown`, `renderMarkdown`, `TerminalRendererOptions`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Lazy-init terminal markdown renderer. **Requires** `marked` and `marked-terminal-renderer` as peer-deps — install only if your CLI uses this subpath.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `options`            | `ViewOptions`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Type contract for `{ json?, ndjson? }` per-command options that machine-output gates derive from.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `spinner`            | `createSpinner`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Loading spinner factory wrapping `yocto-spinner` with disable gates.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `terminal`           | `isCI`, `isStderrTTY`, `isStdinTTY`, `isStdoutTTY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | TTY / CI detection helpers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `testing` (subpath)  | `describeEmptyMachineOutput`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Vitest helpers reusable by consuming CLIs (e.g. parametrised empty-state suite covering `--json` / `--ndjson` / human modes).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 
 ## Usage
 
@@ -250,6 +250,36 @@ Both attachers strip the standard `--json` / `--ndjson` / `--user` registrar fla
 
 `attachTokenViewCommand` writes the bare stored token to stdout (no envelope, pipe-safe) and appends a trailing newline only when stdout is a TTY. When `envVarName` is set and the env var is populated, it throws `CliError('TOKEN_FROM_ENV', …)` to avoid disclosing a token the CLI did not manage. Defaults to subcommand name `token`; pass `name: 'view'` to nest under an existing `token` group.
 
+#### Account selection (`account list` / `account use`)
+
+For multi-account CLIs, `attachAccountListCommand` and `attachAccountUseCommand` wire `account list` and `account use <ref>` against the `TokenStore.list()` / `setDefault()` contract. Attach both to an `account` parent command — the same registrar shape as the auth siblings.
+
+```ts
+import { attachAccountListCommand, attachAccountUseCommand } from '@doist/cli-core/auth'
+
+const account = program.command('account')
+
+attachAccountListCommand<Account>(account, {
+    store,
+    // Optional. Defaults to `<label ?? id> (id:<id>)` (+ ` (default)`); empty-state line otherwise.
+    renderText: ({ accounts }) =>
+        accounts.map(
+            ({ account, isDefault }) => `${account.email}${isDefault ? ' (default)' : ''}`,
+        ),
+    // Optional per-account machine payload (one `accounts[]` entry / one ndjson line).
+    renderJson: ({ account, isDefault }) => ({ id: account.id, email: account.email, isDefault }),
+})
+
+attachAccountUseCommand<Account>(account, {
+    store,
+    onDefaultSet: ({ ref }) => clearCachedClient(), // optional follow-up
+})
+```
+
+`attachAccountListCommand` reads `store.list()` and renders every stored account. `--json` emits a `{ accounts, default }` envelope where `default` is the default entry's `account.id` (or `null`); `--ndjson` streams one per-account object per line (the same shape as the `accounts[]` entries — no envelope, no `default`); human mode uses `renderText`. `renderJson` is invoked once per account and only in machine-output mode. Both renderers are optional — omit them for the built-in defaults.
+
+`attachAccountUseCommand` takes a positional `<ref>`, calls `store.setDefault(ref)` (a ref miss propagates `CliError('ACCOUNT_NOT_FOUND', …)`), then emits `✓ Default account set to <ref>` (human) or `{ "ok": true, "default": <id> }` (`--json`, silent under `--ndjson`). The `--json` `default` is the resolved account's canonical `id` (re-read from `store.list()` after the write) so it round-trips against what `account list --json` reports for the same account; the human line echoes the raw `<ref>` you typed. The optional `onDefaultSet({ ref, view, flags })` hook fires after the success line for CLI-specific follow-ups.
+
 #### Standard flag set
 
 `attachLoginCommand` registers four flags on the `login` subcommand:
diff --git a/src/auth/account.test.ts b/src/auth/account.test.ts
index 1c5a2c6..6e992d3 100644
--- a/src/auth/account.test.ts
+++ b/src/auth/account.test.ts
@@ -22,13 +22,27 @@ const bothAccounts: Entry[] = [
     { account: a2, isDefault: false },
 ]
 
-function buildStore(entries: Entry[] = bothAccounts): {
+function matches(entry: Entry, ref: string): boolean {
+    return entry.account.id === ref || entry.account.email === ref || entry.account.label === ref
+}
+
+// A store that models multi-account state: `setDefault(ref)` matches by
+// id/email/label and re-points the default marker, so a follow-up `list()`
+// reflects the change (exercises `use`'s canonical-id re-read).
+function buildStore(initial: Entry[] = bothAccounts): {
     store: TokenStore<Account>
     listSpy: ReturnType<typeof vi.fn>
     setDefaultSpy: ReturnType<typeof vi.fn>
 } {
-    const listSpy = vi.fn(async () => entries)
-    const setDefaultSpy = vi.fn(async () => {})
+    const entries = initial.map((entry) => ({ ...entry }))
+    const listSpy = vi.fn(async () =>
+        entries.map((entry) => ({ account: entry.account, isDefault: entry.isDefault })),
+    )
+    const setDefaultSpy = vi.fn(async (ref: string) => {
+        const target = entries.find((entry) => matches(entry, ref))
+        if (!target) throw new CliError('ACCOUNT_NOT_FOUND', `No stored account matches "${ref}".`)
+        for (const entry of entries) entry.isDefault = entry === target
+    })
     const store: TokenStore<Account> = {
         active: vi.fn(async () => null),
         set: vi.fn(),
@@ -160,12 +174,31 @@ describe('attachAccountListCommand', () => {
 
         await program.parseAsync(['node', 'cli', 'account', 'list', '--ndjson'])
 
-        expect(logSpy).toHaveBeenCalledWith(
-            formatNdjson([
-                { account: a1, isDefault: true },
-                { account: a2, isDefault: false },
-            ]),
+        const emitted = logSpy.mock.calls.map((call: unknown[]) => call[0])
+        expect(emitted).toEqual([
+            formatNdjson([{ account: a1, isDefault: true }]),
+            formatNdjson([{ account: a2, isDefault: false }]),
+        ])
+    })
+
+    it('shapes each --ndjson line via renderJson, matching the --json accounts entries', async () => {
+        const renderJson = vi.fn(
+            ({ account, isDefault }: { account: Account; isDefault: boolean }) => ({
+                name: account.label,
+                isDefault,
+            }),
         )
+        const { program } = buildList({ renderJson })
+
+        await program.parseAsync(['node', 'cli', 'account', 'list', '--ndjson'])
+
+        expect(renderJson).toHaveBeenNthCalledWith(1, { account: a1, isDefault: true, flags: {} })
+        expect(renderJson).toHaveBeenNthCalledWith(2, { account: a2, isDefault: false, flags: {} })
+        const emitted = logSpy.mock.calls.map((call: unknown[]) => call[0])
+        expect(emitted).toEqual([
+            formatNdjson([{ name: 'Alice', isDefault: true }]),
+            formatNdjson([{ name: 'Bob', isDefault: false }]),
+        ])
     })
 
     it('does not invoke renderJson in human mode', async () => {
@@ -254,42 +287,35 @@ describe('attachAccountUseCommand', () => {
         logSpy.mockRestore()
     })
 
-    it('calls setDefault and prints the success line in human mode', async () => {
+    it('calls setDefault and echoes the raw ref in the human success line', async () => {
         const built = buildStore()
         const { program } = buildUse({}, built.store)
 
-        await program.parseAsync(['node', 'cli', 'account', 'use', 'alice@b'])
+        await program.parseAsync(['node', 'cli', 'account', 'use', 'bob@b'])
 
-        expect(built.setDefaultSpy).toHaveBeenCalledWith('alice@b')
-        expect(logSpy).toHaveBeenCalledWith('✓ Default account set to alice@b')
+        expect(built.setDefaultSpy).toHaveBeenCalledWith('bob@b')
+        expect(logSpy).toHaveBeenCalledWith('✓ Default account set to bob@b')
     })
 
-    it('emits the success envelope under --json', async () => {
+    it('emits the canonical resolved id under --json, not the requested ref', async () => {
         const { program } = buildUse()
 
-        await program.parseAsync(['node', 'cli', 'account', 'use', 'alice@b', '--json'])
+        // `bob@b` is a2's email; the new default resolves to its canonical id `2`.
+        await program.parseAsync(['node', 'cli', 'account', 'use', 'bob@b', '--json'])
 
-        expect(logSpy).toHaveBeenCalledWith(formatJson({ ok: true, default: 'alice@b' }))
+        expect(logSpy).toHaveBeenCalledWith(formatJson({ ok: true, default: '2' }))
     })
 
     it('is silent under --ndjson but still calls setDefault', async () => {
         const built = buildStore()
         const { program } = buildUse({}, built.store)
 
-        await program.parseAsync(['node', 'cli', 'account', 'use', 'alice@b', '--ndjson'])
+        await program.parseAsync(['node', 'cli', 'account', 'use', 'bob@b', '--ndjson'])
 
-        expect(built.setDefaultSpy).toHaveBeenCalledWith('alice@b')
+        expect(built.setDefaultSpy).toHaveBeenCalledWith('bob@b')
         expect(logSpy).not.toHaveBeenCalled()
     })
 
-    it('echoes the raw user-supplied ref, not a resolved id', async () => {
-        const { program } = buildUse()
-
-        await program.parseAsync(['node', 'cli', 'account', 'use', 'alice@b', '--json'])
-
-        expect(logSpy).toHaveBeenCalledWith(formatJson({ ok: true, default: 'alice@b' }))
-    })
-
     it('propagates ACCOUNT_NOT_FOUND from setDefault and prints nothing', async () => {
         const thrown = new CliError('ACCOUNT_NOT_FOUND', 'No stored account matches "ghost".')
         const built = buildStore()
@@ -299,6 +325,7 @@ describe('attachAccountUseCommand', () => {
         await expect(program.parseAsync(['node', 'cli', 'account', 'use', 'ghost'])).rejects.toBe(
             thrown,
         )
+        expect(built.listSpy).not.toHaveBeenCalled()
         expect(logSpy).not.toHaveBeenCalled()
     })
 
@@ -314,10 +341,10 @@ describe('attachAccountUseCommand', () => {
         })
         const { program } = buildUse({ onDefaultSet }, built.store)
 
-        await program.parseAsync(['node', 'cli', 'account', 'use', 'alice@b'])
+        await program.parseAsync(['node', 'cli', 'account', 'use', 'bob@b'])
 
         expect(onDefaultSet).toHaveBeenCalledWith({
-            ref: 'alice@b',
+            ref: 'bob@b',
             view: { json: false, ndjson: false },
             flags: {},
         })
@@ -329,10 +356,10 @@ describe('attachAccountUseCommand', () => {
         const { program, command } = buildUse({ onDefaultSet })
         command.option('--full', 'Extra')
 
-        await program.parseAsync(['node', 'cli', 'account', 'use', 'alice@b', '--full'])
+        await program.parseAsync(['node', 'cli', 'account', 'use', 'bob@b', '--full'])
 
         expect(onDefaultSet).toHaveBeenCalledWith({
-            ref: 'alice@b',
+            ref: 'bob@b',
             view: { json: false, ndjson: false },
             flags: { full: true },
         })
diff --git a/src/auth/account.ts b/src/auth/account.ts
index 76a7a6a..1b51c9b 100644
--- a/src/auth/account.ts
+++ b/src/auth/account.ts
@@ -1,6 +1,6 @@
 import type { Command } from 'commander'
-import { formatJson, formatNdjson } from '../json.js'
-import type { ViewOptions } from '../options.js'
+import { formatNdjson } from '../json.js'
+import { type ViewOptions, emitView } from '../options.js'
 import type { AccountRef, AuthAccount, TokenStore } from './types.js'
 
 export type AttachAccountListContext<TAccount extends AuthAccount> = {
@@ -93,34 +93,44 @@ export function attachAccountListCommand<TAccount extends AuthAccount = AuthAcco
             const accounts = await options.store.list()
             const defaultRef: AccountRef | null =
                 accounts.find((entry) => entry.isDefault)?.account.id ?? null
-            if (view.json || view.ndjson) {
-                const payloads = accounts.map(({ account, isDefault }) =>
-                    options.renderJson
-                        ? options.renderJson({ account, isDefault, flags })
-                        : { account, isDefault },
-                )
-                if (view.json) {
-                    console.log(formatJson({ accounts: payloads, default: defaultRef }))
-                } else if (payloads.length > 0) {
-                    console.log(formatNdjson(payloads))
-                }
+            const toPayload = ({ account, isDefault }: { account: TAccount; isDefault: boolean }) =>
+                options.renderJson
+                    ? options.renderJson({ account, isDefault, flags })
+                    : { account, isDefault }
+            // NDJSON streams one object per account; emit each line as it's
+            // produced rather than buffering a joined string. Empty list → no
+            // lines (EOF-as-end-of-stream, matching `printEmpty`).
+            if (view.ndjson) {
+                for (const entry of accounts) console.log(formatNdjson([toPayload(entry)]))
                 return
             }
-            const text = options.renderText
-                ? options.renderText({ accounts, default: defaultRef, view, flags })
-                : defaultListText({ accounts, default: defaultRef, view, flags })
-            const lines = typeof text === 'string' ? [text] : text
-            for (const line of lines) console.log(line)
+            // `renderJson` is machine-mode only, so build the payload lazily —
+            // emitView ignores it in human mode where the thunk runs instead.
+            const payload = view.json
+                ? { accounts: accounts.map(toPayload), default: defaultRef }
+                : {}
+            emitView(view, payload, () => {
+                const ctx: AttachAccountListContext<TAccount> = {
+                    accounts,
+                    default: defaultRef,
+                    view,
+                    flags,
+                }
+                const text = options.renderText ? options.renderText(ctx) : defaultListText(ctx)
+                return typeof text === 'string' ? [text] : text
+            })
         })
 }
 
 /**
  * Attach `use <ref>` as a subcommand of `parent` (typically an `account`
- * group). Calls `store.setDefault(ref)` and emits the success envelope
- * (`✓ Default account set to <ref>` in plain, `{ ok: true, default: <ref> }`
- * under `--json`, silent under `--ndjson`). `setDefault`'s
- * `CliError('ACCOUNT_NOT_FOUND', …)` on a ref miss propagates unchanged.
- * Returns the new `Command` so the consumer can chain.
+ * group). Calls `store.setDefault(ref)`, then re-reads `store.list()` to
+ * resolve the now-default account's canonical `id` so the `--json` `default`
+ * field matches what `account list --json` reports for the same account
+ * (round-trippable). The human line echoes the raw `<ref>` the user typed.
+ * `--ndjson` is silent (success-action convention, matching `logout`).
+ * `setDefault`'s `CliError('ACCOUNT_NOT_FOUND', …)` on a ref miss propagates
+ * unchanged. Returns the new `Command` so the consumer can chain.
  */
 export function attachAccountUseCommand<TAccount extends AuthAccount = AuthAccount>(
     parent: Command,
@@ -139,10 +149,15 @@ export function attachAccountUseCommand<TAccount extends AuthAccount = AuthAccou
                 ndjson: Boolean(ndjson),
             }
             await options.store.setDefault(ref)
-            if (view.json) {
-                console.log(formatJson({ ok: true, default: ref }))
-            } else if (!view.ndjson) {
-                console.log(`✓ Default account set to ${ref}`)
+            const accounts = await options.store.list()
+            const resolvedDefault: AccountRef =
+                accounts.find((entry) => entry.isDefault)?.account.id ?? ref
+            // NDJSON stays silent on success-actions (logout convention); the
+            // guard keeps emitView from emitting an ndjson line.
+            if (!view.ndjson) {
+                emitView(view, { ok: true, default: resolvedDefault }, () => [
+                    `✓ Default account set to ${ref}`,
+                ])
             }
             await options.onDefaultSet?.({ ref, view, flags })
         })

From 4a73f204174acfc1dce14db7c2eafac567d1db67 Mon Sep 17 00:00:00 2001
From: Scott Lovegrove <scott@ferretlabs.com>
Date: Sat, 23 May 2026 08:59:51 +0100
Subject: [PATCH 3/3] fix(auth): address second account attacher review

- Machine-output precedence: --json now wins over --ndjson in both
  commands (gate the ndjson cases behind !view.json), matching emitView
  / status / logout.
- account use only re-reads store.list() under --json (where the
  canonical id is needed); human / --ndjson succeed off the original ref
  so a follow-up read error can't fail an already-successful setDefault.
- Validate each per-account renderJson payload before serializing so a
  non-serializable result throws CliError('INVALID_TYPE') in both machine
  modes instead of nulling under --json.
- Extract splitViewFlags(cmd) and reuse it in both actions.
- Tests: rely on buildStore's natural ACCOUNT_NOT_FOUND throw; rewrite
  the onDefaultSet test with a deferred hook to actually prove the
  success line precedes the awaited hook; add json-wins + guard +
  no-reread coverage; drop a restating comment.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/auth/account.test.ts | 84 ++++++++++++++++++++++++++++++--------
 src/auth/account.ts      | 88 +++++++++++++++++++++++++---------------
 2 files changed, 122 insertions(+), 50 deletions(-)

diff --git a/src/auth/account.test.ts b/src/auth/account.test.ts
index 6e992d3..d884207 100644
--- a/src/auth/account.test.ts
+++ b/src/auth/account.test.ts
@@ -201,6 +201,34 @@ describe('attachAccountListCommand', () => {
         ])
     })
 
+    it('prefers --json over --ndjson when both flags are passed', async () => {
+        const { program } = buildList()
+
+        await program.parseAsync(['node', 'cli', 'account', 'list', '--json', '--ndjson'])
+
+        expect(logSpy).toHaveBeenCalledTimes(1)
+        expect(logSpy).toHaveBeenCalledWith(
+            formatJson({
+                accounts: [
+                    { account: a1, isDefault: true },
+                    { account: a2, isDefault: false },
+                ],
+                default: '1',
+            }),
+        )
+    })
+
+    it('throws INVALID_TYPE in both machine modes when renderJson is non-serializable', async () => {
+        const renderJson = vi.fn(() => undefined)
+
+        for (const mode of ['--json', '--ndjson'] as const) {
+            const { program } = buildList({ renderJson })
+            await expect(
+                program.parseAsync(['node', 'cli', 'account', 'list', mode]),
+            ).rejects.toMatchObject({ constructor: CliError, code: 'INVALID_TYPE' })
+        }
+    })
+
     it('does not invoke renderJson in human mode', async () => {
         const renderJson = vi.fn(() => ({ x: 1 }))
         const { program } = buildList({ renderJson })
@@ -300,12 +328,29 @@ describe('attachAccountUseCommand', () => {
     it('emits the canonical resolved id under --json, not the requested ref', async () => {
         const { program } = buildUse()
 
-        // `bob@b` is a2's email; the new default resolves to its canonical id `2`.
         await program.parseAsync(['node', 'cli', 'account', 'use', 'bob@b', '--json'])
 
         expect(logSpy).toHaveBeenCalledWith(formatJson({ ok: true, default: '2' }))
     })
 
+    it('prefers --json over --ndjson when both flags are passed', async () => {
+        const { program } = buildUse()
+
+        await program.parseAsync(['node', 'cli', 'account', 'use', 'bob@b', '--json', '--ndjson'])
+
+        expect(logSpy).toHaveBeenCalledWith(formatJson({ ok: true, default: '2' }))
+    })
+
+    it('does not re-read the store outside --json', async () => {
+        const built = buildStore()
+        const { program } = buildUse({}, built.store)
+
+        await program.parseAsync(['node', 'cli', 'account', 'use', 'bob@b'])
+
+        expect(built.setDefaultSpy).toHaveBeenCalledWith('bob@b')
+        expect(built.listSpy).not.toHaveBeenCalled()
+    })
+
     it('is silent under --ndjson but still calls setDefault', async () => {
         const built = buildStore()
         const { program } = buildUse({}, built.store)
@@ -317,38 +362,41 @@ describe('attachAccountUseCommand', () => {
     })
 
     it('propagates ACCOUNT_NOT_FOUND from setDefault and prints nothing', async () => {
-        const thrown = new CliError('ACCOUNT_NOT_FOUND', 'No stored account matches "ghost".')
         const built = buildStore()
-        built.setDefaultSpy.mockRejectedValueOnce(thrown)
         const { program } = buildUse({}, built.store)
 
-        await expect(program.parseAsync(['node', 'cli', 'account', 'use', 'ghost'])).rejects.toBe(
-            thrown,
-        )
+        // `ghost` matches no stored id/email/label, so the store throws naturally.
+        await expect(
+            program.parseAsync(['node', 'cli', 'account', 'use', 'ghost']),
+        ).rejects.toMatchObject({ constructor: CliError, code: 'ACCOUNT_NOT_FOUND' })
         expect(built.listSpy).not.toHaveBeenCalled()
         expect(logSpy).not.toHaveBeenCalled()
     })
 
-    it('awaits onDefaultSet after the success line', async () => {
-        const order: string[] = []
-        const built = buildStore()
-        built.setDefaultSpy.mockImplementationOnce(async () => {
-            order.push('setDefault')
+    it('emits the success line before awaiting onDefaultSet', async () => {
+        let releaseHook!: () => void
+        const hookGate = new Promise<void>((resolve) => {
+            releaseHook = resolve
         })
-        const onDefaultSet = vi.fn(async () => {
-            await Promise.resolve()
-            order.push('onDefaultSet')
-        })
-        const { program } = buildUse({ onDefaultSet }, built.store)
+        const onDefaultSet = vi.fn(() => hookGate)
+        const { program } = buildUse({ onDefaultSet })
 
-        await program.parseAsync(['node', 'cli', 'account', 'use', 'bob@b'])
+        const parsed = program
+            .parseAsync(['node', 'cli', 'account', 'use', 'bob@b'])
+            .then(() => 'done')
+        await vi.waitFor(() => expect(onDefaultSet).toHaveBeenCalled())
 
+        // Success line is already out, but the command is still parked on the hook.
+        expect(logSpy).toHaveBeenCalledWith('✓ Default account set to bob@b')
         expect(onDefaultSet).toHaveBeenCalledWith({
             ref: 'bob@b',
             view: { json: false, ndjson: false },
             flags: {},
         })
-        expect(order).toEqual(['setDefault', 'onDefaultSet'])
+        expect(await Promise.race([parsed, Promise.resolve('pending')])).toBe('pending')
+
+        releaseHook()
+        expect(await parsed).toBe('done')
     })
 
     it('exposes consumer-attached options in flags but strips --json / --ndjson', async () => {
diff --git a/src/auth/account.ts b/src/auth/account.ts
index 1b51c9b..6d76811 100644
--- a/src/auth/account.ts
+++ b/src/auth/account.ts
@@ -1,4 +1,5 @@
 import type { Command } from 'commander'
+import { CliError } from '../errors.js'
 import { formatNdjson } from '../json.js'
 import { type ViewOptions, emitView } from '../options.js'
 import type { AccountRef, AuthAccount, TokenStore } from './types.js'
@@ -29,6 +30,8 @@ export type AttachAccountListCommandOptions<TAccount extends AuthAccount = AuthA
      * becomes one element of the `--json` `accounts` array and one `--ndjson`
      * line, so the per-account shape stays identical across both modes.
      * Defaults to `{ account, isDefault }`. Only invoked under `--json` / `--ndjson`.
+     * A non-serializable return throws `CliError('INVALID_TYPE', …)` in both
+     * machine modes (rather than silently nulling under `--json`).
      */
     renderJson?(ctx: {
         account: TAccount
@@ -52,6 +55,15 @@ export type AttachAccountUseCommandOptions<TAccount extends AuthAccount = AuthAc
     }): void | Promise<void>
 }
 
+/** Split the parsed Commander options into the canonical machine-output view + the remaining consumer flags. */
+function splitViewFlags(cmd: Record<string, unknown>): {
+    view: Required<ViewOptions>
+    flags: Record<string, unknown>
+} {
+    const { json, ndjson, ...flags } = cmd
+    return { view: { json: Boolean(json), ndjson: Boolean(ndjson) }, flags }
+}
+
 function defaultListText<TAccount extends AuthAccount>(
     ctx: AttachAccountListContext<TAccount>,
 ): string[] {
@@ -68,8 +80,9 @@ function defaultListText<TAccount extends AuthAccount>(
  * marker. `--json` emits a `{ accounts, default }` envelope where `default` is
  * the default entry's `account.id` (or `null`); `--ndjson` streams one
  * per-account object per line (no envelope, no `default` field — that is
- * envelope-level metadata available only via `--json`). Returns the new
- * `Command` so the consumer can chain.
+ * envelope-level metadata available only via `--json`). When both flags are
+ * present `--json` wins, matching `emitView` / `status` / `logout`. Returns the
+ * new `Command` so the consumer can chain.
  *
  * Note: `default` is derived from `account.id` (the contract's stable index
  * key). A store whose ref-matching rule is not id-based should override the
@@ -85,22 +98,35 @@ export function attachAccountListCommand<TAccount extends AuthAccount = AuthAcco
         .option('--json', 'Emit machine-readable JSON output')
         .option('--ndjson', 'Emit machine-readable NDJSON output')
         .action(async (cmd: Record<string, unknown>) => {
-            const { json, ndjson, ...flags } = cmd
-            const view: Required<ViewOptions> = {
-                json: Boolean(json),
-                ndjson: Boolean(ndjson),
-            }
+            const { view, flags } = splitViewFlags(cmd)
             const accounts = await options.store.list()
             const defaultRef: AccountRef | null =
                 accounts.find((entry) => entry.isDefault)?.account.id ?? null
-            const toPayload = ({ account, isDefault }: { account: TAccount; isDefault: boolean }) =>
-                options.renderJson
-                    ? options.renderJson({ account, isDefault, flags })
-                    : { account, isDefault }
+            // Build + validate one per-account payload. Validating before either
+            // serializer means a non-serializable `renderJson` result fails the
+            // same way under `--json` and `--ndjson` (a raw `undefined` element
+            // would otherwise serialize to `null` in the JSON array but throw
+            // in NDJSON).
+            const toPayload = (entry: { account: TAccount; isDefault: boolean }) => {
+                const payload = options.renderJson
+                    ? options.renderJson({
+                          account: entry.account,
+                          isDefault: entry.isDefault,
+                          flags,
+                      })
+                    : { account: entry.account, isDefault: entry.isDefault }
+                if (JSON.stringify(payload) === undefined) {
+                    throw new CliError(
+                        'INVALID_TYPE',
+                        `renderJson returned a non-serializable value for account "${entry.account.id}".`,
+                    )
+                }
+                return payload
+            }
             // NDJSON streams one object per account; emit each line as it's
-            // produced rather than buffering a joined string. Empty list → no
-            // lines (EOF-as-end-of-stream, matching `printEmpty`).
-            if (view.ndjson) {
+            // produced rather than buffering a joined string. `--json` wins when
+            // both flags are set. Empty list → no lines (EOF-as-end-of-stream).
+            if (view.ndjson && !view.json) {
                 for (const entry of accounts) console.log(formatNdjson([toPayload(entry)]))
                 return
             }
@@ -124,13 +150,15 @@ export function attachAccountListCommand<TAccount extends AuthAccount = AuthAcco
 
 /**
  * Attach `use <ref>` as a subcommand of `parent` (typically an `account`
- * group). Calls `store.setDefault(ref)`, then re-reads `store.list()` to
- * resolve the now-default account's canonical `id` so the `--json` `default`
- * field matches what `account list --json` reports for the same account
- * (round-trippable). The human line echoes the raw `<ref>` the user typed.
- * `--ndjson` is silent (success-action convention, matching `logout`).
- * `setDefault`'s `CliError('ACCOUNT_NOT_FOUND', …)` on a ref miss propagates
- * unchanged. Returns the new `Command` so the consumer can chain.
+ * group). Calls `store.setDefault(ref)`; under `--json` it then re-reads
+ * `store.list()` to resolve the now-default account's canonical `id` so the
+ * `default` field matches what `account list --json` reports for the same
+ * account (round-trippable). Human mode echoes the raw `<ref>` typed and skips
+ * the re-read, so a follow-up store error can't fail a command whose write
+ * already succeeded. `--ndjson` is silent (success-action convention, matching
+ * `logout`); `--json` wins when both flags are present. `setDefault`'s
+ * `CliError('ACCOUNT_NOT_FOUND', …)` on a ref miss propagates unchanged.
+ * Returns the new `Command` so the consumer can chain.
  */
 export function attachAccountUseCommand<TAccount extends AuthAccount = AuthAccount>(
     parent: Command,
@@ -143,18 +171,14 @@ export function attachAccountUseCommand<TAccount extends AuthAccount = AuthAccou
         .option('--json', 'Emit machine-readable JSON output')
         .option('--ndjson', 'Emit machine-readable NDJSON output')
         .action(async (ref: string, cmd: Record<string, unknown>) => {
-            const { json, ndjson, ...flags } = cmd
-            const view: Required<ViewOptions> = {
-                json: Boolean(json),
-                ndjson: Boolean(ndjson),
-            }
+            const { view, flags } = splitViewFlags(cmd)
             await options.store.setDefault(ref)
-            const accounts = await options.store.list()
-            const resolvedDefault: AccountRef =
-                accounts.find((entry) => entry.isDefault)?.account.id ?? ref
-            // NDJSON stays silent on success-actions (logout convention); the
-            // guard keeps emitView from emitting an ndjson line.
-            if (!view.ndjson) {
+            // Skip the silent pure-`--ndjson` case; `--json` wins over it.
+            if (view.json || !view.ndjson) {
+                const resolvedDefault: AccountRef = view.json
+                    ? ((await options.store.list()).find((entry) => entry.isDefault)?.account.id ??
+                      ref)
+                    : ref
                 emitView(view, { ok: true, default: resolvedDefault }, () => [
                     `✓ Default account set to ${ref}`,
                 ])