Guia de Inicialização do Terminal CLI

📚 Navegação da Série: O artigo anterior 07 · Funcionalidades do Aplicativo Desktop apresentou a interface gráfica do assistente. Esta seção retorna ao terminal to detalhar a CLI oficial, abordando a estrutura sintática de comandos, flags de parametrização e o console TUI. No próximo artigo 09 · Extensões para IDE (VS Code e similares), discutiremos o acoplamento do Codex em editores de código.

Embora interfaces gráficas sejam recomendadas para simplificar o primeiro contato com novos utilitários, a CLI do Codex atua como uma ferramenta indispensável para fluxos avançados.

O aplicativo desktop destaca-se na auditoria visual e no gerenciamento concorrente de tarefas. Contudo, tarefas de integração contínua (CI), execuções em servidores remotos sem displays gráficos e automações locais via scripts exigem a flexibilidade da linha de comando.

A CLI do Codex inicializa uma interface interativa baseada em texto (TUI - Terminal User Interface) que preserva a organização de painéis, exibindo histórico de prompts, blocos de códigos formatados com realce de sintaxe e status de tokens em um console orientado ao teclado.

Mapearemos a sintaxe de comandos, flags de compilação, atalhos do teclado e rotinas de automação da CLI.

Ao terminar de ler este artigo, você terá:

• A anatomia sintática dos comandos da CLI (comandos, subcomandos e flags)
• O mapeamento das três seções da TUI: painel de histórico, prompt e linha de status
• A tabela de flags e parâmetros operacionais homologada pela documentação oficial
• Procedimentos de atalhos de controle de sessões e tarefas interativas
• A distinção operacional entre o modo TUI interativo e a execução automatizada (codex exec)

⚠️ Observação: Sintaxes de comandos e flags de sandbox baseiam-se na documentação oficial do Codex; identificadores de modelos de linguagem e planos tarifários mudam conforme as atualizações dos provedores.

---

01 Estrutura e Sintaxe de Comandos

Comandos complexos da CLI tornam-se simples quando analisados estruturalmente.

Qualquer chamada no terminal compõe-se de até quatro elementos ordenados: comando principal, subcomando, flags de parametrização e o prompt de instrução.

Analogia: pedidos customizados em cafeterias. Chamar o comando principal codex equivale a solicitar a bebida básica. Indicar subcomandos como exec ou resume seleciona a receita (como um espresso ou latte). Inserir flags de parametrização (flags precedidas por --) ajusta os ingredientes (leite vegetal, temperatura). Por fim, o prompt representa a instrução de destino entregue à IA.

Estrutura sintática da CLI:

codex   [subcomando]   [flags...]   ["prompt"]
  │         │              │            │
Principal  Ação         Opções       Instrução

Detalhamento dos componentes:

• Comando Principal codex: Binário carregado no path global do sistema. Inicializa o terminal interativo (TUI) por padrão.
• Subcomando: Altera o modo de execução. Exemplos: exec (execução direta e encerramento sem abrir interface gráfica de texto), resume (retoma sessões anteriores) ou login (credenciamento).
• Flags (Opções): Parâmetros precedidos por -- ou - que customizam o processamento. A maioria das flags aceita formatos estendidos ou abreviados (ex: --model ou -m).
• Prompt (Instrução): Texto entre aspas contendo as diretrizes do código a ser gerado ou analisado. Omissões forçam a abertura do console interativo.

Exemplos práticos de chamadas:

# Inicialização direta della interface interativa
codex

# Inicialização com prompt imediato
codex "Explique a arquitetura deste repositório"

# Definição manual de modelo e diretório ativo
codex --model gpt-5.5 --cd ~/my-project "Refatore o README.md"

⚠️ Observação: O identificador gpt-5.5 é ilustrativo. Consulte a lista de modelos de linguagem ativos no provedor executando /model no chat.

💡 Resumo em uma frase: A chamada compreende: comando, ação de subcomando, flags de sandbox/modelo e a instrução do prompt.

---

02 Estrutura da Interface Interativa TUI

Ao inicializar o Codex pelo comando sem parâmetros, o console é preenchido com a interface gráfica de terminal (TUI).

O leiaute de texto exibe três seções principais: o painel de diálogo, a linha do prompt e a barra de status de sistema.

