CLI Reference

CLI Reference

Everything Codex Free accepts on the command line. There are two commands — quickstart and projects list — plus the default (no subcommand) server mode, which is what you run day to day.

Precedence: CLI flags always override values from codex.config.json. A missing config file is tolerated; built-in defaults are used and the startup banner says so.

---

codex-free (server mode)

Running with no subcommand starts the MCP bridge server. This is the mode ChatGPT connects to.

codex-free --work-dir /path/to/your/project

Server flags

Flag	Required	Default	What it does
--work-dir <DIR>	Yes	—	The project directory. With --multi-project (or projects list) it becomes an access root instead of the active project. Every project-scoped tool resolves paths relative to this.
--multi-project	No	Disabled	Turn --work-dir into an access root: each ChatGPT conversation binds once to a project beneath it. Other clients fall back to a transport-session binding. See Multi-Project Mode.
--worktree-mode <MODE>	No	auto	Worktree policy in multi-project mode: auto, always, or never. See Worktree Isolation.
--worktree-root <DIR>	No	Codex worktree location	Parent directory for managed conversation worktrees.
--port <PORT>	No	3000	Server port (legacy/external mode). Native tunnel mode binds loopback regardless.
--api-key <KEY>	No	—	Require Authorization: Bearer <key> on all requests except /health. Cannot be combined with native tunnel mode (which owns its own token).
--config <PATH>	No	./codex.config.json	Config file path. Tolerated if missing.
--codex-cli	No	Auto when available	Require successful Codex CLI-backed MCP discovery. Without it, a discovery failure is only a warning and direct config.toml parsing remains the fallback.
-v, --verbose	No	Info logs	Enable debug diagnostics; repeat (-vv) for trace. --log-tool-calls is an alias. See Audit Logging.
--audit <FILE>	No	Disabled	Append privacy-preserving tool-activity events to a JSONL file. --audit-log is an alias.
--audit-command-preview	No	Disabled	Add bounded, redacted previews of exec_command/run_command to the audit log.
--audit-redact-env <NAME>	No	—	Redact the current value of an env var from command previews. Repeatable.
--openai-tunnel-id <ID>	No	—	Existing OpenAI Secure MCP Tunnel ID; enables native tunnel mode.
--openai-tunnel-api-key-ref <REF>	No	env:CONTROL_PLANE_API_KEY	Runtime key reference: env:NAME or file:/path. Literal keys are rejected.
--openai-tunnel-client <PATH>	No	Managed pinned runtime	Use an explicit tunnel-client / tunnel-client-runtime binary instead of the managed one.
--openai-tunnel-organization-id <ID>	No	—	Optional OpenAI organization ID sent by the tunnel client.

The one required flag

--work-dir is the only mandatory argument. Everything else has a default or a config-file equivalent. In single-project mode it is the project root; in multi-project mode it is the boundary beneath which projects are selected. Nothing a tool does can escape this directory (with one bounded, read-only exception for AGENTS.md discovery — see Security Model).

Common invocations

# Simplest: single project, native tunnel configured in codex.config.json
codex-free --work-dir ~/code/myapp

# Many projects from one server
codex-free --work-dir ~/code --multi-project

# Verbose diagnostics while debugging a connector
codex-free -v --work-dir ~/code/myapp

# With an audit trail (safe subset by default)
codex-free --work-dir ~/code/myapp --audit ~/.codex-free/audit/tools.jsonl

# Native tunnel entirely from flags (no config file)
codex-free --work-dir ~/code/myapp \
  --openai-tunnel-id tunnel_0123... \
  --openai-tunnel-api-key-ref env:CONTROL_PLANE_API_KEY

Logging levels

The default tracing level is info.

• -v → codex_free=debug,rmcp=warn: adds tool-start events, hashed conversation/project context, argument field names, duration, and output accounting — without dumping protocol traffic.

• -vv → codex_free=trace, rmcp stays at warn: adds a fully redacted argument-shape summary.

• An explicit RUST_LOG env var overrides -v/-vv when you need protocol-level detail:

  RUST_LOG=codex_free=trace,rmcp=warn codex-free --work-dir ~/code/myapp

---

codex-free quickstart

Interactive setup wizard. Configures project scope, native OpenAI tunnel credentials, the JSON config, and the ChatGPT developer-mode connector — and can start the server when done. See Quick Start.

Flag	Default	What it does
--config <PATH>	./codex.config.json	Which config file the wizard writes.
--work-dir <DIR>	—	Initial value for the project-directory prompt.

codex-free quickstart
codex-free quickstart --config ~/servers/codex.config.json --work-dir ~/code/myapp

---

codex-free projects list

A local diagnostic for the project catalogue used in multi-project mode. It does not start the HTTP server, the tunnel, or any bridged MCP children — it just prints what would be selectable.

codex-free projects list --work-dir /path/to/projects
codex-free projects list --work-dir /path/to/projects --query "codex free"
codex-free projects list --work-dir /path/to/projects --json
codex-free projects list --work-dir /path/to/projects --show-skipped

Flag	Default	What it does
--work-dir <DIR>	— (required)	The access root whose catalogue to enumerate.
--query <TEXT>	—	Filter candidates by name, alias, description, or relative selector.
--limit <N>	Max project limit	Cap the number of results.
--json	Off	Emit machine-readable JSON.
--show-skipped	Off	Also print paths rejected as missing, untrusted, or outside the access root, plus merged duplicates.

--show-skipped is deliberately local-only: normal CLI output and the list_projects tool expose only aggregate warnings, so an agent never learns absolute paths it cannot select.

---

See also

• Configuration — the codex.config.json equivalents of these flags, and everything that has no flag.
• Security Model — what --work-dir, --api-key, and the allowlists actually bound.
• Connecting to ChatGPT — the --openai-tunnel-* flags in context.