# Workflows from the CLI

> Start, wait for, inspect and recover workflow runs.

Start a workflow run and wait for it, read its history, and recover failed runs from the terminal.

## Guided workflow inspection and recovery

Run `gregale workflow status --interactive` to choose an app and workflow run,
then read its status, deployment, step states, attempt counts, and errors. The app
comes from `--app`, a saved link, or the existing app picker. Run selection is
paged and scoped to that app. `gregale menu` also opens this inspection flow.

Use `gregale workflow retry --interactive` to choose a failed or dead run
and a step that passes the server's manual HTTP retry preview. Review its
attempt and the skipped descendants that would reopen, then confirm (default:
no). The preview uses the captured workflow graph and current quota; it does
not reserve capacity. Retry can execute HTTP effects again. Older servers
without the retry preview offer no steps; explicit retry commands remain
available.

Use `gregale workflow cancel --interactive` to choose a pending, running,
or waiting run. Review its current steps and confirm (default: no).
Cancellation stops further progress and does not undo completed external effects.

Both changes re-read the run and steps after confirmation and stop if the
reviewed state changed. The server remains authoritative when accepting the
request. Responses must match the selected app and run. The printed inspection
and action commands preserve the connection profile and quote arguments for
POSIX shells.

Interactive workflow commands require terminal input and output and reject
JSON output, `--non-interactive`, and mixed explicit run/step arguments.
For scripts, keep using `workflows status RUN_ID`,
`workflows retry RUN_ID STEP_NAME`, and `workflows cancel RUN_ID`.

## Using the linked app for workflows

Inside a checkout linked with an app, these commands use that app by default:

```sh
gregale workflow list
gregale workflow run nightly-report
```

An explicit `--app SLUG` overrides the checkout context, including a missing or
malformed context file. Without an explicit app, missing, ambiguous, or malformed
context stops the command locally with instructions to pass `--app` or repair
the link. Context discovery works from nested directories.

Before a human-mode run submission, stderr shows the selected connection profile,
app, and whether the app came from the flag or linked project. It displays no
input payload, credentials, or idempotency key. Workflow APIs target the app;
a linked environment does not add an environment selector. List filters, run
idempotency, and JSON responses retain their existing behavior.

## Loading workflow input from a file

```sh
gregale workflow run nightly-report --input-file input.json
gregale workflow run nightly-report --input-file -
```

`--input-file -` reads stdin until EOF. File paths are relative to the current
directory. Input must contain exactly one valid JSON value and fit within
1 MiB, including whitespace, before Gregale submits a run. Malformed, empty,
missing, or oversized input stops locally. `--input` and `--input-file` cannot
be combined, even if the explicitly supplied inline value is `{}`. Omitting
both retains the default `{}` input. Inline input receives the same size check.

The linked app, explicit `--app` override, and `--idempotency-key` work as before.
Loading diagnostics and target previews do not display the input payload.
Successful command responses retain their existing format; workflows may
return output according to their own definitions.

## Waiting for a workflow run

```sh
gregale workflow wait RUN_ID --timeout 5m
```

The command polls that exact run every two seconds and succeeds only when the
run reports `succeeded` without a cancellation timestamp. Failed, dead, canceled,
and unrecognized states exit 1; API errors retain their normal exit codes.
Pending, running, and awaiting-event states continue waiting. The command
only reads status; it does not resume, retry, cancel, or send workflow events.

Human progress on stderr changes when status, step, resume count, or availability
changes. The final run details appear on stdout. JSON mode emits one final run
object with the existing status response shape. Transient read failures are
retried; permanent request errors stop the wait. Each read has a 30-second
limit within the overall deadline.

Timeout exits 124 and returns the last observation, if any, plus a resume-wait
command on stderr. The workflow may still be active. Ctrl-C exits 130 and
leaves the run untouched. `--timeout` must be positive; `--poll-interval` accepts
1s to 1h. Accepted-run receipts also show the wait command.

## Starting and waiting in one command

```sh
gregale workflow run nightly-report --input-file input.json --wait --timeout 5m
```

Gregale submits once and follows the ID returned by the server using the same
logic as `workflows wait`. The timeout starts after acceptance; it does not
bound the initial submission. `--poll-interval` defaults to 2s and accepts 1s
to 1h. Explicit wait timing options require `--wait`. Linked-app defaults,
input files/stdin, and idempotency keys continue to work.