Analogia: transmissões de vídeo ao vivo. O centro da tela exibe a demonstração do produto (painel de diálogo, onde a IA apresenta propostas de refatoração e exibe logs de diffs); o rodapé concentra os comentários dos usuários (linha do prompt para novas instruções); o canto inferior exibe informações de conexão e estatísticas (barra de status contendo o modelo ativo e consumo de tokens).

Detalhamento dos componentes da interface:

• Painel de Diálogo: Área de exibição de respostas. Apresenta o plano do agente, códigos gerados e diffs formatados com cores nativas do terminal para facilitar a revisão.
• Linha do Prompt: Entrada de texto. Recebe prompts de voz/texto, atalhos de arquivos e comandos de barra.
• Barra de Status (Rodapé): Indicadores técnicos contendo o consumo de tokens da thread, diretório ativo mapeado, status do Git e modelo ativo. A disposição das métricas é customizável via comando /statusline.

Inconsistências de renderização de vídeo causadas por buffers de consoles em sessões tmux ou SSH podem ser resolvidas pressionando Ctrl+L para forçar o redesenho da tela, sem perda do histórico de contexto.

Enquanto o atalho Ctrl+L limpa a visualização estática do console, o comando de barra /clear descarta o histórico de tokens da thread ativa e inicia novo contexto.

💡 Resumo em uma frase: A TUI é dividida em exibição de respostas, prompt de comandos e métricas de status. Use Ctrl+L para limpar o console mantendo a thread.

---

03 Tabela de Flags e Parâmetros Operacionais

As flags customizam o comportamento do binário. Mapeamos os parâmetros mais utilizados no desenvolvimento cotidiano com base na referência técnica oficial:

Flag da CLI (Completa / Curta)	Finalidade técnica	Exemplo de chamada
--model / -m	Altera o modelo de processamento para a chamada	codex -m gpt-5.5 "Refatore esta classe"
--sandbox / -s	Define a política de sandbox (read-only, workspace-write ou danger-full-access)	codex -s read-only "Analise possíveis brechas"
--ask-for-approval / -a	Define o nível de interrupções de confirmações (untrusted, on-request ou never)	codex -a on-request "Corrija as exceções"
--cd / -C	Inicializa o terminal apontando para um diretório específico	codex --cd ~/my-project "Liste a arquitetura"
--add-dir	Adiciona caminhos adicionais autorizados para escrita no sandbox	codex --cd src --add-dir ../lib
--image / -i	Anexa arquivos de imagens ou capturas de telas de erros no prompt	codex -i crash.png "Depure o erro de log"
--search	Ativa consultas em tempo real na Web	codex --search "Consulte a documentação atual"
--oss	Redireciona chamadas para modelos locais hospedados no Ollama	codex --oss "Gere um script bash simples"

Particularidades dos parâmetros:

A flag --cd permite inicializar sessões apontando para o diretório de destino diretamente, sem exigir comandos extras no console.

As flags --sandbox e --ask-for-approval gerenciam as barreiras lógicas de gravação física do sistema. O padrão de segurança indicado une a sandbox de escrita (workspace-write) com interrupções sob demanda (on-request). Os níveis avançados e arquivos de configurações globais são explicados no Artigo 15.

Por padrão, o Codex acessa consultas Web por bases locais de indexação para mitigar injeções de prompts indiretas. A flag --search força a consulta online direta nos navegadores.

Alerta de segurança:

⚠️ A flag --dangerously-bypass-approvals-and-sandbox (ou --yolo) desativa por completo o sandbox local e os alertas de confirmação de escrita. Evite utilizar este parâmetro em sua máquina principal; destine-o estritamente a ambientes virtuais isolados ou testes de pipelines de CI.

💡 Resumo em uma frase: Domine as flags operacionais como -m (modelo), -s/-a (permissões), --cd (diretório) e --search (consultas Web). Mantenha as restrições do sandbox ativas.

---

04 Comandos de Barra

Comandos digitados no prompt iniciados pelo caractere / alteram configurações de processamento no meio da sessão ativa:

