Deployments, settings and health
Inspect deployments, read settings receipts, and check health in scripts.
On this page
- Guided resource settings
- Guided rollback
- Guided custom-domain setup
- Guided environment promotion
- Guided project linking
- Preview an environment upload
- Browse deployment summaries
- Inspect automatic rollback actions interactively
- Check binding readiness interactively
- Reading the inspection overview
- Understanding a deployment failure from inspect
- Reading deployment readiness
- Going from a failure to evidence
- Checking when saved configuration takes effect
- Understanding empty lists
- Reviewing recent observed changes
- Distinguishing processing from health verification
- Scanning the consolidated inspection output
- Recovering partial configuration operations
- Plain-language settings receipts
- Waiting for recorded health
- Checking health in scripts
- Inspecting the latest deployment
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
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
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
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
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
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
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
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:
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.
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.
Spotted a problem on this page? Tell us