Human output shows acceptance on stderr, then status changes and final run
details. JSON mode returns one final run object, or the last known run object
if waiting stops. Success exits 0, terminal failure exits 1, timeout exits 124,
and Ctrl-C while waiting exits 130. API failures retain their normal codes.
On timeout, cancellation, or a permanent read failure, the accepted ID remains
available and recovery guidance resumes `workflows wait` without another
submission. A malformed acceptance response stops with instructions to inspect
run history before submitting again. Without `--wait`, output stays unchanged.

## Inspecting the newest workflow run

For a one-time workflow success check:

```sh
gregale workflow status RUN_ID --check
gregale workflow status latest --workflow-name billing --check
```

`--check` reads once and shows the same status details, exiting 0 only for
`succeeded` with no cancellation timestamp. Active, failed, dead, unknown,
or cancelled runs exit 1 with an explanation on stderr. JSON retains the run
object on stdout and uses the normal JSON error on stderr for a failed check.
API errors retain their usual codes. Selection and status share a 30-second
deadline, and check mode validates that the returned ID matches the selected
run. Explicit UUIDs keep script checks tied to the intended run. Without
`--check`, successful status reads retain exit 0. Check applies to the explicit
read command, not interactive selection; it does not wait or change the run.

Human `workflows status` output includes an exact-UUID wait command for active
runs, with a brief explanation for queued, executing, or event-waiting states.
Waiting observes the selected run and does not send events. Guidance retains
the active profile and is omitted for cancelled, terminal, unknown-state, or
invalid-ID responses. Existing failure guidance remains available. JSON and
API requests are unchanged. The same active-state explanations appear beside
wait commands in workflow history.

To focus on failed steps without scanning successful or pending steps:

```sh
gregale workflow steps latest --workflow-name billing --failed-only
```

`--failed-only` includes only steps whose recorded status is `failed`.
Explicit UUIDs also work. Human output includes commands for run diagnostics
and each failed step's attempts, using the selected UUID. These commands
inspect evidence; they do not retry or resume the workflow. When no steps
match, human output says so without claiming the run succeeded. JSON retains
NDJSON and emits no rows for an empty result. Step states may change after
the read. Without the flag, existing step output remains unchanged.

```sh
gregale workflow status latest --workflow-name nightly-report
gregale workflow steps latest --workflow-name nightly-report
gregale workflow diagnose latest --workflow-name nightly-report
gregale workflow attempts latest charge-card --workflow-name billing
gregale workflow resumes latest --workflow-name billing
```

These reads require an exact workflow name and use the linked app unless
`--app SLUG` overrides it. The server filters the history lookup by workflow
name; Gregale resolves the newest matching run once and reads that exact ID.
Latest includes unfinished and failed runs. Human stderr identifies the app,
workflow, run ID, and recorded status; JSON retains its existing shape.
`diagnose` explains queue or failure reasons and previews recovery eligibility
for the selected run without changing it. A diagnostics response identifying
a different run is rejected before displaying its recovery preview.
`attempts` lists retained retry attempts and managed-effect delivery status
for the explicitly named step. It reads the selected run without retrying the
step or changing the workflow. A missing step name stops before any lookup.
Add `--failed-only` to show only attempts whose recorded status is `failed`,
with the existing HTTP status, start/finish times, and next-attempt details.
For example: `gregale workflow attempts latest charge-card --workflow-name
billing --failed-only`. Explicit UUIDs also work. Human output explains when
no failed attempts match; JSON retains NDJSON and emits no rows for an empty
result. An empty result does not establish that the step or workflow succeeded;
attempt states and retained history may change. Ordinary output without the
flag remains unchanged.
`resumes` reads continuation history for the selected run. It does not resume
the workflow or submit any other change. Explicit UUID output and JSON
formats remain unchanged.

Lookup and detail reads share a 30-second deadline. Empty history gives a
filtered history command before another submission. Each command resolves
independently; use the printed UUID to inspect the same run across commands.
Explicit UUID reads need no app or workflow selectors. Retry, resume,
and cancellation continue to use explicit run IDs.

To wait for the newest matching workflow run without copying its UUID:

```sh
gregale workflow wait latest --workflow-name billing --timeout 5m
```

Selection uses the linked app or `--app SLUG`, requires an exact workflow name,
and resolves once within a 30-second lookup deadline. Waiting then uses the
normal timeout and follows only the selected UUID, even if newer runs appear.
Timeout and interruption provide a wait command containing that UUID. JSON
retains the final or last observed run object on stdout and wait errors on
stderr. Exit codes remain 0 for success, 1 for terminal failure, 124 for
timeout, and 130 for interruption. No run is submitted or cancelled.

