CLI

Run builds and manage cache

The CLI is the entrypoint for most teams. Run boringcache onboard once per repo, then use archive mode or the adapter named after your build tool.

workspace = "my-org/app"

[proxy]
metadata-hints = ["project=web"]

[entries.bundler]
tag = "bundler-gems"

[profiles.bundle-install]
entries = ["bundler"]

[adapters.bazel]
tag = "bazel-cache"
metadata-hints = ["tool=bazel", "lane=ci"]

[adapters.docker]
tag = "docker-cache"
command = ["docker", "buildx", "build", "."]

[entries.build-output]
path = "build"
exclude = ["*.tmp", "scratch/"]

[profiles.build]
entries = ["build-output"]

# Archive mode (run/save/restore)
boringcache run -- bundle install

# Docker adapter from repo config
boringcache docker

boringcache run --profile bundle-install -- bundle install
boringcache run -- bundle install

Authentication

Most projects should start with boringcache onboard, which connects the CLI to a workspace for the repo. Use boringcache login --email you@example.com for account sign-in on a developer machine. CI platforms with workload OIDC can use a Machine connection instead of storing a BoringCache token. If workload OIDC is unavailable, scoped restore and save credentials remain a supported explicit choice.

With CLI and Action 1.32.0 or later, a Machine connection supplies its approved workspace. An explicit workspace must match it. Local and scoped-token runs keep the repository workspace or configured default; an explicit workspace can override it.

For organizations that require SSO, browser approval issues human CLI credentials that expire with the organization SSO grant, up to eight hours. Sign in again to issue a new credential. Use an approved machine credential or workload identity for CI. See organization SSO.

A CI without a native BoringCache adapter can enroll an exact provider profile with --oidc-profile and submit one fresh ID token from a bounded regular file with --oidc-token-file. Run boringcache onboard with --skip-workflows --manual, then approve the printed URL from any browser. Approval can authorize the exact workload to restore and publish, or deliberately keep it restore-only when the identity is shared with untrusted jobs. A failed OIDC path never falls back to a static CI credential and never creates one.

You can start the same transaction from a Workspace by choosing Connect CI. Pick OIDC, explicit scoped restore/save credentials, or local CLI only. GitHub Actions, Buildkite, CircleCI, GitLab.com, and BoringBuild route to a native command with no BoringCache secret: run boringcache ci connect inside the CI job, open its verification URL on any signed-in device, and choose the Workspace. The server delivers the one-time enrollment only to the waiting job and the CLI keeps it in memory while it submits the provider assertion. A registered OIDC issuer or automated setup can still use the explicit one-time value through standard input with --oidc-token-command. Completion posts once without retry and prints no credential or assertion.

permissions:
  contents: read
  id-token: write
steps:
  - name: Connect BoringCache once
    run: boringcache ci connect --oidc-provider github-actions

steps:
  - label: Connect BoringCache once
    command: boringcache ci connect --oidc-provider buildkite

version: 2.1
jobs:
  connect-boringcache:
    docker:
      - image: cimg/base:current
    steps:
      - checkout
      - run: boringcache ci connect --oidc-provider circleci

# Run once in a BoringBuild job with id-token: write,
# then approve the printed URL and choose the Workspace.
boringcache ci connect --oidc-provider boringbuild

BoringBuild enrollment is a one-time bootstrap job. Its controller gives that job a short-lived assertion endpoint; BoringCache verifies the exact BoringBuild organization, repository, and connection IDs before creating the Machine connection. After approval, normal native jobs need no repository secret or workflow auth step: the BoringBuild supervisor renews assertions and keeps the private runner-local broker running before repository code starts. Pull requests and other untrusted source contexts are restore-only.

connect-boringcache:
  timeout: 1h
  id_tokens:
    BORINGCACHE_OIDC_TOKEN:
      aud: urn:boringcache:workload
  script:
    - boringcache ci connect --oidc-provider gitlab

After enrollment, providers whose workflow handles activation use boringcache ci run; BoringBuild's supervisor activates the broker before repository code starts. Renewable providers acquire a fresh token at startup and before session expiry. A provider that exposes one fixed token per job can use a native adapter or --oidc-token-env NAME; BoringCache exchanges it once, removes the variable from the broker and wrapped command, and keeps the private broker session no longer than the signed assertion, capped at one hour. Cache, Artifact, and Registry clients receive separate five-minute capabilities, with live connection, binding, product, and publication policy checked each time. Static BoringCache credential variables are removed from every child process, and acquisition, exchange, renewal, or broker failure stops the wrapped command without fallback.

boringcache ci run \
  --oidc-provider github-actions \
  -- your-build-command

boringcache ci run \
  --oidc-provider circleci \
  -- your-build-command

build:
  timeout: 1h
  id_tokens:
    BORINGCACHE_OIDC_TOKEN:
      aud: urn:boringcache:workload
  script:
    - boringcache ci run --oidc-provider gitlab -- your-build-command

Native assertion acquisition is built in for GitHub Actions, Buildkite, CircleCI, GitLab CI, and BoringBuild. GitHub Actions, Buildkite, CircleCI, and BoringBuild can renew assertions; BoringBuild's normal path is supervisor-managed, so workflow authors do not wrap their build with boringcache ci run. CircleCI verifies the signed project, VCS origin, and ref; issued fork assertions or missing source context stay restore-only. GitLab injects the audience-bound token declared by id_tokens; the CLI consumes it once, and GitLab's explicit job timeout determines its lifetime up to BoringCache's one-hour broker cap. GitLab merge-request and fork source jobs remain restore-only. A custom acquisition command must print exactly one fresh OIDC ID token each time it runs. Use a scoped credential or split a job that must run beyond a fixed provider token's bounded lifetime. Wrapped-command standard output is preserved, while broker status is written to standard error.

For manual local auth, use boringcache auth --token .... In CI using scoped credentials, use split tokens and let the CLI pick the least-privileged one that can do the job.

# Restore-only CI job
export BORINGCACHE_RESTORE_TOKEN=...

# Trusted CI job that should also save
export BORINGCACHE_SAVE_TOKEN=...

Environment Variables

Set these variables to control authentication, defaults, and runtime behavior.