soia-env-codex-install

Install Codex CLI through an officially supported installation entry point, and handle "missing dependencies", "command not in PATH", and "login incomplete" separately. Installation and login can be assisted by the Agent, but the customer completes authorization only on the official browser page.

Customer-readable instructions

What this skill can do

Customer wants	Skill will do	Customer can see
Install Codex	Check dependencies, install the official package, verify the command	Codex CLI fixed status list and installation directory
Check for Codex updates	Identify the CLI source actually in effect and compare versions, without automatically updating	Current version, latest version, and source
Update Codex to the latest	After the customer explicitly requests the latest version, update using the original source	Intermediate status, update result, installation method, and configuration directory
Log in to Codex	Start the official login flow	Clickable official authorization steps, without displaying keys
Codex not found	Diagnose PATH, npm global directory, and shell	Fix suggestions or changes requiring confirmation

How the customer uses it

Other recognizable phrasings include "update Codex to the latest", "configure Codex", and "Codex login"; desktop app won't open, performance, or disk issues are handed off to soia-env-codex-setup-support。

Say "install Codex" and state the operating system; the Agent first checks the system, network, and existing CLI source.
The official standalone installation does not require Node.js; only when choosing or continuing with the npm channel is missing Node.js/npm used to invoke soia-env-node-install。
"Install Codex" only authorizes installing a missing standalone CLI, not updating an existing CLI; "check for updates" or an ambiguous "update Codex" only performs a version audit and asks whether to update to the latest.
Only when the customer explicitly says "update Codex to the latest", "upgrade to the latest version", or an equivalent instruction is upgrade execution invoked; administrator privileges, switching sources, or modifying PATH still require separate confirmation.
During installation/update, the Agent continuously displays stage status and writes a private progress record; the customer only clicks to authorize on the official login page.

First login and real configuration verification

配置文件目录Only display CODEX_HOME or the default candidate path; the skill must also check config_status, and must not treat ~/.codex directly as logged in.
If the standalone CLI is not logged in, the Agent uses the same absolute path to execute codex --login; the customer clicks "Sign in with ChatGPT" on the official page to complete authorization, and the customer does not need to apply for or paste an API key. This flow saves credentials locally.
If the customer explicitly chooses the traditional API key method, the customer creates it in OpenAI API Keys and injects it through the customer's own secure environment; the Agent does not read, receive, or echo the key.
After logging in, run login status、--version、--helpagain, and recheck config_status; if authorization has not been completed, write "waiting for first login" in the result, and do not write only "installed". ChatGPT.app login status remains separate from the CLI.

Dependencies and installation

Dependency	Type	Handling
`soia-env-ai-cli-upgrade`	CLI update depends on	Unified execution of Codex version audit and original channel update
Node.js/npm	npm channel dependency	Only required for npm installation or update; when missing, call `soia-env-node-install`
Network diagnostics	Pre-checks	On failure, first call `soia-env-network-diagnose`
OpenAI account or API configuration	User authorization	Do not read or request keys; handled by the official login flow

When the CLI upgrade skill is missing, install it from this environment's skill library:

claude plugin marketplace add soia-team/soia-open-skills

claude plugin install soia-env@soia

When only this one skill is needed, the npx route can be used. Note that the skill will land in the shared source of truth ~/.agents/skills; if a plugin is also installed, the same skill will appear in two indexes and each will drift, so it is recommended to choose one of the two:

npx skills add soia-team/soia-open-env-skills -g -a '*' -s soia-env-ai-cli-upgrade -y

For official sources and command facts, see official-sources.md。

Standard procedure

First execute python3 scripts/inspect_installation.py --json, find the standalone Codex CLI, and record the version, installation method, installation directory, command path, and whether the configuration directory actually exists.
Treat ChatGPT.app/Contents/Resources/codex as an internal component of the desktop application, not as a standalone Codex CLI; even if the current Agent process's PATH hits it first, continue searching the login shell, npm, Homebrew, and the official standalone installation paths.
When the standalone CLI is missing, on macOS/Linux prefer the OpenAI official standalone installation entry point; only when the customer explicitly chooses npm, or the machine originally used the npm channel, require Node.js/npm and install @openai/codex。