Comando de barra	Finalidade técnica	Aplicação prática
/model	Altera o modelo de linguagem e dedução de raciocínio	Troca rápida de IA na thread ativa
/permissions	Altera o modo do sandbox (Auto / Read Only / Full Access)	Ajuste de restrições de escrita de arquivos
/status	Exibe as estatísticas da sessão local	Checagem de tokens, permissões e caminhos de sandbox
/diff	Exibe o histórico de diffs pendentes	Revisão de modificações de código no repositório
/compact	Compacta o histórico para economizar tokens	Limpeza de contexto sob sessões longas de depuração
/review	Executa rotina de auditoria de segurança	Delega varredura de bugs a um agente secundário
/init	Inicializa o arquivo AGENTS.md	Criação de regras de comportamento locais
/clear	Limpa o console e inicializa nova thread	Descarte do contexto anterior para novo escopo

O console do Codex aceita o enfileiramento de comandos. Enquanto o agente executa a gravação de arquivos, digite novas diretrizes no prompt e aperte Tab para programar o próximo processamento na fila.

Nota: A listagem de comandos é customizável. A estrutura estendida de automações e atalhos programados é explicada no Artigo 12.

💡 Resumo em uma frase: Os comandos de barra gerenciam a thread ativa do console. /status, /model, /permissions e /diff cobrem as ações frequentes.

---

05 Atalhos de Teclado Operacionais

Atalhos físicos de teclado mapeados no console interativo:

Atalho de console	Ação do sistema
Ctrl+C	Cancela o processamento ativo ou encerra a sessão da CLI (alternativa: /exit)
Ctrl+L	Redesenha a TUI (corrige falhas de vídeo sem limpar o histórico de chat)
↑ / ↓	Navega pelo histórico de prompts locais enviados na sessão
Ctrl+R	Abre a busca reversa no histórico de comandos de prompts
Ctrl+O	Copia a última resposta gerada pelo Codex (equivalente a /copy)
Tab	Enfileira a instrução digitada no prompt durante a execução de tarefas
Esc + Esc (com prompt vazio)	Retorna ao histórico da última mensagem enviada para edição direta
Ctrl+G	Abre o editor de sistema configurado ($EDITOR) para escrita de prompts longos

Atalhos avançados de terminal:

Atalho de comando Shell (!): Digitar o caractere ! no início do prompt permite executar comandos direto no shell local (ex: !git status, !ls). Os retornos gerados são adicionados ao contexto da sessão e respeitam as regras ativas de sandbox.

!git status

Edição de Prompts longos (Ctrl+G): Dispara o editor de texto preferencial cadastrado no sistema (nano, vim ou VS Code). Ao salvar e fechar o arquivo temporário, o texto é copiado para o console do Codex.

Utilize o caractere @ para buscar caminhos de arquivos por autocompletar, otimizando as instruções de prompts de compilação.

💡 Resumo em uma frase: Comandos ! executam subinstruções locais; Ctrl+G gerencia blocos longos de texto; @ vincula caminhos. Use /keymap para personalizar.

---

06 Prática: Validando o fluxo operacional da CLI

Rode a sequência a seguir para validar o mapeamento de arquivos e a TUI da CLI:

Passo 1: Crie o diretório temporário e inicialize

macOS / Linux (no Windows PowerShell, substitua mkdir -p por mkdir):

mkdir -p ~/codex-cli-demo && cd ~/codex-cli-demo
codex

Saída esperada: Inicialização da TUI gráfica de console com o prompt de comandos ativo e métricas de status no rodapé.

Passo 2: Verifique os parâmetros técnicos

Digite no prompt:

/status

Saída esperada: O Codex listará o modelo de processamento, as permissões ativas de sandbox e o limite de tokens da thread.

O software utilitário token-tracker exibe os tokens de cotas ativos no terminal, além de estatísticas do consumo de tokens.

Passo 3: Execute comandos shell (!)

Digite no prompt:

!echo hello-codex-cli

Saída esperada: O terminal executará a instrução localmente, retornando o texto hello-codex-cli para a thread de contexto do chat.

Passo 4: Navegue pelo histórico

Pressione a tecla ↑:

Saída esperada: O console preencherá a linha de comando com a instrução anterior, facilitando edições.

Passo 5: Execute refatorações locais e verifique o diff

Envie o comando de escrita:

新建一个文件 hi.txt，里面写一行 "hello from codex cli"。

Se solicitado pelo sandbox, autorize a gravação do arquivo e execute:

/diff

Saída esperada: A CLI exibirá a alteração estrutural no arquivo hi.txt em formato diff.

Passo 6: Encerre a sessão

/exit

