⌨️ Terminal and Graphical Interface

🟢 What It Is

Before using Codex, you need Node.js v18 or later (which includes npm) and Git. Older Node versions cause silent errors during Codex installation.

💡 Why learn

npm is the package manager that installs Codex globally. Without Node.js v18+, even the installation command fails with confusing messages.

🔑 Installation by System

# Instalar Git
winget install --id Git.Git -e --source winget

# Instalar Node.js (baixe de nodejs.org → LTS)
# Verificar depois:
node -v    # deve ser v18+
npm -v     # deve ser 9+

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs git
node -v && npm -v

brew install node git
node -v && npm -v

🟢 What It Is

The Codex CLI is distributed as an npm package: @openai/codex. The flag -g installs globally — available in any directory.

💡 Why learn

Global vs. local installation makes a difference: global lets you call codex from any folder. Local works only inside the project with npx.

🔑 Installation Commands

npm install -g @openai/codex
# Verificar instalação:
codex --version

npm update -g @openai/codex

# Se erro EACCES, configure npm prefix:
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

⚠️ Common errors on the first run—and how to fix them

codex : O arquivo codex.ps1 não pode ser carregado porque a
execução de scripts foi desabilitada neste sistema.
    + FullyQualifiedErrorId : UnauthorizedAccess

# In PowerShell, run this once and confirm with "S":
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

# Test again:
codex --version

# Rode o Codex pelo Prompt de Comando (cmd), que
# não passa pela política de execução do PowerShell:
codex --version

# Conferir a política atual, se quiser:
Get-ExecutionPolicy -List

git add skills/minha-skill
git commit -m "Add skill"
git push -u origin main   # ...e nada aparece no GitHub

git status     # 1. os arquivos estão "staged" (verdes)?
git remote -v  # 2. existe 'origin' e a URL está certa?
git branch     # 3. seu branch é 'main' ou 'master'?

# Se ainda não houver remote:
git remote add origin https://github.com/usuario/repo.git

git add .
git commit -m "Add automatic climate dashboard update skill"

# Se o push for rejeitado (remoto à frente):
git pull --rebase origin main
git push -u origin main

# ~/.codex/config.toml — fixa o padrão e evita repetir flags:
approval_policy = "on-request"      # untrusted | on-failure | on-request | never
sandbox_mode    = "workspace-write" # read-only | workspace-write | danger-full-access

🟢 What It Is

Login uses device auth: the terminal displays a code + link. You open the link in the browser, enter the code, and you're authenticated. No exposing API keys in the terminal.

💡 Why learn

Device auth is secure even in shared environments. The code expires in 15 minutes — open the link immediately.

🔑 Step by Step

codex login --device-auth

# Saída esperada:
# Abra: https://auth.openai.com/codex/device
# Código: XXXX-XXXX (expira em 15 min)
# ⚠️ NUNCA compartilhe este código
# ✓ Successfully logged in

export OPENAI_API_KEY="sk-..."
codex auth login

🟢 What It Is

After installing and logging in, Codex works in the terminal in two modes: interactive (codex) and directly (codex "prompt").

💡 Why learn

Interactive mode is ideal for long, iterative tasks. Direct mode is great for scripts and CI/CD automation.

🔑 Quick Reference

codex                      # modo interativo
codex "crie testes"        # prompt direto
codex chat                 # modo conversa
codex --full-auto "..."    # sem confirmação
codex --model gpt-5 "..."  # modelo específico
codex generate --prompt "..."|# gerar código

🟢 What It Is

The Codex App for Windows is the full graphical interface: skills with UI, external plugins, inline previews, multiple parallel threads, an Automations tab, and an integrated browser.

💡 Why learn

The graphical interface is superior to the CLI for tasks involving multiple simultaneous threads, scheduled automations, and browser use for computer use.

🔑 Key Features

🟢 What It Is

Codex works in Docker via device auth. The file ~/.codex/config.toml persists global settings such as approval policy and sandbox mode.

💡 Why learn

Containers are ideal for using --dangerously-bypass-approvals safely — the host system stays protected. Config.toml avoids repeating flags in every session.

🔑 Config.toml and Docker

# Configuração equilibrada (recomendada)
approval_policy = "never"
sandbox_mode = "workspace-write"
model = "gpt-5"

docker run --rm -it \
  -v "$PWD:/app" -w /app \
  node:20 bash
# dentro do container:
npm install -g @openai/codex
codex login --device-auth