Run a one-shot agent task in CI

Goal

Run one agent task to completion without a terminal UI and get a process exit code your CI job can gate on.

Prerequisites

• The redgold client installed and a key in REDGOLD_KEY (see Install the terminal client).
• The repository the task runs against.

Steps

--one-shot <repo> drives a single task to completion, then exits with a code that reflects the outcome. It needs a prompt, from --prompt or --prompt-file:

redgold --one-shot redgold --prompt "run the tests"

It runs until the session reaches a terminal state or a bounded idle-quiescence fallback fires, then prints a final line and exits non-zero on failure or timeout:

[one-shot] exit_status=<status> summary=<summary>

--timeout-secs (default 1800) bounds the whole run; exceeding it exits with exit_status = "timeout". --agent-kind selects the backend — claude (the default) or redgold.

Expected output

A single [one-shot] exit_status=... summary=... line, and a process exit code of 0 on success or non-zero on failure or timeout — so a CI step fails when the task does.

When it breaks

• Exits with exit_status=timeout — the run exceeded --timeout-secs. Raise the timeout, or check whether the task actually stalled.
• Non-zero exit with an auth message — confirm REDGOLD_KEY (or --key) is set in the CI environment.

Source

Terminal client reference (batch and non-interactive runs).