# Deployments, settings and health

> Inspect deployments, read settings receipts, and check health in scripts.

Inspect what is deployed and why it is or is not serving, read what a settings change did, and check health from scripts.

## Guided resource settings

Run `gregale app scale my-api --interactive` to review current settings and
choose a resource profile, instance cap, and minimum warm instances within
your account plan's limits. Add `--environment staging` to edit that
environment's desired workload settings.

The flow previews the changes, compatibility warnings, and available resident
usage estimates. Choose to finish, save a reusable plan to a new file, or apply
after a separate confirmation (default: no). Applying reuses saved-plan checks
and rejects settings that changed since the preview was read.

This mode requires terminal input and output and cannot be combined with JSON,
automation mode, setting flags, or the saved-plan flags. For scripts, use
`scale --plan ... --out plan.json`, then `scale --apply plan.json --confirm`.

## Guided rollback

Run `gregale rollback my-api --interactive` to choose a historical release
from the app's deployment history. The list shows revision (or deployment ID),
creation date, status, and scope. The flow identifies a completed release
serving full traffic in that same scope, then shows the selected release's
summary. Summary changes compare that release with its own predecessor.

Enter an optional reason and confirm (default: no). The request pins both the
selected target and the observed current deployment. The checked rollback API
rechecks artifact availability, deployment state, bindings, and handoff
requirements; a changed current deployment requires a fresh review. The flow
waits for completion and uses the existing operation report to show blockers.
`--timeout` and `--poll-interval` control the wait. Interruption or a wait timeout
does not undo an accepted rollback; use its operation ID with
`gregale rollback status my-api --operation <id> --wait` to continue observing.

This mode requires terminal input and output. For scripts or JSON output,
use explicit `--to` and `--expected-current` flags. The guided mode accepts
only `--timeout` and `--poll-interval` alongside `--interactive`.

## Guided custom-domain setup

Run `gregale domain setup api.example.com --app my-api` to bind a domain,
show the DNS records to publish, and wait for ownership verification and an
unexpired TLS certificate. Add `--environment staging` for an environment
binding. An existing binding is reused only when its app and environment match.

After publishing the records, confirm when to start checking. Pending results
include available DNS and certificate diagnostics. The wait defaults to 10
minutes; `--timeout` accepts up to 1 hour, and `--poll-interval` accepts 5 seconds
to 1 minute. Timeout returns a failure status and prints a command to continue
checking the same binding. Leaving the flow preserves the binding and records.
For app bindings, the flow offers a default-domain change with a separate
confirmation, defaulting to no. Environment bindings keep their environment routing.

Setup requires terminal input and output. For scripts or JSON output, use the
existing `domains add`, `domains verify`, and `domains set-default` commands.

## Guided environment promotion

Run `gregale environment promote my-project --interactive` to choose
source and destination environments. Protected environments are marked in the
list. Choose whether to copy non-secret source configuration; secrets remain
scoped to the destination.

The flow displays the existing promotion preview, including release graphs,
workload changes, configuration changes, and blockers. Confirmation names the
project and both environments and defaults to no. Promotion uses the exact
reviewed preview token and the existing protected-environment approval flow.
Stale previews are rejected by the server and require a fresh review.

After submission, the flow waits and shows promotion progress. Use `--timeout`
to set the wait deadline (seconds or a duration, up to 24 hours). Interruption
or a wait timeout does not undo an accepted promotion. The existing promotion
status command can continue observing its promotion ID.

This mode requires terminal input and output and accepts only `--timeout`
alongside `--interactive`. Scripts retain the existing explicit `--from`,
`--to`, `--sync-config`, `--yes`, `--wait`, and `--progress` options.

## Guided project linking

```sh
gregale link --interactive
# Skip the project chooser when you know the project:
gregale link my-project --interactive
```

Choose a project, default app, and default environment. The flow shows current
checkout defaults and the proposed replacement, marks protected environments,
and asks before saving. You can choose no default app or environment. Selecting
an environment sets the scope used by commands that support linked environment
defaults; protection requirements still apply to future operations.

The guide saves the existing local project context and adds `.gregale/` to the
repository `.gitignore` if needed. Pass `--no-gitignore` to skip that update.
It requires an interactive terminal; for scripts, use
`gregale link PROJECT --app APP --env ENV`. Run `gregale config context get` to
inspect saved defaults or `gregale unlink` to remove them.

