Documentation CLI

Logs and saved log views

Filter logs, save and reuse log views, and query archives.

~20 min read
On this page

Read application logs from the terminal, save the filters you use as named views, and query archived logs by instance and date.

Guided log filtering

Run gregale logs my-api --interactive to choose runtime output or HTTP request events, a time window, and filters. Runtime queries offer log level, text matching, and optional following. HTTP queries offer an exact status code and route path and return up to 100 events.

The flow prints an equivalent command for POSIX shells, then asks whether to run it. Declining leaves the command available to copy. App selection uses the explicit target, linked app, or the interactive app picker. --app my-api is also accepted.

This mode requires terminal input and output and accepts only an app target alongside --interactive. Scripts and JSON output retain the existing source, time-window, and filter flags.

Saved log views

Save frequently used filters and reuse them for any explicit or linked app:

sh
gregale logs views save runtime-errors --since 1h --level error
gregale logs my-api --view runtime-errors
gregale logs --view runtime-errors
gregale logs views list
gregale logs views show runtime-errors
gregale logs views delete runtime-errors

The guided logs --interactive flow also offers to save the chosen filters. Names use 1–64 lowercase letters, digits, underscores, or hyphens. Use --replace when saving over an existing name. Views require relative windows such as 15m, 1h, or 3d, recalculated each time you run them.

Views store filter text in log-views.json beside the CLI configuration, with file permissions restricted to the owner. They do not store app targets, credentials, or log output. Runtime views support level, text, and follow; HTTP views support status, route, and page size. Supply an app target and compatible one-off overrides alongside --view; add --dry-run to preview them without changing the saved view. Update the view to persist filter changes.

Read logs for the latest failed deployment

Run gregale logs --latest-failure in a linked project, or gregale logs my-api --latest-failure with an explicit app. This read-only, noninteractive shortcut selects the newest failed deployment from app-scoped history, including failures without a typed error code. It resolves the target once and reads at most 500 recent retained build/deploy entries for that exact ID. A newer successful deployment does not replace the selected failure.

Selection uses app deployment history without an environment filter; the receipt states that scope, the connection profile, exact deployment, source, and limit. Deployment creation time is labeled separately from the unknown failure time. The endpoint has no time-window selector. This shortcut does not inspect runtime crashes or HTTP request failures, and does not automatically query runtime logs. It accepts only an app target alongside --latest-failure; other filters, saved views, follow, and archive modes are rejected before API access.

An empty log result points to deployment get ID for persisted evidence. It does not claim that retention expired or that nothing executed. No failed deployment exits 1; unreadable or incomplete history fails without switching to live logs. History search is bounded to 50 pages with repeated-cursor protection, and the whole read has a 30-second deadline (exit 124) with interrupt support (exit 130).

With --json, stdout is newline-delimited JSON: a selected metadata receipt, log records containing the exact deployment ID and line, and a completion summary. API/stream failures exit nonzero without a success summary.

Find the latest recorded HTTP server error

gregale logs --latest-request-error searches the linked app's retained HTTP request telemetry for the newest recorded 500–599 response. The default window is 15m; use --since 1h (or an RFC3339 start) and optionally --route /checkout. An explicit app is accepted positionally or through --app. Other log filters, views, follow, archive, and deployment-failure selection are rejected before API access. The HTTP source is implicit.

Selection inspects up to 50 pages of 200 rows under a 30-second deadline, pins the server's window across cursor pages, and then looks up the exact selected public request ID or telemetry row ID. It verifies that the lookup matches the selected identity, route, status, and timestamp. It never substitutes an older row when identifiers, coverage, or matching evidence are unavailable. Incomplete coverage, repeated cursors, invalid error timestamps, changed windows, and the page cap fail rather than claiming a newest result.

