CLI & terminal

Install the complete application with ./install.sh or bun run setup. Both install dependencies, CLI, TUI, plugin, official daemon integration, and the local backend. Use bun run install:cli or ./install.sh --cli-only only when you want the manager command alone. Then use codex-accounts from any directory. bun run setup installs the command and registers the plugin. Keep using the official codex command to work on your conversations.

For a fresh installation:

git clone https://github.com/eduardoaugustolb/codex-accounts.git
cd codex-accounts
./install.sh

The installer installs project dependencies automatically; a separate bun install is unnecessary. Git, Bun, and the official Codex CLI must already be installed.

The command is installed in ~/.local/bin by default. Add that directory to your shell’s PATH if necessary; no shell alias or startup-file modification is needed. Use ./install.sh --help for custom binary and data directories. Installation copies the built marketplace into a separate release directory, so moving the source checkout does not break the command. Reinstall after updating the source.

Start here

codex-accounts
codex-accounts --help
codex-accounts usage work --json
codex-accounts switch personal
# From the project checkout, these forms also work:
bun run help
bun run tui
bun run usage
bun run usage work
bun run switch personal

Names such as personal and work are local aliases. Register them with add or capture first. Each name must start with a letter or number, followed by letters, numbers, underscores, or hyphens, up to 64 characters. Names are case-sensitive.

In an interactive terminal, bun run start opens the TUI. When input or output is redirected, the command without arguments prints help. tui requires a TTY and returns an error in scripts; use usage --json instead.

Command reference

The installed form is codex-accounts <command> [arguments]. From the project checkout, commands also work with bun run start <command> or bun src/native-cli.ts <command>. Script shortcuts are shown where available.

| Command | Shortcut | Purpose | | --- | --- | --- | | help, --help, -h | bun run help | Show help without accessing the vault or starting the backend. | | tui | bun run tui | Open the interactive terminal account manager. | | add NAME [--device] | — | Register a new account through official login, in an isolated home. | | capture NAME | — | Save the current official file-based login. | | list | — | Print saved account aliases, one per line. | | usage [NAME] [--json] | bun run usage | Read fresh limits for one or all saved accounts. | | switch NAME | bun run switch NAME | Switch the shared idle Codex session to a saved account. | | resume-after-reset on\|off | bun run resume-after-reset on | Persist the independent reset-continuation preference. | | remove NAME | bun run remove NAME | Delete an inactive account from this device. | | logout | bun run logout | Sign out of the daemon without deleting saved accounts. | | panel | bun run panel | Start the backend if needed and open its local browser panel. | | status | bun run status | Print the private panel URL, or report that the backend is stopped. | | start | bun run start start | Start the backend and print the private panel URL. | | restart | bun run restart | Restart the plugin backend, preserving accounts and preferences. | | stop | bun run stop | Stop the plugin backend; this does not stop the official daemon. | | install | — | Register the built plugin and start the official daemon. Prefer bun run setup to build first. |

<command> --help shows the command overview. Invalid arguments and unknown commands return a nonzero exit code. Quota windows that cannot be read are data availability failures rather than a command failure: inspect unavailable and null windows in JSON. status reports a stopped backend without starting it.

Register accounts

Configure file-based authentication as described in the README. Then save the current login or add another one:

bun run start capture personal
bun run start add work
bun run start add secondary --device
bun run start list

Registration does not switch your current session. Existing aliases cannot be overwritten; choose another name or remove the inactive saved account first. capture reads the official login cache and never asks you to paste tokens.

Read quotas

bun run usage
bun run usage work
bun run usage work --json

The text output identifies the current account and reports remaining capacity, not used capacity. Reset timestamps are ISO 8601 in UTC. The browser panel formats reset times in Brasilia time; the TUI shows time remaining until the reported reset. An elapsed timestamp is not evidence that the service has restored capacity.

Illustrative output:

work (current)
  5h: 40% remaining; resets 2026-11-12T18:00:00.000Z
  Weekly: 70% remaining; resets unknown

The JSON shape is the same for single-account and all-account queries:

{
  "accounts": [
    {
      "name": "work",
      "current": true,
      "usage": {
        "fiveHour": { "remaining": 40, "resetsAt": 1794506400 },
        "weekly": { "remaining": 70, "resetsAt": null },
        "updatedAt": 1794502800000
      }
    }
  ]
}

resetsAt is Unix time in seconds, or null; updatedAt is Unix time in milliseconds. Missing windows are null. A failed read sets unavailable: true and both windows to null. Unknown capacity never qualifies an account for automatic switching or continuation. An empty vault returns {"accounts": []}. The response does not include emails, authentication tokens, or the private panel URL.

Reads for inactive accounts use isolated official App Server helpers. They do not switch the live session or make inference requests. Large vaults may take longer because quota reads are sequential.