For an installed CLI, by default only perform a dry-run version audit, selecting only Codex:

TOOLS=codex DRY_RUN=1 bash ~/.agents/skills/soia-env-ai-cli-upgrade/scripts/upgrade-ai-clis.sh

When dry-run finds a new version, first report "update available, not executed." When the customer only says "update," stop and ask; only when the customer explicitly requests updating to the latest, remove DRY_RUN=1 to execute the upgrade.
Do not copy another set of update decisions on your own. After obtaining authorization for the latest version,soia-env-ai-cli-upgrade is responsible for calling codex update, and Codex selects npm, Homebrew cask, or the official standalone installer based on the standalone CLI's installation context.
After updating, execute this skill's check script again, and use the returned absolute path of the standalone CLI to verify --version、--help and login status. Only when the same standalone CLI is updated and passes verification should the handling result be written as "updated."
When not logged in, execute the standalone CLI's login flow, and leave browser authorization to the customer; do not require the customer to paste an API key in the terminal.
Output the result using the fixed list below; dependency checks are used only internally, and under normal conditions do not add Node.js, npm, ChatGPT desktop, or other skill lines for the customer.

Customer status list (mandatory)

The customer-visible reply must begin with the following Markdown table, with fixed column names and order, outputting only one row Codex CLI：

Skill	Current status	Current version	Latest version	Running status	Installation method	Installation directory	Configuration file directory	Update time	Handling result
Codex CLI	<installed/not installed/blocked>	<version or not obtained>	<version or not obtained>	<normal/abnormal/unverified>	<npm global installation/Homebrew cask/official standalone installation/not obtained>	<directory or not obtained>	<directory or not obtained>		<No update needed/Update available, not executed/Waiting to confirm whether to update to the latest/Updated/Waiting for installation/Blocked: reason>

Output rules:

When the user only asks about Codex CLI, do not add Node.js, npm, ChatGPT desktop app, or other skill lines.
更新时间 Record the source, version, and time after harmless run verification is complete for the standalone CLI.
Do not display Node.js/npm checks when they are normal; only when they block Codex CLI installation, compress the reason into 处理结果。
soia-env-ai-cli-upgrade Returns ALREADY_LATEST and verification passes:处理结果 write "Already up to date".
soia-env-ai-cli-upgrade Returns UPDATED and recheck succeeds:处理结果 write "Updated".
dry-run finds a new version but there is no authorization for the latest version:处理结果 write "Update available, not executed"; for a vague update request write "Waiting to confirm whether to update to the latest".
An installation request only authorizes installing a missing CLI, not updating an existing CLI; when administrator privileges, switching sources, modifying PATH, or updating the desktop app requires customer action, clearly show the next step.
Not installed:运行状态 write "Not verified",处理结果 write "Waiting for installation" or the specific blocking reason; merely finding the internal binary inside ChatGPT.app still counts as the standalone CLI not being installed.
When the latest version cannot be obtained, write "Not obtained"; do not fill it in with old cache, memory, or guesses.
For installation directories and configuration directories, prefer to display ~ relative paths to avoid exposing usernames; for the configuration file directory use CODEX_HOME, and when unset use ~/.codex。
When multiple standalone Codex CLIs exist at the same time, prioritize reporting the standalone copy actually resolved by the login shell; the internal ChatGPT.app path additionally injected by the desktop Agent process must not override this judgment.
config_status=未创建 or login_status=未登录 , write the handling result as "Waiting for first login", and provide codex --login; do not display only ~/.codex this default path.
After the table, append a brief next step only when browser authorization, administrator confirmation, or an error explanation is needed; do not echo the internal dependency check log.

To ensure stable formatting, prefer to use scripts/render_status.py to generate the table.

Installed status and updates

First determine whether the standalone Codex CLI is already available and its actual source; when installed and verification passes, do not reinstall:

python3 scripts/inspect_installation.py --json
TOOLS=codex DRY_RUN=1 \
  bash ~/.agents/skills/soia-env-ai-cli-upgrade/scripts/upgrade-ai-clis.sh