Human output states the requested/effective window, retention clamp, route, status, IDs, timestamp, and represented-request count. No matching retained 5xx row exits 1 and explains that absence does not establish every request was captured or succeeded. Aggregated telemetry rows may represent multiple requests; this shortcut reads HTTP request telemetry, not raw runtime logs or request payloads. JSON emits one selection receipt followed by the existing canonical HTTP log record. No matching row emits only the selection receipt. Reads make no writes, deployments, retries, or recovery actions.

Save a latest-request-error log view

Create a reusable error search with gregale logs views save recent-server-errors --latest-request-error --since 1h --route /checkout. Run it with gregale logs --view recent-server-errors (linked app) or gregale logs my-api --view recent-server-errors (explicit app). The existing saved-view store, show/list/delete commands, and --replace behavior are reused. No app, request ID, or connection is pinned in the view: each invocation uses its current app and connection and finds the newest recorded 5xx in the saved window.

The selector implies HTTP; optional --source http is accepted. Saved error views accept only a positive relative --since, optional route, and replace; status, limit, follow, grep, level, and runtime source are rejected. Existing runtime and HTTP views retain their behavior and version-1 file compatibility. The view stores a latest_request_error selector alongside its window/route, not a second defaults file. Human execution identifies the saved view and filters; normal selection output reports the effective retained window. JSON keeps the latest-error selection receipt and canonical HTTP log record.

Understand and run saved log views from the list

gregale logs views list now describes each saved view's purpose: runtime logs, HTTP requests, or latest HTTP error. The human list shows the relative window and applicable route, level, grep, HTTP status/page size, and follow filters, plus a POSIX run command using the view name and current connection profile. Commands use the linked app; add --app APP_SLUG to select another app explicitly. Listing never executes a view or makes API requests.

The sorted JSON list remains an array of names for compatibility. Use logs views show NAME --json for the saved selector and full filter details. Existing empty-list guidance, storage, and show/save/delete behavior remain unchanged. Relative windows are recalculated when the view is run.

Update one saved log-view filter

gregale logs views update recent-server-errors --since 3h changes the saved window while preserving its selector, route, and omitted settings. Update requires an existing view and validates the complete resulting definition before saving. The source and latest-error selector stay unchanged; use save --replace when intentionally rebuilding a view of another type.

Use --clear-route, --clear-grep, or --clear-level to remove a filter, and --follow=false to turn off following. Normal HTTP views also support --status 0 to clear status filtering and --limit N to change page size. Latest-error views accept only window and route changes, keeping their existing filter rules. Setting and clearing the same filter, empty operations, incompatible filters, and extra arguments fail without modifying storage.

Human and JSON receipts show before/after settings, whether anything changed, and the store path. Other views remain untouched. A no-op preserves the file; changed views are re-read before the atomic private write to detect intervening edits. Updating performs no API requests and never executes a view. Existing save, show, list, delete, and JSON-list compatibility remain unchanged.

Preview a saved log-view update

gregale logs views update recent-server-errors --since 3h --dry-run validates the proposed view and shows its before/after filters and resulting run command, without modifying storage or querying logs. Omitted fields, view type, explicit clear options, and incompatible-filter validation follow normal update rules. Use show NAME to inspect a view when no update is intended.

JSON adds dry_run: true, would_change, and run_command, with changed: false and after containing the proposed definition. Normal updates also include would_change and the command. The printed command uses inline proposed filters rather than --view NAME, because that name still refers to the old saved definition during a preview. It preserves the selected profile explicitly, uses the linked app, and can take --app APP_SLUG for an explicit target. Nothing executes automatically. Remove --dry-run from the update to save it.

Rename a saved log view

gregale logs views rename recent-server-errors production-errors moves the existing definition to an unused name, preserving every selector and filter. Other views remain unchanged. Missing sources, invalid names, identical names, and existing destinations fail without writing. Renaming re-reads the store before the existing atomic private write to detect intervening edits.