## Preview an environment upload

```sh
gregale env push --app my-api --dry-run
gregale env push --app my-api --env staging -f .env.staging --dry-run --restart
```

The preview uses the same input parsing and secret scan mode as `env push`.
It shows the resolved app and scope, keys to add or update, scan findings,
projected app secret usage across all scopes, and how changes would apply.
Values and scan snippets are hidden in both human and `--json` output.
Existing keys are marked as updates; sealed values cannot be compared to detect
unchanged values. Repeated keys are shown in upload order.

The default scan skips detected pairs; strict mode blocks the upload. Invalid
keys, values above the plan limit, exceeding the secret quota, or an input
entirely skipped by the scan produce a nonzero exit status. The JSON preview
includes `can_push`, `changes`, `scan_findings`, and `blockers`.

`--dry-run` reads account and secret metadata but uploads nothing and requests
no restart, even with `--restart`. Remove `--dry-run` to upload. The preview
reflects current metadata; the server validates rules again during the upload.
The `--from-stdin` input option is also supported.

## Browse deployment summaries

```sh
gregale release summary --app my-api --interactive
# Use the linked app, or choose an app when no default is linked:
gregale release summary --interactive
```

Choose a release from recent app history, with revision, status, creation time,
and scope shown for each entry. Choose **Show older releases** to browse the
next page or **Cancel** to exit. The summary shows changes relative to the
preceding release and the reported rollback target. The flow prints an
equivalent command pinned to the selected release ID for reuse.

The guide requires an interactive terminal. For scripts or JSON output, use
`gregale release summary ID --app APP --json`. The history picker reads
release data and does not submit a rollback.

## Inspect automatic rollback actions interactively

```sh
gregale alert actions --app my-api --interactive
# Use the linked app, or pick one:
gregale alert actions --interactive
```

Pick an action from the returned history, ordered newest first and labeled with
its status, rule ID, and fire time. The CLI fetches fresh details for that action
and shows its deployment pair, evidence, blockers, and rollback or service
handoff progress. It prints a reusable inspection command with the active profile.

For a pending or blocked action, choose whether to follow it until completion.
The wait defaults to 10 minutes with a 2-second polling interval; configure these
with `--timeout` and `--poll-interval`. A resume command is printed before waiting.
Interrupting or timing out stops observation; the rollback continues independently.
The flow only reads status and never submits or retries rollback actions.

For scripts, use `alerts actions --app APP --fire UUID [--wait] --json`.

## Check binding readiness interactively

```sh
gregale app binding check --app my-api --interactive
# Use the linked app, or choose one:
gregale app binding check --interactive
```

Choose a live deployment from paginated history. The check stays pinned to its
ID and scope, including live candidates with no traffic. Choose the maximum age
of verification evidence (default 10 minutes), whether to require current
PostgreSQL/object-storage application acknowledgements, and whether to waive
unsupported connectivity coverage for active queue/outbound bindings (default no).

The flow prints a reusable command and the readiness report, including blockers
and runtime freshness. If blocked, optionally wait with the existing read-only
poller. It stops when checks pass or blockers cannot progress through existing
work. Configure the wait with `--timeout` and `--poll-interval`; a resume command
is printed before waiting. The flow does not start probes, rotate credentials,
or restart applications. A deployment that stops being live cannot pass.

For scripts, use `bindings check APP --deployment ID` with explicit flags and
`--json`. Blocked checks return a nonzero exit status.

## Reading the inspection overview

`gregale inspect APP` starts with a short human-readable overview, the main
known reason, and one copyable next command that retains the selected profile.
Known errors take priority, followed by blocked recovery, processing operations,
unavailable information, and warnings. The detailed observations and all
recommendations remain below. “No urgent issues reported” means this snapshot
has no error or warning recommendations; it is not a claim that every route or
workload is healthy. JSON snapshots retain their existing schema and contents.
The same overview appears in human-readable watch snapshots.

## Understanding a deployment failure from inspect

