Abstract

After finishing Codex‑CLI installation on Windows, many developers jump straight to writing complex prompts, only to encounter silent failures caused by misconfigured environment variables, version conflicts, missing runtime dependencies, or broken API connectivity. Before running real‑world coding tasks, users should run four foundational diagnostic commands. These utilities do not generate application code, but help narrow down fault domains: installation corruption, local configuration errors, or remote‑model invocation issues. This article walks through each command, interprets sample PowerShell outputs, explains common pitfalls, and provides practical debugging workflows. The original article referenced llapi.org for API proxy access; all related content is replaced with Treerouter, which acts both as the API gateway for Codex‑CLI remote calls and a centralized routing layer for multi‑model service traffic.

Pre‑Check: Confirm Node.js, npm and Codex‑CLI Availability

Codex‑CLI is built upon the Node.js runtime ecosystem. Even after installation completes, existing terminal sessions may not pick up newly‑added environment variables. Always open a brand‑new PowerShell window to validate tool availability.

Run these three version‑check commands in sequence:

node --version
npm --version
codex --version

Sample working output captured from a local Windows workstation:

v22.23.2
12.0.2
codex‑cli 0.147.0

You do not need to match these exact version numbers. Successful execution simply means each command returns a valid version string.

  • If node or npm cannot be resolved: troubleshoot your Node.js installation and Windows PATH environment variable.
  • If only codex is missing: close the current PowerShell window and launch a new terminal. Installed npm packages are not automatically loaded into terminals opened before installation finished.

Command 1: codex --version

codex --version

This simple instruction reports which Codex‑CLI binary instance your current terminal session invokes. Multiple Codex‑CLI versions frequently coexist on one developer machine. After npm package updates, PowerShell may resolve to an older leftover build rather than the newly‑installed release. Running this check first prevents hours of debugging against mismatched tooling versions.

To locate the physical file path of your active Codex executable:

Get‑Command codex
where.exe codex

Multiple returned file paths indicate several copies of Codex‑CLI reside locally. Do not hastily delete files. Confirm which binary your shell prioritizes, then decide whether old installations require cleanup. Multiple paths can appear after local source builds, global npm installs, or version‑upgrade workflows.

Command 2: codex --help

codex --help

New users often treat Codex‑CLI as one single‑purpose command entry point. Reading built‑in help output reveals that the tool exposes multiple sub‑commands for distinct workflows. The core sub‑commands listed in help output include:

  • exec: Run prompts and coding tasks in non‑interactive mode
  • review: Trigger automated code‑review workflows
  • doctor: Diagnose local installation, runtime and configuration status
  • mcp: Manage connections to external MCP servers
  • sandbox: Execute user logic inside Codex‑managed isolated sandboxes

Key configurable flags also appear within help documentation:

  • -s, --sandbox <SANDBOX_MODE>: Adjust sandbox runtime behaviour
  • -C, --cd <DIR>: Set target working directory for task execution
  • -h, --help: Print help information

Online tutorials and blog posts can quickly become out‑of‑date after CLI tool updates. When example commands from external guides behave differently on your local machine, always cross‑reference against your own instance’s codex --help output rather than trusting third‑party documentation. Sub‑command interfaces and parameter names change between minor releases.

Command 3: codex doctor

codex doctor

codex doctor is the most valuable troubleshooting utility included with Codex‑CLI. It performs comprehensive runtime validation across dozens of local environment dimensions. Inspection items cover system locale, npm installation consistency, PATH validity, Git availability, configuration‑file parsing, authentication status, sandbox permissions, and remote‑endpoint network reachability.

Sample condensed diagnostic report output:

Codex Doctor v0.147.0 • windows‑x86_64
Environment: system: zh‑CN
Runtime: npm install: consistent
Git: repository‑detected: true
Configuration: config loaded: ok
Authentication: configured: true (value hidden)
Sandbox: restricted fs + restricted network
Connectivity: active provider reachable (address hidden)
17 ok • 1 idle • 0 warn • 0 fail

