Manage multiple Codex profiles from your terminal. Switch subscriptions, encrypt credentials at rest, and never manually juggle ~/.codex/ again.
- Instant profile switching — swap
~/.codex/credentials in one command - AES-256-GCM encryption — inactive profiles encrypted at rest, key stored in your OS keychain
- Interactive TUI — full-screen terminal UI with keyboard shortcuts (or use the CLI)
- Process guard — blocks switching while Codex is running to prevent corruption
- Strictly offline — zero network dependencies, works fully air-gapped
Download the archive for your target from GitHub Releases. macOS and Linux builds ship as .tar.gz; Windows builds ship as .zip.
1. Verify the archive before running anything. Every release archive is covered by a Sigstore-backed GitHub build provenance attestation, which proves it was built by this repository's release workflow:
gh attestation verify sub-swap-v<version>-<target>.tar.gz \
--repo minakoto00/sub-swapThe published .sha256 sidecar is a convenience for catching transit corruption; it is not a provenance check. If you only have time for one check, run gh attestation verify.
2. Extract the archive.
macOS / Linux:
tar xzf sub-swap-v<version>-<target>.tar.gzWindows (PowerShell):
Expand-Archive sub-swap-v<version>-x86_64-pc-windows-msvc.zip -DestinationPath .3. Install onto your PATH.
macOS / Linux:
chmod +x sub-swap
sudo mv sub-swap /usr/local/bin/Windows: move sub-swap.exe into a directory on %PATH% (e.g. %LOCALAPPDATA%\Programs\sub-swap\).
First-launch warnings: sub-swap releases are not notarized with Apple Developer ID and are not signed with an EV Authenticode certificate, so macOS Gatekeeper and Windows SmartScreen will warn on the first launch. Run
gh attestation verifyfirst, then approve the OS prompt manually.
Requires a stable Rust toolchain.
git clone https://github.com/minakoto00/sub-swap.git
cd sub-swap
cargo build --release
# Binary at target/release/sub-swapLinux note: The
keyringcrate may requirelibdbus-1-devandlibsecret-1-dev(Debian/Ubuntu) depending on your desktop environment.
1. Save your current Codex profile
sub-swap add work --note "work account"2. Set up a second profile
Log into your other Codex account in ~/.codex/, then:
sub-swap add personal --note "personal account"3. Switch between them
sub-swap use work4. Or use the interactive TUI
sub-swap| Command | Description |
|---|---|
sub-swap list |
List all profiles (-v for details) |
sub-swap add <name> |
Import current ~/.codex/ as a new profile |
sub-swap add <name> --from <path> |
Import from a specific directory |
sub-swap use <name> |
Switch to a profile (--force to skip process guard) |
sub-swap rename <old> <new> |
Rename a profile |
sub-swap remove <name> |
Delete a stored profile |
sub-swap note <name> <text> |
Set or update a profile's note |
sub-swap decrypt <name> |
View decrypted profile contents (stdout only, never written to disk) |
sub-swap config show |
Show current settings |
sub-swap config set encryption <on|off> |
Toggle encryption for stored profiles |
Run sub-swap with no arguments to launch the interactive terminal UI.
Keys: Enter switch · a add · r rename · d delete · n note · v view · q quit
- Encryption: Inactive profiles are encrypted with AES-256-GCM. The active profile in
~/.codex/remains plaintext (Codex requires this). - Key storage: Your encryption key lives in the OS keychain (macOS Keychain, GNOME Keyring, Windows Credential Manager) — never on disk.
- File permissions: All files under
~/.sub-swap/are created with mode0600(owner-only) on Unix. - Offline: Zero network crates in the dependency tree, enforced by architectural tests.
- Process guard:
sub-swap usedetects running Codex processes and blocks switching to prevent credential corruption.
For the full threat model, see docs/SECURITY.md.
cargo test # all tests (unit + integration)
cargo test --lib # unit tests only
just validate # fmt + clippy + test| Doc | Purpose |
|---|---|
| ARCHITECTURE.md | Module layout and dependency rules |
| SECURITY.md | Encryption model and threat model |
| TESTING.md | Test infrastructure and recipes |
Copyright (C) 2025 Juewei Dong
This project is licensed under the GNU General Public License v3.0.