Codex Account Manager: User Guide¶
Welcome to the Codex Account Manager! This guide covers everything you need to know to install, configure, and use the tool effectively.
📚 Table of Contents¶
- Installation
- Getting Started
- Daily Workflow
- Organization (Tags & Lists)
- Universal Proxy (Run)
- Context Awareness
- Data Portability & Sync
- Security & Auditing
- Troubleshooting
1. Installation¶
Prerequisites¶
- Python 3.9 or higher
- Pip (Python Package Installer)
Install via Pip¶
If you have the .whl file (from the build):
Install from Source¶
git clone https://github.com/your-org/codex-account-backups.git
cd codex-account-manager
poetry install
poetry shell
2. Getting Started¶
Initialize Storage¶
Before using the tool, you must initialize the secure storage vault. This creates the ~/.codex-accounts directory with secure permissions (0600).
Add Your First Account¶
You can add an account using the interactive wizard:
Follow the prompts to enter: * Name: A unique nickname (e.g.,work, personal).
* Email: Your registered email (e.g., alice@example.com).
* API Key: Your Codex API Key (sk-...).
3. Daily Workflow¶
Switching Accounts¶
The core feature of this tool is Context Switching. When you switch accounts, the tool updates the central ~/.codex/auth.json file used by the Codex CLI.
Command:
Example:
Checking Status¶
Unsure which account is active?
Output:Interactive Selection (TUI)¶
If you forget your account names, use the interactive browser:
Use Arrow Keys to highlight an account and Enter to switch.4. Organization¶
Tagging Accounts¶
Group your accounts logically using tags (e.g., v1, v2, prod, dev).
Add with Tags:
Filtering Lists¶
View only relevant accounts:
5. Universal Proxy (Run Command)¶
The superpower of Codex Account Manager is the ability to inject credentials into any other CLI tool without manual exports.
Basic Usage¶
Use codex-account run to wrap your target command.
Environment Variables¶
You can attach arbitrary environment variables (like AWS keys, Database URLs) to an account.
Add Variable:
Run with Vars:
6. Context Awareness¶
Stop switching accounts manually. Link directories to specific identities.
Link Directory¶
Now, this directory is permanently linked toclient-alpha.
Session Override¶
You can also override the account for a specific terminal session (useful for temporary work):
export CODEX_ACTIVE_ACCOUNT=personal
codex-account run -- ./script.sh # Uses 'personal' regardless of global settings
7. Data Portability & Sync¶
Keep your accounts backed up and synchronized across devices.
Manual Backup (Zip)¶
# Access denied? Encryption protects your data.
codex-account export --output ./backup.zip
# Restore
codex-account import ./backup.zip
Git Sync (Recommended)¶
Sync your encrypted vault to a private Git repository.
Setup: 1. Create a private repo (e.g., on GitHub/GitLab). 2. Initialize sync:
Workflow:
8. Security & Auditing¶
Track who accessed your keys and when.
View Audit Log¶
Filter Logs¶
9. Troubleshooting¶
"Permission Denied" Errors¶
Ensure your ~/.codex-accounts directory has correct permissions.
Fix it manually:
"Account Not Found"¶
Run codex-account list to see available names. Names are "slugified" (e.g., "My Account" becomes "my-account").
Manual Recovery¶
If the tool breaks, your data is stored in standard JSON files at ~/.codex-accounts/. You can back up or inspect this directory manually (requires root or user permissions).
10. Agile Teams (Team Vaults)¶
Collaborate securely with shared team vaults.
Join a Team¶
You need the Team Name, Git URL, and the Team Master Key (from your admin).
Enter the Team Master Key when prompted.Access Team Accounts¶
Team accounts are namespaced: team-name/account-name.