Add scriptable Codex Cloud environment and task lifecycle management

Proposal

Add a comprehensive, scriptable Codex Cloud CLI/API surface for environment discovery, environment lifecycle management, repo-based task dispatch, task/session monitoring, and PR/result handoff.

Today, codex cloud exec --env ENV_ID ... can submit work once the caller already knows an opaque server-side environment ID. The CLI also supports task list, status, diff, and apply, but there does not appear to be a public non-interactive workflow for discovering or managing the Codex Cloud environments that those tasks depend on.

That means automation currently has to open the interactive codex cloud TUI or web UI, find an environment manually, copy an opaque ID, and paste it into scripts. This blocks reliable multi-repo dispatch, CI integration, and agent-driven workflows.

Current Codex Cloud CLI gap

Current public task commands are useful, but environment IDs remain the missing primitive:

codex cloud exec --env ENV_ID "..."
codex cloud list --env ENV_ID --json
codex cloud status TASK_ID
codex cloud diff TASK_ID
codex cloud apply TASK_ID

The CLI can operate on a task or known environment, but scripts cannot yet:

• list available environments,
• resolve owner/repo to the correct environment,
• create an environment for a repo,
• update labels/default branches/pinned status,
• delete/archive stale environments,
• dispatch by repo without knowing an opaque environment ID,
• monitor and continue a cloud task lifecycle in a fully scriptable way.

Requested CLI surface

Environment discovery and resolution

codex cloud env list
codex cloud env list --repo owner/repo
codex cloud env list --json
codex cloud env get ENV_ID --json
codex cloud env resolve --repo owner/repo --json

JSON output should expose stable automation fields, for example:

[
  {
    "id": "env_...",
    "repo": "owner/repo",
    "label": "main",
    "branch": "main",
    "status": "ready",
    "is_pinned": true,
    "is_default": true
  }
]

The exact schema can follow the backend model, but scripts need at least: environment ID, repo binding, label/display name, branch/default branch if applicable, status/readiness, pinned/default/preferred state, and enough metadata to disambiguate multiple environments for one repo.

Repo-based task dispatch

codex cloud exec --repo owner/repo "implement/fix ..."
codex cloud exec --repo owner/repo --branch main "implement/fix ..."
codex cloud exec --env ENV_ID "implement/fix ..."

--repo should resolve the environment internally using the same behavior as codex cloud env resolve.

If repo resolution is ambiguous, interactive use can show choices, but non-interactive use should fail clearly and suggest a disambiguating flag such as --env, --label, or --branch.

Environment lifecycle management

codex cloud env create --repo owner/repo --branch main --label "main"
codex cloud env update ENV_ID --label "main" --branch main
codex cloud env pin ENV_ID
codex cloud env unpin ENV_ID
codex cloud env set-default ENV_ID
codex cloud env delete ENV_ID --yes

Optional follow-ons depending on the backend model:

codex cloud env rename ENV_ID "new label"
codex cloud env archive ENV_ID
codex cloud env restore ENV_ID

Mutation commands should be safe by default:

• destructive actions require confirmation unless --yes is supplied;
• all commands support --json;
• create/update validate repo and branch bindings;
• delete/archive refuses or warns for active, pinned, or default environments;
• behavior matches the web UI/TUI canonical environment model.

Task lifecycle controls

Codex Cloud already has task list, status, diff, and apply. For parity with async coding-agent workflows, it would be useful to make the task lifecycle fully scriptable:

codex cloud wait TASK_ID --timeout 1800 --interval 10
codex cloud logs TASK_ID --json
codex cloud message TASK_ID "additional instruction or answer"
codex cloud cancel TASK_ID
codex cloud output TASK_ID --json

The goal is for automation to dispatch a task, wait until it completes or needs input, answer questions, retrieve the diff/result, and report the final URL/status without using the TUI.

If Codex Cloud supports PR creation now or in the future, expose that result explicitly:

{
  "task_id": "task_...",
  "status": "completed",
  "url": "https://...",
  "pull_request": {
    "url": "https://github.com/owner/repo/pull/123",
    "title": "...",
    "description": "..."
  }
}

Prior art: Jules feature parity

Jules exposes this workflow as a first-class CLI/API surface, and it is a strong comparison point for Codex Cloud.

Jules CLI provides:

jules remote list --repo
jules remote list --session
jules remote new --repo owner/repo --session "..."
jules remote pull --session SESSION_ID

The Jules API provides:

• GET /v1alpha/sources to list connected repos/sources,
• GET /v1alpha/sources/{sourceId} to inspect one source,
• POST /v1alpha/sessions with sourceContext.source and githubRepoContext.startingBranch,
• automationMode: "AUTO_CREATE_PR" for PR-producing sessions,
• session states such as QUEUED, PLANNING, AWAITING_PLAN_APPROVAL, AWAITING_USER_FEEDBACK, IN_PROGRESS, COMPLETED, and FAILED,
• outputs[].pullRequest.url when a PR is created.

This makes Jules powerful for fleet workflows because an external dispatcher can:

1. enumerate connected repos,
2. resolve owner/repo to an internal source ID,
3. create many async cloud sessions,
4. poll status,
5. answer questions or approve plans,
6. collect PR URLs,
7. continue review/merge through GitHub.

Codex Cloud has some of these pieces internally, especially environment discovery in the TUI and by-repo environment lookup, but the missing piece is a stable public CLI/API contract.

Why this matters

A complete Codex Cloud automation surface would let scripts and agents:

• bootstrap Codex Cloud for a repo,
• keep repo/environment metadata in sync,
• dispatch tasks by stable repo slug instead of opaque environment ID,
• run multi-repo issue/spec fanout,
• track task state and output URLs,
• retrieve diffs/results,
• safely clean up stale environments.

This is especially important for agentic workflows where the unit of work is naturally owner/repo + prompt, not opaque environment ID + prompt.

Suggested phased implementation

Phase 1: read / resolve / dispatch

codex cloud env list [--repo owner/repo] [--json]
codex cloud env get ENV_ID [--json]
codex cloud env resolve --repo owner/repo [--json]
codex cloud exec --repo owner/repo "..."

This solves the immediate automation gap without adding destructive operations.

Phase 2: task lifecycle

codex cloud wait TASK_ID
codex cloud logs TASK_ID --json
codex cloud message TASK_ID "..."
codex cloud output TASK_ID --json

This makes cloud tasks usable end-to-end in scripts.

Phase 3: environment mutation

codex cloud env create --repo owner/repo --branch main --label "main"
codex cloud env update ENV_ID --label "..." --branch main
codex cloud env pin ENV_ID
codex cloud env unpin ENV_ID
codex cloud env set-default ENV_ID
codex cloud env delete ENV_ID --yes

This completes the feature by letting automation maintain the environment layer, not just consume existing environments.

Consistency considerations

The CLI should use the same environment discovery and selection logic as the existing codex cloud TUI so CLI, TUI, IDE extensions, web, and future API surfaces agree.

Prefer command names that can grow:

codex cloud env list/get/resolve/create/update/delete

A compatibility alias like codex cloud list-envs could still be useful, but the durable model should be a full env subcommand group.

Prototype branch

I implemented a smaller Phase 1 prototype here, but this repo currently only accepts PRs from collaborators:

https://github.com/Kurry/codex/tree/codex-cloud-env-list

The prototype currently covers:

• codex cloud list-envs / codex cloud envs
• codex cloud list-envs --json
• codex cloud list-envs --repo owner/repo --json
• codex cloud exec --repo owner/repo ...

Validation run on the prototype:

• just fmt
• just fix
• cargo test -p codex-cloud-tasks
• cargo test -p codex-cli