Codex Auth Split

Use different auth.json files for Codex Desktop and Codex CLI, without duplicating your Codex config.

Codex Auth Split gives the two Codex modes separate local auth state. Codex Desktop can keep using your normal ~/.codex/auth.json; Codex CLI can run from a separate CODEX_HOME profile with its own auth.json; both keep the same Codex config linked from ~/.codex.

This project is not affiliated with OpenAI.

Why

Codex stores local auth under CODEX_HOME. That is fine until the Desktop app and CLI need different login state but the same rules, skills, MCP config, memories, and plugins.

Codex Auth Split keeps the sharp boundary where it matters:

• Desktop keeps ~/.codex/auth.json
• CLI gets ~/.codex-auth-split/cli/auth.json
• shared config.toml, AGENTS.md, skills, plugins, rules, memories, mcp, and browser when present
• no automatic token copying
• redacted diagnostics for email, workspace, account, and expiry

Install

From GitHub:

npm install -g github:vyctorbrzezowski/codex-auth-split

After npm publish:

npm install -g @vyctorbrzezowski/codex-auth-split

Local development:

npm install
npm run check

Requires Node.js 20 or newer.

Quick Start

Create the default CLI profile:

codex-auth-split init

Log in inside that profile:

codex-auth-split login

Run Codex CLI with that profile:

codex-auth-split run -- codex

Short alias:

cas run -- codex exec "summarize this repo"

Named profiles still work when you need them:

cas run work -- codex --version

The default Codex Desktop can keep using:

~/.codex/auth.json

The CLI profile uses:

~/.codex-auth-split/cli/auth.json

Both share linked configuration from ~/.codex.

Commands

codex-auth-split init [name]

Creates a CLI auth profile and links shared config entries. Defaults to cli.

codex-auth-split login [name]

Runs codex login with CODEX_HOME pointed at the profile. Defaults to cli.

codex-auth-split run [name] -- [command...]

Runs any command with CODEX_HOME set to the profile. Defaults to the cli profile and to codex when no command is provided.

codex-auth-split shell [name]

Opens your shell with CODEX_HOME already set. Defaults to cli.

codex-auth-split app [name]

macOS-only. Launches Codex Desktop with the selected profile and a separate Electron user-data path. Most users can leave Desktop on the default ~/.codex auth and use run for the CLI profile.

codex-auth-split status [--json]

Lists profiles, auth presence, and linked shared config entries.

codex-auth-split check [--json]

Shows the active email and workspace/account for the default Codex home and each profile, without printing token contents. Use this when you explicitly want identity diagnostics.

codex-auth-split doctor [--json]

Checks the local setup without printing secrets.

Use Cases

Desktop and CLI with different auth

cas init
cas login
cas run -- codex

Codex Desktop keeps ~/.codex/auth.json. Codex CLI gets ~/.codex-auth-split/cli/auth.json. Both share the same Codex config.

Configuration

Set a custom profile root:

CODEX_AUTH_SPLIT_ROOT=~/.my-codex-profiles cas status

Set a custom shared Codex home:

CODEX_SHARED_HOME=~/custom-codex cas init cli

Safety

• Token contents are never printed.
• auth.json is not copied automatically.
• Profile names cannot escape the configured profile root.
• status --json and doctor --json omit auth identity details; check is the explicit identity diagnostic.
• Shared config entries are symlinks; rerun init or doctor if a link is broken.
• Prefer codex-auth-split login <name> over manually copying auth files.
• Avoid reusing the same auth.json in multiple active profiles.

Project Docs

• Architecture
• Contributing
• Security policy
• Changelog