## Reading all workflow history pages

Human history also includes exact-UUID `workflows wait` commands for pending,
running, and event-waiting runs. Guidance covers up to three distinct active
runs in returned order, with a count for additional runs. Event-waiting guidance
explains that waiting only observes the run and does not send an event or
advance it. Cancelled runs, successful/unknown states, and invalid UUIDs receive
no active-run guidance. Commands retain the active profile. This adds no API
reads or mutations, and JSON remains unchanged.

Human workflow history includes troubleshooting commands for runs recorded
as `failed` or `dead`: `workflows diagnose RUN_ID` and
`workflows steps RUN_ID --failed-only`. Commands use exact UUIDs and the active
profile, so newer runs cannot change the inspection target. Guidance covers
up to three distinct failed runs in returned order and reports how many more
are listed. Successful, pending, running, and event-waiting runs receive no
failure guidance. This adds no API reads or mutations; JSON remains unchanged.

```sh
gregale workflow list --workflow-name nightly-report --all
```

`--all` walks matching pages starting at `--offset` (default 0), with `--limit`
controlling page size. Every request keeps the selected app, workflow name,
status, and date filters. Ordinary human listings show a copyable next-page
command with the same filters when more results are reported. JSON remains
one run object per line and includes no pagination instructions.

Traversal buffers results so a failed page does not emit a partial list. Each
read has a 30-second deadline; Ctrl-C stops traversal with exit 130. The existing
1,000-page guard bounds traversal. Repeated run IDs are suppressed with `--all`.
Offset history is not an atomic snapshot: runs arriving or changing status
while pages are read can shift the history. Narrow creation-time filters help
keep a historical query bounded.

## Loading workflow event payloads

```sh
gregale workflow events RUN_ID approved --payload-file approval.json
gregale workflow events RUN_ID approved --payload-file -
```

`--payload-file -` reads stdin until EOF. Files use paths relative to the current
directory and must contain one valid JSON value. Empty, malformed, missing,
oversized, or conflicting input stops locally before sending. Choose either
`--payload` or `--payload-file`; omitting both retains `{}`. The existing
`workflows events send` spelling supports both options too.

The event request must fit within 1 MiB, including the event name and JSON
envelope; Gregale also bounds raw file/stdin input to 1 MiB. Inline payloads
receive the same validation. Loading diagnostics do not display the payload.
The run ID stays explicit, and successful output keeps its existing format.

## Resuming and waiting in one command

```sh
gregale workflow resume RUN_ID --expected-resume-count 1 --wait --timeout 5m
```

The command sends one resume request, retaining the expected resume-count
check and optional idempotency key, then follows the exact accepted run with
`workflows wait` logic. The deadline starts after resume acceptance. Explicit
`--timeout` and `--poll-interval` require `--wait`; timeout must be positive and
the poll interval must be 1s to 1h (default 2s).

Human output identifies the accepted resume before showing status changes.
JSON returns one final run object, or the last observation when waiting stops.
Success exits 0, terminal failure exits 1, timeout exits 124, and Ctrl-C while
waiting exits 130. API errors retain their usual codes. Timeout, cancellation,
and permanent read failures preserve the accepted run and a wait command for
continuing without another resume request. A mismatched acceptance response
stops and directs you to inspect the requested run and resume history.
Without `--wait`, existing resume output and behavior are unchanged.

## Retrying and waiting in one command

```sh
gregale workflow retry RUN_ID STEP_NAME --wait --timeout 5m
```

With an explicit run ID and step name, Gregale sends one retry request and
then follows that exact run using the existing workflow wait logic. Server
retry eligibility checks still apply. The deadline starts after acceptance;
explicit `--timeout` and `--poll-interval` require `--wait`. Timeout must be
positive, and the poll interval must be 1s to 1h (default 2s).

Human output identifies the accepted run and step before status updates.
JSON emits one final run object, or the last observation if waiting stops.
Success exits 0, terminal failure exits 1, timeout exits 124, and Ctrl-C while
waiting exits 130. API errors retain their usual codes. Timeout, cancellation,
and permanent read failures provide a command to continue waiting without
retrying again. A mismatched acceptance response stops and directs you to
inspect the requested run and step attempts before repeating the retry.
Without `--wait`, existing retry output is unchanged. These wait options
apply to the explicit command, not interactive selection.

## Narrow recorded workflow runs by app