The human-readable `gregale inspect APP` overview includes the selected failed
deployment's persisted cause and recovery instruction when available. It reuses
the existing deployment history response without another request. Each field is
limited to 400 characters; an exact deployment command provides the full details.
A newer failed zero-traffic candidate is labeled separately from the release
still serving traffic. No explanation is inferred when persisted text is absent.
Log excerpts stay in the detailed failure view. JSON summaries retain their
existing fields and schema. Human-readable watch output refreshes the overview
when the persisted explanation changes.

## Reading deployment readiness

Human-readable `deploy --dry-run`, `--diff`, and `--server-diff` previews print a
short readiness overview on stderr before the stable diff on stdout. It shows
the app, connection profile, default target scope, inferred runtime/start command
when available, and the first blocking finding or warning. Named environment
previews remain unsupported; the overview does not imply that another environment
was checked. `--lenient` still changes only the exit-code gate. No findings does
not guarantee a successful build or runtime.

Doctor's human-readable report now leads with its first error (or first warning
when no errors exist), existing recovery instruction, and source location before
the full check list. Existing strictness, checks, and JSON formats are unchanged.

## Going from a failure to evidence

Inspection overviews with persisted deployment failures and `inspect --errors`
include a log command pinned to the failed deployment, including a failed
candidate rather than the serving release. `jobs tasks JOB RUN_ID` prints scoped
log commands for up to three failed/dead-letter tasks, sorted by task index;
other failed task indexes remain in the table. A failed `jobs wait` receipt points
to that task view. Workflow status failures link to diagnostics and the current
step's attempts, or to the step list when no current step is available. These
commands retain the selected profile. Logs may expire; retained Job attempt
outcomes remain a separate evidence source. JSON output is unchanged.

## Checking when saved configuration takes effect

Human-readable `env push` receipts now show the app and scope, a scoped secret
delivery command (env push stores values as sealed secrets), and a command to
follow the requested fresh restart or request one after reviewing the serving
scope. Without a restart, running instances retain their environment until a
cold wake. A saved value does not by itself confirm application acknowledgement.

App-setting and scaling receipts list the saved field names without their values,
identify the app and environment, and include a command to reread that same
configuration. Default app updates also point to current operations through
`inspect`. Routing, scheduling, and boot settings have different application
paths; the update response confirms saved intent, not runtime convergence. Named
environment updates do not confirm a release there. These receipts do not
request extra mutations or change the JSON response format.

## Understanding empty lists

Empty app, deployment, Job, and workflow-run lists now identify the selected
connection profile and offer a copyable next command. Workflow lists echo their
status, name, time, and offset filters. Empty deployment cursor pages are distinct
from an empty deployment history; their next command returns to the newest page.
Job lists distinguish the first page from an offset page. Empty run lists do not
prove that an uncertain submission was rejected. Existing JSON envelopes and
NDJSON output remain unchanged. Completed non-follow runtime log queries with
no returned lines show the app, deployment and filters, with an inspection
command. Filters and retention can limit results; active follow streams and
JSON log output keep their existing behavior.

## Reviewing recent observed changes

Human-readable `inspect` summaries show up to three newest observations from the
already-loaded deployment submissions and pending/failed recovery operations.
Each row identifies its reported status, scope when available, and whether its
UTC timestamp is submission, request, or update time. Missing timestamps are
labeled unavailable. Each row includes a profile-preserving command for that
exact deployment, rollback, or restart. Deployment history remains one command
away. This is partial history, not an audit of all configuration changes, and
nearby timestamps do not establish causation. JSON summaries and JSON watch
contents retain their existing schema; human watch output includes these rows.

## Distinguishing processing from health verification

Human-readable `inspect` output separates deployment-time verification receipts
from production route evidence, including the available evaluation time and
coverage, and provides a profile-preserving default-scope `app APP health`
command. This adds no API request to inspection. Health assessment output names
its serving deployments and request-evidence timestamp when supplied. A reported
healthy assessment is bounded by its scope, timestamp, and validity; this read
uses recorded evidence and does not wake the app or probe every route.

Restart receipts include request/completion timestamps when available and a
copyable next command. Pending operations link to restart status, failed
processing links to inspection, and completed processing links to HTTP health.
Completing a restart does not establish application health. JSON responses and
existing exit codes are unchanged.

## Scanning the consolidated inspection output

