@zuke/gcloud

`@zuke/gcloud` — typed Google Cloud tooling for Zuke builds: the `gcloud`

Symbols

AccessTokenProvider

type

type AccessTokenProvider = unknown

Supplies a Google Cloud OAuth access token for a REST call.

cloudMonitoring

function

function cloudMonitoring(configure: Configure<CloudMonitoringAnalysisSettings>): CloudMonitoringAnalysis

An analysis that reads a Cloud Monitoring metric — or counts log entries — over a recent window and fails the canary when any point is out of bounds, or when there is no data, unless CloudMonitoringAnalysisSettings.missingDataAs says what no data means.

The lambda runs on each check, so it may read resolved parameters, and every failure message — one from the lambda included — passes through the run's redactor.

CloudMonitoringAggregate

type

type CloudMonitoringAggregate = latest | sum | average | maximum | minimum

How CloudMonitoringMetricValueSettings turns the points into one number: the newest, or the sum, average, maximum or minimum of all of them.

CloudMonitoringAligner

type

type CloudMonitoringAligner = ALIGN_NONE | ALIGN_DELTA | ALIGN_RATE | ALIGN_INTERPOLATE | ALIGN_NEXT_OLDER | ALIGN_MIN | ALIGN_MAX | ALIGN_MEAN | ALIGN_COUNT | ALIGN_SUM | ALIGN_STDDEV | ALIGN_COUNT_TRUE | ALIGN_COUNT_FALSE | ALIGN_FRACTION_TRUE | ALIGN_PERCENTILE_99 | ALIGN_PERCENTILE_95 | ALIGN_PERCENTILE_50 | ALIGN_PERCENTILE_05 | ALIGN_PERCENT_CHANGE

How each series' points are aligned into one value per alignment period (aggregation.perSeriesAligner).

CloudMonitoringAnalysis

interface

interface CloudMonitoringAnalysis

A health check run against a canary, in the shape @zuke/canary's c.analysis(...) accepts: throw to fail it, which rolls the rollout back.

Member	Signature	Doc
`validate`	`validate(context: CloudMonitoringAnalysisContext): Promise<void>`	Read the metric and throw when a point is out of bounds.
`name`	`name: string`	`"cloudMonitoring"`, for diagnostics.

CloudMonitoringAnalysisContext

interface

interface CloudMonitoringAnalysisContext

The part of the canary engine's context the analysis uses: the run's redactor, applied to every failure message. The engine hands a richer context; this is the narrow view.

Member	Signature	Doc
`redact`	`redact(text: string): string`	Mask every resolved `secret` parameter in `text`.
`signal?`	`signal?: AbortSignal`	Aborted when the run is cancelled; stops the check between steps.

CloudMonitoringAnalysisSettings

class

class CloudMonitoringAnalysisSettings extends CloudMonitoringTimeSeriesSettings

Settings for cloudMonitoring: the metric — with the same setters as a CloudMonitoringTasks.timeSeriesList read, which these extend — or a log filter, and the bounds.

Member	Signature	Doc
`cloudRunCandidate`	`cloudRunCandidate(service: string, region?: string): this`	Judge only the canary revision of a Cloud Run service: before each check, read the service's latest created revision — the one `cloudRunCanary(...)` staged — with the `.gcloud(...)` flags, and narrow the metric (or the log filter) to `resource.labels.service_name` and `resource.labels.revision_name`. Pair it with `.resourceType("cloud_run_revision")`. A revision deployed by someone else mid-rollout would be read instead; `cloudRunCanary`'s promote refuses that case before moving traffic.
`name`	`name(name: string): this`	What to call the metric when it is out of bounds.
`min`	`min(value: number): this`	Fail when any point is below `value`, a finite number.
`max`	`max(value: number): this`	Fail when any point is above `value`, a finite number.
`missingDataAs`	`missingDataAs(value: number): this`	Judge `value` when the window has no points, instead of failing. Cloud Monitoring writes no point for a period with no events, so for a count of errors no data means `0`; for a latency it usually means the metric, resource or labels are wrong, which is why that is a failure by default.
`logEntries`	`logEntries(configure: Configure<GcloudLoggingReadSettings>): this`	Judge the number of log entries a Cloud Logging filter matches over the window, instead of a metric — `(l) => l.resourceType("cloud_run_revision") .resourceLabel("revision_name", rev).minSeverity("ERROR")`. The window is added to the filter as `timestamp` bounds, and the read runs with the `.gcloud(...)` flags. It counts at most `.limit(n)` entries (default 1000) and fails when more match, since the exact count is then unknown. Only each entry's id is read: no payload reaches the build. A `project` set on the analysis is the read's `--project` too.
`name_?`	`name_?: string`	What the metric is called in a failure (set by `name`).
`min_?`	`min_?: number`	The lowest acceptable value (set by `min`).
`max_?`	`max_?: number`	The highest acceptable value (set by `max`).
`missingData_?`	`missingData_?: number`	The value to judge when there is no data (set by `missingDataAs`).
`logEntries_?`	`logEntries_?: Configure<GcloudLoggingReadSettings>`	The log filter of the log-count mode (set by `logEntries`).
`cloudRunCandidate_?`	`cloudRunCandidate_?: CloudRunService`	The service whose candidate revision is judged (set by `cloudRunCandidate`).

CloudMonitoringLabelled

interface

interface CloudMonitoringLabelled

A type and its labels: a metric, or a monitored resource.

Member	Signature	Doc
`type`	`type: string`	The metric type or resource type.
`labels`	`labels: Record<string, string>`	Its labels.

CloudMonitoringMetricValueSettings

class

class CloudMonitoringMetricValueSettings extends CloudMonitoringTimeSeriesSettings

Settings for CloudMonitoringTasks.metricValue: a time-series read, and how to turn it into one number. The view is always FULL — the reader needs the points.

Member	Signature	Doc
`aggregate`	`aggregate(how: CloudMonitoringAggregate): this`	How to turn the points into one number, across every series the answer holds. `"latest"` (the default) sums each series' own newest point, so a metric split by a label reads as its total. The others combine every point in the window: a `"sum"` of per-minute `ALIGN_SUM` points is the window's total. A `DISTRIBUTION` point reads as its mean. `"average"` weights each mean by its sample count; `"maximum"` and `"minimum"` are of the means. Means cannot be added, so `"sum"` refuses distributions, and `"latest"` refuses more than one distribution series — collapse them with `.crossSeriesReducer(...)`, or align them to a number with `ALIGN_PERCENTILE_99`, `ALIGN_MEAN` and the like.
`missingDataAs`	`missingDataAs(value: number): this`	Return `value` when there are no points, instead of failing. Cloud Monitoring writes no point for a period with no events, so for a count of errors no data does mean `0`; for a latency it usually means the filter is looking in the wrong place.
`aggregate_`	`aggregate_: CloudMonitoringAggregate`	How to turn the points into one number (set by `aggregate`).
`missingData_?`	`missingData_?: number`	The value to return when there are no points (set by `missingDataAs`).

CloudMonitoringPoint

interface

interface CloudMonitoringPoint

One point of a time series: the interval it covers, and its value.

Member	Signature	Doc
`start?`	`start?: Date`	The start of the interval; absent for a `GAUGE` point.
`end`	`end: Date`	The end of the interval — the time the point is for.
`value`	`value: CloudMonitoringValue`	The value.

CloudMonitoringReducer

type

type CloudMonitoringReducer = REDUCE_NONE | REDUCE_MEAN | REDUCE_MIN | REDUCE_MAX | REDUCE_SUM | REDUCE_STDDEV | REDUCE_COUNT | REDUCE_COUNT_TRUE | REDUCE_COUNT_FALSE | REDUCE_FRACTION_TRUE | REDUCE_PERCENTILE_99 | REDUCE_PERCENTILE_95 | REDUCE_PERCENTILE_50 | REDUCE_PERCENTILE_05

How aligned series are combined into fewer (aggregation.crossSeriesReducer).

CloudMonitoringTasks

const

const CloudMonitoringTasks: CloudMonitoringTasksApi

Typed Cloud Monitoring reads.

CloudMonitoringTasksApi

interface

interface CloudMonitoringTasksApi

The shape of CloudMonitoringTasks.

