152 lines
3.7 KiB
Markdown
152 lines
3.7 KiB
Markdown
# Codex CLI Guide
|
|
|
|
Codex CLI is OpenAI's lightweight local coding agent. It runs in your terminal, reads your codebase, edits files, and executes commands. Part of ChatGPT Plus/Pro/Business plans or usable with an API key.
|
|
|
|
**Official docs:** https://developers.openai.com/codex
|
|
**GitHub:** https://github.com/openai/codex
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
# macOS / Linux (recommended)
|
|
curl -fsSL https://chatgpt.com/codex/install.sh | sh
|
|
|
|
# Homebrew
|
|
brew install --cask codex
|
|
|
|
# npm (global)
|
|
npm install -g @openai/codex
|
|
|
|
# Windows PowerShell
|
|
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
|
|
```
|
|
|
|
---
|
|
|
|
## Authentication
|
|
|
|
```bash
|
|
codex # On first run, select "Sign in with ChatGPT"
|
|
```
|
|
|
|
**With API key instead:**
|
|
```bash
|
|
export OPENAI_API_KEY=sk-...
|
|
codex
|
|
```
|
|
|
|
For full auth options: https://developers.openai.com/codex/auth
|
|
|
|
---
|
|
|
|
## Basic Usage
|
|
|
|
```bash
|
|
# Start interactive session in current directory
|
|
codex
|
|
|
|
# One-shot task (non-interactive)
|
|
codex "add input validation to the login form"
|
|
|
|
# Quiet mode (minimal output)
|
|
codex -q "fix the TypeScript errors"
|
|
|
|
# Full auto mode (no confirmations — use carefully)
|
|
codex --approval-mode full-auto "refactor the API layer"
|
|
```
|
|
|
|
---
|
|
|
|
## Approval Modes
|
|
|
|
| Mode | Behavior |
|
|
|------|----------|
|
|
| `suggest` (default) | Shows proposed changes, waits for approval |
|
|
| `auto-edit` | Edits files automatically, asks before shell commands |
|
|
| `full-auto` | Runs everything without asking (use in sandboxed environments) |
|
|
|
|
```bash
|
|
codex --approval-mode auto-edit "clean up unused imports"
|
|
codex --approval-mode full-auto "run tests and fix failures"
|
|
```
|
|
|
|
---
|
|
|
|
## Key Flags
|
|
|
|
| Flag | Description |
|
|
|------|-------------|
|
|
| `--model <model>` | Specify model (`o4-mini`, `o3`, etc.) |
|
|
| `--approval-mode <mode>` | Set approval level |
|
|
| `-q` / `--quiet` | Minimal output |
|
|
| `--no-project-doc` | Ignore `AGENTS.md` / `CODEX.md` |
|
|
| `--project-doc <file>` | Use custom instructions file |
|
|
| `--full-stdout` | Show all shell output (not truncated) |
|
|
|
|
---
|
|
|
|
## AGENTS.md / CODEX.md (Project Instructions)
|
|
|
|
Codex automatically reads `AGENTS.md` from the project root (and parent directories). Put project-specific instructions there:
|
|
|
|
```markdown
|
|
# Project Instructions
|
|
- Use TypeScript strict mode
|
|
- Run `npm test` to verify changes
|
|
- Never modify files in /dist directly
|
|
```
|
|
|
|
In this environment, `AGENTS.md` is already used by Silma's workspace. For a client project, create one in the repo root.
|
|
|
|
---
|
|
|
|
## Using with Local LLMs
|
|
|
|
Codex CLI supports OpenAI-compatible endpoints:
|
|
|
|
```bash
|
|
# Point at local llama.cpp (Gemma models on Tabitha)
|
|
OPENAI_BASE_URL=http://localhost:8080/v1 \
|
|
OPENAI_API_KEY=local \
|
|
codex --model gemma-4-e4b "explain this codebase"
|
|
```
|
|
|
|
See `tools/local-llm.llm.md` for available local models and endpoints.
|
|
|
|
---
|
|
|
|
## Working with This Environment
|
|
|
|
```bash
|
|
# Clone from Gitea first, then run codex in the repo
|
|
git clone http://100.79.253.19:3000/jacob-mathison/aarete-doczyai-app.git
|
|
cd aarete-doczyai-app
|
|
codex
|
|
|
|
# Load credentials before running if the task touches AWS/GitHub
|
|
source /Users/Tabitha/.openclaw/workspace/credentials/secrets.env
|
|
codex "deploy the latest build to Amplify"
|
|
```
|
|
|
|
---
|
|
|
|
## IDE Integration
|
|
|
|
Codex also works as a VS Code / Cursor / Windsurf extension:
|
|
|
|
```
|
|
VS Code: https://marketplace.visualstudio.com/items?itemName=OpenAI.codex
|
|
Cursor: Install from Cursor extensions panel (search "Codex")
|
|
```
|
|
|
|
---
|
|
|
|
## Tips
|
|
|
|
- Start with `suggest` mode to review changes before they land
|
|
- Use `full-auto` only in throwaway branches or sandboxed environments
|
|
- For long-running tasks, use the Codex web app at https://chatgpt.com/codex (cloud-based, parallel agents)
|
|
- Codex reads `AGENTS.md` — keep it concise and action-oriented
|