# 🟢 Codex CLI — Cheat Sheet

> **What it is:** OpenAI's **Codex CLI** — an open-source terminal coding agent that
> edits files and runs commands inside a built-in sandbox, interactively or as a
> scriptable one-shot (`codex exec`).
> **Best for:** Fast local edits, and **automation** — `codex exec` slots cleanly into
> CI / Gitea Actions and one-shot scripts.
> **Per-repo rules:** reads `AGENTS.md` (merged with `~/.codex/AGENTS.md` and any
> project-local `AGENTS.md`).
> **In this repo:** delegation examples live under
> [`docs/ecosystem/delegation/codex/`](../../docs/ecosystem/delegation/codex/) and
> [`docs/CODEX_RESUME_PROMPT.md`](../../docs/CODEX_RESUME_PROMPT.md).

> ⚠️ **Flags/modes drift between versions.** Confirm with `codex --help`.
>
> **Official docs:** <https://developers.openai.com/codex/cli> · source: <https://github.com/openai/codex>

---

## Install & auth

```bash
npm install -g @openai/codex     # or: brew install codex
codex --version
codex login                      # ChatGPT sign-in, or set OPENAI_API_KEY
```

- Config & state live under `~/.codex/` (notably `~/.codex/config.toml`).

## Launching

```bash
codex                            # interactive TUI in the current dir
codex "add a vitest for src/lib/utils.ts"   # seed the first instruction
codex exec "run the test suite and fix failures"   # non-interactive one-shot (scripts/CI)
codex resume                     # resume a previous session
```

## Approval + sandbox modes

Codex couples **what it can touch** (sandbox) with **when it asks** (approvals).

| Flag                                                                      | Meaning                                                            |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `--sandbox read-only`                                                     | Can read; no writes, no commands                                   |
| `--sandbox workspace-write`                                               | Can edit the working dir + run commands in it (default-ish)        |
| `--sandbox danger-full-access`                                            | No sandbox restrictions                                            |
| `--ask-for-approval untrusted` \| `on-failure` \| `on-request` \| `never` | When to prompt you                                                 |
| `--full-auto`                                                             | Convenience: low-friction auto (workspace-write + minimal prompts) |
| `--dangerously-bypass-approvals-and-sandbox`                              | **No approvals, no sandbox** (CI/throwaway only)                   |

```bash
codex --full-auto                                   # everyday autonomy, still sandboxed
codex --sandbox workspace-write --ask-for-approval on-failure
codex exec --dangerously-bypass-approvals-and-sandbox "..."   # CI only, isolated runner
```

> 🧠 The sandbox is **built in** (unlike Devin's optional `--sandbox`). For ByteLyst,
> `workspace-write` is fine for single-package work, but cross-package `workspace:*`
> builds and the corp proxy / Gitea tunnel may need broader access — prefer running from
> the monorepo root and, if installs fail, loosen the sandbox rather than fighting it.

## Config (`~/.codex/config.toml`)

```toml
model = "..."                 # default model
approval_policy = "on-failure"
sandbox_mode = "workspace-write"
# [mcp_servers.*]            # wire external tools via MCP
```

Project-level `AGENTS.md` is layered on top of `~/.codex/AGENTS.md`.

## `codex exec` for automation (the high-value mode)

```bash
# One-shot, non-interactive — perfect for Gitea Actions / scripts:
codex exec "typecheck the repo and fix any TS errors" \
  --sandbox workspace-write --ask-for-approval never
```

- Deterministic, no TUI; exits with a status you can gate CI on.
- Pair with a tight prompt + explicit verify commands (see below).

## ByteLyst workflow

Lead with the shared guardrails (Codex reads `AGENTS.md`, but restate scope):

```text
Follow AGENTS.md + AI.dev/SKILLS/agent-behavior-guidelines.md.
Scope: <paths> only. Tests are sacred. No console.log. productId on Cosmos docs.
Verify: pnpm --filter <pkg> typecheck && ... test && ... build  (next build --webpack).
pnpm workspace; @bytelyst/* via workspace:*. Conventional commits, one per change.
Only mark done after verify passes; never fabricate results.
```

- Start in `read-only` for a plan, then switch to `workspace-write` to execute.
- Reserve `--dangerously-bypass-approvals-and-sandbox` for the isolated CI runner.

## Troubleshooting

| Symptom                               | Fix                                                                             |
| ------------------------------------- | ------------------------------------------------------------------------------- |
| "permission denied" writing files     | Sandbox is `read-only`; use `--sandbox workspace-write`                         |
| Can't build `@bytelyst/*` deps        | Sandbox can't see sibling `packages/*` — run from monorepo root, loosen sandbox |
| Network/registry errors               | Corp proxy must be active; workspace deps avoid the registry                    |
| `next build` fails (Turbopack)        | Use `next build --webpack`                                                      |
| Non-interactive run hangs on a prompt | Add `--ask-for-approval never` to `codex exec`                                  |

## Quick-reference card

```text
codex                              # interactive
codex "..."                        # seed an instruction
codex exec "..."                   # one-shot (CI/scripts)
codex resume                       # resume session
--sandbox read-only|workspace-write|danger-full-access
--ask-for-approval untrusted|on-failure|on-request|never
--full-auto                        # convenient autonomy (still sandboxed)
~/.codex/config.toml               # defaults: model, approval_policy, sandbox_mode
```

---

**Related:** [`devin-cli.md`](./devin-cli.md) · [`claude-code-cli.md`](./claude-code-cli.md) ·
[`../PROMPTS/`](../PROMPTS/) · [`../SKILLS/agent-behavior-guidelines.md`](../SKILLS/agent-behavior-guidelines.md)

_Last updated: 2026-05-28 · verify flags against your installed version (`codex --help`)._