`gregale workflow recover --workflow order-processing --app payments-api
--dry-run` filters local recovery records by both workflow and recorded app slug,
on the current profile and API. Omit `--dry-run` to wait, or add `--diagnose`
to inspect that exact run. If several runs still match, use a UUID or unique
prefix from the offered choices; no latest run is guessed. `--app` also works
alone, with `--run`, and with `--list` or `--overview`, but not `--forget`.

The slug must be valid and nonempty. It is compared with saved record metadata;
no linked app, remote app lookup, or app-ID-to-slug lookup is used. Older records
with only an app ID do not match a slug filter; use their explicit UUID without
`--app`. Empty filtered lists/overviews succeed, while unmatched recovery
selectors fail locally. Full-store validation still happens before filtering.
No defaults, linked targets, or records are changed by selection.

App, workflow-name, and UUID completion use validated local records for the
current connection. App completion can be narrowed by a completed workflow
selector; workflow and UUID completion respect the recorded-app filter.
Suggestions and exact-run preview commands preserve app selection. App metadata
is unverified until the normal read action performs its existing identity checks.

## Select the most recently recorded workflow run

`gregale workflow recover --workflow order-processing --app payments-api
--latest --dry-run` selects the most recently recorded local run for that
workflow and recorded app on the current profile/API. Add `--diagnose` to preview
diagnostics, or omit `--dry-run` to observe the selected run. Both explicit
selectors are required unless `--saved-workflow` is used; linked defaults are
never substituted. UUID order, file modification
times, and remote run history are not used.

The same timestamp rules as Job recovery apply: every matching record must have
a valid `recorded_at`, and the newest timestamp must be unique. Matching older
records without timestamps or tied newest timestamps fail before API access,
with exact-run choices preserving the app, workflow, action, and preview flag.
Unrelated workflows, apps, and connections are excluded from selection after
full-store validation. Explicit UUID recovery remains available for older records.

`--latest` excludes `--run`, `--list`, `--overview`, `--forget`, and
`--current-connection`; `--latest=false` keeps normal selection. Actual actions
report the selected record on stderr, using the same
`latest_recorded_run_selected` JSON event as Job recovery. Successful previews
instead return one stdout report with `selection: "latest_recorded"` and an
exact-UUID action command. Existing remote identity checks still apply to real
waits and diagnostic reads. No run is submitted or replayed by selection.

## Reuse project-local workflow recovery selectors

Configure `gregale workflow defaults set order-processing --app payments-api`
once, then preview recovery with
`gregale workflow recover --saved-workflow --latest --dry-run`.
`workflows defaults show` reports the workflow/app pair, preference path, and
copyable preview command; `workflows defaults clear` removes only the preference.
These commands are offline. Set validates selectors but does not require a
matching local record or verify remote existence. A preview still needs an
unambiguous matching record and, with `--latest`, valid unique recording times.

The versioned name/app pair is stored in a private, atomically written
`.gregale/workflows.json` at the nearest linked project root, otherwise Git root,
otherwise working directory. Nested directories inherit it. The file does not
store a connection, credentials, timing, or run settings. JSON is strict and
bounded to 8 KiB; symlinks and nonregular files are rejected. Missing preferences
show as not saved, and clear is idempotent; malformed regular files can be
explicitly cleared. Recovery records and linked app defaults are retained.

`--saved-workflow` is opt-in and excludes explicit `--workflow`, `--app`, and
`--forget`. It works with exact/prefix `--run`, `--latest`, `--dry-run`,
`--diagnose`, `--list`, and `--overview`; their existing option constraints still
apply. Both saved selectors filter records on the current profile/API. There is
no fallback to linked targets when preferences are missing or invalid, and
ordinary/explicit recovery does not read this file. `--saved-workflow=false`
keeps the existing explicit behavior. Empty lists/overviews succeed, while
unmatched saved selectors receive preference-specific guidance.

Preview JSON adds `defaults_path` when the saved selector is used. The offered
action command pins the exact workflow, app, and UUID rather than depending on
preferences at execution time. UUID completion reads the saved pair once and
filters validated local records on the current connection; conflicting app/name
completion stays empty, and context probes do not read preferences. The project
inventory and its `--problems-only` view include workflow recovery preferences,
validating the file format without claiming remote or recorded-run availability.

## Check saved workflow recovery readiness

`gregale workflow defaults show` now checks local accepted-run records for the
saved workflow/app on the current profile/API. It reports the matching count and
whether `--latest` can resolve a unique run. JSON adds `readiness` with status
`ready`, `no_matches`, `missing_timestamps`, `tied_timestamps`, or `unreadable`,
the record-store path, unverified connection details, and `latest_ready`.
Ready reports include `latest_run_id` and `latest_recorded_at`; legacy reports
include the count of matching records without timestamps.