Member	Signature	Doc
`timeSeriesList`	`timeSeriesList(configure?: Configure<CloudMonitoringTimeSeriesSettings>): Promise<CloudMonitoringTimeSeries[]>`	Read the time series the settings describe, every page of them. A series can arrive split across two pages; each part is returned as the API sent it. Fails when the read still has a next page after `.maxPages(n)` pages, rather than return part of the answer.
`metricValue`	`metricValue(configure?: Configure<CloudMonitoringMetricValueSettings>): Promise<number>`	One number from the time series the settings describe: the latest value, or an aggregate of every point in the window.

CloudMonitoringTimeSeries

interface

interface CloudMonitoringTimeSeries

One time series: what it measures, on what, and its points, newest first.

Member	Signature	Doc
`metric`	`metric: CloudMonitoringLabelled`	The metric and its labels.
`resource`	`resource: CloudMonitoringLabelled`	The monitored resource and its labels.
`metricKind?`	`metricKind?: string`	`GAUGE`, `DELTA` or `CUMULATIVE`, as the API reports it.
`valueType?`	`valueType?: string`	`BOOL`, `INT64`, `DOUBLE`, `STRING` or `DISTRIBUTION`.
`unit?`	`unit?: string`	The unit of the points, when the API reports one.
`points`	`points: CloudMonitoringPoint[]`	The points, newest first. Empty for a `HEADERS` view.

CloudMonitoringTimeSeriesSettings

class

class CloudMonitoringTimeSeriesSettings

Settings for a Cloud Monitoring time-series read, configured through CloudMonitoringTasks.timeSeriesList((s) => …).

s.project("my-proj")
  .metricType("run.googleapis.com/request_count")
  .resourceType("cloud_run_revision")
  .resourceLabel("service_name", "api")
  .metricLabel("response_code_class", "5xx")
  .alignmentPeriod("60s").perSeriesAligner("ALIGN_SUM")
  .crossSeriesReducer("REDUCE_SUM")
  .window("15m")

