explaingit

r266-tech/sub2cli

★ 12PythonAudience · developerComplexity · 2/5Setup · moderate

TLDR

A macOS tool that simplifies switching between API relay accounts for OpenAI's Codex CLI by automatically updating config files, testing model endpoints, and managing credentials through a menu-driven desktop app or terminal interface.

Mindmap

mindmap
  root((sub2cli))
    What it does
      Switch relay accounts
      Test endpoints
      Write config files
      Backup configs
    Tech Stack
      Python
      requests lib
      websocket-client
      macOS native
    Use Cases
      Dev relay switching
      Endpoint testing
      Config management
    Audience
      Codex CLI users
      API relay users
      macOS developers
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Switch between different Codex API relay accounts without manually editing configuration files

USE CASE 2

Test which AI model endpoints are available from a relay service and compare their latency

USE CASE 3

Manage multiple relay subscriptions with automatic config backups for easy rollback

USE CASE 4

Set up Codex CLI with a third-party API relay service using a guided menu interface

Tech stack

Pythonrequestswebsocket-clientmacOS

Getting it running

Difficulty · moderate Time to first run · 30min

Requires macOS 12+ and Python 3.10+, the desktop app is unsigned and requires removing Apple's quarantine flag before opening.

In plain English

Sub2cli is a macOS tool for people using Codex CLI or Codex App (OpenAI's command-line coding assistant) who access it through an API relay service rather than directly through an official OpenAI account. An API relay is a third-party service that provides access to AI models, often with different pricing or subscription arrangements. The primary supported relay is codex2api.com, but the tool works with any self-hosted instance of the Sub2API relay software. The problem it solves is switching between API channels. Without this tool, changing your Codex setup to use a different relay account, key, or endpoint means manually editing configuration files at ~/.codex/config.toml and ~/.codex/auth.json, restarting Codex App, and hoping nothing breaks. Sub2cli wraps all of that into a menu-driven interface: you pick a relay account, test which model endpoints are available, select one, and the tool writes the config files for you with automatic backups in case you need to roll back. It comes in two forms. The desktop app is a macOS native window with a dark industrial interface that shows account balances, subscription status, and endpoint latency side by side. The CLI is a terminal REPL (an interactive command-line menu) backed by the same Python logic. Both are distributed from the same single Python file with minimal dependencies: just the requests and websocket-client packages. Under the hood, the tool reads your relay auth token from a browser's local storage via a debugging connection to Chrome or Edge, then calls the relay's REST API to get your keys, groups, and subscription details. When writing config changes, it uses an atomic copy approach and a lock file to prevent Codex App's own token refresh mechanism from corrupting the files at the same time. The desktop app is unsigned, so macOS will block it by default. The README provides the command to remove Apple's quarantine flag before opening it. Installation for the CLI version is via a shell script from the repository or from a local clone, targeting macOS 12 or later with Python 3.10 or later.

Copy-paste prompts

Prompt 1
I want to use sub2cli to switch my Codex CLI from one API relay account to another on macOS. Walk me through installing the CLI version and running the interactive menu.
Prompt 2
Help me configure sub2cli to read my relay auth token from Chrome's local storage and automatically update my ~/.codex/config.toml and ~/.codex/auth.json.
Prompt 3
I have sub2cli installed. How do I test multiple relay endpoints to find the fastest one and write that endpoint to my Codex config?
Prompt 4
Show me how sub2cli's atomic file copy and lock file prevents Codex App's token refresh from corrupting my config during a relay switch.
Prompt 5
I need to roll back my Codex CLI config after a bad relay switch. How do I use sub2cli's automatic backup to restore the previous config?
Open on GitHub → Explain another repo

← r266-tech on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.