The latest preview command is offered only for ready references. Missing matches
include a current-connection listing command. Missing or tied recording times
include a matching-record listing and a clearly labeled exact-UUID preview
template. Unreadable stores direct users to the local configuration problem
report, omit unknown counts and selected UUIDs, and return nonzero while keeping
the structured stdout report. Missing matches and timestamp limitations remain
advisory (exit zero); explicit UUID recovery may still be possible.

The complete store is validated before filtering, using pinned, regular-file
reads bounded to 8 KiB per record, 1000 JSON records, and 10000 directory entries.
Malformed, oversized, symlinked, or nonregular records and incomplete scans
cannot produce a ready result, even if they would be excluded by selection.
Raw record contents are not displayed on failure. Checks are offline and
read-only; remote identity, status, diagnostics, and access remain unknown.
Missing preferences still report not saved without scanning records. Set
receipts, clear behavior, and the project preference inventory stay unchanged.

## Preview changing workflow recovery defaults

`gregale workflow defaults set order-processing --app payments-api --dry-run`
shows the resolved preference path, current and proposed workflow/app pair, and
local recovery readiness for the proposed pair. No files are written or
directories created, and no API calls occur. Flags can precede or follow the
workflow name. JSON includes `dry_run: true`, `changed: false`, `would_change`,
`before_saved`, `before` (null when absent), `after`, `path`, and `readiness`.
Matching saved selectors report no change needed.

Readiness follows the same bounded full-store validation as defaults show.
Ready proposals include a copyable recovery preview; missing or tied timestamps
include listing and exact-UUID guidance. Every matching-record command uses the
explicit proposed workflow/app, without `--saved-workflow`, so it does not
depend on existing preferences. Missing matches and timestamp limitations are
advisory; unreadable records return nonzero with the structured preview report.
Existing malformed, oversized, symlinked, or nonregular preference files fail
before readiness inspection, without displaying their contents.

Destination write permissions and remote resources are not verified. Omit
`--dry-run` to save; `--dry-run=false` retains normal set behavior and its receipt.

## Complete workflow recovery preferences

Use Tab after `workflows defaults set` or `workflows defaults update` for local
workflow names, or after `--app` for recorded app slugs. Suggestions use only
validated workflow records on the current profile/API; linked targets and remote
app caches are not used. The other supplied selector narrows candidates. Update
uses the saved app when completing a new workflow name, and the saved workflow
when completing a new app unless an explicit replacement is already supplied.

Both `--app SLUG` and `--app=SLUG` support completion, including interspersed
options and `--dry-run`. Update requires valid saved preferences; set works
without them. Missing, malformed, unsafe, or over-limit record stores produce
no suggestions. Context-only shell probes do not read preferences or records.
Completion is offline and read-only; manually typed new selectors remain valid.

## Update one workflow recovery selector

Use `gregale workflow defaults update --app billing-api --dry-run` to change
only the saved app selector, or
`gregale workflow defaults update nightly-report --dry-run` to change only
the workflow name. The omitted selector is preserved. Both can be supplied
together, and at least one must be supplied. Existing valid preferences are
required; use `workflows defaults set NAME --app SLUG` for initial setup.

The offline preview shows before/after selectors and local recovery readiness
for the proposed pair. Generated recovery commands use explicit selectors, so
they work before saving. An unchanged pair reports `would_change: false`.
Remove `--dry-run` to save through the private atomic writer. Saving does not
read recorded runs or contact the API, and remote target existence/access are
not verified. Invalid or unsafe preference files are errors without replacement.

## Preview clearing workflow recovery preferences

Run `gregale workflow defaults clear --dry-run` to see which preference file
and workflow/app selectors would be removed. The preview explains that
`--saved-workflow` will require new preferences and provides a profile-pinned
listing command with explicit selectors, usable after clearing the preference.
Recorded runs and linked targets remain unchanged. The listing is guidance;
the preview does not read the record store or verify that matches exist.

Missing preferences return zero with nothing to clear. Existing preferences must
be valid, regular, nonsymlink files within 8 KiB; unreadable or malformed files
return an error without a partial preview. The command is offline and read-only,
supports `--json` with before/after and removal effects, and creates no directories.
Use `gregale workflow defaults clear` to perform the removal after review.

Source: https://gregale.dev/docs/cli-workflows