Human and JSON receipts identify the old/new names, preserved definition, store path, and run command with the selected profile. The command uses the linked app; add --app APP_SLUG to select one explicitly. No app or environment is changed by naming a view, and no log query or API request occurs. Existing show/list/update/delete commands use the new name after a successful rename.

Preview a log query offline

Use logs --view errors --dry-run or logs --app my-api --source http --status 500 --since 1h --dry-run to inspect the effective app, source, and validated filters without authentication or remote reads. Human and JSON output distinguish explicit flags/names, saved view filters, linked app targeting, CLI defaults, and inferred selection rules. Saved views accept an app target, --dry-run, and compatible one-off filter overrides. No interactive picker is opened by a preview. Logs are app-scoped: a linked environment does not filter these queries. Runtime lookbacks are normalized to timestamps; HTTP lookbacks retain their query duration. Deployment revisions/latest references, server defaults, retention, and runtime/build-log routing remain unresolved. Archive and latest-failure/latest-request-error selectors can also be previewed without selecting remote records. JSON includes dry_run, app, profile, environment_scope, mode, source, filters, setting_sources, notes, and optional saved view metadata. The existing log-query validation still applies. Omit --dry-run to execute the query through its existing path.

Override saved log filters for one query

logs --view errors --since 15m --dry-run uses the saved view with an explicit window override. Remove --dry-run to execute the same effective query; the saved view is never rewritten. Runtime views support since, grep, level, and follow overrides; ordinary HTTP views support since, route, status, and limit. Latest-request-error views support only since and route. App targeting remains independent. View source and selection type cannot be changed. Explicit empty --grep=, --level=, or --route= clears that filter for this query; --follow=false disables saved follow mode. Existing query validation still applies, including HTTP status 100..599 and page limits 1..200. Temporary windows may use RFC3339 timestamps as well as relative durations. Previews mark overridden values as explicit_flag while inherited filters remain saved_view.

Temporarily remove a saved HTTP status filter

logs --view http-errors --clear-status --dry-run previews the saved query without restricting it to the saved status code. Remove --dry-run to query all statuses with the remaining filters. The saved view is unchanged. --clear-status requires an ordinary HTTP view, excludes explicit --status, and is unavailable for runtime or latest-request-error views. --clear-status=false keeps the saved status filter. Clearing an already unfiltered HTTP view is valid. Preview JSON marks status as explicit_flag, uses filters.status: 0 for no status restriction, and adds view.cleared_filters: ["status"]; human output labels it as all HTTP statuses.

Clear saved text filters for one log query

logs --view errors --clear-grep --clear-level --dry-run removes saved text and level restrictions from the preview. --clear-route removes a saved route restriction from ordinary HTTP or latest-request-error views. These options require a compatible saved view, conflict with their corresponding explicit filter flags, and leave the saved file unchanged. False clear flags leave the saved filters in place. Clearing an already-empty filter is valid. Preview JSON lists cleared fields under view.cleared_filters, with empty filter values marked explicit_flag; human output labels the cleared restrictions. Empty overrides such as --grep= still work. Omit --dry-run to query through the same validated path with the saved restrictions removed for that invocation.

Copy the effective log query from a preview

Log previews now include a POSIX-shell quoted query_command in JSON and a copyable human command. It pins the app and selected profile, expands saved filters, applies overrides/clears, and omits view, clear, and dry-run flags. Changes to the saved view cannot change the copied query’s filters. Relative windows stay relative and are recalculated when the command is run; explicit timestamps and unresolved deployment references are preserved. Runtime, HTTP, archive, and latest-error selectors keep their query mode. The command uses the selected profile’s configured connection with any API environment override still applying; no connection or remote resource is verified by the preview. Commands are shown for review and never executed automatically.

Validate archived-log instance IDs before querying

