# Running a plan

Choose a mode, watch it execute per host in the console, and read the run record afterwards. A failed step halts the run in every mode.

Source: https://opafra.com/docs/running/executing

---

Starting a run means choosing which plan, which mode, and any variables it needs. The
console then shows each step executing against each host, live.

## Choose a mode

| Mode | What it does |
|---|---|
| **Automatic** | Runs start to finish without stopping |
| **Step through** | Pauses at each step for you to continue, skip, retry or roll back |
| **Dry run** | Changes nothing; reports what would happen |

Automatic is the normal choice for a plan that has run before. Step through is for a plan
you are still learning to trust, and it is a different thing from an
[approval gate](/docs/running/approval-gates): the gate asks somebody else once, before
anything runs, while step through keeps you in the loop throughout.

Start with a [dry run](/docs/running/dry-run) the first time a plan meets a host you care
about.

## Variables at start

If the plan declares typed inputs, you are prompted for them, with defaults filled in and
required ones enforced. Otherwise you can supply free-form variables that override the
plan's own.

Values supplied here take precedence over plan variables, which take precedence over
environment values. Environment values are resolved per host, so a run spanning staging
and production gives each host its own.

## What happens first

Before the first step, Opafra resolves the plan's targets, works out which environments
they belong to, and checks two things:

**Concurrency.** If the same plan is already running against any of the same hosts, the
run is refused and the overlapping hosts are named. A plan can opt into concurrent runs
where that is genuinely safe.

**The approval gate.** If any environment the run touches requires approval, the run
pauses before its first step and waits. Dry runs skip this, because they change nothing.

## Reading the console

The console streams per step and per host. Each host shows its own status, output and
duration, because the interesting information in a multi-host run is where the hosts
disagree.

A step that calls a [module](/docs/plans/modules) expands into its items as it runs, so
you see the actual work rather than an opaque single line.

## When a step fails

**The run halts.** Later steps do not execute, and the run is recorded as failed. This is
the default in every mode, including the step-through ones, because the second half of a
plan usually assumes the first half worked.

Three per-item settings, declared in the plan rather than chosen now, change this:
`continue_on_error` lets an item fail without failing the run, `retries` adds attempts,
and `retry_delay_seconds` spaces them out. See [plan structure](/docs/plans/structure).

A failed item under `continue_on_error` is still recorded as failed. The setting stops it
halting the run; it does not make it invisible.

## Aborting

A run can be aborted while it is running or while it is paused. Aborting stops further
steps; it does not undo what has already been done, because Opafra does not assume every
step has an inverse.

Where a plan needs to undo something, that is a step in the plan.

## Statuses

| Status | Meaning |
|---|---|
| **Pending** | Created, not yet started |
| **Running** | Executing |
| **Paused** | Waiting at an approval gate or a step-through decision |
| **Completed** | Every step succeeded |
| **Failed** | A step failed and the run halted |
| **Aborted** | Someone stopped it |

A paused run is durable. The checkpoint is written to the database rather than held in
memory, so a run waiting overnight is still waiting after a restart.

## The run record

Every run keeps what was asked for, who started it, who approved it and against which
plan revision, what each step did on each host, the output, and the result. It survives
the plan being edited or deleted afterwards.

That record is the answer to "what actually happened", and it is why a run is worth
starting from Opafra rather than from a terminal.

## Next steps

- [Dry runs](/docs/running/dry-run) for previewing before you run for real
- [Scheduling](/docs/running/scheduling) for running a plan on a timer