skip to content

How do you start a Codex Cloud task from the terminal, and how does its change reach your local checkout or a pull request?

level: middleimportance: nice to knowfreq 5%

answer

  1. an experimental CLI subcommand
  2. a published environment id
  3. best-of-N attempts
  4. diff, then git apply
  5. pull request from the review

basics

~20 s

codex cloud exec --env ENV_ID "task" submits a task to a published Codex Cloud environment; codex cloud is marked experimental in 0.159.3. Review the result in ChatGPT and commit or open a pull request there, or bring the diff home with codex apply TASK_ID.

solid answer

~40 s

Codex Cloud runs a task in a VM built from a **published environment** (repositories, tools, internet settings, secrets), so it keeps working while your laptop sleeps. From the terminal, `codex cloud` (marked `[EXPERIMENTAL]` in 0.159.3) opens a picker; `codex cloud exec --env <ENV_ID> "<task>"` submits directly, with `--attempts 1-4` for best-of-N and `--branch` (default: the current branch). `codex cloud list` (add `--json`), `status`, and `diff <TASK_ID>` let you follow it. The change then takes one of two routes: review it in ChatGPT on the web, desktop or mobile and **commit or open a pull request** there, or apply it locally with `codex apply <TASK_ID>` (or `codex cloud apply <TASK_ID> --attempt N`), which runs `git apply` on your working tree and exits non-zero if the patch does not apply.

go deeper

for a junior

Recall that codex cloud exec needs an environment id, and that codex apply brings a task's diff into your working tree.

for a middle

Explain the two routes from a finished task, pull request from the review or git apply locally, and what --attempts and --branch change.

for a senior

Know the failure modes: experimental CLI behaviour, patches that no longer apply, and environment network and secret settings that differ from the local sandbox.

for a principal

Decide which work goes to cloud tasks rather than local runs, and how environments, secrets and pull-request review are owned across teams.

## What a Codex Cloud task is Codex, OpenAI's coding agent, runs either locally (terminal, IDE extension, desktop app) or in **Codex Cloud**, where each task runs in its own virtual machine. A task starts from a **published environment**: a saved setup that names the GitHub repositories, installs dependencies and tools, and holds the environment's internet settings, variables and network secrets. Because the work happens remotely, a task keeps going while your computer is asleep, and you can return to it on the web, in the desktop app or on mobile. Environments are created and published on the web or in the desktop app; the terminal is for starting and collecting tasks. ## Starting a task from the terminal In 0.159.3 the subcommand is **`codex cloud`** (alias `codex cloud-tasks`), and its help text marks it **[EXPERIMENTAL]**. Its pieces: | Command | What it does | |---|---| | `codex cloud` | interactive picker to browse tasks and apply changes | | `codex cloud exec --env <ENV_ID> "<task>"` | submits a task without opening the picker; `--env` is required | | `codex cloud list` | recent tasks; `--env` filters, `--limit` 1-20 (default 20), `--json` for scripts | | `codex cloud status <TASK_ID>` | shows a task's status | | `codex cloud diff <TASK_ID>` | prints the task's unified diff | | `codex cloud apply <TASK_ID>` | applies the task's diff locally | Two options on `codex cloud exec` matter in practice: - **`--attempts N`** (1 to 4, default 1) asks for best-of-N: several independent attempts, each with its own diff, that you compare before choosing one. - **`--branch <BRANCH>`** names the Git branch the task runs on; it defaults to your current branch. Submission uses the same credentials as the rest of the CLI, and the command exits non-zero if submission fails. ## Route one: review and open a pull request The documented flow ends in ChatGPT: you inspect the changed files and test results, ask for follow-up changes in the same task if needed, and **commit or open a pull request** when you are ready. In the documented flow, publishing is a step you take after review, and the repository's normal checks and reviews apply from there. ## Route two: apply the diff locally When you want to finish the work on your own machine: 1. Pick the task, from `codex cloud list` or the picker. 2. If you asked for several attempts, compare them with `codex cloud diff <TASK_ID> --attempt N`. 3. Apply one: `codex cloud apply <TASK_ID> --attempt N`, or the top-level **`codex apply <TASK_ID>`** (alias `codex a`), which applies the latest diff from that task. 4. Codex runs it as a **`git apply`** on your working tree, prints the patched files, and **exits non-zero** if the patch fails, for example because of conflicts. Nothing is committed or pushed by `codex apply`; the change lands as uncommitted edits for you to test, commit and push. ## Scripting the loop For automation around cloud tasks, `codex cloud list --json` returns a `tasks` array and an optional `cursor` for the next page. Each task carries `id`, `url`, `title`, `status`, `updated_at`, `environment_id`, `environment_label`, `summary`, `is_review` and `attempt_total`, which is enough to: - poll for tasks in one environment with `--env`; - page through history with `--cursor`; - feed a finished task's `id` to `codex cloud diff` or `codex apply`. ## Network and secrets in the cloud - In the current Codex Cloud, internet access is an environment setting: you turn on **Allow Codex to access internet** and choose the **Package managers** preset, custom domains only, or unrestricted access. - Allowing a domain does not supply credentials; network secrets are tied to allowed HTTPS destinations. - In **Codex Cloud (Legacy)**, setup scripts have internet access, the agent phase is offline by default, and environment secrets are removed before the agent phase starts. ## Common mistakes - Treating `codex cloud exec` as a remote version of local `codex exec`: it runs in the environment's VM, not in your local sandbox. - Expecting `codex apply` to push: it only patches the local working tree. - Applying onto a checkout that has moved far from the task's branch, then reading the `git apply` failure as a Codex bug.

  • What does `--attempts` on `codex cloud exec` give you, and how do you use the result?
    It asks Codex Cloud for best-of-N: 1 to 4 independent attempts, default 1, each producing its own diff. Compare them with `codex cloud diff <TASK_ID> --attempt N` and apply the one you want with `codex cloud apply <TASK_ID> --attempt N`.
  • `codex apply <TASK_ID>` exits non-zero with conflicts. What happened, and what do you do?
    Codex applies the task's diff with `git apply`, which fails when your working tree no longer matches what the patch expects, such as after local edits or a moved branch. Clean or stash local changes, check out the branch the task ran on, and apply again; nothing was committed in the meantime.

  • codex cloud exec runs the task on your laptop inside the local sandbox
  • A Codex Cloud task merges its own pull request as soon as its tests pass
  • codex cloud is a stable command in 0.159.3
  • codex apply commits the cloud diff and pushes it to the remote branch
  • --attempts keeps retrying until one attempt passes the tests

Assumes Codex 0.159.3, where codex cloud is labelled [EXPERIMENTAL] in the CLI help and codex apply applies a cloud task's latest diff with git apply.