Saída esperada: Fechamento da TUI e retorno ao console tradicional.

💡 Resumo em uma frase: Siga estas 6 etapas para dominar os atalhos de terminal e as validações de sandbox locais da CLI.

---

07 Terminal Interativo versus Execução Não-Interativa

O subcomando codex exec (ou codex e) constitui um recurso exclusivo da CLI para automações sem interface gráfica.

O modo interativo TUI foca na iteração manual e revisões pontuais. O subcomando exec roda tarefas em plano único: processa a instrução enviada, gera as gravações e encerra o processo, gravando logs na saída padrão (stdout), o que o torna ideal para pipelines de CI/CD.

Analogia: restaurantes versus entregas em domicílio. O terminal interativo funciona como a mesa do restaurante, permitindo ajustar a refatoração a cada etapa. O subcomando exec representa o pedido de entrega: você envia a instrução, a IA processa o código internamente e entrega a alteração pronta na pasta, sem demandar sua presença ativa.

Chamada básica de automação:

codex exec "Analise as modificações locais em busca de bugs de compilação"

O processo lerá as dependências locais, gerará as correções correspondentes e retornará o output no terminal antes de encerrar o processo.

Flags úteis para o subcomando exec:

Flag do subcomando exec	Finalidade técnica
--model / -m	Especifica o modelo de processamento para a automação
--json	Retorna saídas formatadas em JSON (para leitura via scripts secundários)
--output-last-message / -o	Grava o relatório textual final em um arquivo físico
--skip-git-repo-check	Permite rodar execuções em pastas sem Git inicializado
--ephemeral	Não armazena o histórico da chamada no banco de dados local do Codex

Comparativo operacional:

Métrica	Modo Interativo (codex)	Modo Não-Interativo (codex exec)
Comportamento pós-tarefa	Mantém a TUI ativa aguardando novas instruções	Grava os arquivos e encerra a execução
Público indicado	Depurações estruturais e refatorações complexas	Execuções agendadas, pipelines de CI e scripts locais
Presença do desenvolvedor	Necessária para revisões interativas de sandbox	Dispensa acompanhamento visual
Formato de saída	Renderização em TUI com diffs interativos	Envio de logs para stdout ou arquivos JSON/Markdown

Recomenda-se usar o modo interativo para desenvolvimento comum. Use o exec integrado com as flags --json e --output-last-message para automações que geram documentações ou correções de testes em lote.

Nota de segurança: O modo exec atua por padrão sob aprovação imediata (never). Garanta o isolamento do sandbox --sandbox workspace-write para evitar alterações de arquivos fora do repositório durante tarefas automatizadas.

💡 Resumo em uma frase: O modo interativo gerencia depurações complexas na TUI; o exec automatiza tarefas via linha de comando para scripts e pipelines.

---

08 Resumo

Este manual cobriu as diretivas sintáticas de comandos e atalhos operacionais da CLI do Codex.

Guia rápido de referência:

Demanda de desenvolvimento	Ação recomendada
Inicializar a interface interativa	codex
Especificar modelo e restrições de sandbox	codex -m <modelo> -s <sandbox> -a <aprovação>
Definir pasta de trabalho ativa sem usar cd	codex --cd <caminho>
Anexar capturas de erros no prompt	codex -i <imagem>
Mudar modelo, permissões ou ver diffs na TUI	Comandos /model, /permissions ou /diff
Rodar comandos locais sem interromper o chat	Comando precedido por ! no prompt
Resolver erros de renderização no terminal	Ctrl+L
Digitar prompts longos em editores do sistema	Ctrl+G
Rodar automações sem interface interativa	codex exec "<instrução>"

Com essas rotinas consolidadas, você está apto a operar a CLI do Codex, gerenciar permissões de sandbox direto no shell e automatizar chamadas do terminal.

Regra técnica final: A CLI estende as capacidades do aplicativo desktop, servindo como a base de dados principal para automações e deploy em servidores.

---

O próximo artigo 09 · Extensões para IDE (VS Code e similares) demonstrará como acoplar a CLI do Codex dentro dos editores de código, acompanhando diffs inline e rodando testes sem sair da tela do editor.

---

Leituras Recomendadas

• Execução no Windows: Configurações nativas e via WSL
• Guia Rápido de Configurações da CLI
• Guia de Instalação e Autenticação