Skip to content

Codex CLI 0.48 & 0.49 Update Guide for Automation Teams

Codex CLI Complete Guide

What you will learn

Key changes in Codex CLI 0.48.0 and their operational impact
How to use --add-dir, MCP tool gating, and forced login settings
Why 0.49.0 exists and what to verify after upgrading

Codex CLI 0.48.0 delivers one of the biggest MCP (Model Context Protocol) upgrades to date. You can now whitelist extra working directories with --add-dir, toggle MCP tools per server, and enforce login methods or workspace IDs through managed configuration. Version 0.49.0 follows immediately after as a Homebrew validation build; it keeps all 0.48.0 functionality unchanged.

Target Audience

  • Engineering leads upgrading from 0.47.x and tracking workflow changes
  • Automation/SRE teams running MCP servers who need fine-grained tool controls and OAuth scopes
  • Enterprise administrators rolling out managed configs and enforcing SSO or workspace policies

Highlights from 0.48.0

  • --add-dir lets you explicitly allow additional directories outside the current working tree, essential for monorepos and generated docs.
  • Stdio MCP servers now use the official Rust MCP SDK client, gain cwd support, and can specify enabled_tools / disabled_tools for safer automation.
  • Streamable HTTP MCP servers may request OAuth scopes during codex mcp login, improving least-privilege rollouts.
  • Two new config keys—forced_login_method and forced_chatgpt_workspace_id—allow administrators to lock down authentication workflows.
  • Agent UX improvements: local tokenizer support, the plan tool enabled by default, richer approval events, and removal of the risky approve all command.

Deep dive on the new capabilities

--add-dir for additional working directories

  • Use --add-dir <PATH> to grant Codex controlled access to repositories or assets outside the main workspace.
  • This keeps audits simple: only the directories you whitelist can be touched during automation runs.
# Example: allow docs/ as a secondary workspace
codex --add-dir ../docs --full-auto "Run link checks inside docs/"

MCP stability and governance upgrades

  • Stdio servers migrate to the official Rust SDK client (rmcp), improving connection reliability and error handling. [PR #5423]
  • Each server can specify a cwd, so relative paths resolve reliably for bundled tools.
  • enabled_tools / disabled_tools fields let operators pause risky tools without deleting server definitions.
  • OAuth-backed MCP servers may request explicit scopes via codex mcp login, enforcing least privilege from the CLI.
  • Expired authentication now triggers a login prompt, and startup errors surface with actionable diagnostics. [PR #5300]

Enterprise enforcement controls

  • forced_login_method locks Codex CLI to the approved login channel (SSO, API key, etc.).
  • forced_chatgpt_workspace_id directs all sessions to a specific workspace, centralizing billing and audit trails.
  • Ship these values via Managed Configuration so every laptop receives a consistent policy.

Agent experience and TUI refinements

  • The plan tool is now enabled out of the box, making turn planning visible immediately. [PR #5384]
  • unified_exec adopts the production tokenizer to keep long commands within safe token limits. [PR #5514]
  • Clearing input with Ctrl+C stores the text in history, so pressing ↑ recovers it. [PR #5470]
  • Approval events include the current working directory, simplifying forensic reviews. [PR #5415]
  • The legacy approve all shortcut is removed to avoid unintentional blanket approvals. [PR #5503]

Upgrade path to 0.48.0

# npm / Bun (recommended)
npm install -g @openai/codex@0.48.0
codex --version

# Homebrew
brew upgrade openai/codex/codex
  1. Back up MCP server entries that will use enabled_tools / disabled_tools, then stage the desired allowlist.
  2. Prepare a directory inventory for any automation jobs that need --add-dir, and send it through your security review.
  3. Roll out forced_login_method / forced_chatgpt_workspace_id via managed configs and document the fallback path (e.g., break-glass accounts).

Post-upgrade validation checklist

  • Run codex mcp list to confirm every server reports the expected tool availability state.
  • Trigger codex mcp login on OAuth servers and verify the requested scopes match your compliance requirements.
  • In CI, double-check that the new plan tool prompts and tokenizer changes do not break scripted approvals.
  • Audit ~/.codex/sessions/ to ensure cwd values appear in session transcripts and align with your logging policy.

Understanding 0.49.0

According to the official release notes, version 0.49.0 introduces no functional changes—it simply validates the Homebrew upgrade workflow. Treat it as 0.48.0 with an updated Homebrew artifact.

# Homebrew smoke test
brew upgrade openai/codex/codex
codex --version  # => codex 0.49.0

Quick checks specific to 0.49.0

  • Confirm the Homebrew formula replaces the binary end to end
  • Update any policy files or managed configs that pin the allowed version list
  • If CI relies on brew upgrade, monitor cache invalidation and rollout timing

Upgrade to the 0.48/0.49 line to benefit from tighter MCP governance and enterprise controls, then brief your automation team on the new flags and config keys.