The human-readable overview has one primary next command. Persisted failure
recovery and deployment log commands appear below it in a dedicated detail
section. Deployment-check timestamps remain beside runtime evidence; current
route-health timestamps and coverage stay in Current operations, replacing the
separate duplicate Verification section. A primary recommendation's explanation
is not repeated at the end, but its recovery advice remains available. Identical
additional recommendations are deduplicated in human output only. A snapshot
with no urgent recommendations points to the existing HTTP health assessment.
JSON snapshots, observations, and recommendations remain unchanged.

## Recovering partial configuration operations

Human-readable errors for partially completed env pushes, multi-secret updates,
secret removals, and rotations identify confirmed writes separately from an
unconfirmed restart or incomplete acknowledgement. They show confirmed key names
without values and include a scoped metadata command. When a restart identifier
is known, the recovery command targets that exact operation; otherwise it points
to current operations before another restart is requested. Failed writes may have
been accepted despite a transport error, so the guidance does not recommend
repeating the whole operation. Existing JSON receipts and error exit codes remain
unchanged. Deployment submissions retain their existing recovery receipts.

## Plain-language settings receipts

Human app-setting target previews and saved receipts use readable labels such as
“Idle timeout (seconds)” and “Minimum warm instances,” reusing scale-plan labels.
They show names without values and retain explicit zero, false, and reset fields.
An app-level update now says “App-level settings saved” rather than implying a
named `default` environment. Named-environment receipts retain their target.
Request payloads, JSON responses, and saved scale-plan formats are unchanged.

## Waiting for recorded health

```sh
gregale app health my-api --wait --timeout 2m
```

Gregale polls recorded default-scope health every two seconds. Success requires
a `healthy` assessment whose evaluation time is not in the future and remains
within its positive validity window. This does not wake or restart the app or
prove every route and workload is healthy. Transient read failures are retried;
authorization and other permanent request errors stop the wait.

Human progress appears on stderr only when the status, phase, scope, freshness,
or summary changes. `--json` emits one final assessment on stdout. On timeout,
exit code 124 accompanies the last fetched assessment, if any, plus an error on
stderr; that observation may be stale. Cancellation exits 130. Ordinary reads
and history output remain unchanged. `--poll-interval` accepts 1s to 1h; timeout
must be positive. Both options require `--wait`, which excludes history options.

## Checking health in scripts

```sh
gregale app health my-api --check
```

`--check` makes one read of recorded health and exits 0 only when the assessment
is healthy, default-scope, and within its positive timestamp validity window.
Degraded, unhealthy, unknown, stale, future-dated, invalid-timestamp, and other-scope
assessments exit 1. API failures retain their existing error exit codes. The read
has a 30-second deadline and does not wake or restart the app.

The full assessment remains on stdout, including with `--json`; a failed check
also writes a diagnostic to stderr. Use the exit code rather than parsing the
assessment to gate a script. `--check` excludes wait, history, timeout, poll
interval, and history pagination options. Ordinary health reads are unchanged.

## Inspecting the latest deployment

To find failed deployments in history:

```sh
gregale release list --app my-api --failed-only --all
```

`--failed-only` filters fetched history to deployments whose recorded status
is `failed`. It filters one page by default or all pages from the supplied
cursor with `--all`. Page size and cursors describe unfiltered history. Human
output includes exact deployment-detail commands and, for app-scoped reads,
deployment-log commands. Account-wide reads provide detail commands and suggest
`--app` for scoped logs. Next-page commands retain the app, filter, limit, and
wide-output option even when the current page has no failures. JSON preserves
the one-page envelope/cursors or the existing `--all` NDJSON format. Empty
results only describe fetched history and do not establish application health.
The command changes no deployments; ordinary output remains unchanged.

```sh
gregale deployment latest
gregale release wait latest --timeout 2m
```

Use a linked app or supply `--app SLUG`. `latest` selects the newest entry in
that app's deployment history across scopes, including failed or pending
deployments; it does not mean the currently serving deployment. Human output
identifies the selected ID, revision, scope, and recorded status on stderr.

The selection uses one history read and pins the resulting ID for the command,
so a later upload cannot change what a running wait observes. JSON output keeps
the existing deployment response format. Inspection bounds the latest lookup
and initial detail read to 30 seconds; waiting includes lookup in its existing
timeout. Empty history reports how to proceed. This selector is supported by
`deployment latest` and `deployment wait latest`; other deployment operations
continue to require their existing explicit references.

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