# Codex CLI and terminal reference

> Codex: Startup, exec, resume, app-server, remote connections, diagnostics, JSONL and stdin pipelines.

URL: https://docs.passion8.cc/en/docs/codex/cli-terminal-reference
Language: en
Publisher: Passion8

[Commands](https://docs.passion8.cc/en/docs/codex/commands) is the quick reference. This page explains terminal sessions, non-interactive output, remote app-server connections and diagnostics.

## Working directory

Start at the project root so the workspace boundary is clear:

```bash
cd /path/to/project
codex
```

Select a directory for a single run:

```bash
codex -C /path/to/project
codex --cd /path/to/project "Explain this project"
```

For multiple directories, prefer a worktree, the monorepo root or `--add-dir` rather than granting whole-disk access.

## Common startup combinations

| Scenario | Command |
| --- | --- |
| Interactive session | `codex` |
| Initial task | `codex "Fix this error"` |
| Read-only investigation | `codex --sandbox read-only --ask-for-approval on-request` |
| Focused implementation | `codex --sandbox workspace-write --ask-for-approval on-request` |
| Selected Passion8 model | `codex --model gpt-6-sol` |
| Live search for this run | `codex --search` |
| Strict configuration check | `codex --strict-config` |

`--dangerously-bypass-approvals-and-sandbox` belongs only in isolated, recoverable environments. Do not make it the default in production or secret-bearing directories.

## Interactive habits

| Action | Approach |
| --- | --- |
| Reference files | `@` or `/mention` |
| Complex task | Plan with `/plan` first |
| Long task | Define completion conditions with `/goal` |
| Inspect state | `/status` |
| Inspect diff | `/diff` |
| Review | `/review` |
| Change access | `/permissions` |
| Compact context | `/compact` |
| Resume | `/resume` or `codex resume --last` |

Threads can be continued, forked, archived or deleted. Do not have two threads edit the same files unless they use independent worktrees.

## Non-interactive exec

Use `codex exec` for scripts, CI and one-off batches:

```bash
codex exec "review the current diff and list P0/P1 risks"
```

Continue a previous run:

```bash
codex exec "review the change for race conditions"
codex exec resume --last "fix the race conditions you found"
```

Or select a session:

```bash
codex exec resume <SESSION_ID> "continue with the same constraints"
```

Non-interactive runs normally require a Git repository. Use `--skip-git-repo-check` only when deliberately running outside one.

## stdin pipelines

Pass generated context through stdin together with a task prompt:

```bash
npm test 2>&1 \
  | codex exec "summarize the failing tests and propose the smallest likely fix"
```

Inspect logs:

```bash
tail -n 200 app.log \
  | codex exec "identify the likely root cause and next three debugging steps"
```

Explain a CI failure:

```bash
gh run view 123456 --log \
  | codex exec "write a concise PR comment explaining the CI failure"
```

## Output and automation

| Need | Approach |
| --- | --- |
| Machine-readable result | JSON/JSONL output and a defined output structure |
| Multi-stage pipeline | `codex exec resume` |
| Save final answer | Redirect stdout or use the output-last-message option |
| Preserve a complete patch | `git diff --binary HEAD > codex.patch` |
| Pin model and permissions | Explicit model, sandbox and approval options |

For GitHub Actions, see [Non-interactive, CI and SDK](https://docs.passion8.cc/en/docs/codex/noninteractive-ci-sdk).

## app-server and remote connections

`codex app-server` provides the protocol used by richer clients such as desktop and IDE integrations. It is useful for integration/debugging rather than ordinary one-off CI.

```bash
codex app-server
codex app-server --listen ws://127.0.0.1:4500
codex app-server --listen unix://
```

Connect to a server:

```bash
codex --remote ws://127.0.0.1:4500
```

Keep WebSocket listeners on localhost or behind an SSH tunnel. Remote exposure requires authentication; do not expose an unauthenticated listener on a public or local network.

## Diagnostics

```bash
codex doctor
codex debug models
codex features
codex mcp list
```

Inside the TUI:

```text
/debug-config
/mcp
/status
/usage
/feedback
```

Logs:

```bash
RUST_LOG=debug codex -c log_dir=./.codex-log
tail -F ./.codex-log/codex-tui.log
```

Use `codex-login.log` for authentication troubleshooting where the installed client provides it. Non-interactive runs normally include diagnostics in command output.

## Shell completion

Inspect the installed version's completion options:

```bash
codex completion --help
```

If a command is missing, update the client or consult `codex --help` and `codex <subcommand> --help` for that version.

## Official references

- [CLI reference](https://developers.openai.com/codex/cli/reference)
- [Codex manual: slash commands](https://developers.openai.com/codex/codex-manual.md)
- [Non-interactive mode](https://developers.openai.com/codex/noninteractive)
- [Codex manual: app-server](https://developers.openai.com/codex/codex-manual.md)