Archive queries and --dry-run previews validate --instance locally using the server’s exact format: 1..128 ASCII letters, numbers, dots, underscores, or hyphens. IDs do not have to be UUIDs. Spaces, slashes, non-ASCII characters, and longer IDs fail with format guidance before app selection, authentication, or network access. The instance value is not trimmed or rewritten; valid IDs and UTC-date behavior are unchanged. Local format validation does not establish instance ownership, archive availability, or retention.

Use UTC archive date shortcuts

logs --archive --instance INSTANCE --date yesterday --dry-run resolves the previous UTC day locally. --date today selects the current UTC day. Previews show the resolved YYYY-MM-DD date, and the copyable query command pins that date rather than retaining the shortcut. Without a preview, the shortcut resolves when the query starts. Local timezone settings do not change the result. Existing explicit YYYY-MM-DD dates remain supported and validated; invalid dates fail before authentication or network access. Format validation does not establish archive availability or retention.

Preview archives from the instance history list

ps --all now includes copyable archive-preview commands for each instance with a valid archive ID. Each command pins the app and current profile and uses --date yesterday --dry-run; running the preview resolves the previous UTC day locally without reading an archive. Instance listing does not establish archive availability, retention, or plan access. JSON remains NDJSON and preserves existing instance fields, adding archive_preview_command and archive_availability: "not_checked" when --all is used. Commands are omitted for IDs or app targets that fail archive query validation. Ordinary ps output, empty-list behavior, and the history cap are unchanged. The listing makes no additional API calls and executes none of the suggested commands.

Complete filters compatible with the selected log view

After logs --view errors --, shell completion reads the selected view locally and suggests compatible runtime or HTTP filters and clear flags. Latest-error views suggest only since/route filters plus app, view, and dry-run options. Both --view NAME and --view=NAME work; repeated selectors use the last name. Flag values are consumed as data and are not treated as view selectors. Unknown, missing, malformed, or unreadable saved views fall back to ordinary completion. Value completion remains unchanged. Bash, Zsh, Fish, and PowerShell use the shared local helper; no credentials or remote API calls are needed. Reload or regenerate the Fish completion script to enable its static-flag suppression rule for recognized saved-view flag positions.

Avoid conflicting log-view options during completion

Saved-view flag completion now omits a filter when its clear flag is enabled, and omits the corresponding clear flag when the filter was explicitly provided. This applies to grep, level, route, and status. Explicit empty filter values count as supplied. --clear-grep=false allows grep suggestions again; repeated clear flags use their last boolean value, matching command parsing. Only completed flags are considered, and values that resemble flags remain data. Saved filters alone do not suppress overrides or clears. Command-side validation remains authoritative, and completion stays offline.

Preview directly from saved-view listings

logs views list now shows a copyable preview command beside each query command, for example gregale --profile default logs --view errors --dry-run. Listing is offline and never runs the suggested commands. Previews use the linked app or an explicit app override and do not verify remote access. gregale --json logs views list --details returns sorted objects with name, view, run_command, and preview_command. The existing JSON names array remains the default (--details=false also retains it). Empty detailed listings are empty arrays. Each command retains the selected connection profile.

Target saved-view listing commands at an app

logs views list --app my-api includes the explicit app in each query and preview command, without resolving project links or calling the API. --app must be a valid nonempty slug; it is not saved into the view. --details JSON entries add the explicit app (when supplied) and app_verified: false. The default JSON names array remains unchanged even with --app. Without the flag, generated commands retain their existing linked-app behavior. Listing and preview do not establish app existence or access.

Complete the app target in a saved-view listing

logs views list --app <TAB> and logs views list --app=prefix<TAB> now use the shared local completion helper to suggest cached app slugs. The inline form retains the --app= prefix. Suggestions are validated, sorted, and deduplicated; --details may precede app targeting. The current connection’s credential-bound cache is used, or the explicit FAAS_COMPLETION_CACHE_PATH override. No remote refresh or app verification is performed. Missing, unreadable, malformed, oversized, or unsupported-version caches produce no suggestions. The context probe does not read the cache. Reload generated completion scripts, especially Fish, for the updated rules.

