You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-`codex auth` unrecognized: run `where codex`, then follow `docs/troubleshooting.md` for routing fallback commands
238
244
- Switch succeeds but wrong account appears active: run `codex auth switch <index>`, then restart session
239
245
- OAuth callback on port `1455` fails: free the port and re-run `codex auth login`
246
+
- Interactive login skipped restore and went straight to OAuth: place named backups in `~/.codex/multi-auth/backups/`, then rerun `codex auth login` in a normal TTY
240
247
-`missing field id_token` / `token_expired` / `refresh_token_reused`: re-login affected account
Copy file name to clipboardExpand all lines: docs/features.md
+5Lines changed: 5 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,6 +9,8 @@ User-facing capability map for `codex-multi-auth`.
9
9
| Capability | What it gives you | Primary entry |
10
10
| --- | --- | --- |
11
11
| Multi-account dashboard login | Add and manage multiple OAuth identities from one terminal flow |`codex auth login`|
12
+
| Startup recovery prompt | Offer restore before OAuth when recoverable named backups are found and no active accounts exist |`codex auth login`|
13
+
| Backup restore manager | Review named backups, merge with dedupe, and skip invalid or over-limit restores |`codex auth login` -> `Restore From Backup`|
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.
84
+
85
+
---
86
+
87
+
## Sync And Settings
88
+
89
+
The settings flow is split into two productized sections:
90
+
91
+
-`Everyday Settings` for list appearance, details line, results and refresh behavior, and colors
92
+
-`Advanced & Operator` for `Codex CLI Sync`, `Experimental`, and backend tuning
93
+
94
+
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.
Copy file name to clipboardExpand all lines: docs/reference/settings.md
+13-3Lines changed: 13 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -21,7 +21,7 @@ When `CODEX_MULTI_AUTH_DIR` is set, this root moves accordingly.
21
21
22
22
## Everyday Settings
23
23
24
-
The top-level settings flow separates everyday dashboard preferences from advanced operator controls.
24
+
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.
25
25
26
26
### List Appearance
27
27
@@ -72,9 +72,11 @@ Controls display style:
72
72
73
73
## Advanced and Operator Controls
74
74
75
+
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.
76
+
75
77
### Codex CLI Sync
76
78
77
-
The advanced section includes a preview-first sync center for Codex CLI account sync.
79
+
`Codex CLI Sync` is a preview-first sync center for Codex CLI account sync.
78
80
See [upgrade notes](../upgrade.md) for sync workflow changes.
79
81
80
82
Before applying sync, it shows:
@@ -86,6 +88,13 @@ Before applying sync, it shows:
86
88
- destination-only preservation behavior
87
89
- backup and rollback context (`.bak`, `.bak.1`, `.bak.2`, `.wal`)
88
90
91
+
Workflow notes:
92
+
93
+
- refresh recomputes the read-only preview from Codex CLI source files
94
+
- apply writes the preview result into the target path
95
+
- sync is one-way, it is not a bidirectional merge
96
+
- target-only accounts are preserved rather than deleted
97
+
89
98
Validation:
90
99
91
100
-`npm run typecheck`
@@ -116,7 +125,7 @@ Named backup behavior:
116
125
117
126
### Advanced Backend Controls
118
127
119
-
Expert backend controls stay available without changing the saved settings schema. They are grouped into categories so the default path can stay simpler for day-to-day use.
128
+
`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.
120
129
121
130
## Backend Categories
122
131
@@ -208,6 +217,7 @@ For most environments:
208
217
209
218
- smart sort enabled
210
219
- auto-fetch limits enabled
220
+
- storage backups enabled when you want rollback context for sync and recovery flows
Copy file name to clipboardExpand all lines: docs/troubleshooting.md
+32-1Lines changed: 32 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# Troubleshooting
2
2
3
-
Recovery guide for install, login, switching, worktree storage, and stale local auth state.
3
+
Recovery guide for install, login, backup restore, sync preview, worktree storage, and stale local auth state.
4
4
5
5
---
6
6
@@ -20,6 +20,8 @@ codex auth login
20
20
21
21
If `codex auth login` starts with no saved accounts and recoverable named backups are present, you will be prompted to restore before OAuth. This prompt only appears in interactive terminals and is skipped after same-session fresh/reset flows.
22
22
23
+
If you want to inspect backup options yourself instead of taking the prompt immediately, open `codex auth login` and choose `Restore From Backup`.
24
+
23
25
---
24
26
25
27
## Verify Install And Routing
@@ -57,6 +59,17 @@ npm i -g codex-multi-auth
57
59
58
60
---
59
61
62
+
## Backup Restore Problems
63
+
64
+
| Symptom | Likely cause | Action |
65
+
| --- | --- | --- |
66
+
| You expected a restore prompt but went straight to OAuth | No recoverable named backups were found, the terminal is non-interactive, or the flow is skipping restore after an intentional reset | Put named backup files in `~/.codex/multi-auth/backups/`, then rerun `codex auth login` in an interactive terminal |
67
+
|`Restore From Backup` says no backups were found | The named backup directory is empty or the files are elsewhere | Place backup files in `~/.codex/multi-auth/backups/` and retry |
68
+
| A backup is listed but cannot be selected | The backup is invalid or would exceed the account limit | Trim current accounts first or choose a different backup |
69
+
| Restore succeeded but some rows were skipped | Deduping kept the existing matching account state | Run `codex auth list` and `codex auth check` to review the merged result |
70
+
71
+
---
72
+
60
73
## Switching And State Problems
61
74
62
75
| Symptom | Likely cause | Action |
@@ -67,6 +80,19 @@ npm i -g codex-multi-auth
67
80
68
81
---
69
82
83
+
## Codex CLI Sync Problems
84
+
85
+
Use `codex auth login` -> `Settings` -> `Codex CLI Sync` when you want to inspect sync state before applying it.
86
+
87
+
| Symptom | Likely cause | Action |
88
+
| --- | --- | --- |
89
+
| Sync preview looks one-way | This is the shipped behavior | Review the preview, then apply only if the target result is what you want |
90
+
| A target-only account would be lost | The sync center preserves destination-only accounts instead of deleting them | Recheck the preview summary before apply |
91
+
| You want rollback context before syncing | Backup support is disabled in current settings | Enable storage backups in advanced settings, then refresh the sync preview |
92
+
| Active selection does not match expectation | Preview kept the newer local choice or updated from Codex CLI based on selection precedence | Refresh preview and review the selection summary before apply |
0 commit comments