Member	Signature	Doc
`project`	`project(id: string): this`	The project to read from; when omitted, `GOOGLE_CLOUD_PROJECT` (then `GCLOUD_PROJECT`).
`metricType`	`metricType(type: string): this`	The metric to read: `metric.type = "<type>"`, e.g. `"run.googleapis.com/request_count"`. The API reads exactly one metric type per call.
`resourceType`	`resourceType(type: string): this`	Only series on this monitored-resource type: `resource.type = "<type>"`.
`resourceLabel`	`resourceLabel(key: string, value: string): this`	Only series whose resource label `key` is `value`; repeatable.
`metricLabel`	`metricLabel(key: string, value: string): this`	Only series whose metric label `key` is `value`; repeatable.
`filter`	`filter(expression: string): this`	Raw text in the Monitoring filter language, joined with the typed parts by `AND`; repeatable. It is the caller's own text and is not escaped — never build it from an untrusted value. With no `metricType`, it must name the metric itself.
`window`	`window(duration: string \| number): this`	How far back to read (`"15m"`, or ms; default five minutes), ending now — or, with an `alignmentPeriod`, at the last period boundary, so the period still being written is not read. The window must be at least one period long.
`interval`	`interval(start: Date, end: Date): this`	Read exactly this interval instead of a window ending now.
`now`	`now(clock: unknown): this`	The clock the window is read against — the seam a test pins it with.
`alignmentPeriod`	`alignmentPeriod(duration: string \| number): this`	What each aligned point covers (`aggregation.alignmentPeriod`) — `"60s"`, `"5m"`, or ms; whole seconds, at least 60, as the API requires.
`perSeriesAligner`	`perSeriesAligner(aligner: CloudMonitoringAligner): this`	How each series is aligned (`aggregation.perSeriesAligner`).
`crossSeriesReducer`	`crossSeriesReducer(reducer: CloudMonitoringReducer): this`	How aligned series are combined (`aggregation.crossSeriesReducer`).
`groupByFields`	`groupByFields(...fields: string[]): this`	The labels the reducer keeps series apart by (`aggregation.groupByFields`), e.g. `"resource.labels.revision_name"`.
`view`	`view(view: CloudMonitoringView): this`	`FULL` (the default) returns points; `HEADERS` only each series' labels.
`pageSize`	`pageSize(count: number): this`	The most results per page (`pageSize`; the API's default is 100,000).
`maxPages`	`maxPages(count: number): this`	The most pages to read (default 100). A read that still has a next page after that many fails — a partial answer is never returned as a whole.
`delay`	`delay(duration: string \| number): this`	End the window this long before now (`"2m"`, or ms) — for the time a metric takes to become readable. Google's metrics list gives it per metric: Cloud Run's `request_count` and `request_latencies` are "not visible for up to 120 seconds" after sampling. Without it the newest points may not exist yet, or hold only part of their period. Default `0` for a read; the `cloudMonitoring(...)` analysis defaults to two minutes.
`token`	`token(value: string): this`	A pre-resolved OAuth access token.
`tokenProvider`	`tokenProvider(provider: AccessTokenProvider): this`	Resolves the access token, when no `token` is set.
`gcloud`	`gcloud(configure: Configure<GcloudSettings>): this`	Global gcloud flags for the default token read, `gcloud auth print-access-token` — `(g) => g.account("ci@p.iam…")`, or a `.runner(...)`, the seam a test answers through. Unused when a `token` or `tokenProvider` is set.
`fetch`	`fetch(implementation: fetch): this`	The `fetch` the API is called through; the global by default.
`readEnv`	`readEnv(reader: unknown): this`	Reads an environment variable for the project; `Deno.env.get` by default.
`project_?`	`project_?: string`	The project read from (set by `project`).
`metricType_?`	`metricType_?: string`	The metric type (set by `metricType`).
`resourceType_?`	`resourceType_?: string`	The monitored-resource type (set by `resourceType`).
`resourceLabels_`	`resourceLabels_: Array<unknown>`	Resource labels the series must carry (set by `resourceLabel`).
`metricLabels_`	`metricLabels_: Array<unknown>`	Metric labels the series must carry (set by `metricLabel`).
`filters_`	`filters_: string[]`	Raw filter parts (set by `filter`).
`window_`	`window_: number`	How far back to read, in ms (set by `window`).
`interval_?`	`interval_?: unknown`	An explicit interval, instead of the window (set by `interval`).
`alignmentPeriod_?`	`alignmentPeriod_?: number`	The alignment period, in ms (set by `alignmentPeriod`).
`perSeriesAligner_?`	`perSeriesAligner_?: CloudMonitoringAligner`	The per-series aligner (set by `perSeriesAligner`).
`crossSeriesReducer_?`	`crossSeriesReducer_?: CloudMonitoringReducer`	The cross-series reducer (set by `crossSeriesReducer`).
`groupByFields_`	`groupByFields_: string[]`	The labels the reducer keeps series apart by (set by `groupByFields`).
`view_`	`view_: CloudMonitoringView`	How much of each series to return (set by `view`).
`pageSize_?`	`pageSize_?: number`	The page size to ask for (set by `pageSize`).
`maxPages_?`	`maxPages_?: number`	The most pages to read before failing (set by `maxPages`); 100 when unset.
`delay_?`	`delay_?: number`	How far before now the window ends, in ms (set by `delay`).
`token_?`	`token_?: string`	A pre-resolved OAuth token (set by `token`).
`tokenProvider_?`	`tokenProvider_?: AccessTokenProvider`	Resolves the token (set by `tokenProvider`).
`gcloud_`	`gcloud_: Configure<GcloudSettings>`	Global gcloud flags for the default token read (set by `gcloud`).
`fetch_?`	`fetch_?: fetch`	The `fetch` the API is called through (set by `fetch`).
`readEnv_?`	`readEnv_?: unknown`	Reads an environment variable for the project (set by `readEnv`).
`now_`	`now_: unknown`	The clock the window is read against (set by `now`).

CloudMonitoringValue

type

type CloudMonitoringValue = unknown | unknown | unknown | unknown | unknown

One point's value, by the metric's value type. A 64-bit integer is returned as a number — exact up to 2^53, beyond which it rounds — with the decimal string it arrived as beside it.

CloudMonitoringView

type

type CloudMonitoringView = FULL | HEADERS

How much of each series the API returns: its points, or only its labels.

cloudRunCanary

function

function cloudRunCanary(configure: Configure<CloudRunCanarySettings>): CloudRunCanary

A Cloud Run service as a canary platform, for @zuke/canary:

c.platform(cloudRunCanary((r) =>
  r.service("api").region("europe-west1").image(this.image.value)
    .gcloud((g) => g.project("my-project"))
))

The lambda runs on every call, so it may read resolved parameters.

- stage — reads the service's metadata.uid, runs run services update <service> --image <image> --tag canary --no-traffic, then records the service, region, tag, gcloud flags and uid, and the new revision. - expose — run services update-traffic <service> --to-tags canary=<n>. - promote — checks the latest revision is still the candidate, then update-traffic --to-latest. - abort — update-traffic --to-tags canary=0 mid-rollout; run by hand, --to-revisions <stable>=100 to the revision set with .stable(...). A rollback with nothing recorded runs nothing: nothing was staged.

Every call after stage that has its record — expose, promote, and abort mid-rollout — first compares the configured service, region, tag and gcloud flags with the record, then reads the service's uid again, and refuses on any difference before changing anything. A hand-run abort has no record and uses the configuration as it is.

CloudRunCanary

class

class CloudRunCanary

A Cloud Run service as a canary platform. Create one with cloudRunCanary; hand it to @zuke/canary's c.platform(...).

Exposure is a share of requests, set exactly, in whole percents.

Member	Signature	Doc
`describe`	`describe(): string`	`"Cloud Run service api"`, for the build summary.
`stage`	`stage(ctx: CloudRunCanaryContext): Promise<void>`	Read the service's uid, deploy the candidate image as a new revision carrying the tag and no traffic, then record the service, region, tag, gcloud flags and uid every later call is checked against, and which revision the candidate is. `services update` never creates a service, so a misspelt name fails here rather than standing up a second service. A stage run again over a record that shows the candidate tagged is checked against that record first, as every later call is.
`expose`	`expose(percent: number, ctx: CloudRunCanaryContext): Promise<number>`	Send `percent` of the requests to the candidate, through its tag. gcloud spreads the rest over the revisions already serving, in proportion and in whole percents, so a split the service had before the canary keeps its shape only approximately — a revision whose share rounds to 0 drops out. First the configuration is compared with what `stage` recorded, then the service's uid is read again; on any difference this refuses, changing nothing.
`promote`	`promote(ctx: CloudRunCanaryContext): Promise<void>`	Send all traffic to the latest revision — after checking that it is still the candidate this rollout staged, so a revision someone deployed in the meantime is not promoted in its place. The check and the traffic move are two gcloud calls, so a deploy landing in the seconds between them is not caught. Before either, the configuration is compared with what `stage` recorded and the service's uid is read again; on any difference this refuses, changing nothing. Idempotent.
`abort`	`abort(ctx: CloudRunCanaryContext): Promise<void>`	Take the candidate's traffic back. Idempotent. What it does depends on what this rollout recorded: - The candidate is tagged (a rollback mid-rollout): once the configuration and the service's uid match what `stage` recorded, the tag goes to 0 % and gcloud returns that share to the revisions already serving. The candidate revision stays, with no traffic. On a mismatch this refuses, changing nothing. - `stage` failed before tagging it: nothing has any traffic to take back, so nothing runs. - Any other stage marker: the record is damaged, and this refuses. - Nothing recorded, on a rollback (`ctx.reason` is `"rollback"`): nothing was staged, so nothing runs — the stable revision is not even read. - Nothing recorded, run by hand (`rollout.abort` on its own, a fresh run, or an engine that names no reason): all traffic goes to the revision set with `CloudRunCanarySettings.stable`. Without one this refuses, since claiming a rollback it cannot do would be worse.
`exposure`	`exposure: traffic`	Cloud Run splits requests, so exposure is a traffic share.

CloudRunCanaryContext

interface

interface CloudRunCanaryContext

The part of the canary engine's context the Cloud Run platform uses: the rollout's durable state, where the staged revision is recorded, and the build summary. The engine hands a richer context; this is the narrow view.

Member	Signature	Doc
`reportSummary`	`reportSummary(pairs: SummaryPairs): void`	Add key/value pairs to the calling target's row in the build summary.
`state`	`state: TargetStateHandle`	The rollout's durable platform state, shared by every call.
`reason?`	`reason?: rollback \| hand-run`	Why `abort` runs: `"rollback"` when the engine undoes a rollout, `"hand-run"` for `rollout.abort` run on its own. An engine older than this field leaves it out, which is treated as a hand run — the behaviour from before the field existed.

CloudRunCanarySettings

class

class CloudRunCanarySettings

How cloudRunCanary reaches the service, configured through its lambda.

Member	Signature	Doc
`service`	`service(name: string): this`	The Cloud Run service to roll out to. It must already exist.
`region`	`region(value: string): this`	The region the service runs in (`--region`).
`image`	`image(reference: string): this`	The candidate's container image, deployed by `stage`.
`tag`	`tag(name: string): this`	The tag the candidate revision carries, and that every traffic move routes through (default `canary`). Lowercase letters, digits and hyphens, starting with a letter.
`stable`	`stable(revision: string): this`	The revision to send all traffic back to when `rollout.abort` is run by hand. Such a run is fresh, with no record of a rollout, so it has nothing else to go on — and the release it is undoing has usually been promoted already. A rollback the engine runs mid-rollout does not use it: that one takes the candidate's tag back to 0 % instead.
`gcloud`	`gcloud(configure: Configure<GcloudSettings>): this`	Global flags for every gcloud command the platform runs — `(g) => g.project("p").account("deploy@p.iam.gserviceaccount.com")`, or a `.toolPath(...)` to a specific gcloud.
`runner`	`runner(run: GcloudSettingsRunner): this`	Replace how each prepared command is run. The default runs it; this is for a test, or for a build that executes gcloud through something else.
`service_?`	`service_?: string`	The Cloud Run service (set by `service`).
`region_?`	`region_?: string`	The region the service runs in (set by `region`).
`image_?`	`image_?: string`	The candidate's container image (set by `image`).
`tag_`	`tag_: string`	The tag that routes the candidate's traffic (set by `tag`).
`stable_?`	`stable_?: string`	The revision a hand-run rollback returns to (set by `stable`).
`gcloud_?`	`gcloud_?: Configure<GcloudSettings>`	Global gcloud flags for every command (set by `gcloud`).
`runner_`	`runner_: GcloudSettingsRunner`	How each command is run (set by `runner`).

CloudRunService

interface

interface CloudRunService

A Cloud Run service, and the region it runs in when one is named.

Member	Signature	Doc
`service`	`service: string`	The service's name.
`region?`	`region?: string`	Its region (`--region`); gcloud's `run/region` when omitted.

DEFAULT_COUNT_LIMIT

const

const DEFAULT_COUNT_LIMIT: 1000

The most entries the count reader reads when no .limit(...) is set.

gcloudAccessToken

function

async function gcloudAccessToken(run?: GcloudRunner): Promise<string>

The default AccessTokenProvider: the one line gcloud auth print-access-token prints, run with --quiet so the token never streams to the build log. A failed exit is an error even when the runner's settings say .noThrow(), and an empty, multi-line or truncated answer is refused — each would otherwise be sent as a broken token. run defaults to "./gcloud.ts".GcloudTasks .run and is injectable for tests.

GcloudArtifactsImagesDeleteSettings

class

class GcloudArtifactsImagesDeleteSettings extends GcloudSettings

Settings for gcloud artifacts docker images delete.

Member	Signature	Doc
`image`	`image(reference: string): this`	The image or version to delete (positional).
`deleteTags`	`deleteTags(): this`	Delete the version even though tags point at it (`--delete-tags`), which gcloud otherwise refuses.

GcloudArtifactsImagesListSettings

class

class GcloudArtifactsImagesListSettings extends GcloudSettings

Settings for gcloud artifacts docker images list.

Member	Signature	Doc
`repository`	`repository(path: string): this`	The repository or image to list (positional).
`includeTags`	`includeTags(): this`	Include each version's tags (`--include-tags`).
`limit`	`limit(value: number): this`	Return at most this many images (`--limit`).
`filter`	`filter(expression: string): this`	Restrict the listing (`--filter`).

GcloudArtifactsRepositoriesDescribeSettings

class

class GcloudArtifactsRepositoriesDescribeSettings extends GcloudSettings

Settings for gcloud artifacts repositories describe.

Member	Signature	Doc
`repository`	`repository(name: string): this`	The repository to describe (positional).
`location`	`location(value: string): this`	The location it lives in (`--location`).

GcloudArtifactsRepositoriesListSettings

class

class GcloudArtifactsRepositoriesListSettings extends GcloudSettings

Settings for gcloud artifacts repositories list.

Member	Signature	Doc
`location`	`location(value: string): this`	The location to list from (`--location`).
`limit`	`limit(value: number): this`	Return at most this many repositories (`--limit`).

GcloudAuthActivateServiceAccountSettings

class

class GcloudAuthActivateServiceAccountSettings extends GcloudSettings

Settings for gcloud auth activate-service-account.

Member	Signature	Doc
`serviceAccount`	`serviceAccount(email: string): this`	The service account to activate (positional); optional beside a key file.
`keyFile`	`keyFile(path: string): this`	The JSON key to activate it from (`--key-file`).

GcloudAuthConfigureDockerSettings

class

class GcloudAuthConfigureDockerSettings extends GcloudSettings

Settings for gcloud auth configure-docker.

Member	Signature	Doc
`registries`	`registries(...values: string[]): this`	The registries to add a credential helper for (positional, comma separated), e.g. `"us-central1-docker.pkg.dev"`; repeatable.

GcloudAuthListSettings

class

class GcloudAuthListSettings extends GcloudSettings

Settings for gcloud auth list.

Member	Signature	Doc
`filterAccount`	`filterAccount(email: string): this`	Only the named account (`--filter-account`).

GcloudAuthPrintAccessTokenSettings

class

class GcloudAuthPrintAccessTokenSettings extends GcloudSettings

Settings for gcloud auth print-access-token.

Member	Signature	Doc
`forAccount`	`forAccount(email: string): this`	Print the token for this account rather than the active one (positional).

GcloudAuthPrintIdentityTokenSettings

class

class GcloudAuthPrintIdentityTokenSettings extends GcloudSettings

Settings for gcloud auth print-identity-token.

Member	Signature	Doc
`forAccount`	`forAccount(email: string): this`	Print the token for this account rather than the active one (positional).
`audiences`	`audiences(...values: string[]): this`	The audiences the token is minted for (`--audiences`); repeatable. A Cloud Run service invoked service-to-service is the usual reason: the receiving service's URL is the audience, and a token minted without one is rejected there.
`includeEmail`	`includeEmail(): this`	Include the service account email in the token (`--include-email`).

GcloudAuthRevokeSettings

class

class GcloudAuthRevokeSettings extends GcloudSettings

Settings for gcloud auth revoke.

Member	Signature	Doc
`accounts`	`accounts(...values: string[]): this`	The accounts to revoke (positional); repeatable.
`all`	`all(): this`	Revoke every credentialed account (`--all`).

GcloudBuildsDescribeSettings

class

class GcloudBuildsDescribeSettings extends GcloudSettings

Settings for gcloud builds describe.

Member	Signature	Doc
`build`	`build(id: string): this`	The build to describe (positional).
`region`	`region(value: string): this`	The region it ran in (`--region`).

GcloudBuildsListSettings

class

class GcloudBuildsListSettings extends GcloudSettings

Settings for gcloud builds list.

Member	Signature	Doc
`limit`	`limit(value: number): this`	Return at most this many builds (`--limit`).
`filter`	`filter(expression: string): this`	Restrict the listing (`--filter`), e.g. `"status=SUCCESS"`.
`region`	`region(value: string): this`	The region to list from (`--region`).
`ongoing`	`ongoing(): this`	Only builds that have not finished (`--ongoing`).

GcloudBuildsLogSettings

class

class GcloudBuildsLogSettings extends GcloudSettings

Settings for gcloud builds log.

Member	Signature	Doc
`build`	`build(id: string): this`	The build whose log to read (positional).
`stream`	`stream(): this`	Follow the log until the build finishes (`--stream`), which makes the task block for the build's duration rather than returning what exists now.
`region`	`region(value: string): this`	The region it ran in (`--region`).

GcloudBuildsSubmitSettings

class

class GcloudBuildsSubmitSettings extends GcloudSettings

Settings for gcloud builds submit.

Member	Signature	Doc
`source`	`source(path: string): this`	The source to build (positional), e.g. `"."` or a `gs://` archive.
`tag`	`tag(image: string): this`	Build a container and push it to this tag (`--tag`).
`config`	`config(path: string): this`	Build from a config file (`--config`), e.g. `cloudbuild.yaml`.
`pack`	`pack(spec: string): this`	Build with buildpacks (`--pack`), e.g. `"image=gcr.io/p/i"`.
`timeout`	`timeout(value: string): this`	Fail the build after this long (`--timeout`), e.g. `"600s"`.
`machineType`	`machineType(value: string): this`	The machine type to build on (`--machine-type`).
`substitutions`	`substitutions(...pairs: string[]): this`	Substitution values for the config (`--substitutions`); repeatable.
`async`	`async(): this`	Return as soon as the build is queued (`--async`).
`gcsSourceStagingDir`	`gcsSourceStagingDir(uri: string): this`	Stage the source under this bucket path (`--gcs-source-staging-dir`).
`ignoreFile`	`ignoreFile(path: string): this`	Exclude files matching this ignore file (`--ignore-file`).
`region`	`region(value: string): this`	The region to build in (`--region`).

GcloudClustersDescribeSettings

class

class GcloudClustersDescribeSettings extends GcloudSettings

Settings for gcloud container clusters describe.

Member	Signature	Doc
`cluster`	`cluster(name: string): this`	The cluster to describe (positional).
`location`	`location(value: string): this`	The cluster's location (`--location`).
`region`	`region(value: string): this`	The cluster's region (`--region`).
`zone`	`zone(value: string): this`	The cluster's zone (`--zone`).

GcloudClustersGetCredentialsSettings

class

class GcloudClustersGetCredentialsSettings extends GcloudSettings

Settings for gcloud container clusters get-credentials.

Member	Signature	Doc
`cluster`	`cluster(name: string): this`	The cluster to fetch credentials for (positional).
`location`	`location(value: string): this`	The cluster's location (`--location`).
`region`	`region(value: string): this`	The cluster's region (`--region`).
`zone`	`zone(value: string): this`	The cluster's zone (`--zone`).
`internalIp`	`internalIp(): this`	Use the internal endpoint (`--internal-ip`), for a private cluster.
`dnsEndpoint`	`dnsEndpoint(): this`	Use the DNS endpoint (`--dns-endpoint`).

GcloudClustersListSettings

class

class GcloudClustersListSettings extends GcloudSettings

Settings for gcloud container clusters list.

Member	Signature	Doc
`location`	`location(value: string): this`	Restrict to a location (`--location`).
`region`	`region(value: string): this`	Restrict to a region (`--region`).
`zone`	`zone(value: string): this`	Restrict to a zone (`--zone`).
`filter`	`filter(expression: string): this`	Restrict the listing (`--filter`).

GcloudConfigGetValueSettings

class

class GcloudConfigGetValueSettings extends GcloudSettings

Settings for gcloud config get-value.

Member	Signature	Doc
`property`	`property(name: string): this`	The property to read (positional).

GcloudConfigListSettings

class

class GcloudConfigListSettings extends GcloudSettings

Settings for gcloud config list.

Member	Signature	Doc
`all`	`all(): this`	Include properties left at their defaults (`--all`).

GcloudConfigSetSettings

class

class GcloudConfigSetSettings extends GcloudSettings

Settings for gcloud config set.

Member	Signature	Doc
`property`	`property(name: string): this`	The property to set (positional), e.g. `"project"` or `"run/region"`.
`value`	`value(text: string): this`	The value to set it to (positional).

GcloudConfigUnsetSettings

class

class GcloudConfigUnsetSettings extends GcloudSettings

Settings for gcloud config unset.

Member	Signature	Doc
`property`	`property(name: string): this`	The property to clear (positional).

GcloudFunctionsDeploySettings

class

class GcloudFunctionsDeploySettings extends GcloudSettings

Settings for gcloud functions deploy.

Member	Signature	Doc
`function`	`function(name: string): this`	The function to deploy (positional).
`runtime`	`runtime(value: string): this`	The language runtime (`--runtime`), e.g. `"nodejs20"`.
`region`	`region(value: string): this`	The region to deploy into (`--region`).
`entryPoint`	`entryPoint(value: string): this`	The exported symbol to invoke (`--entry-point`).
`source`	`source(path: string): this`	Where the source lives (`--source`).
`triggerHttp`	`triggerHttp(): this`	Trigger on HTTP requests (`--trigger-http`).
`triggerTopic`	`triggerTopic(name: string): this`	Trigger on a Pub/Sub topic (`--trigger-topic`).
`triggerBucket`	`triggerBucket(name: string): this`	Trigger on a Cloud Storage bucket (`--trigger-bucket`).
`triggerEventFilters`	`triggerEventFilters(...filters: string[]): this`	Trigger on matching Eventarc events (`--trigger-event-filters`).
`serviceAccount`	`serviceAccount(email: string): this`	The identity the function runs as (`--service-account`).
`setEnvVars`	`setEnvVars(...pairs: string[]): this`	Environment variables (`--set-env-vars`), as `KEY=value`; repeatable.
`memory`	`memory(value: string): this`	Memory per instance (`--memory`).
`timeout`	`timeout(value: string): this`	Execution timeout (`--timeout`).
`gen2`	`gen2(): this`	Deploy as a 2nd-generation function (`--gen2`).

GcloudFunctionsDescribeSettings

class

class GcloudFunctionsDescribeSettings extends GcloudSettings

Settings for gcloud functions describe.

Member	Signature	Doc
`function`	`function(name: string): this`	The function to describe (positional).
`region`	`region(value: string): this`	The region it runs in (`--region`).
`gen2`	`gen2(): this`	Look it up as a 2nd-generation function (`--gen2`).

GcloudLoggingEntryCountSettings

class

class GcloudLoggingEntryCountSettings extends GcloudLoggingReadSettings

Settings for GcloudTasks.logEntryCount: a gcloud logging read whose matches are counted. .limit(n) is the most entries counted; a count above it fails as "more than n".

GcloudLoggingLogsListSettings

class

class GcloudLoggingLogsListSettings extends GcloudSettings

Settings for gcloud logging logs list: the logs that hold entries.

Member	Signature	Doc
`logView`	`logView(bucket: string, location: string, view: string): this`	List the logs of a log view (`--bucket`, `--location`, `--view`).
`filter`	`filter(expression: string): this`	Keep only matching logs (`--filter`), gcloud's own list filter.
`limit`	`limit(count: number): this`	List at most this many logs (`--limit`).
`sortBy`	`sortBy(...fields: string[]): this`	Sort by these fields (`--sort-by`); prefix one with `~` to descend.

GcloudLoggingReadSettings

class

class GcloudLoggingReadSettings extends GcloudSettings

Settings for gcloud logging read: which entries (the filter), from where (project, folder, organization, billing account, or a log view), and how many.

Member	Signature	Doc
`filter`	`filter(expression: string): this`	Raw filter text in the Logging query language, joined with every other part by `AND`; repeatable. It is the caller's own text and is not escaped — never build it from an untrusted value; use the typed setters for those.
`resourceType`	`resourceType(type: string): this`	Only entries from this monitored-resource type: `resource.type="…"`.
`resourceLabel`	`resourceLabel(key: string, value: string): this`	Only entries whose resource label `key` is `value`; repeatable.
`label`	`label(key: string, value: string): this`	Only entries whose own label `key` is `value`; repeatable.
`minSeverity`	`minSeverity(severity: GcloudLogSeverity): this`	Only entries at `severity` or above: `severity>=ERROR`.
`since`	`since(time: GcloudLogTime): this`	Only entries at or after `time`: `timestamp>="…"`.
`until`	`until(time: GcloudLogTime): this`	Only entries before `time`: `timestamp<"…"`.
`freshness`	`freshness(duration: string \| number): this`	Only entries newer than this — `"1h"`, `"90s"`, or ms — sent as an explicit `timestamp>="<now − duration>"` in the filter, measured from `now`. gcloud's own `--freshness` is not used: gcloud silently drops it whenever the filter's text contains the word `timestamp` anywhere, or the order is `asc`, and the read then spans the whole retention period.
`now`	`now(clock: unknown): this`	The clock `freshness` is measured from — the seam a test pins it with. Either may be set first.
`order`	`order(order: asc \| desc): this`	Newest first (`desc`, gcloud's default) or oldest first (`--order`).
`limit`	`limit(count: number): this`	Read at most this many entries (`--limit`; gcloud's default is unlimited).
`organization`	`organization(id: string): this`	Read from an organization's logs (`--organization`). gcloud takes one of `--organization`, `--folder`, `--billing-account` and `--project`.
`folder`	`folder(id: string): this`	Read from a folder's logs (`--folder`).
`billingAccount`	`billingAccount(id: string): this`	Read from a billing account's logs (`--billing-account`).
`logView`	`logView(bucket: string, location: string, view: string): this`	Read through a log view (`--bucket`, `--location`, `--view`).
`resourceNames`	`resourceNames(...names: string[]): this`	Read from these resources instead (`--resource-names`): a project, folder or organization name, or a full log-view path. gcloud takes these or a log view, not both.
`limit_?`	`limit_?: number`	The most entries to read (set by `limit`).
`freshness_?`	`freshness_?: number`	How long back `.freshness(...)` reaches, in ms (set by `freshness`).
`since_?`	`since_?: GcloudLogTime`	The earliest time `.since(...)` admits (set by `since`).
`now_`	`now_: unknown`	The clock `.freshness(...)` is measured from (set by `now`).

GcloudLogSeverity

type

type GcloudLogSeverity = DEFAULT | DEBUG | INFO | NOTICE | WARNING | ERROR | CRITICAL | ALERT | EMERGENCY

A Cloud Logging severity, lowest to highest.

GcloudLogTime

type

type GcloudLogTime = Date | string

A time a log filter compares timestamp with.

GcloudMonitoringDashboardsListSettings

class

class GcloudMonitoringDashboardsListSettings extends GcloudMonitoringListSettings

Settings for gcloud monitoring dashboards list.

GcloudMonitoringListSettings

class

class GcloudMonitoringListSettings extends GcloudSettings

The list flags every gcloud monitoring … list command takes: --filter, --limit, --page-size, --sort-by and --uri. Each listing extends it and names its own command path.

Member	Signature	Doc
`filter`	`filter(expression: string): this`	Keep only matching items (`--filter`), gcloud's own list filter.
`limit`	`limit(count: number): this`	List at most this many items (`--limit`).
`pageSize`	`pageSize(count: number): this`	How many items to request per page (`--page-size`).
`sortBy`	`sortBy(...fields: string[]): this`	Sort by these fields (`--sort-by`); prefix one with `~` to descend.
`uri`	`uri(): this`	Print each item's resource URI instead (`--uri`).

GcloudMonitoringPoliciesDescribeSettings

class

class GcloudMonitoringPoliciesDescribeSettings extends GcloudSettings

Settings for gcloud monitoring policies describe.

Member	Signature	Doc
`policy`	`policy(idOrName: string): this`	The policy to describe (positional): its id, or its full name `projects/<project>/alertPolicies/<id>`.

GcloudMonitoringPoliciesListSettings

class

class GcloudMonitoringPoliciesListSettings extends GcloudMonitoringListSettings

Settings for gcloud monitoring policies list: the alerting policies.

GcloudMonitoringUptimeListConfigsSettings

class

class GcloudMonitoringUptimeListConfigsSettings extends GcloudMonitoringListSettings

Settings for gcloud monitoring uptime list-configs: the uptime checks and synthetic monitors.

GcloudOutputError

class

class GcloudOutputError extends Error

gcloud or a Google API succeeded but returned something a reader cannot use: output that is not JSON, JSON of an unexpected shape, or a capture that was truncated.

The message never quotes the output itself. A log read can return any payload an application logged, and an error that echoed it would put a secret in the build log.

Member	Signature	Doc
`name`	`name: string`	The error name.

GcloudRunDeploySettings

class

class GcloudRunDeploySettings extends GcloudSettings

Settings for gcloud run deploy.

Member	Signature	Doc
`service`	`service(name: string): this`	The service to deploy (positional).
`image`	`image(reference: string): this`	The container image to deploy (`--image`).
`source`	`source(path: string): this`	Build and deploy from source instead of an image (`--source`).
`region`	`region(value: string): this`	The region to deploy into (`--region`).
`platform`	`platform(value: string): this`	The platform to target (`--platform`), e.g. `"managed"`.
`allowUnauthenticated`	`allowUnauthenticated(): this`	Let unauthenticated callers invoke the service (`--allow-unauthenticated`).
`noAllowUnauthenticated`	`noAllowUnauthenticated(): this`	Require authentication to invoke it (`--no-allow-unauthenticated`).
`serviceAccount`	`serviceAccount(email: string): this`	The identity the service runs as (`--service-account`).
`setEnvVars`	`setEnvVars(...pairs: string[]): this`	Environment variables (`--set-env-vars`), as `KEY=value`; repeatable.
`setSecrets`	`setSecrets(...pairs: string[]): this`	Secret Manager mounts (`--set-secrets`); repeatable.
`memory`	`memory(value: string): this`	Memory per instance (`--memory`), e.g. `"512Mi"`.
`cpu`	`cpu(value: string): this`	CPU per instance (`--cpu`).
`concurrency`	`concurrency(value: number): this`	Requests served concurrently per instance (`--concurrency`).
`maxInstances`	`maxInstances(value: number): this`	Upper bound on instances (`--max-instances`).
`minInstances`	`minInstances(value: number): this`	Lower bound on instances (`--min-instances`).
`port`	`port(value: number): this`	The port the container listens on (`--port`).
`timeout`	`timeout(value: string): this`	Request timeout (`--timeout`).
`tag`	`tag(value: string): this`	Tag this revision (`--tag`), so it is addressable without traffic.
`noTraffic`	`noTraffic(): this`	Deploy without moving traffic to the new revision (`--no-traffic`).

GcloudRunner

type

type GcloudRunner = unknown

Runs a gcloud command — the seam gcloudAccessToken resolves the token through. Defaults to "./gcloud.ts".GcloudTasks .run; injectable so the default provider is unit-testable without invoking gcloud.

GcloudRunServicesDescribeSettings

class

class GcloudRunServicesDescribeSettings extends GcloudSettings

Settings for gcloud run services describe.

Member	Signature	Doc
`service`	`service(name: string): this`	The service to describe (positional).
`region`	`region(value: string): this`	The region it runs in (`--region`).
`platform`	`platform(value: string): this`	The platform it runs on (`--platform`).

GcloudRunServicesListSettings

class

class GcloudRunServicesListSettings extends GcloudSettings

Settings for gcloud run services list.

Member	Signature	Doc
`region`	`region(value: string): this`	The region to list from (`--region`).
`platform`	`platform(value: string): this`	The platform to list from (`--platform`).
`filter`	`filter(expression: string): this`	Restrict the listing (`--filter`).

GcloudRunServicesUpdateSettings

class

class GcloudRunServicesUpdateSettings extends GcloudSettings

Settings for gcloud run services update — amending a service that already exists.

Distinct from GcloudRunDeploySettings on purpose. run deploy creates the service when it is absent and resets settings the invocation does not name; run services update only ever amends an existing one. A deploy that points a live service at a freshly built image wants the second guarantee, and getting the first by accident — a service quietly created, or scaling config quietly dropped — is a worse failure than an error.

Member	Signature	Doc
`service`	`service(name: string): this`	The service to update (positional).
`region`	`region(value: string): this`	The region it runs in (`--region`).
`platform`	`platform(value: string): this`	The platform it runs on (`--platform`).
`image`	`image(reference: string): this`	The container image to point the service at (`--image`).
`updateEnvVars`	`updateEnvVars(...pairs: string[]): this`	Set or overwrite environment variables (`--update-env-vars`), as `KEY=value`; repeatable. Variables the call does not name are left alone — which is the difference from `run deploy`'s `--set-env-vars`.
`removeEnvVars`	`removeEnvVars(...names: string[]): this`	Remove environment variables by name (`--remove-env-vars`); repeatable.
`clearEnvVars`	`clearEnvVars(): this`	Remove every environment variable the service has (`--clear-env-vars`).
`updateSecrets`	`updateSecrets(...pairs: string[]): this`	Set or overwrite Secret Manager mounts (`--update-secrets`), as `KEY=secret:version`; repeatable.
`memory`	`memory(value: string): this`	Memory per instance (`--memory`), e.g. `"512Mi"`.
`cpu`	`cpu(value: string): this`	CPU per instance (`--cpu`).
`concurrency`	`concurrency(value: number): this`	Requests served concurrently per instance (`--concurrency`).
`maxInstances`	`maxInstances(value: number): this`	Upper bound on instances (`--max-instances`).
`minInstances`	`minInstances(value: number): this`	Lower bound on instances (`--min-instances`).
`tag`	`tag(value: string): this`	Tag the revision this update creates (`--tag`).
`noTraffic`	`noTraffic(): this`	Create the revision without moving traffic to it (`--no-traffic`).

GcloudRunUpdateTrafficSettings

class

class GcloudRunUpdateTrafficSettings extends GcloudSettings

Settings for gcloud run services update-traffic.

Member	Signature	Doc
`service`	`service(name: string): this`	The service whose traffic to move (positional).
`region`	`region(value: string): this`	The region it runs in (`--region`).
`toLatest`	`toLatest(): this`	Send all traffic to the newest revision (`--to-latest`).
`toRevisions`	`toRevisions(...splits: string[]): this`	Split traffic across revisions (`--to-revisions`), as `rev=percent`.
`toTags`	`toTags(...splits: string[]): this`	Split traffic across tags (`--to-tags`), as `tag=percent`.

GcloudSecretsVersionsAccessSettings

class

class GcloudSecretsVersionsAccessSettings extends GcloudSettings

Settings for gcloud secrets versions access.

Member	Signature	Doc
`version`	`version(value: string): this`	The version to read (positional); defaults to `latest`.
`secret`	`secret(name: string): this`	The secret to read it from (`--secret`).

GcloudSettings

class

class GcloudSettings extends SubcommandSettings

Settings for a gcloud invocation.

Member	Signature	Doc
`containerImagesAddTag`	`containerImagesAddTag(source: string, ...destinations: string[]): this`	Add tags to a container image across registries: `gcloud container images add-tag <source> <destination…>`. Each argument is a discrete argv token, so an image reference can't inject flags. Runs with `--quiet` (the re-tag is non-interactive automation; `add-tag` otherwise prompts for confirmation).
`sqlInstancesDescribe`	`sqlInstancesDescribe(instance: string): this`	Describe a Cloud SQL instance: `gcloud sql instances describe <instance>`. Add `.format("json")` to get a machine-readable body to parse from the command's stdout.
`sqlOperationsWait`	`sqlOperationsWait(operation: string): this`	Block until a Cloud SQL operation completes: `gcloud sql operations wait <operation>` — the typed form of the poll-an-operation shell loop.
`project`	`project(id: string): this`	Target Google Cloud project (`--project`).
`account`	`account(email: string): this`	Account to run as (`--account`).
`configuration`	`configuration(name: string): this`	Named gcloud configuration to use (`--configuration`).
`format`	`format(value: string): this`	Output format, e.g. `json`, `yaml`, `value(name)` (`--format`).
`verbosity`	`verbosity(level: string): this`	Logging verbosity: `debug`, `info`, `warning`, `error`, … (`--verbosity`).
`noPrompt`	`noPrompt(): this`	Disable interactive prompts, accepting defaults (gcloud's `--quiet`). Named `noPrompt` to avoid clashing with the base `.quiet()`, which suppresses Zuke's own output streaming.
`runner`	`runner(run: GcloudSettingsRunner): this`	Replace how this command is run. The default spawns gcloud; this is the seam a test answers commands through, and the way a build executes gcloud through something else. The runner reads the argv from the settings it is handed and must not call their `run()` — that is the call it replaces.
`run`	`run(): Promise<CommandOutput>`	Run the command — through the `runner` when one is set, otherwise by spawning gcloud. Either way the output is reported to the settings' output hook and a non-zero exit throws a `CommandError` unless `.noThrow()` was called.

GcloudSettingsRunner

type

type GcloudSettingsRunner = unknown

Runs one prepared gcloud command and returns what the process produced. The default spawns gcloud; a test, or a build that executes gcloud some other way, injects its own with GcloudSettings.runner. The runner only produces the output: the exit code is judged afterwards exactly as for a spawned process, so a non-zero code still raises a CommandError unless the settings say .noThrow().

GcloudStorageCpSettings

class

class GcloudStorageCpSettings extends GcloudSettings

Settings for gcloud storage cp.

Member	Signature	Doc
`sources`	`sources(...paths: string[]): this`	The sources to copy (positional); repeatable.
`destination`	`destination(path: string): this`	Where to copy them (positional).
`recursive`	`recursive(): this`	Copy directories and their contents (`--recursive`).
`noClobber`	`noClobber(): this`	Skip objects that already exist (`--no-clobber`).
`contentType`	`contentType(value: string): this`	Set the uploaded objects' content type (`--content-type`).
`cacheControl`	`cacheControl(value: string): this`	Set the uploaded objects' cache control (`--cache-control`).

GcloudStorageLsSettings

class

class GcloudStorageLsSettings extends GcloudSettings

Settings for gcloud storage ls.

Member	Signature	Doc
`paths`	`paths(...values: string[]): this`	The paths to list (positional); repeatable.
`recursive`	`recursive(): this`	Recurse into prefixes (`--recursive`).
`long`	`long(): this`	Include size and creation time (`--long`).

GcloudStorageRmSettings

class

class GcloudStorageRmSettings extends GcloudSettings

Settings for gcloud storage rm.

Member	Signature	Doc
`paths`	`paths(...values: string[]): this`	The objects or prefixes to remove (positional); repeatable.
`recursive`	`recursive(): this`	Remove prefixes and everything under them (`--recursive`).

GcloudStorageRsyncSettings

class

class GcloudStorageRsyncSettings extends GcloudSettings

Settings for gcloud storage rsync.

Member	Signature	Doc
`source`	`source(path: string): this`	The source tree (positional).
`destination`	`destination(path: string): this`	The destination tree (positional).
`recursive`	`recursive(): this`	Recurse into directories (`--recursive`).
`deleteUnmatchedDestinationObjects`	`deleteUnmatchedDestinationObjects(): this`	Delete objects at the destination that the source does not have (`--delete-unmatched-destination-objects`), which makes the destination a mirror rather than a superset.
`exclude`	`exclude(pattern: string): this`	Skip paths matching this pattern (`--exclude`).

GcloudTasks

const

const GcloudTasks: GcloudTasksApi

Typed task functions for the gcloud CLI.

GcloudTasksApi

interface

interface GcloudTasksApi

The shape of GcloudTasks.

Member	Signature	Doc
`run`	`run(configure?: Configure<GcloudSettings>): Promise<CommandOutput>`	Run a `gcloud` command.
`authActivateServiceAccount`	`authActivateServiceAccount(configure?: Configure<GcloudAuthActivateServiceAccountSettings>): Promise<CommandOutput>`	Activate a service account: `gcloud auth activate-service-account`.
`authPrintAccessToken`	`authPrintAccessToken(configure?: Configure<GcloudAuthPrintAccessTokenSettings>): Promise<CommandOutput>`	Print an OAuth access token: `gcloud auth print-access-token`.
`accessToken`	`accessToken(configure?: Configure<GcloudAuthPrintAccessTokenSettings>): Promise<string>`	The OAuth access token itself, read back as a string.
`authPrintIdentityToken`	`authPrintIdentityToken(configure?: Configure<GcloudAuthPrintIdentityTokenSettings>): Promise<CommandOutput>`	Print an identity token: `gcloud auth print-identity-token`.
`identityToken`	`identityToken(configure?: Configure<GcloudAuthPrintIdentityTokenSettings>): Promise<string>`	The identity token itself, read back as a string.
`authConfigureDocker`	`authConfigureDocker(configure?: Configure<GcloudAuthConfigureDockerSettings>): Promise<CommandOutput>`	Register gcloud as a Docker credential helper: `gcloud auth configure-docker`.
`authList`	`authList(configure?: Configure<GcloudAuthListSettings>): Promise<CommandOutput>`	List credentialed accounts: `gcloud auth list`.
`authRevoke`	`authRevoke(configure?: Configure<GcloudAuthRevokeSettings>): Promise<CommandOutput>`	Revoke credentials: `gcloud auth revoke`.
`configSet`	`configSet(configure?: Configure<GcloudConfigSetSettings>): Promise<CommandOutput>`	Set a property: `gcloud config set`.
`configUnset`	`configUnset(configure?: Configure<GcloudConfigUnsetSettings>): Promise<CommandOutput>`	Clear a property: `gcloud config unset`.
`configGetValue`	`configGetValue(configure?: Configure<GcloudConfigGetValueSettings>): Promise<CommandOutput>`	Read a property: `gcloud config get-value`.
`configValue`	`configValue(configure?: Configure<GcloudConfigGetValueSettings>): Promise<string>`	A configured property's value, read back as a string.
`configList`	`configList(configure?: Configure<GcloudConfigListSettings>): Promise<CommandOutput>`	List the active configuration: `gcloud config list`.
`buildsSubmit`	`buildsSubmit(configure?: Configure<GcloudBuildsSubmitSettings>): Promise<CommandOutput>`	Submit a Cloud Build: `gcloud builds submit`.
`buildsList`	`buildsList(configure?: Configure<GcloudBuildsListSettings>): Promise<CommandOutput>`	List builds: `gcloud builds list`.
`buildsDescribe`	`buildsDescribe(configure?: Configure<GcloudBuildsDescribeSettings>): Promise<CommandOutput>`	Describe a build: `gcloud builds describe`.
`buildsLog`	`buildsLog(configure?: Configure<GcloudBuildsLogSettings>): Promise<CommandOutput>`	Read a build's log: `gcloud builds log`.
`runDeploy`	`runDeploy(configure?: Configure<GcloudRunDeploySettings>): Promise<CommandOutput>`	Deploy to Cloud Run: `gcloud run deploy`.
`runServicesDescribe`	`runServicesDescribe(configure?: Configure<GcloudRunServicesDescribeSettings>): Promise<CommandOutput>`	Describe a Cloud Run service: `gcloud run services describe`.
`runServiceUrl`	`runServiceUrl(configure?: Configure<GcloudRunServicesDescribeSettings>): Promise<string>`	The URL Cloud Run assigned a service, read back as a string. Pins `--format` to gcloud's own value projection, so gcloud extracts the field.
`runServicesList`	`runServicesList(configure?: Configure<GcloudRunServicesListSettings>): Promise<CommandOutput>`	List Cloud Run services: `gcloud run services list`.
`runServicesUpdate`	`runServicesUpdate(configure?: Configure<GcloudRunServicesUpdateSettings>): Promise<CommandOutput>`	Amend an existing Cloud Run service: `gcloud run services update`. Unlike `runDeploy`, it never creates the service and never resets settings the call does not name.
`runUpdateTraffic`	`runUpdateTraffic(configure?: Configure<GcloudRunUpdateTrafficSettings>): Promise<CommandOutput>`	Move traffic between revisions: `gcloud run services update-traffic`.
`artifactsImagesList`	`artifactsImagesList(configure?: Configure<GcloudArtifactsImagesListSettings>): Promise<CommandOutput>`	List images in Artifact Registry: `gcloud artifacts docker images list`.
`artifactsImagesDelete`	`artifactsImagesDelete(configure?: Configure<GcloudArtifactsImagesDeleteSettings>): Promise<CommandOutput>`	Delete an image: `gcloud artifacts docker images delete`.
`artifactsRepositoriesList`	`artifactsRepositoriesList(configure?: Configure<GcloudArtifactsRepositoriesListSettings>): Promise<CommandOutput>`	List repositories: `gcloud artifacts repositories list`.
`artifactsRepositoriesDescribe`	`artifactsRepositoriesDescribe(configure?: Configure<GcloudArtifactsRepositoriesDescribeSettings>): Promise<CommandOutput>`	Describe a repository: `gcloud artifacts repositories describe`.
`storageCp`	`storageCp(configure?: Configure<GcloudStorageCpSettings>): Promise<CommandOutput>`	Copy to or from Cloud Storage: `gcloud storage cp`.
`storageRsync`	`storageRsync(configure?: Configure<GcloudStorageRsyncSettings>): Promise<CommandOutput>`	Sync a tree to or from Cloud Storage: `gcloud storage rsync`.
`storageLs`	`storageLs(configure?: Configure<GcloudStorageLsSettings>): Promise<CommandOutput>`	List objects: `gcloud storage ls`.
`storageRm`	`storageRm(configure?: Configure<GcloudStorageRmSettings>): Promise<CommandOutput>`	Remove objects: `gcloud storage rm`.
`clustersGetCredentials`	`clustersGetCredentials(configure?: Configure<GcloudClustersGetCredentialsSettings>): Promise<CommandOutput>`	Write a kubeconfig entry for a GKE cluster: `gcloud container clusters get-credentials`.
`clustersList`	`clustersList(configure?: Configure<GcloudClustersListSettings>): Promise<CommandOutput>`	List GKE clusters: `gcloud container clusters list`.
`clustersDescribe`	`clustersDescribe(configure?: Configure<GcloudClustersDescribeSettings>): Promise<CommandOutput>`	Describe a GKE cluster: `gcloud container clusters describe`.
`functionsDeploy`	`functionsDeploy(configure?: Configure<GcloudFunctionsDeploySettings>): Promise<CommandOutput>`	Deploy a Cloud Function: `gcloud functions deploy`.
`functionsDescribe`	`functionsDescribe(configure?: Configure<GcloudFunctionsDescribeSettings>): Promise<CommandOutput>`	Describe a Cloud Function: `gcloud functions describe`.
`secretsAccess`	`secretsAccess(configure?: Configure<GcloudSecretsVersionsAccessSettings>): Promise<CommandOutput>`	Read a secret version: `gcloud secrets versions access`.
`secretValue`	`secretValue(configure?: Configure<GcloudSecretsVersionsAccessSettings>): Promise<string>`	A secret version's payload, read back as a string.
`loggingRead`	`loggingRead(configure?: Configure<GcloudLoggingReadSettings>): Promise<CommandOutput>`	Read log entries: `gcloud logging read`. What it reads is printed, as gcloud prints it — into the build log unless `.quiet()` is set, and log entries can carry secrets.
`logEntryCount`	`logEntryCount(configure?: Configure<GcloudLoggingEntryCountSettings>): Promise<number>`	How many log entries a `gcloud logging read` filter matches, counting at most `.limit(n)` (default 1000) and failing when more match. Reads only each entry's id, quietly, so no payload reaches the build.
`loggingLogsList`	`loggingLogsList(configure?: Configure<GcloudLoggingLogsListSettings>): Promise<CommandOutput>`	List the logs that hold entries: `gcloud logging logs list`.
`monitoringPoliciesList`	`monitoringPoliciesList(configure?: Configure<GcloudMonitoringPoliciesListSettings>): Promise<CommandOutput>`	List alerting policies: `gcloud monitoring policies list`.
`monitoringPoliciesDescribe`	`monitoringPoliciesDescribe(configure?: Configure<GcloudMonitoringPoliciesDescribeSettings>): Promise<CommandOutput>`	Describe an alerting policy: `gcloud monitoring policies describe`.
`monitoringDashboardsList`	`monitoringDashboardsList(configure?: Configure<GcloudMonitoringDashboardsListSettings>): Promise<CommandOutput>`	List dashboards: `gcloud monitoring dashboards list`.
`monitoringUptimeListConfigs`	`monitoringUptimeListConfigs(configure?: Configure<GcloudMonitoringUptimeListConfigsSettings>): Promise<CommandOutput>`	List uptime checks and synthetic monitors: `gcloud monitoring uptime list-configs`.

GcpRestOptions

interface

interface GcpRestOptions

Common options for a Google REST call: the bearer token and an injectable fetch.

Member	Signature	Doc
`token`	`token: string`	The OAuth access token (see `"./auth.ts".gcloudAccessToken`).
`fetch?`	`fetch?: fetch`	The `fetch` implementation; defaults to the global. Overridable for tests.

GcsListOptions

interface

interface GcsListOptions

Options for GcsTasksApi.list: the auth/transport plus an object-name prefix.

Member	Signature	Doc
`prefix?`	`prefix?: string`	Keep only objects whose name starts with this prefix.

GcsOptions

interface

interface GcsOptions

Auth + transport options common to every GcsTasks call.

Member	Signature	Doc
`token?`	`token?: string`	A pre-resolved OAuth token; when omitted, `tokenProvider` supplies one.
`tokenProvider?`	`tokenProvider?: AccessTokenProvider`	Resolves the token when `token` is omitted (default: `"./auth.ts".gcloudAccessToken`).
`fetch?`	`fetch?: fetch`	The `fetch` implementation; defaults to the global. Overridable for tests.

GcsTasks

const

const GcsTasks: GcsTasksApi

Typed Google Cloud Storage JSON operations.

GcsTasksApi

interface

interface GcsTasksApi

The shape of GcsTasks.

Member	Signature	Doc
`readJson`	`readJson(bucket: string, object: string, options?: GcsOptions): Promise<T>`	Read object `object` from `bucket` and parse its body as JSON.
`writeJson`	`writeJson(bucket: string, object: string, data: unknown, options?: GcsOptions): Promise<void>`	Write `data` (JSON-serialised) as object `object` in `bucket`.
`list`	`list(bucket: string, options?: GcsListOptions): Promise<string[]>`	List object names in `bucket` (optionally filtered by `prefix`).

resolveAccessToken

function

async function resolveAccessToken(options: unknown): Promise<string>

Resolve a bearer token from an explicit token or, when it is omitted, the tokenProvider (defaulting to gcloudAccessToken). Shared by the REST task groups so every call resolves auth the same way. The token is returned trimmed of the whitespace a header drops anyway.

An empty token is refused, and so is one holding a control character after that trim — a line break inside it, or a \v or \f at either end. It cannot be an OAuth token, it is not quoted here, and the runtime's own refusal of such a header value would quote the whole value, token and all, into the error.

RUN_SERVICE_URL_FORMAT

const

const RUN_SERVICE_URL_FORMAT: value(status.url)

The --format the service-URL reader pins, so gcloud does the extraction.

SecretManagerAccessOptions

interface

interface SecretManagerAccessOptions

Options for SecretManagerTasksApi.access: the common options plus a version.

Member	Signature	Doc
`version?`	`version?: string`	The version to access; defaults to `"latest"`.

SecretManagerOptions

interface

interface SecretManagerOptions

Auth + transport + project options common to every SecretManagerTasks call.

Member	Signature	Doc
`project?`	`project?: string`	The Google Cloud project id; when omitted, resolved from the environment.
`token?`	`token?: string`	A pre-resolved OAuth token; when omitted, `tokenProvider` supplies one.
`tokenProvider?`	`tokenProvider?: AccessTokenProvider`	Resolves the token when `token` is omitted (default: `"./auth.ts".gcloudAccessToken`).
`fetch?`	`fetch?: fetch`	The `fetch` implementation; defaults to the global. Overridable for tests.
`readEnv?`	`readEnv?: unknown`	Reads an environment variable for project resolution; defaults to `Deno.env.get`.

SecretManagerTasks

const

const SecretManagerTasks: SecretManagerTasksApi

Typed Google Secret Manager operations.

SecretManagerTasksApi

interface

interface SecretManagerTasksApi

The shape of SecretManagerTasks.

Member	Signature	Doc
`access`	`access(name: string, options?: SecretManagerAccessOptions): Promise<string>`	Access secret `name`'s payload as a string (version defaults to `"latest"`).
`addVersion`	`addVersion(name: string, value: string, options?: SecretManagerOptions): Promise<string>`	Add a new version holding `value` to secret `name`, creating the secret first if it does not exist (an already-exists `409` is ignored) — the write-before-create idempotency a deploy relies on. Returns the new version's resource name.