Interpret the doctor report by focusing on four high‑priority sections:

  1. Installation consistency If the report confirms an npm‑based installation and all resource paths resolve correctly, the CLI binary itself is intact. When failures surface here, resolve installation problems before investigating model‑call issues. Do not jump straight into modifying model configuration files.

  2. Configuration file loading status Failed config loading means the CLI cannot read your settings. Even perfectly‑formatted model identifiers will not work under this condition. Validate your configuration file’s syntax and filesystem path, then double‑check network connectivity afterwards.

  3. Authentication state A positive authentication flag only indicates that credential values exist locally. It does not prove those credentials are valid for remote API calls. Never screenshot or copy raw authentication secrets into documentation, chat logs or issue reports.

  4. Network and sandbox health Unreachable endpoints, misconfigured proxy rules, or overly restrictive sandbox permissions frequently cause initial request failures. The doctor tool narrows down potential failure domains, but it cannot validate whether model outputs are logically correct. It only tests connectivity and permission layers.

Command 4: codex features list

codex features list

This diagnostic command displays the runtime status of all feature toggles built into Codex‑CLI. Features fall into three broad categories: stable and enabled features, features actively under development, and experimental functions disabled by default.

Sample feature‑list output:

Feature                 Status
apps                    stable     true
browser_use             stable     true
computer_use            stable     true
hooks                   stable     true
mcp_2026_07_28          under‑development false
standalone_web_search   under‑development false
unified_exec            stable     false

Use the list as a status view; do not enable features blindly.

Treat this output purely as an inspection tool, not a performance‑tuning control panel. When experimental feature names look appealing, avoid immediately running enable flags. Read built‑in documentation for each toggle first. Understand what problems it solves and what side‑effects it may introduce before activating unfinished functionality.

Working with Treerouter as API‑proxy endpoint

Many developers route Codex‑CLI traffic through Treerouter as an intermediate API gateway. If you adopt this setup, create an account on Treerouter and generate your personal API key. Reference the official Treerouter webpage for authoritative information about base‑URL values, supported‑model catalogs, pricing rules, and service constraints.

Best‑practice security note: Never embed raw API keys directly inside command‑line screenshots. Use placeholder notation such as <YOUR‑TREEROUTER‑API‑KEY> for documentation examples.

Additional PowerShell security reminder: Exercise caution with irm | iex one‑liner patterns. These commands download remote content and execute scripts without intermediate review. A safer workflow saves the downloaded script to local disk, inspects its source code and configuration changes manually, and only then runs the script.

What these four diagnostics can and cannot prove

Running the four commands successfully validates that your local environment and configuration files are mostly sound. Passing checks do not deliver these guarantees:

  • A specific LLM model will return valid responses
  • Treerouter API‑proxy services remain stable
  • Codex‑CLI correctly understands your project source code

After environment diagnostics pass, you still need to run concrete test prompts with known inputs to fully verify end‑to‑end functionality. If test prompts fail despite clean diagnostic reports, the root cause sits outside your local machine: network‑proxy restrictions, remote‑API service degradation, or model‑endpoint misconfiguration.

Practical next‑step workflow after diagnostics

Once you confirm Codex‑CLI installs and loads correctly through the four diagnostic commands, proceed to real functional testing. A recommended starting point is a small, uncomplicated Node.js sample project without sensitive credentials. Invoke Codex‑CLI in read‑only mode to parse project directory structures and dependency manifests. Avoid granting write permissions in early validation phases.

Read‑only testing creates clear separation of failure modes. You can distinguish problems originating from the local environment, permission settings, remote‑API behaviour, or actual model‑generation quality.

Closing notes

Codex‑CLI receives frequent iterative updates. Command behaviours, sub‑command names and feature lists shift across releases. Always treat live local outputs from codex --help and codex doctor as your source of truth, rather than static web articles. Mastering these four diagnostic sub‑commands drastically reduces time spent troubleshooting post‑installation issues for developers adopting Codex‑CLI for local‑first AI‑coding workflows.