tanmay/aetheel-2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: Discord-Claude Gateway with event-driven agent runtime

Browse Source
This commit is contained in:
tanmay11k
2026-02-22 13:59:57 -05:00
parent b4f340b610
commit f2247ea3ac
28 changed files with 2056 additions and 205 deletions
Download Patch File Download Diff File Expand all files Collapse all files

196
references/codex cli/agents.md Normal file
View File

@@ -0,0 +1,196 @@
# Custom instructions with AGENTS.md
Codex reads `AGENTS.md` files before doing any work. By layering global guidance with project-specific overrides, you can start each task with consistent expectations, no matter which repository you open.
## How Codex discovers guidance
Codex builds an instruction chain when it starts (once per run; in the TUI this usually means once per launched session). Discovery follows this precedence order:
1. **Global scope:** In your Codex home directory (defaults to `~/.codex`, unless you set `CODEX_HOME`), Codex reads `AGENTS.override.md` if it exists. Otherwise, Codex reads `AGENTS.md`. Codex uses only the first non-empty file at this level.
2. **Project scope:** Starting at the project root (typically the Git root), Codex walks down to your current working directory. If Codex cannot find a project root, it only checks the current directory. In each directory along the path, it checks for `AGENTS.override.md`, then `AGENTS.md`, then any fallback names in `project_doc_fallback_filenames`. Codex includes at most one file per directory.
3. **Merge order:** Codex concatenates files from the root down, joining them with blank lines. Files closer to your current directory override earlier guidance because they appear later in the combined prompt.
Codex skips empty files and stops adding files once the combined size reaches the limit defined by `project_doc_max_bytes` (32 KiB by default). For details on these knobs, see [Project instructions discovery](https://developers.openai.com/codex/config-advanced#project-instructions-discovery). Raise the limit or split instructions across nested directories when you hit the cap.
## Create global guidance
Create persistent defaults in your Codex home directory so every repository inherits your working agreements.
1. Ensure the directory exists:
```bash
mkdir -p ~/.codex
```
2. Create `~/.codex/AGENTS.md` with reusable preferences:
```md
# ~/.codex/AGENTS.md
## Working agreements
- Always run `npm test` after modifying JavaScript files.
- Prefer `pnpm` when installing dependencies.
- Ask for confirmation before adding new production dependencies.
```
3. Run Codex anywhere to confirm it loads the file:
```bash
codex --ask-for-approval never "Summarize the current instructions."
```
Expected: Codex quotes the items from `~/.codex/AGENTS.md` before proposing work.
Use `~/.codex/AGENTS.override.md` when you need a temporary global override without deleting the base file. Remove the override to restore the shared guidance.
## Layer project instructions
Repository-level files keep Codex aware of project norms while still inheriting your global defaults.
1. In your repository root, add an `AGENTS.md` that covers basic setup:
```md
# AGENTS.md
## Repository expectations
- Run `npm run lint` before opening a pull request.
- Document public utilities in `docs/` when you change behavior.
```
2. Add overrides in nested directories when specific teams need different rules. For example, inside `services/payments/` create `AGENTS.override.md`:
```md
# services/payments/AGENTS.override.md
## Payments service rules
- Use `make test-payments` instead of `npm test`.
- Never rotate API keys without notifying the security channel.
```
3. Start Codex from the payments directory:
```bash
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."
```
Expected: Codex reports the global file first, the repository root `AGENTS.md` second, and the payments override last.
Codex stops searching once it reaches your current directory, so place overrides as close to specialized work as possible.
Here is a sample repository after you add a global file and a payments-specific override:
<FileTree
class="mt-4"
tree={[
{
name: "AGENTS.md",
comment: "Repository expectations",
highlight: true,
},
{
name: "services/",
open: true,
children: [
{
name: "payments/",
open: true,
children: [
{
name: "AGENTS.md",
comment: "Ignored because an override exists",
},
{
name: "AGENTS.override.md",
comment: "Payments service rules",
highlight: true,
},
{ name: "README.md" },
],
},
{
name: "search/",
children: [{ name: "AGENTS.md" }, { name: "…", placeholder: true }],
},
],
},
]}
/>
## Customize fallback filenames
If your repository already uses a different filename (for example `TEAM_GUIDE.md`), add it to the fallback list so Codex treats it like an instructions file.
1. Edit your Codex configuration:
```toml
# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536
```
2. Restart Codex or run a new command so the updated configuration loads.
Now Codex checks each directory in this order: `AGENTS.override.md`, `AGENTS.md`, `TEAM_GUIDE.md`, `.agents.md`. Filenames not on this list are ignored for instruction discovery. The larger byte limit allows more combined guidance before truncation.
With the fallback list in place, Codex treats the alternate files as instructions:
<FileTree
class="mt-4"
tree={[
{
name: "TEAM_GUIDE.md",
comment: "Detected via fallback list",
highlight: true,
},
{
name: ".agents.md",
comment: "Fallback file in root",
},
{
name: "support/",
open: true,
children: [
{
name: "AGENTS.override.md",
comment: "Overrides fallback guidance",
highlight: true,
},
{
name: "playbooks/",
children: [{ name: "…", placeholder: true }],
},
],
},
]}
/>
Set the `CODEX_HOME` environment variable when you want a different profile, such as a project-specific automation user:
```bash
CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"
```
Expected: The output lists files relative to the custom `.codex` directory.
## Verify your setup
- Run `codex --ask-for-approval never "Summarize the current instructions."` from a repository root. Codex should echo guidance from global and project files in precedence order.
- Use `codex --cd subdir --ask-for-approval never "Show which instruction files are active."` to confirm nested overrides replace broader rules.
- Check `~/.codex/log/codex-tui.log` (or the most recent `session-*.jsonl` file if you enabled session logging) after a session if you need to audit which instruction files Codex loaded.
- If instructions look stale, restart Codex in the target directory. Codex rebuilds the instruction chain on every run (and at the start of each TUI session), so there is no cache to clear manually.
## Troubleshoot discovery issues
- **Nothing loads:** Verify you are in the intended repository and that `codex status` reports the workspace root you expect. Ensure instruction files contain content; Codex ignores empty files.
- **Wrong guidance appears:** Look for an `AGENTS.override.md` higher in the directory tree or under your Codex home. Rename or remove the override to fall back to the regular file.
- **Codex ignores fallback names:** Confirm you listed the names in `project_doc_fallback_filenames` without typos, then restart Codex so the updated configuration takes effect.
- **Instructions truncated:** Raise `project_doc_max_bytes` or split large files across nested directories to keep critical guidance intact.
- **Profile confusion:** Run `echo $CODEX_HOME` before launching Codex. A non-default value points Codex at a different home directory than the one you edited.
## Next steps
- Visit the official [AGENTS.md](https://agents.md) website for more information.
- Review [Prompting Codex](https://developers.openai.com/codex/prompting) for conversational patterns that pair well with persistent guidance.

859
references/codex cli/cli.md Normal file
View File

@@ -0,0 +1,859 @@
# Command line options
export const globalFlagOptions = [
{
key: "PROMPT",
type: "string",
description:
"Optional text instruction to start the session. Omit to launch the TUI without a pre-filled message.",
},
{
key: "--image, -i",
type: "path[,path...]",
description:
"Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag.",
},
{
key: "--model, -m",
type: "string",
description:
"Override the model set in configuration (for example `gpt-5-codex`).",
},
{
key: "--oss",
type: "boolean",
defaultValue: "false",
description:
'Use the local open source model provider (equivalent to `-c model_provider="oss"`). Validates that Ollama is running.',
},
{
key: "--profile, -p",
type: "string",
description:
"Configuration profile name to load from `~/.codex/config.toml`.",
},
{
key: "--sandbox, -s",
type: "read-only | workspace-write | danger-full-access",
description:
"Select the sandbox policy for model-generated shell commands.",
},
{
key: "--ask-for-approval, -a",
type: "untrusted | on-request | never",
description:
"Control when Codex pauses for human approval before running a command. `on-failure` is deprecated; prefer `on-request` for interactive runs or `never` for non-interactive runs.",
},
{
key: "--full-auto",
type: "boolean",
defaultValue: "false",
description:
"Shortcut for low-friction local work: sets `--ask-for-approval on-request` and `--sandbox workspace-write`.",
},
{
key: "--dangerously-bypass-approvals-and-sandbox, --yolo",
type: "boolean",
defaultValue: "false",
description:
"Run every command without approvals or sandboxing. Only use inside an externally hardened environment.",
},
{
key: "--cd, -C",
type: "path",
description:
"Set the working directory for the agent before it starts processing your request.",
},
{
key: "--search",
type: "boolean",
defaultValue: "false",
description:
'Enable live web search (sets `web_search = "live"` instead of the default `"cached"`).',
},
{
key: "--add-dir",
type: "path",
description:
"Grant additional directories write access alongside the main workspace. Repeat for multiple paths.",
},
{
key: "--no-alt-screen",
type: "boolean",
defaultValue: "false",
description:
"Disable alternate screen mode for the TUI (overrides `tui.alternate_screen` for this run).",
},
{
key: "--enable",
type: "feature",
description:
"Force-enable a feature flag (translates to `-c features.<name>=true`). Repeatable.",
},
{
key: "--disable",
type: "feature",
description:
"Force-disable a feature flag (translates to `-c features.<name>=false`). Repeatable.",
},
{
key: "--config, -c",
type: "key=value",
description:
"Override configuration values. Values parse as JSON if possible; otherwise the literal string is used.",
},
];
export const commandOverview = [
{
key: "codex",
href: "/codex/cli/reference#codex-interactive",
type: "stable",
description:
"Launch the terminal UI. Accepts the global flags above plus an optional prompt or image attachments.",
},
{
key: "codex app-server",
href: "/codex/cli/reference#codex-app-server",
type: "experimental",
description:
"Launch the Codex app server for local development or debugging.",
},
{
key: "codex app",
href: "/codex/cli/reference#codex-app",
type: "stable",
description:
"Launch the Codex desktop app on macOS, optionally opening a specific workspace path.",
},
{
key: "codex debug app-server send-message-v2",
href: "/codex/cli/reference#codex-debug-app-server-send-message-v2",
type: "experimental",
description:
"Debug app-server by sending a single V2 message through the built-in test client.",
},
{
key: "codex apply",
href: "/codex/cli/reference#codex-apply",
type: "stable",
description:
"Apply the latest diff generated by a Codex Cloud task to your local working tree. Alias: `codex a`.",
},
{
key: "codex cloud",
href: "/codex/cli/reference#codex-cloud",
type: "experimental",
description:
"Browse or execute Codex Cloud tasks from the terminal without opening the TUI. Alias: `codex cloud-tasks`.",
},
{
key: "codex completion",
href: "/codex/cli/reference#codex-completion",
type: "stable",
description:
"Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell.",
},
{
key: "codex features",
href: "/codex/cli/reference#codex-features",
type: "stable",
description:
"List feature flags and persistently enable or disable them in `config.toml`.",
},
{
key: "codex exec",
href: "/codex/cli/reference#codex-exec",
type: "stable",
description:
"Run Codex non-interactively. Alias: `codex e`. Stream results to stdout or JSONL and optionally resume previous sessions.",
},
{
key: "codex execpolicy",
href: "/codex/cli/reference#codex-execpolicy",
type: "experimental",
description:
"Evaluate execpolicy rule files and see whether a command would be allowed, prompted, or blocked.",
},
{
key: "codex login",
href: "/codex/cli/reference#codex-login",
type: "stable",
description:
"Authenticate Codex using ChatGPT OAuth, device auth, or an API key piped over stdin.",
},
{
key: "codex logout",
href: "/codex/cli/reference#codex-logout",
type: "stable",
description: "Remove stored authentication credentials.",
},
{
key: "codex mcp",
href: "/codex/cli/reference#codex-mcp",
type: "experimental",
description:
"Manage Model Context Protocol servers (list, add, remove, authenticate).",
},
{
key: "codex mcp-server",
href: "/codex/cli/reference#codex-mcp-server",
type: "experimental",
description:
"Run Codex itself as an MCP server over stdio. Useful when another agent consumes Codex.",
},
{
key: "codex resume",
href: "/codex/cli/reference#codex-resume",
type: "stable",
description:
"Continue a previous interactive session by ID or resume the most recent conversation.",
},
{
key: "codex fork",
href: "/codex/cli/reference#codex-fork",
type: "stable",
description:
"Fork a previous interactive session into a new thread, preserving the original transcript.",
},
{
key: "codex sandbox",
href: "/codex/cli/reference#codex-sandbox",
type: "experimental",
description:
"Run arbitrary commands inside Codex-provided macOS seatbelt or Linux sandboxes (Landlock by default, optional bubblewrap pipeline).",
},
];
export const execOptions = [
{
key: "PROMPT",
type: "string | - (read stdin)",
description:
"Initial instruction for the task. Use `-` to pipe the prompt from stdin.",
},
{
key: "--image, -i",
type: "path[,path...]",
description:
"Attach images to the first message. Repeatable; supports comma-separated lists.",
},
{
key: "--model, -m",
type: "string",
description: "Override the configured model for this run.",
},
{
key: "--oss",
type: "boolean",
defaultValue: "false",
description:
"Use the local open source provider (requires a running Ollama instance).",
},
{
key: "--sandbox, -s",
type: "read-only | workspace-write | danger-full-access",
description:
"Sandbox policy for model-generated commands. Defaults to configuration.",
},
{
key: "--profile, -p",
type: "string",
description: "Select a configuration profile defined in config.toml.",
},
{
key: "--full-auto",
type: "boolean",
defaultValue: "false",
description:
"Apply the low-friction automation preset (`workspace-write` sandbox and `on-request` approvals).",
},
{
key: "--dangerously-bypass-approvals-and-sandbox, --yolo",
type: "boolean",
defaultValue: "false",
description:
"Bypass approval prompts and sandboxing. Dangerous—only use inside an isolated runner.",
},
{
key: "--cd, -C",
type: "path",
description: "Set the workspace root before executing the task.",
},
{
key: "--skip-git-repo-check",
type: "boolean",
defaultValue: "false",
description:
"Allow running outside a Git repository (useful for one-off directories).",
},
{
key: "--ephemeral",
type: "boolean",
defaultValue: "false",
description: "Run without persisting session rollout files to disk.",
},
{
key: "--output-schema",
type: "path",
description:
"JSON Schema file describing the expected final response shape. Codex validates tool output against it.",
},
{
key: "--color",
type: "always | never | auto",
defaultValue: "auto",
description: "Control ANSI color in stdout.",
},
{
key: "--json, --experimental-json",
type: "boolean",
defaultValue: "false",
description:
"Print newline-delimited JSON events instead of formatted text.",
},
{
key: "--output-last-message, -o",
type: "path",
description:
"Write the assistant’s final message to a file. Useful for downstream scripting.",
},
{
key: "Resume subcommand",
type: "codex exec resume [SESSION_ID]",
description:
"Resume an exec session by ID or add `--last` to continue the most recent session from the current working directory. Add `--all` to consider sessions from any directory. Accepts an optional follow-up prompt.",
},
{
key: "-c, --config",
type: "key=value",
description:
"Inline configuration override for the non-interactive run (repeatable).",
},
];
export const appServerOptions = [
{
key: "--listen",
type: "stdio:// | ws://IP:PORT",
defaultValue: "stdio://",
description:
"Transport listener URL. `ws://` is experimental and intended for development/testing.",
},
];
export const appOptions = [
{
key: "PATH",
type: "path",
defaultValue: ".",
description:
"Workspace path to open in Codex Desktop (`codex app` is available on macOS only).",
},
{
key: "--download-url",
type: "url",
description:
"Advanced override for the Codex desktop DMG download URL used during install.",
},
];
export const debugAppServerSendMessageV2Options = [
{
key: "USER_MESSAGE",
type: "string",
description:
"Message text sent to app-server through the built-in V2 test-client flow.",
},
];
export const resumeOptions = [
{
key: "SESSION_ID",
type: "uuid",
description:
"Resume the specified session. Omit and use `--last` to continue the most recent session.",
},
{
key: "--last",
type: "boolean",
defaultValue: "false",
description:
"Skip the picker and resume the most recent conversation from the current working directory.",
},
{
key: "--all",
type: "boolean",
defaultValue: "false",
description:
"Include sessions outside the current working directory when selecting the most recent session.",
},
];
export const featuresOptions = [
{
key: "List subcommand",
type: "codex features list",
description:
"Show known feature flags, their maturity stage, and their effective state.",
},
{
key: "Enable subcommand",
type: "codex features enable <feature>",
description:
"Persistently enable a feature flag in `config.toml`. Respects the active `--profile` when provided.",
},
{
key: "Disable subcommand",
type: "codex features disable <feature>",
description:
"Persistently disable a feature flag in `config.toml`. Respects the active `--profile` when provided.",
},
];
export const execResumeOptions = [
{
key: "SESSION_ID",
type: "uuid",
description:
"Resume the specified session. Omit and use `--last` to continue the most recent session.",
},
{
key: "--last",
type: "boolean",
defaultValue: "false",
description:
"Resume the most recent conversation from the current working directory.",
},
{
key: "--all",
type: "boolean",
defaultValue: "false",
description:
"Include sessions outside the current working directory when selecting the most recent session.",
},
{
key: "--image, -i",
type: "path[,path...]",
description:
"Attach one or more images to the follow-up prompt. Separate multiple paths with commas or repeat the flag.",
},
{
key: "PROMPT",
type: "string | - (read stdin)",
description:
"Optional follow-up instruction sent immediately after resuming.",
},
];
export const forkOptions = [
{
key: "SESSION_ID",
type: "uuid",
description:
"Fork the specified session. Omit and use `--last` to fork the most recent session.",
},
{
key: "--last",
type: "boolean",
defaultValue: "false",
description:
"Skip the picker and fork the most recent conversation automatically.",
},
{
key: "--all",
type: "boolean",
defaultValue: "false",
description:
"Show sessions beyond the current working directory in the picker.",
},
];
export const execpolicyOptions = [
{
key: "--rules, -r",
type: "path (repeatable)",
description:
"Path to an execpolicy rule file to evaluate. Provide multiple flags to combine rules across files.",
},
{
key: "--pretty",
type: "boolean",
defaultValue: "false",
description: "Pretty-print the JSON result.",
},
{
key: "COMMAND...",
type: "var-args",
description: "Command to be checked against the specified policies.",
},
];
export const loginOptions = [
{
key: "--with-api-key",
type: "boolean",
description:
"Read an API key from stdin (for example `printenv OPENAI_API_KEY | codex login --with-api-key`).",
},
{
key: "--device-auth",
type: "boolean",
description:
"Use OAuth device code flow instead of launching a browser window.",
},
{
key: "status subcommand",
type: "codex login status",
description:
"Print the active authentication mode and exit with 0 when logged in.",
},
];
export const applyOptions = [
{
key: "TASK_ID",
type: "string",
description:
"Identifier of the Codex Cloud task whose diff should be applied.",
},
];
export const sandboxMacOptions = [
{
key: "--full-auto",
type: "boolean",
defaultValue: "false",
description:
"Grant write access to the current workspace and `/tmp` without approvals.",
},
{
key: "--config, -c",
type: "key=value",
description:
"Pass configuration overrides into the sandboxed run (repeatable).",
},
{
key: "COMMAND...",
type: "var-args",
description:
"Shell command to execute under macOS Seatbelt. Everything after `--` is forwarded.",
},
];
export const sandboxLinuxOptions = [
{
key: "--full-auto",
type: "boolean",
defaultValue: "false",
description:
"Grant write access to the current workspace and `/tmp` inside the Landlock sandbox.",
},
{
key: "--config, -c",
type: "key=value",
description:
"Configuration overrides applied before launching the sandbox (repeatable).",
},
{
key: "COMMAND...",
type: "var-args",
description:
"Command to execute under Landlock + seccomp. Provide the executable after `--`.",
},
];
export const completionOptions = [
{
key: "SHELL",
type: "bash | zsh | fish | power-shell | elvish",
defaultValue: "bash",
description: "Shell to generate completions for. Output prints to stdout.",
},
];
export const cloudExecOptions = [
{
key: "QUERY",
type: "string",
description:
"Task prompt. If omitted, Codex prompts interactively for details.",
},
{
key: "--env",
type: "ENV_ID",
description:
"Target Codex Cloud environment identifier (required). Use `codex cloud` to list options.",
},
{
key: "--attempts",
type: "1-4",
defaultValue: "1",
description:
"Number of assistant attempts (best-of-N) Codex Cloud should run.",
},
];
export const cloudListOptions = [
{
key: "--env",
type: "ENV_ID",
description: "Filter tasks by environment identifier.",
},
{
key: "--limit",
type: "1-20",
defaultValue: "20",
description: "Maximum number of tasks to return.",
},
{
key: "--cursor",
type: "string",
description: "Pagination cursor returned by a previous request.",
},
{
key: "--json",
type: "boolean",
defaultValue: "false",
description: "Emit machine-readable JSON instead of plain text.",
},
];
export const mcpCommands = [
{
key: "list",
type: "--json",
description:
"List configured MCP servers. Add `--json` for machine-readable output.",
},
{
key: "get <name>",
type: "--json",
description:
"Show a specific server configuration. `--json` prints the raw config entry.",
},
{
key: "add <name>",
type: "-- <command...> | --url <value>",
description:
"Register a server using a stdio launcher command or a streamable HTTP URL. Supports `--env KEY=VALUE` for stdio transports.",
},
{
key: "remove <name>",
description: "Delete a stored MCP server definition.",
},
{
key: "login <name>",
type: "--scopes scope1,scope2",
description:
"Start an OAuth login for a streamable HTTP server (servers that support OAuth only).",
},
{
key: "logout <name>",
description:
"Remove stored OAuth credentials for a streamable HTTP server.",
},
];
export const mcpAddOptions = [
{
key: "COMMAND...",
type: "stdio transport",
description:
"Executable plus arguments to launch the MCP server. Provide after `--`.",
},
{
key: "--env KEY=VALUE",
type: "repeatable",
description:
"Environment variable assignments applied when launching a stdio server.",
},
{
key: "--url",
type: "https://…",
description:
"Register a streamable HTTP server instead of stdio. Mutually exclusive with `COMMAND...`.",
},
{
key: "--bearer-token-env-var",
type: "ENV_VAR",
description:
"Environment variable whose value is sent as a bearer token when connecting to a streamable HTTP server.",
},
];
## How to read this reference
This page catalogs every documented Codex CLI command and flag. Use the interactive tables to search by key or description. Each section indicates whether the option is stable or experimental and calls out risky combinations.
The CLI inherits most defaults from <code>~/.codex/config.toml</code>. Any
<code>-c key=value</code> overrides you pass at the command line take
precedence for that invocation. See [Config
basics](https://developers.openai.com/codex/config-basic#configuration-precedence) for more information.
## Global flags
<ConfigTable client:load options={globalFlagOptions} />
These options apply to the base `codex` command and propagate to each subcommand unless a section below specifies otherwise.
When you run a subcommand, place global flags after it (for example, `codex exec --oss ...`) so Codex applies them as intended.
## Command overview
The Maturity column uses feature maturity labels such as Experimental, Beta,
and Stable. See [Feature Maturity](https://developers.openai.com/codex/feature-maturity) for how to
interpret these labels.
<ConfigTable
client:load
options={commandOverview}
secondColumnTitle="Maturity"
secondColumnVariant="maturity"
/>
## Command details
### `codex` (interactive)
Running `codex` with no subcommand launches the interactive terminal UI (TUI). The agent accepts the global flags above plus image attachments. Web search defaults to cached mode; use `--search` to switch to live browsing and `--full-auto` to let Codex run most commands without prompts.
### `codex app-server`
Launch the Codex app server locally. This is primarily for development and debugging and may change without notice.
<ConfigTable client:load options={appServerOptions} />
`codex app-server --listen stdio://` keeps the default JSONL-over-stdio behavior. `--listen ws://IP:PORT` enables WebSocket transport (experimental). If you generate schemas for client bindings, add `--experimental` to include gated fields and methods.
### `codex app`
Launch Codex Desktop from the terminal on macOS and optionally open a specific workspace path.
<ConfigTable client:load options={appOptions} />
`codex app` installs/opens the desktop app on macOS, then opens the provided workspace path. This subcommand is macOS-only.
### `codex debug app-server send-message-v2`
Send one message through app-server's V2 thread/turn flow using the built-in app-server test client.
<ConfigTable client:load options={debugAppServerSendMessageV2Options} />
This debug flow initializes with `experimentalApi: true`, starts a thread, sends a turn, and streams server notifications. Use it to reproduce and inspect app-server protocol behavior locally.
### `codex apply`
Apply the most recent diff from a Codex cloud task to your local repository. You must authenticate and have access to the task.
<ConfigTable client:load options={applyOptions} />
Codex prints the patched files and exits non-zero if `git apply` fails (for example, due to conflicts).
### `codex cloud`
Interact with Codex cloud tasks from the terminal. The default command opens an interactive picker; `codex cloud exec` submits a task directly, and `codex cloud list` returns recent tasks for scripting or quick inspection.
<ConfigTable client:load options={cloudExecOptions} />
Authentication follows the same credentials as the main CLI. Codex exits non-zero if the task submission fails.
#### `codex cloud list`
List recent cloud tasks with optional filtering and pagination.
<ConfigTable client:load options={cloudListOptions} />
Plain-text output prints a task URL followed by status details. Use `--json` for automation. The JSON payload contains a `tasks` array plus an optional `cursor` value. Each task includes `id`, `url`, `title`, `status`, `updated_at`, `environment_id`, `environment_label`, `summary`, `is_review`, and `attempt_total`.
### `codex completion`
Generate shell completion scripts and redirect the output to the appropriate location, for example `codex completion zsh > "${fpath[1]}/_codex"`.
<ConfigTable client:load options={completionOptions} />
### `codex features`
Manage feature flags stored in `~/.codex/config.toml`. The `enable` and `disable` commands persist changes so they apply to future sessions. When you launch with `--profile`, Codex writes to that profile instead of the root configuration.
<ConfigTable client:load options={featuresOptions} />
### `codex exec`
Use `codex exec` (or the short form `codex e`) for scripted or CI-style runs that should finish without human interaction.
<ConfigTable client:load options={execOptions} />
Codex writes formatted output by default. Add `--json` to receive newline-delimited JSON events (one per state change). The optional `resume` subcommand lets you continue non-interactive tasks. Use `--last` to pick the most recent session from the current working directory, or add `--all` to search across all sessions:
<ConfigTable client:load options={execResumeOptions} />
### `codex execpolicy`
Check `execpolicy` rule files before you save them. `codex execpolicy check` accepts one or more `--rules` flags (for example, files under `~/.codex/rules`) and emits JSON showing the strictest decision and any matching rules. Add `--pretty` to format the output. The `execpolicy` command is currently in preview.
<ConfigTable client:load options={execpolicyOptions} />
### `codex login`
Authenticate the CLI with a ChatGPT account or API key. With no flags, Codex opens a browser for the ChatGPT OAuth flow.
<ConfigTable client:load options={loginOptions} />
`codex login status` exits with `0` when credentials are present, which is helpful in automation scripts.
### `codex logout`
Remove saved credentials for both API key and ChatGPT authentication. This command has no flags.
### `codex mcp`
Manage Model Context Protocol server entries stored in `~/.codex/config.toml`.
<ConfigTable client:load options={mcpCommands} />
The `add` subcommand supports both stdio and streamable HTTP transports:
<ConfigTable client:load options={mcpAddOptions} />
OAuth actions (`login`, `logout`) only work with streamable HTTP servers (and only when the server supports OAuth).
### `codex mcp-server`
Run Codex as an MCP server over stdio so that other tools can connect. This command inherits global configuration overrides and exits when the downstream client closes the connection.
### `codex resume`
Continue an interactive session by ID or resume the most recent conversation. `codex resume` scopes `--last` to the current working directory unless you pass `--all`. It accepts the same global flags as `codex`, including model and sandbox overrides.
<ConfigTable client:load options={resumeOptions} />
### `codex fork`
Fork a previous interactive session into a new thread. By default, `codex fork` opens the session picker; add `--last` to fork your most recent session instead.
<ConfigTable client:load options={forkOptions} />
### `codex sandbox`
Use the sandbox helper to run a command under the same policies Codex uses internally.
#### macOS seatbelt
<ConfigTable client:load options={sandboxMacOptions} />
#### Linux Landlock
<ConfigTable client:load options={sandboxLinuxOptions} />
## Flag combinations and safety tips
- Set `--full-auto` for unattended local work, but avoid combining it with `--dangerously-bypass-approvals-and-sandbox` unless you are inside a dedicated sandbox VM.
- When you need to grant Codex write access to more directories, prefer `--add-dir` rather than forcing `--sandbox danger-full-access`.
- Pair `--json` with `--output-last-message` in CI to capture machine-readable progress and a final natural-language summary.
## Related resources
- [Codex CLI overview](https://developers.openai.com/codex/cli): installation, upgrades, and quick tips.
- [Config basics](https://developers.openai.com/codex/config-basic): persist defaults like the model and provider.
- [Advanced Config](https://developers.openai.com/codex/config-advanced): profiles, providers, sandbox tuning, and integrations.
- [AGENTS.md](https://developers.openai.com/codex/guides/agents-md): conceptual overview of Codex agent capabilities and best practices.

59
references/codex cli/sdk.md Normal file
View File

@@ -0,0 +1,59 @@
# Codex SDK
If you use Codex through the Codex CLI, the IDE extension, or Codex Web, you can also control it programmatically.
Use the SDK when you need to:
- Control Codex as part of your CI/CD pipeline
- Create your own agent that can engage with Codex to perform complex engineering tasks
- Build Codex into your own internal tools and workflows
- Integrate Codex within your own application
## TypeScript library
The TypeScript library provides a way to control Codex from within your application that is more comprehensive and flexible than non-interactive mode.
Use the library server-side; it requires Node.js 18 or later.
### Installation
To get started, install the Codex SDK using `npm`:
```bash
npm install @openai/codex-sdk
```
### Usage
Start a thread with Codex and run it with your prompt.
```ts
const codex = new Codex();
const thread = codex.startThread();
const result = await thread.run(
"Make a plan to diagnose and fix the CI failures"
);
console.log(result);
```
Call `run()` again to continue on the same thread, or resume a past thread by providing a thread ID.
```ts
// running the same thread
const result = await thread.run("Implement the plan");
console.log(result);
// resuming past thread
const threadId = "<thread-id>";
const thread2 = codex.resumeThread(threadId);
const result2 = await thread2.run("Pick up where you left off");
console.log(result2);
```
For more details, check out the [TypeScript repo](https://github.com/openai/codex/tree/main/sdk/typescript).

115
references/gemini/cli.md Normal file
View File

@@ -0,0 +1,115 @@
# Gemini CLI cheatsheet
This page provides a reference for commonly used Gemini CLI commands, options,
and parameters.
## CLI commands
| Command | Description | Example |
| ---------------------------------- | ---------------------------------- | --------------------------------------------------- |
| `gemini` | Start interactive REPL | `gemini` |
| `gemini "query"` | Query non-interactively, then exit | `gemini "explain this project"` |
| `cat file \| gemini` | Process piped content | `cat logs.txt \| gemini` |
| `gemini -i "query"` | Execute and continue interactively | `gemini -i "What is the purpose of this project?"` |
| `gemini -r "latest"` | Continue most recent session | `gemini -r "latest"` |
| `gemini -r "latest" "query"` | Continue session with a new prompt | `gemini -r "latest" "Check for type errors"` |
| `gemini -r "<session-id>" "query"` | Resume session by ID | `gemini -r "abc123" "Finish this PR"` |
| `gemini update` | Update to latest version | `gemini update` |
| `gemini extensions` | Manage extensions | See [Extensions Management](#extensions-management) |
| `gemini mcp` | Configure MCP servers | See [MCP Server Management](#mcp-server-management) |
### Positional arguments
| Argument | Type | Description |
| -------- | ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| `query` | string (variadic) | Positional prompt. Defaults to one-shot mode. Use `-i/--prompt-interactive` to execute and continue interactively. |
## CLI Options
| Option | Alias | Type | Default | Description |
| -------------------------------- | ----- | ------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--debug` | `-d` | boolean | `false` | Run in debug mode with verbose logging |
| `--version` | `-v` | - | - | Show CLI version number and exit |
| `--help` | `-h` | - | - | Show help information |
| `--model` | `-m` | string | `auto` | Model to use. See [Model Selection](#model-selection) for available values. |
| `--prompt` | `-p` | string | - | Prompt text. Appended to stdin input if provided. **Deprecated:** Use positional arguments instead. |
| `--prompt-interactive` | `-i` | string | - | Execute prompt and continue in interactive mode |
| `--sandbox` | `-s` | boolean | `false` | Run in a sandboxed environment for safer execution |
| `--approval-mode` | - | string | `default` | Approval mode for tool execution. Choices: `default`, `auto_edit`, `yolo` |
| `--yolo` | `-y` | boolean | `false` | **Deprecated.** Auto-approve all actions. Use `--approval-mode=yolo` instead. |
| `--experimental-acp` | - | boolean | - | Start in ACP (Agent Code Pilot) mode. **Experimental feature.** |
| `--experimental-zed-integration` | - | boolean | - | Run in Zed editor integration mode. **Experimental feature.** |
| `--allowed-mcp-server-names` | - | array | - | Allowed MCP server names (comma-separated or multiple flags) |
| `--allowed-tools` | - | array | - | **Deprecated.** Use the [Policy Engine](/docs/reference/policy-engine) instead. Tools that are allowed to run without confirmation (comma-separated or multiple flags) |
| `--extensions` | `-e` | array | - | List of extensions to use. If not provided, all extensions are enabled (comma-separated or multiple flags) |
| `--list-extensions` | `-l` | boolean | - | List all available extensions and exit |
| `--resume` | `-r` | string | - | Resume a previous session. Use `"latest"` for most recent or index number (e.g. `--resume 5`) |
| `--list-sessions` | - | boolean | - | List available sessions for the current project and exit |
| `--delete-session` | - | string | - | Delete a session by index number (use `--list-sessions` to see available sessions) |
| `--include-directories` | - | array | - | Additional directories to include in the workspace (comma-separated or multiple flags) |
| `--screen-reader` | - | boolean | - | Enable screen reader mode for accessibility |
| `--output-format` | `-o` | string | `text` | The format of the CLI output. Choices: `text`, `json`, `stream-json` |
## Model selection
The `--model` (or `-m`) flag lets you specify which Gemini model to use. You can
use either model aliases (user-friendly names) or concrete model names.
### Model aliases
These are convenient shortcuts that map to specific models:
| Alias | Resolves To | Description |
| ------------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `auto` | `gemini-2.5-pro` or `gemini-3-pro-preview` | **Default.** Resolves to the preview model if preview features are enabled, otherwise resolves to the standard pro model. |
| `pro` | `gemini-2.5-pro` or `gemini-3-pro-preview` | For complex reasoning tasks. Uses preview model if enabled. |
| `flash` | `gemini-2.5-flash` | Fast, balanced model for most tasks. |
| `flash-lite` | `gemini-2.5-flash-lite` | Fastest model for simple tasks. |
## Extensions management
| Command | Description | Example |
| -------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------ |
| `gemini extensions install <source>` | Install extension from Git URL or local path | `gemini extensions install https://github.com/user/my-extension` |
| `gemini extensions install <source> --ref <ref>` | Install from specific branch/tag/commit | `gemini extensions install https://github.com/user/my-extension --ref develop` |
| `gemini extensions install <source> --auto-update` | Install with auto-update enabled | `gemini extensions install https://github.com/user/my-extension --auto-update` |
| `gemini extensions uninstall <name>` | Uninstall one or more extensions | `gemini extensions uninstall my-extension` |
| `gemini extensions list` | List all installed extensions | `gemini extensions list` |
| `gemini extensions update <name>` | Update a specific extension | `gemini extensions update my-extension` |
| `gemini extensions update --all` | Update all extensions | `gemini extensions update --all` |
| `gemini extensions enable <name>` | Enable an extension | `gemini extensions enable my-extension` |
| `gemini extensions disable <name>` | Disable an extension | `gemini extensions disable my-extension` |
| `gemini extensions link <path>` | Link local extension for development | `gemini extensions link /path/to/extension` |
| `gemini extensions new <path>` | Create new extension from template | `gemini extensions new ./my-extension` |
| `gemini extensions validate <path>` | Validate extension structure | `gemini extensions validate ./my-extension` |
See [Extensions Documentation](/docs/extensions) for more details.
## MCP server management
| Command | Description | Example |
| ------------------------------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `gemini mcp add <name> <command>` | Add stdio-based MCP server | `gemini mcp add github npx -y @modelcontextprotocol/server-github` |
| `gemini mcp add <name> <url> --transport http` | Add HTTP-based MCP server | `gemini mcp add api-server http://localhost:3000 --transport http` |
| `gemini mcp add <name> <command> --env KEY=value` | Add with environment variables | `gemini mcp add slack node server.js --env SLACK_TOKEN=xoxb-xxx` |
| `gemini mcp add <name> <command> --scope user` | Add with user scope | `gemini mcp add db node db-server.js --scope user` |
| `gemini mcp add <name> <command> --include-tools tool1,tool2` | Add with specific tools | `gemini mcp add github npx -y @modelcontextprotocol/server-github --include-tools list_repos,get_pr` |
| `gemini mcp remove <name>` | Remove an MCP server | `gemini mcp remove github` |
| `gemini mcp list` | List all configured MCP servers | `gemini mcp list` |
See [MCP Server Integration](/docs/tools/mcp-server) for more details.
## Skills management
| Command | Description | Example |
| -------------------------------- | ------------------------------------- | ------------------------------------------------- |
| `gemini skills list` | List all discovered agent skills | `gemini skills list` |
| `gemini skills install <source>` | Install skill from Git, path, or file | `gemini skills install https://github.com/u/repo` |
| `gemini skills link <path>` | Link local agent skills via symlink | `gemini skills link /path/to/my-skills` |
| `gemini skills uninstall <name>` | Uninstall an agent skill | `gemini skills uninstall my-skill` |
| `gemini skills enable <name>` | Enable an agent skill | `gemini skills enable my-skill` |
| `gemini skills disable <name>` | Disable an agent skill | `gemini skills disable my-skill` |
| `gemini skills enable --all` | Enable all skills | `gemini skills enable --all` |
| `gemini skills disable --all` | Disable all skills | `gemini skills disable --all` |
See [Agent Skills Documentation](/docs/cli/skills) for more details.