Inspect one view with targeted preview guidance

logs views show errors --app my-api shows saved filters plus copyable query and preview commands for that explicit, unverified app. Without --app, the commands use linked-app targeting. App flags may precede or follow the view name and are validated locally; no API calls or saved-file changes occur. --details JSON uses the same name/view/app/app_verified/run_command/ preview_command fields as detailed listings. The default JSON saved-filter object is unchanged, including when an app target is supplied. Unknown-name corrections retain app targeting and details options.

Complete a view name after show options

logs views show --app my-api --details <TAB> now completes saved view names after the completed options. Inline app values and boolean details values work too; an unfinished app value is left to app completion. Only the first view-name position is completed. Option values are consumed as data, so flag-looking values cannot become options or view names. The existing name-first form remains supported. Completion stays offline, and its context probe does not read saved files.

Complete app targets while inspecting one saved view

logs views show errors --app=prefix<TAB> and the spaced --app <TAB> form now share the listing’s bounded, validated local cache reader. Options may appear before or after the view name, and --details is supported. The helper accepts at most one completed view name and consumes app values as data. Cache isolation, sorted/deduplicated suggestions, missing/invalid-cache behavior, and the read-free context probe are unchanged. Completion performs no API calls.

Find saved views by log source

logs views list --source http --app my-api lists only HTTP views, including latest-request-error views. --source runtime selects runtime views. Filtering works in human output, the default JSON names array, and --details JSON entries. App-targeted commands and their preview metadata remain available; source filtering does not change any stored view. Omit --source to list all views. Only runtime/http are accepted, and empty matches remain valid empty arrays with explanatory human guidance. Listing remains offline; the full saved store is still validated. App completion continues to work after source options.

Find saved log views by part of their name

logs views list --name checkout selects views whose names contain that literal, case-sensitive text. Combine it with --source, --app, and --details; name and source filters both must match. JSON retains its sorted names-array or detailed-entry shape, and empty matches are valid empty arrays. No glob or regular-expression matching is performed. Empty or blank-only filters are rejected; omit --name to list without a name filter. Repeated filters use their last value. Listing remains offline and read-only, and app completion works after completed name filters.

Inspect the configured connection in log previews

logs --view errors --dry-run now includes configured profile/API details with their sources, including a FAAS_API override. JSON adds connection with profile, profile_source, api_base, api_source, verified (false), and address_redacted, while preserving the existing profile field. The same shared offline formatter is used by Job previews. API URL credentials, query strings, and fragments are hidden; malformed addresses are not displayed. Configuration is not changed, and no credentials, app access, API health, or remote logs are checked. Runtime, HTTP, archive, and latest-error previews all include this metadata. Copyable commands retain their existing profile targeting and API-environment-override behavior.

Reuse a project-specific preferred log view

Configure an existing saved view with logs defaults set errors, then preview it with logs --saved-view --dry-run. logs defaults show reports the stored name, absolute file path, and preview command; logs defaults clear removes only the preference and is idempotent. The versioned .gregale/logs.json stores only the view name, using the same nearest project/Git/cwd root as Job defaults and a private atomic write. Readers reject malformed, unknown-field, oversized (over 8 KiB), symlink, or nonregular defaults files. The selector is opt-in: plain logs and explicit --view do not read or apply the preference. --saved-view excludes --view, other latest selectors, and interactive selection. Compatible overrides and clear flags work as before. Missing preferences or deleted/renamed referenced views fail locally with reconfiguration guidance; no alternate view is selected automatically. Current global view filters are loaded when used, and existing app/profile/API targeting remains unchanged. Preview metadata includes view.defaults_path and marks the view selection as project_defaults, while filter origins remain saved_view or explicit_flag. Copyable query commands expand the effective filters and do not depend on the preference. Local configuration summaries include the new defaults file. Default-set name completion and saved-view compatible flag completion use local files only.