Switch and sign out

bun run switch work
bun run logout
bun run switch personal
bun run remove secondary

Switching and logout affect all conversations sharing the official daemon. They are rejected while any loaded turn is active. Finish or stop those turns in Codex and retry. Manual switching preserves history but does not start a new turn: send continue yourself in the original conversation when ready.

An active account cannot be removed. Switch to another account or log out first. Removal deletes only that alias’s local credentials and uploaded profile image; it does not delete the remote account or conversation history.

Terminal interface

bun run tui

The active account is marked * current. Quota bars fill with remaining capacity. Select a row with Up/Down or j/k; selection wraps and scrolls as needed. The interface follows the selected Codex theme dynamically, including built-in and custom TextMate definitions. See theme behavior. Resize the terminal to see both quota windows together on wider screens.

| Key | Result | | --- | --- | | Enter | Ask to switch to the selected account; y confirms, any other key cancels. | | r | Refresh all quotas immediately. | | a | Toggle autoSwitch. | | c | Toggle autoContinue. | | w | Toggle resumeAfterReset. | | n | Enter a new alias and start official device login. | | s | Enter an alias and capture the current official login. | | d | Ask to remove the selected account; y confirms. | | l | Ask to log out; y confirms. | | Esc | Cancel a name prompt or confirmation; exit from the main view. | | q / Ctrl+C | Exit the main view / exit the manager. |

Quotas refresh on entry, on r, and every 30 seconds while the manager is idle and no prompt is open. The manager does not submit overlapping UI actions. Backend locks still protect concurrent operations from other terminals or the browser. Device login temporarily leaves raw mode and the alternate screen so the official login flow owns input. The TUI restores the cursor, terminal mode, and previous screen when it exits. Closing the TUI leaves the backend running.

Automation

bun run resume-after-reset on
bun run resume-after-reset off

Use the TUI’s a/c/w keys or the browser preferences to configure the three independent settings. Turning on reset continuation does not enable autoswitch. See Automatic behavior and recovery for timing and eligibility.

Troubleshooting

| Symptom | What to do | | --- | --- | | codex-accounts command not found | Run ./install.sh, then add the reported binary directory to your shell PATH. | | Installer finds an unmanaged command | Choose another --bin-dir; the installer will not overwrite unrelated commands or symlinks. | | TUI requires an interactive terminal | Open it in a terminal; use usage --json for redirected input/output. | | Unknown command or invalid arguments | Run bun run help; include an account alias where required. | | Account not registered | Run bun run start list, then register the intended alias. | | Quotas unavailable | Check official login and daemon connectivity; refresh with r or bun run usage NAME. Never replace unknown quotas with zero in scripts. | | Turn still active | Wait for all daemon conversations to finish, then retry switching or logout. | | Backend unavailable or old commands unsupported | Run bun run restart after updating; reopen the TUI. | | Panel link no longer works | Backend restarts rotate its private address; run bun run panel. | | Authentication refresh stopped after a backend restart | Select the saved account again after turns are idle to restore backend-owned refresh handling. | | Temporary daemon cannot be installed | Choose a short, writable TMPDIR with enough free space; integration tests install isolated daemons. | | Legacy directory lock detected | Stop all older clients and inspect the abandoned directory lock before removing it. Current SQLite locks release on process exit; never delete mutation-lock.sqlite while a client is running. |

Treat status output and panel links as private. Do not paste authentication files, private panel URLs, or account emails into issues. Report vulnerabilities using SECURITY.md.

Hosted browser dashboard

Run codex-accounts panel to open the browser dashboard.

The browser opens https://ca.eduardoaugusto.work and pairs with the backend on this device. The command prints a compact, already-paired hosted URL. The private local endpoint is encoded in its URL fragment, consumed by the browser, and retained only for this tab. Allow access to apps on this device if the browser prompts. If local-network access is blocked, use the private local URL printed by codex-accounts status directly. Backend restarts require pairing again. The static hosting service does not receive your account credentials or relay local requests. Update the installation and restart the backend before using this feature.

Updating without a checkout

Once installed with the current installer, run from any directory:

codex-accounts update
codex-accounts restart

The updater clones the official repository’s latest main into a temporary directory and runs its installer. Git and Bun must be available. It preserves custom binary/data directories, manager-only installation mode, saved accounts, and preferences. It does not run git pull in your working checkout. The temporary source is removed after success or failure. This currently installs the latest source version rather than a tagged release.

Running backends and conversations are preserved during installation. Restart the backend when ready, review changed hooks in Codex /hooks, and reopen codex-accounts panel. Installations created before update metadata was introduced need one ./install.sh run from the existing checkout first; later updates use codex-accounts update. A source invocation of update is rejected because it has no managed installation target.