ChatGPT.app: it is a desktop app, and its version and update channel are separate from the standalone CLI; its internal codex does not enter this skill's CLI status line.
npm global installation: the installation directory shows the global node_modules/@openai/codex; upgrades are left to soia-env-ai-cli-upgrade。
Homebrew cask or official standalone installation: show the real directory of the standalone CLI; upgrades are likewise left to soia-env-ai-cli-upgrade。
Installed and login status normal:当前状态 always write "Installed"; update actions are only written to 处理结果。
When there is no explicit customer instruction to "update to the latest", stop at dry-run and version reporting, and do not execute the upgrade command.
After updating, use the cli_path returned by the check script to execute --version、--help and login status; do not use an unqualified path for codex to reintroduce App/CLI confusion.

Before updating, record the old version, installation source, and command path. If the update fails, keep the existing usable version and error evidence, and do not automatically uninstall, downgrade, or clean up the configuration.

Intermediate states of installation and update

When actually performing an installation or obtaining the latest authorized update, generate a random run_id, and run it immediately as each stage occurs scripts/record_install_progress.py: record before performing the check checking, record after forming the plan planning, record when additional permissions are needed or the source is changed waiting_confirmation, record before invoking the installer/updater installing/updating, then record verifying and the final state. Do not write the entire history retroactively after finishing; timestamps are generated by the recorder. Read-only checks do not run the recorder.

python3 scripts/record_install_progress.py --run-id <run-id> --action <install|update> --stage checking --status in_progress --result-code checking_started
python3 scripts/record_install_progress.py --run-id <run-id> --action update --stage updating --status in_progress --result-code update_started --customer-requested-latest
python3 scripts/record_install_progress.py --run-id <run-id> --action update --stage verifying --status in_progress --result-code verification_started --customer-requested-latest
python3 scripts/record_install_progress.py --run-id <run-id> --action update --stage completed --status completed --result-code operation_completed --customer-requested-latest

Also keep updating continuously during the conversation; do not output only at the end:

Stage	Current status	Update time	Result
<check/plan/awaiting confirmation/install or update/verify/complete or failed>	<in progress/waiting/completed/failed/blocked>		<redacted result>

Any failure or cancellation immediately appends failed or blocked final state.--customer-requested-latest may only be passed in when the customer's own words explicitly request the latest version; the recorder rejects update execution stages that lack this declaration. The record does not store complete commands, tokens, accounts, private absolute paths, or URLs with query parameters, nor does it output the absolute path of the record file to the customer.

Permissions and rollback

npm global installs or CLI self-updates may write to the user's global directory; prefer user-level configuration and do not use sudo by default.
Do not overwrite the project's package.json, lockfile, or Node version management configuration.
Record the old version before upgrading; on failure, retain error evidence and do not automatically uninstall or downgrade.

Private information and intermediate data

Codex login credentials are managed by the official codex login/browser authorization flow and the system credential store; SOIA configuration only stores non-secret preferences and paths.
If installation or update receipts need to be traceable, only save the redacted source, version, result, and time in the user state directory; read-only checks do not write to disk by default.
Version metadata may be placed in cache; the installer and extracted contents go in a system temporary directory unique to each run and are cleaned up after success or failure.
Do not read or copy credential contents, and do not record authorization codes, tokens, accounts, sessions, or the customer's private absolute paths.

Logs and completion receipts

| 技能 | 当前状态 | 当前版本 | 最新版本 | 运行状态 | 安装方式 | 安装目录 | 配置文件目录 | 更新时间 | 处理结果 |
|---|---|---|---|---|---|---|---|---|---|
| Codex CLI | <状态> | <当前版本> | <最新版本> | <运行状态> | <安装方式> | <安装目录> | <配置文件目录> | <RFC3339-with-timezone> | <处理结果> |

Forward testing

Use a fake command runner to cover successful installation, missing standalone CLI, only the internal binary inside ChatGPT.app existing, npm global installation, and a newer version existing; verify source identification and scripts/render_status.py 's fixed ten columns. Upgrade behavior is covered by soia-env-ai-cli-upgrade 's own tests; this skill only verifies delegation, standalone CLI re-checking, and customer status mapping.

WorkBuddy 's loading unit is role-based experts rather than plugins,npx skills add -a '*' cannot cover it, and it needs to be installed separately, see docs/install/workbuddy.md。