Add a cli command like `codex models` to print available models

Can you provide more details about the problem you want to solve? What is the use case?

There is already a way to do this through the app server API. It requires a bit more scripting, but codex can write that script for you.

Expose available models through a supported CLI command (codex models / codex list-models)

Summary

Please add a supported, non-interactive CLI command that prints the effective model list Codex would use for the current config, auth mode, provider, and profile.

Suggested shape:

codex models
codex models --json
codex models --profile <profile>
codex models --provider <provider-id>
codex models --refresh

This should be a first-class CLI surface over the same model-discovery path already used by the app server, TUI, and desktop surfaces, not a separate hard-coded list.

Why this is needed

Codex already accepts model overrides through --model, but the CLI does not provide a supported way to discover which values are valid for the user's current account, provider, profile, and local catalog. In codex-cli 0.137.0, both codex help models and codex help list-models return unrecognized subcommand.

There is an existing request for this exact feature in #23279, and an earlier request in #8871. The maintainer response in both threads points users toward the app-server model/list API, but that leaves a gap for CLI users and third-party integrations:

• The app-server API is not a documented CLI contract.
• It requires scripting and lifecycle management just to answer a basic CLI question.
• It is awkward for editor integrations, shell scripts, CI checks, and host applications that already invoke codex exec.
• It pushes every integration to rediscover the same private protocol details.

This is especially painful because model availability in Codex is no longer a static OpenAI-only list. It depends on provider, auth mode, account entitlement, rollout state, model catalog source, local config, cached remote data, and sometimes the specific app surface.

Evidence from related issues and PRs

There is already user demand for a CLI-visible model list:

• #23279 asks directly for codex models.
• #8871 asks for a way for a Neovim plugin to list available models before calling codex exec --model <model>, without asking for the user's API key.
• #8392 asks Codex to list valid models when an invalid --model value is provided.
• #8319 and #6032 ask for provider-specific model lists for local/custom providers.

There have also been implementation attempts or internal building blocks:

• #1291 proposed a list-models subcommand for the Rust CLI.
• #9839 proposed a --list-models flag with available models and reasoning efforts.
• #8198 made app_server.list_models non-blocking.
• #18950 moved model discovery behind provider-owned implementations.
• #22547 changed merging behavior to prefer backend-fetched model lists for users whose allowed models are more limited than the bundled catalog.
• #21909 added more catalog-driven metadata such as default service tiers.
• #26080, #26141, #27109, and #27208 show active work around model-catalog attribution, diagnostics, refreshes, and backend request state.

That history suggests the hard part, model discovery itself, already exists in Codex. The missing piece is a stable CLI interface for the same effective model list.

Recent bugs also show why this is not only a convenience feature:

• #26892 and #27021 show cases where gpt-5.5 was locally listed or selectable but actual Codex requests failed with 404 Model not found.
• #18565 reports the app showing models that were not actually usable with the current ChatGPT account.
• #19404 and #19694 report model picker mismatches where the backend/app-server returned models that the desktop UI did not show.
• #26915 and #27216 report models disappearing or being empty after app updates.
• #23119 reports repeated codex_models_manager refresh errors on stderr during codex exec, creating noise for host integrations.
• #22205 and #24286 show custom-provider model refresh failures where the command itself may succeed or fail for reasons separate from the actual target model.
• #24659 shows --oss / custom model metadata can be present in cache but not loaded at turn setup.
• #15138 shows custom-provider model selectors behaving differently across app surfaces even when the CLI can use the provider.

A CLI command would give users, integration authors, and maintainers a shared diagnostic question:

What models does Codex believe are available for this exact config right now, and where did that answer come from?

Proposed behavior

codex models should print the effective model list for the same config resolution that codex exec would use.

For human output, it could include:

• model slug
• display name, if available
• provider
• default marker
• supported reasoning efforts / service tier metadata, if available
• source, for example bundled catalog, backend, cache, model_catalog_json, or provider endpoint
• status, for example available, hidden, unsupported for current auth, stale cache, or refresh failed

For automation, codex models --json should expose the same data in a stable schema.

Example:

MODEL                PROVIDER  DEFAULT  SOURCE    STATUS
gpt-5.5              openai    yes      backend   available
gpt-5.4              openai             backend   available
gpt-5.4-mini         openai             cache     available

Example JSON shape:

{
  "provider": "openai",
  "profile": null,
  "default_model": "gpt-5.5",
  "source": "backend",
  "cache": {
    "used": true,
    "stale": false,
    "last_refresh_error": null
  },
  "models": [
    {
      "slug": "gpt-5.5",
      "display_name": "GPT-5.5",
      "provider": "openai",
      "is_default": true,
      "status": "available",
      "reasoning_efforts": ["low", "medium", "high"]
    }
  ]
}

The exact schema can be adjusted to match existing app-server model/list types, but the important part is that it is documented and stable enough for tools to consume.

Acceptance criteria

• codex models works without launching the TUI or starting a prompt.
• codex models --json provides machine-readable output suitable for editor integrations and CI/host tooling.
• The command uses the same provider/profile/config/auth resolution as codex exec.
• It supports ChatGPT auth, API-key auth, configured custom providers, and local/OSS provider modes as much as the underlying model manager supports them.
• It reuses existing model-discovery code paths instead of maintaining a separate model list.
• It surfaces refresh/cache errors in a structured way instead of requiring users to infer state from stderr logs.
• It is documented in CLI help and docs.
• Tests cover default OpenAI behavior, provider/profile overrides, cached catalog behavior, custom/local catalog behavior, and JSON output stability.

Why the app-server workaround is not enough

The app-server model/list API is useful, but it is not a replacement for a CLI command. A user who can run:

codex exec --model <model> "..."

should also be able to run:

codex models

to discover valid <model> values under the same resolved config. This is the same level of discoverability users expect from command-line tools with named runtime targets, and it would reduce repeated issues caused by model picker mismatches, stale local catalogs, custom-provider confusion, and backend availability drift.