Terms in this guide: Acceptance criteria · Verification
Check the workspace, sign-in, instructions, and validation evidence in a useful order.
Start with the exact symptom
Capture the message you see and the action that produced it. “It does not work” could mean the CLI is missing, sign-in failed, the wrong project is open, or a repository command failed. Diagnose one layer at a time instead of changing several settings together.
Record your operating system, the client you are using, and whether the issue affects a fresh session. Keep account tokens and private configuration out of shared screenshots.
Check the project before the prompt
Confirm that the working directory is the project you intended. Look for the files you referenced and the project’s own setup instructions. A convincing answer about the wrong checkout is still the wrong result.
Ask Codex to identify the files it is using as context. If they are unexpected, correct the workspace and begin with a narrow inspection request before asking for edits.
Separate installation from project validation
Follow the current official CLI installation and authentication instructions for your platform. Once the client starts, treat a failing repository command as a separate problem. Read the command output: a missing dependency, unsupported runtime, and failed assertion call for different fixes.
Use the existing project documentation to choose installation and validation commands. Do not repeatedly rerun a failing command without checking what changed between attempts.
Make instruction problems observable
Ask the session to summarize the relevant repository rules and point to their files. Compare the summary with the actual files. If you have just changed instruction files, start a fresh session and repeat the small check.
Use the AGENTS.md troubleshooting tutorial for instruction scope and conflicts. If the symptom persists, prepare a minimal reproduction with expected behavior, actual behavior, and sanitized output.
Primary source: Official CLI setup. Source checked September 10, 2026.
Progress stays in this browser. No account needed.
Updates and upgrade guidance
- Learning context added
Added prerequisites, a suggested practice estimate, expected output, and connected definitions. The article procedure was not independently re-evaluated in this change.
What to do: Use the opening checklist to prepare. No software update is required for this editorial change.
This log starts with the first recorded review; it is not a reconstruction of earlier revisions.