Skip to content

docs(auth): align front-door flows with shipped workflows #109

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
ndycode wants to merge 11 commits into from
Closed

docs(auth): align front-door flows with shipped workflows #109

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
af7f137
fix(auth): define reset and delete safety flows
ndycode Mar 15, 2026
f48ee06
feat(auth): add backup restore manager
ndycode Mar 15, 2026
12074e2
feat(auth): prompt for recovery on startup
ndycode Mar 15, 2026
eeecf6e
feat(sync): add sync center and status surface
ndycode Mar 15, 2026
ccb06f6
fix(auth): clean startup recovery prompt branch
ndycode Mar 16, 2026
d0a80b5
feat(settings): productize stable and advanced controls
ndycode Mar 15, 2026
310325d
fix(auth): drop recovery fallback from settings slice
ndycode Mar 16, 2026
01ee35b
docs(auth): align front-door flows with shipped workflows
ndycode Mar 15, 2026
d1e44d7
docs(auth): clarify settings and sync wording
ndycode Mar 16, 2026
c27ac97
docs(auth): tighten frontdoor references
ndycode Mar 17, 2026
52d2cfa
docs(auth): fix advanced sync navigation
ndycode Mar 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 21 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@ Codex CLI-first multi-account OAuth manager for the official `@openai/codex` CLI
- Canonical `codex auth ...` workflow for account login, switching, checks, and diagnostics
- Multi-account OAuth pool with health-aware selection and automatic failover
- Project-scoped account storage under `~/.codex/multi-auth/projects/<project-key>/...`
- Interactive dashboard for account actions and settings
- Experimental settings tab for staged sync, backup, and refresh-guard controls
- Interactive dashboard for login, restore, switching, sync preview, and settings
- Productized settings flow with `Everyday Settings` plus `Advanced & Operator` sections for `Codex CLI Sync`, `Experimental`, and `Advanced Backend Controls`
- Forecast, report, fix, and doctor commands for operational safety
- Flagged account verification and restore flow
- Session affinity and live account sync controls
Expand Down Expand Up @@ -50,6 +50,7 @@ Codex CLI-first multi-account OAuth manager for the official `@openai/codex` CLI
### Option A: Standard install

```bash
npm i -g @openai/codex
npm i -g codex-multi-auth
```

Expand All @@ -74,16 +75,18 @@ codex auth status

### Step-by-step

1. Install global package:
1. Install global packages:
- `npm i -g @openai/codex`
- `npm i -g codex-multi-auth`
2. Run first login flow with `codex auth login`
3. Validate state with `codex auth status` and `codex auth check`
3. Validate state with `codex auth list` and `codex auth check`
4. Confirm routing with `codex auth forecast --live`

### Verification

```bash
codex auth status
codex auth list
codex auth check
```

Expand All @@ -95,7 +98,7 @@ codex auth check

```bash
codex auth login
codex auth status
codex auth list
codex auth check
codex auth forecast --live
```
Expand All @@ -109,6 +112,12 @@ codex auth fix --dry-run
codex auth doctor --fix
```

Interactive dashboard paths:

- restore named backups: `codex auth login` -> `Restore From Backup`
- preview Codex CLI sync: `codex auth login` -> `Settings` -> `Advanced & Operator` -> `Codex CLI Sync`
- adjust stable dashboard preferences: `codex auth login` -> `Settings` -> `Everyday Settings`

---

## Command Toolkit
Expand Down Expand Up @@ -170,16 +179,17 @@ Override root with `CODEX_MULTI_AUTH_DIR=<path>`.

## Configuration

Primary config root:
- `~/.codex/multi-auth/settings.json`
- or `CODEX_MULTI_AUTH_DIR/settings.json` when custom root is set
Primary config file:
- `~/.codex/multi-auth/settings.json` by default
- `CODEX_MULTI_AUTH_DIR/settings.json` when a custom root is set
- `CODEX_MULTI_AUTH_CONFIG_PATH=<path>` when you want to override the default config file lookup

Selected runtime/environment overrides:

| Variable | Effect |
| --- | --- |
| `CODEX_MULTI_AUTH_DIR` | Override settings/accounts root |
| `CODEX_MULTI_AUTH_CONFIG_PATH` | Alternate config file path |
| `CODEX_MULTI_AUTH_CONFIG_PATH` | Override the default config file path lookup |
| `CODEX_MODE=0/1` | Disable/enable Codex mode |
| `CODEX_TUI_V2=0/1` | Disable/enable TUI v2 |
| `CODEX_TUI_COLOR_PROFILE=truecolor|ansi256|ansi16` | TUI color profile |
Expand All @@ -201,7 +211,7 @@ codex auth forecast --live

The Settings menu now includes an `Experimental` section for staged features:

- preview-first sync into `oc-chatgpt-multi-auth`
- preview-first sync into the companion `oc-chatgpt-multi-auth` account pool
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# verify stale naming references in docs and tests
rg -n -C2 'oc-chatgpt-multi-auth|codex-multi-auth' README.md docs test

Repository: ndycode/codex-multi-auth

Length of output: 50382

update README and docs to use canonical package naming in experimental sync references.

README.md:214 and docs/reference/storage-paths.md:120 both reference oc-chatgpt-multi-auth where canonical naming should be codex-multi-auth to align with the rest of the front-door docs. this matters because test/documentation.test.ts already validates canonical naming consistency. fix both references to match the canonical naming policy.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@README.md` at line 214, Replace the incorrect experimental sync package name
string "oc-chatgpt-multi-auth" with the canonical package name
"codex-multi-auth" wherever it appears in the docs (the README reference and the
storage-paths reference tested by documentation.test.ts); ensure both
occurrences are updated to "codex-multi-auth" so naming is consistent with the
front-door docs and the tests.

