Authenticate Codex with ChatGPT sign-in or an API key

The agent is running inside budgetcli and the first thing it wants is for you to sign in. There are two ways to do it, and unlike a lot of “pick a login method” screens, this one isn’t cosmetic — the path you choose quietly decides what the agent can do and how it’ll behave when you later try to run it unattended. Ninety seconds of understanding here saves you a confusing afternoon in a much later chapter.

The two paths

Run the sign-in flow and Codex offers you a choice:

> codex login

• Sign in with ChatGPT. This is the default, browser-based path. It opens a browser, you authorize the session against your existing ChatGPT account, and you land back in the terminal logged in. Nothing to copy-paste, no key to manage. For interactive work at your own desk, this is the smoother door.

• An API key, via OPENAI_API_KEY. Here you authenticate with a key instead of a browser session — the path meant for programmatic and CI use, where there’s no human to click through a browser prompt:

  printenv OPENAI_API_KEY | codex login --with-api-key

Both are fully supported, and you can switch later. The current list of supported flows and their setup lives in the authentication docs — that’s the page to check if a sign-in misbehaves.

Why the choice isn’t cosmetic

Two consequences make this more than a login preference.

Your sign-in method gates which capabilities you get. The two paths don’t necessarily unlock the same tier of agent behind them — how much reasoning muscle is available to you can depend on how you authenticated, not just what you typed. You don’t need to act on this today; the budget date-bug is well within reach of either path. But file it away, because a later chapter is entirely about dialing the agent’s effort up for hard problems and down for boilerplate — and what that dial can reach is shaped by the door you came in through. (We’ll never put a name to a specific tier here — that detail churns; the durable fact is only that the door you choose has a ceiling attached to it.)

The browser path doesn’t survive automation. A ChatGPT browser sign-in is perfect for sitting at your terminal. It is exactly wrong for the moment — chapters from now — when you want budgetcli to generate a monthly report on a schedule with no human present. That unattended run needs the API-key path, because there’s no browser for it to open. You don’t have to set that up now. You just want to know, before you build habits, that the interactive door and the automation door are different doors.

For this chapter, sign in with ChatGPT and move on — it’s the least friction for the work in front of you. Just remember the API key exists for the day the agent needs to run without you watching.

You’re at a live agent now, authenticated and pointed at the repo. Before you hand it the date bug, spend one more minute understanding how a single turn works — because watching that shape once is what makes the actual fix unsurprising. Next: one turn of the loop.