auto-auth-cli

Profile-aware auth switching for coder agent CLIs.

auto-auth lets you keep multiple authentication profiles for a supported CLI and launch that CLI with the profile you choose. For Codex, it only replaces:

~/.codex/auth.json

Everything else in ~/.codex stays shared across profiles.

Table of Contents

• Supported Tools
• Prerequisites
• Installation
  • From PyPI
  • Quick Try from GitHub
  • Install from GitHub
  • From Source
• Quick Start
• Usage
  • Codex
  • Claude Code
• Stored Files
• Development

Supported Tools

Prerequisites

• Python 3.13+ - Required by the package.
• uv - Used for installation and local development.
• Codex CLI - Required for the current codex category. The codex executable must be available in PATH.

Installation

Use --python 3.13 so uv builds the isolated tool environment with a supported Python version.

From PyPI

Use this for the latest published release.

Quick try (no installation):

uvx --python 3.13 --from auto-auth-cli@latest auto-auth codex --status

Install globally:

uv tool install --python 3.13 auto-auth-cli

Then run from any directory:

auto-auth codex --status

Upgrading: Run uv tool upgrade --python 3.13 auto-auth-cli.

Quick Try from GitHub

Run auto-auth directly from GitHub without installing it globally:

uvx --python 3.13 --from git+https://github.com/midodimori/auto-auth-cli auto-auth codex --status

You can use the same uvx form for any Codex command:

uvx --python 3.13 --from git+https://github.com/midodimori/auto-auth-cli auto-auth codex --setup
uvx --python 3.13 --from git+https://github.com/midodimori/auto-auth-cli auto-auth codex --auto
uvx --python 3.13 --from git+https://github.com/midodimori/auto-auth-cli auto-auth codex --profile you -- -m gpt-5.5

Install from GitHub

Recommended when you want the latest version from the repository available as a normal command.

uv tool install --python 3.13 git+https://github.com/midodimori/auto-auth-cli

Then run from any directory:

auto-auth codex --status

Upgrading: Re-run uv tool install --force --python 3.13 git+https://github.com/midodimori/auto-auth-cli.

From Source

git clone https://github.com/midodimori/auto-auth-cli.git
cd auto-auth-cli
uv sync
uv run auto-auth codex --status

To install globally from source:

uv tool install --python 3.13 --editable .

Then run from any directory:

auto-auth codex --status

Quick Start

Create a Codex profile:

auto-auth codex --setup

List saved profiles:

auto-auth codex --status

Run Codex with a saved profile:

auto-auth codex --profile you@example.com

Run Codex with the first profile that has available quota:

auto-auth codex --auto

Pass Codex arguments after --:

auto-auth codex --profile you -- -m gpt-5.5  # Run Codex with a specific profile and model
auto-auth codex --auto -- -m gpt-5.5  # Auto-select a profile, then run Codex with a model
auto-auth codex --auto -- --yolo app  # Auto-select a profile, then run the Codex app in yolo mode

Usage

The first positional argument is the tool category. Codex is the only supported category today.

auto-auth <tool> [OPTIONS] [-- TOOL_ARGS...]

Codex

Create a Profile

auto-auth codex --setup

--setup runs codex login in a temporary Codex home, extracts the account metadata from the generated auth file, and saves it as a reusable profile. It does not overwrite your active ~/.codex/auth.json.

If setup cannot detect an email or account id, provide a label:

auto-auth codex --setup --label work

List Profiles

auto-auth codex --status

The status output shows the active profile, saved profiles, detected plan type, active state, and the primary and secondary quota windows for each profile.

Select a Profile

auto-auth codex --profile you@example.com

--profile accepts a profile email, profile key, account id, or unique prefix:

auto-auth codex --profile you

Before switching, auto-auth backs up the current Codex auth file, then installs the selected profile into:

~/.codex/auth.json

Auto-Select a Profile

auto-auth codex --auto

--auto checks saved profiles and launches Codex with the first account that has available quota. Smaller subscriptions are checked first.

Pass Codex Arguments

Put Codex arguments after --:

auto-auth codex --profile you -- -m gpt-5.5  # Run Codex with a specific profile and model
auto-auth codex --auto -- -m gpt-5.5  # Auto-select a profile, then run Codex with a model
auto-auth codex --auto -- --yolo app  # Auto-select a profile, then run the Codex app in yolo mode

The last example runs the Codex app in yolo mode after selecting an available profile.

Codex Environment Variables

Claude Code

Claude Code support is planned for a future tool category. Until that adapter exists, auto-auth only accepts:

auto-auth codex ...

Stored Files

Codex profiles:

~/.auto-auth/codex/profiles/

Codex auth backups:

~/.auto-auth/codex/backups/

If AUTO_AUTH_HOME is set, those paths move under that directory.

Development

uv sync --all-groups
uv run pre-commit install
uv run pre-commit run --all-files
uv run pytest -q
uv run ruff check .
uv run ty check