- named local pool backup export with filename prompt
- refresh guard toggle and interval controls moved out of Backend Controls

Expand Down Expand Up @@ -234,6 +244,7 @@ codex auth login
- `codex auth` unrecognized: run `where codex`, then follow `docs/troubleshooting.md` for routing fallback commands
- Switch succeeds but wrong account appears active: run `codex auth switch <index>`, then restart session
- OAuth callback on port `1455` fails: free the port and re-run `codex auth login`
- Interactive login skipped restore and went straight to OAuth: place named backups in your active backup root (`$CODEX_MULTI_AUTH_DIR/backups` or `%CODEX_MULTI_AUTH_DIR%\backups`; default examples: `~/.codex/multi-auth/backups/` and `C:\Users\<User>\.codex\multi-auth\backups\`), then rerun `codex auth login` in a normal TTY
- `missing field id_token` / `token_expired` / `refresh_token_reused`: re-login affected account

</details>
Expand Down
12 changes: 6 additions & 6 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,13 +17,13 @@ Public documentation for `codex-multi-auth`.

| Document | Focus |
| --- | --- |
| [index.md](index.md) | Daily-use landing page for common `codex auth ...` workflows |
| [getting-started.md](getting-started.md) | Install, first login, and first health check |
| [index.md](index.md) | Daily-use landing page for login, restore, sync, and diagnostics workflows |
| [getting-started.md](getting-started.md) | Install, first login, startup restore prompt, and first health check |
| [faq.md](faq.md) | Short answers to common adoption questions |
| [architecture.md](architecture.md) | Public system overview of the wrapper, storage, and optional plugin runtime |
| [features.md](features.md) | User-facing capability map |
| [features.md](features.md) | User-facing capability map, including backup restore, sync center, and settings split |
| [configuration.md](configuration.md) | Stable defaults, precedence, and environment overrides |
| [troubleshooting.md](troubleshooting.md) | Recovery playbooks for install, login, switching, and stale state |
| [troubleshooting.md](troubleshooting.md) | Recovery playbooks for install, login, restore, sync, and stale state |
| [privacy.md](privacy.md) | Data handling and local storage behavior |
| [upgrade.md](upgrade.md) | Migration from legacy package and path history |
| [releases/v0.1.9.md](releases/v0.1.9.md) | Stable release notes |
Expand All @@ -39,8 +39,8 @@ Public documentation for `codex-multi-auth`.

| Document | Focus |
| --- | --- |
| [reference/commands.md](reference/commands.md) | Commands, flags, and hotkeys |
| [reference/settings.md](reference/settings.md) | Dashboard and runtime settings |
| [reference/commands.md](reference/commands.md) | Commands, flags, hotkeys, and interactive entry points |
| [reference/settings.md](reference/settings.md) | Everyday settings, sync center, and advanced operator controls |
| [reference/storage-paths.md](reference/storage-paths.md) | Canonical and compatibility storage paths |
| [reference/public-api.md](reference/public-api.md) | Public API stability and semver contract |
| [reference/error-contracts.md](reference/error-contracts.md) | CLI, JSON, and helper error semantics |
Expand Down
6 changes: 5 additions & 1 deletion docs/features.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ User-facing capability map for `codex-multi-auth`.
| Capability | What it gives you | Primary entry |
| --- | --- | --- |
| Multi-account dashboard login | Add and manage multiple OAuth identities from one terminal flow | `codex auth login` |
| Startup recovery prompt | Offer restore before OAuth when recoverable named backups are found and no active accounts exist | `codex auth login` |
| Backup restore manager | Review named backups, merge with dedupe, and skip invalid or over-limit restores | `codex auth login` -> `Restore From Backup` |
| Account dedupe and identity normalization | Avoid duplicate saved account rows | login flow |
| Explicit active-account switching | Pick the current account by index instead of relying on hidden state | `codex auth switch <index>` |
| Fast and deep health checks | See whether the current pool is usable before a coding session | `codex auth check` |
Expand All @@ -22,7 +24,7 @@ User-facing capability map for `codex-multi-auth`.
| --- | --- | --- |
| Readiness and risk forecast | Suggests the best next account | `codex auth forecast` |
| Live quota probe mode | Uses live headers for stronger decisions | `codex auth forecast --live` |
| JSON report output | Lets you inspect account state in automation or support workflows | `codex auth report --live --json` |
| JSON report and diagnostics pack | Lets you inspect account state in automation, support, and bug-report workflows | `codex auth report --live --json` |

---

Expand Down Expand Up @@ -53,6 +55,8 @@ User-facing capability map for `codex-multi-auth`.
| --- | --- |
| Quick switch and search hotkeys | Faster navigation in the dashboard |
| Account action hotkeys | Per-account set, refresh, toggle, and delete shortcuts |
| Productized settings split | Keeps `Everyday Settings` separate from `Advanced & Operator` controls |
| Preview-first sync center | Shows one-way Codex CLI sync results and rollback context before apply |
| In-dashboard settings hub | Runtime and display tuning without editing files directly |
| Browser-first OAuth with manual fallback | Works in normal and constrained terminal environments |

Expand Down
25 changes: 25 additions & 0 deletions docs/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,8 @@ Expected flow:
4. Return to the terminal when the browser step completes.
5. Confirm the account appears in the saved account list.

If interactive `codex auth login` starts with zero saved accounts and recoverable named backups in your `backups/` directory, the login flow will prompt you to restore before opening OAuth. Confirm to launch the existing restore manager; skip to proceed with a fresh login. The prompt is suppressed in non-interactive/fallback flows and after same-session `fresh` or `reset` actions.

Verify the new account:

```bash
Expand All @@ -70,6 +72,29 @@ codex auth forecast --live

---

## Restore Or Start Fresh

Use the restore path when you already have named backup files and want to recover account state before creating new OAuth sessions.

- Automatic path: run `codex auth login`, then confirm the startup restore prompt when it appears
- Manual path: run `codex auth login`, then choose `Restore From Backup`
- Backup location: `~/.codex/multi-auth/backups/<name>.json`

The restore manager shows each backup name, account count, freshness, and whether the restore would exceed the account limit before it lets you apply anything.

---

## Sync And Settings

The settings flow is split into two productized sections:

- `Everyday Settings` for list appearance, details line, results and refresh behavior, and colors
- `Advanced & Operator` for `Codex CLI Sync`, `Experimental`, and backend tuning

Use `Codex CLI Sync` when you want to preview one-way sync from official Codex CLI account files before applying it. The sync screen shows source and target paths, preview summary, destination-only preservation, and backup rollback paths before apply.

---

## Day-1 Command Pack

```bash
Expand Down
10 changes: 9 additions & 1 deletion docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# codex-multi-auth Docs

Daily-use guide for the `codex auth ...` workflow.
Daily-use guide for the `codex auth ...` workflow, including restore, sync, and diagnostics.

---

Expand All @@ -12,6 +12,8 @@ codex auth list
codex auth check
```

If login detects recoverable named backups before OAuth, confirm the prompt to open `Restore From Backup` first.

If you are choosing an account for the next session:

```bash
Expand Down Expand Up @@ -39,6 +41,12 @@ codex auth report --live --json
codex auth doctor --fix
```

Interactive workflows that ship in the dashboard:

- backup restore: `codex auth login` -> `Restore From Backup`
- sync preview and apply: `codex auth login` -> `Settings` -> `Advanced & Operator` -> `Codex CLI Sync`
- settings split: `codex auth login` -> `Settings` -> `Everyday Settings` or `Advanced & Operator`

---

## Canonical Policy
Expand Down
24 changes: 18 additions & 6 deletions docs/reference/commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,12 +20,13 @@ Compatibility aliases are supported:

| Command | Description |
| --- | --- |
| `codex auth login` | Open interactive auth dashboard |
| `codex auth login` | Open interactive auth dashboard, including login, restore, settings, and dashboard paths and links to diagnostics commands |
| `codex auth list` | List saved accounts and active account |
| `codex auth status` | Print short runtime/account summary |
| `codex auth switch <index>` | Set active account by index |
| `codex auth check` | Run quick account health check |
| `codex auth features` | Print implemented feature summary |
| `codex auth restore-backup` | Open the backup restore picker directly |

---

Expand Down Expand Up @@ -90,16 +91,26 @@ Compatibility aliases are supported:

Settings screen hotkeys are panel-specific:

- Account List View: `Enter Toggle | Number Toggle | M Sort | L Layout | S Save | Q Back (No Save)`
- Summary Line: `Enter Toggle | 1-3 Toggle | [ ] Reorder | S Save | Q Back (No Save)`
- Menu Behavior: `Enter Select | 1-3 Delay | P Pause | L AutoFetch | F Status | T TTL | S Save | Q Back (No Save)`
- Color Theme: `Enter Select | 1-2 Base | S Save | Q Back (No Save)`
- Backend Controls: `Enter Open | 1-4 Category | S Save | R Reset | Q Back (No Save)`
- List Appearance: `Enter Toggle | Number Toggle | M Sort | L Layout | S Save | Q Back (No Save)`
- Details Line: `Enter Toggle | 1-3 Toggle | [ ] Reorder | S Save | Q Back (No Save)`
- Results & Refresh: `Enter Select | 1-3 Delay | P Pause | L AutoFetch | F Status | T TTL | S Save | Q Back (No Save)`
- Colors: `Enter Select | 1-2 Base | S Save | Q Back (No Save)`
- Advanced Backend Controls: `Enter Open | 1-4 Category | S Save | R Reset | Q Back (No Save)`

---

## Workflow Packs

Interactive dashboard workflows:

- Backup restore: `codex auth login` -> `Restore From Backup`
- Startup recovery prompt: interactive `codex auth login` TTY flow only, then confirm restore when recoverable named backups are found before OAuth
- Sync preview and apply: `codex auth login` -> `Settings` -> `Advanced & Operator` -> `Codex CLI Sync`
- Stable settings path: `codex auth login` -> `Settings` -> `Everyday Settings`
- Advanced settings path: `codex auth login` -> `Settings` -> `Advanced & Operator`

---

Health and planning:

```bash
Expand All @@ -111,6 +122,7 @@ codex auth report --live --json
Repair and recovery:

```bash
codex auth restore-backup
codex auth fix --dry-run
codex auth fix --live --model gpt-5-codex
codex auth doctor --fix
Expand Down
47 changes: 40 additions & 7 deletions docs/reference/settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Settings Reference

Reference for dashboard and backend settings available from `codex auth login` -> `Settings`.
Reference for the settings surface available from `codex auth login` -> `Settings`.

---

Expand All @@ -19,7 +19,11 @@ When `CODEX_MULTI_AUTH_DIR` is set, this root moves accordingly.

---

## Account List View
## Everyday Settings

The shipped settings menu starts with `Everyday Settings` and keeps the stable dashboard path separate from advanced operator controls. This is the default path for most users.

### List Appearance

Controls account-row display and sorting behavior:

Expand All @@ -37,7 +41,7 @@ Controls account-row display and sorting behavior:
- `menuSortQuickSwitchVisibleRow`
- `menuLayoutMode`

## Summary Line
### Details Line

Controls detail-line fields and order:

Expand All @@ -46,7 +50,7 @@ Controls detail-line fields and order:
- `limits`
- `status`

## Menu Behavior
### Results & Refresh

Controls result-screen and fetch behavior:

Expand All @@ -56,7 +60,7 @@ Controls result-screen and fetch behavior:
- `menuShowFetchStatus`
- `menuQuotaTtlMs`

## Color Theme
### Colors

Controls display style:

Expand All @@ -66,7 +70,31 @@ Controls display style:

---

## Experimental
## Advanced & Operator

The second top-level section is `Advanced & Operator`. It holds the sync workflow and backend tuning that are useful when you need to inspect or change lower-level behavior.

### Codex CLI Sync

`Codex CLI Sync` is a preview-first sync center for Codex CLI account sync.

Before applying sync, it shows:

- target path
- current source path when available
- last sync result for this session
- preview summary (adds, updates, destination-only preserved accounts)
- destination-only preservation behavior
- backup and rollback context (`.bak`, `.bak.1`, `.bak.2`, `.wal`) when storage backups are enabled

Workflow notes:

- refresh recomputes the read-only preview from Codex CLI source files
- apply writes the preview result into the target path
- sync is one-way, it is not a bidirectional merge
- target-only accounts are preserved rather than deleted

### Experimental

Experimental currently hosts:

Expand All @@ -88,7 +116,11 @@ Named backup behavior:
- rejects separators, traversal (`..`), `.rotate.`, `.tmp`, and `.wal` suffixes
- fails safely on collisions instead of overwriting by default

## Backend Controls
### Advanced Backend Controls

`Advanced Backend Controls` stay available without changing the saved settings schema. They are grouped into categories so the everyday path can stay simpler for day-to-day use.

## Backend Categories

### Session & Sync

Expand Down Expand Up @@ -178,6 +210,7 @@ For most environments:

- smart sort enabled
- auto-fetch limits enabled
- storage backups enabled when you want rollback context for sync and recovery flows
- live sync enabled
- session affinity enabled
- preemptive quota deferral enabled
Expand Down
Loading