Check the preferred view reference before querying

logs defaults show now reports whether the preferred view exists in the local saved-view store, its source and latest-error mode, and the saved-view file path. JSON adds reference with status available, missing, or unreadable. Missing references include a list command and a clearly labeled reconfiguration template; unreadable stores identify the file to review without displaying invalid contents. Preview commands are offered only for available references. Show returns nonzero for missing/unreadable references while retaining the structured report. Missing preferences still report not saved successfully. Set receipts and clear behavior are unchanged. All checks are local; no view existence or availability is established on the remote API, and no defaults or view files are rewritten automatically.

context --local-config includes the same reference check whenever a valid log preference is saved. Its log-defaults row keeps the preference file and saved-view store separate: configured means the reference is available; broken_reference means the preference file is valid but its view is missing or the store is unreadable. JSON includes the reference details, sets valid to false, and returns nonzero for broken references. Human output shows the store path, inspection command, and replacement template when applicable. Missing optional preferences remain successful, and invalid preference files retain their existing validation guidance. This check is offline and read-only.

Preview a preferred log view before saving

Run gregale logs defaults set errors --dry-run to inspect the resolved preference path, before/after view names, and selected filters without writing files. The copyable log-preview command uses --view errors directly, so it works before the preference is saved; add --app SLUG if no app is linked. Flags can appear before or after the name. JSON reports dry_run, changed (false), would_change, before_saved, before, after, filters, and preview_command. Matching preferences report no change needed. Existing malformed or unsafe preference files must be reviewed before previewing. The command reads local configuration only and does not check remote app access or guarantee that the destination is writable. Omit --dry-run to save.

Show only local configuration problems

Use gregale config context get --local-config --problems-only for a compact check of invalid configuration files, broken preferred-log-view references, and damaged or incompletely scanned recovery stores. The same full offline validation runs before filtering, and the exit status is unchanged. Missing optional files and healthy entries are omitted. A healthy project prints “No local configuration problems found”; remote resources and health are still not checked.

JSON includes problems_only: true, the project root, the overall valid result, and a files array containing only problem entries. recovery_records is included only when that store has a problem. Healthy reports contain an empty files array. Inspection and explicit repair guidance is retained, and no files are changed. --problems-only requires --local-config; omit it for the complete inventory.

Preview clearing a preferred log view

gregale logs defaults clear --dry-run shows the resolved preference path, current view name, and the effect of removing the preference. It does not delete files or read the global saved-view store, so deleted views and broken view stores do not prevent this preview. Missing preferences succeed with “nothing to clear.” JSON reports dry_run: true, changed: false, cleared: false, would_change, before_saved, before, after: null, and effects. Existing malformed, oversized, or unsafe preference files are rejected without displaying their contents. Ordinary clear can still explicitly remove a malformed regular preference file. Omit --dry-run to remove the preference; saved views remain available via logs --view NAME. All preview checks are offline and read-only.

Inspect preferred log filters in one command

gregale logs defaults show now includes the preferred view's current saved filters: its relative time window and active runtime or HTTP filters. The existing source and latest-error mode identify the query type. JSON adds filters using the saved-view format, only when the reference is available. The filters and reference status come from the same validated local snapshot; editing a saved view is reflected on the next show. Missing or unreadable references retain their repair guidance and do not display filters or a preview command. Set receipts and the project inventory JSON remain unchanged. This does not check remote logs or apply one-off query overrides.

gregale logs defaults show --app payments-api targets the generated preview command at that app without changing the preferred view or linked app. The slug is validated locally; existence and access are not checked. JSON adds app and app_verified: false only when an app is supplied. Missing preferences and broken references still omit preview commands, while retaining the requested target metadata. App completion uses the existing local cache for spaced and inline --app values. All inspection remains offline and read-only.

Spotted a problem on this page? Tell us