HumanLayer Docs

Codex CLI Setup ​

HumanLayer can run sessions with Codex as the provider after the CLI is authenticated with OpenAI Codex.

Install the CLI ​

bash
npm install -g @humanlayer/cli@latest
humanlayer --help

Authenticate Codex ​

Run the Codex auth flow from the HumanLayer CLI.

bash
humanlayer agents auth codex

The command opens the browser-based authorization flow when available and may fall back to a device-code flow depending on the environment.

Select Codex for sessions ​

When launching a HumanLayer session, choose codex as the provider. Codex supports reasoning-effort choices of low, medium, high, and xhigh.

The exact session launch command can vary by CLI release. Check your installed CLI before publishing scripts or runbooks.

bash
humanlayer --help
humanlayer agents --help

Troubleshooting ​

  • If authentication fails in a headless shell, rerun the command in a terminal that can complete the device-code instructions.
  • If Codex is unavailable as a provider, update the CLI with npm install -g @humanlayer/cli@latest.
  • If a session starts with the wrong provider, confirm the provider selection before launch and verify the CLI version in use.