Skip to main content
Log in once: your builds read and write the same remote cache as your CI, and every build you run shows up in the Build Results UI. There’s nothing to configure first. Aspect Cloud’s endpoints are built into the CLI.

​
Before you start

  • The Aspect CLI, v2026.41.24 or newer. Install it, then pin the version for everyone in .aspect/version.axl:
    .aspect/version.axl
  • An Aspect account. Sign up on the Free tier. See pricing for what it includes.

​
1. Log in

This opens a browser, signs you in, and stores the credential in your OS keyring. It’s the same account that installs the GitHub and GitLab Apps. If your account belongs to more than one organization, you’re prompted to pick one. Pass --org <name|id> to choose without a prompt. Over SSH, the CLI detects the remote session and prints the sign-in URL instead of opening a browser. Open it anywhere, sign in, and paste back either the callback URL from the address bar or the authorization code. --no-browser forces this flow.

​
2. Build with --remote

--remote connects the task to the remote cache and the build event service. The first build fills the cache; after that, actions already built with the same inputs, platform and configuration come back from it. Off CI, a task builds locally unless you pass the flag, so you choose when your builds use the cache.

​
What the flag accepts

--remote takes a comma-separated list. The cache and build events are on unless you subtract them with a no- token. Remote execution is coming soon to Aspect Cloud (early access); until then, naming exec against Aspect Cloud is an error. To stop typing the flag, set it once for the repository:
.aspect/config.axl
--remote=none on the command line opts a single build out of that default.

​
3. Or use vanilla bazel

--remote is an Aspect CLI flag, so a bazel build from the same shell doesn’t know about it. aspect setup bazelrc writes the equivalent flags where Bazel finds them.
On your machine this writes the repository rc: .aspect/bazelrc in the checkout, plus a try-import at the top of the repository’s .bazelrc. Commit both. The file declares what’s available and turns nothing on, so it’s safe for everyone who builds the repository. Opt a build in by name:
To turn the cache on for every bazel call on your machine instead, write the machine rc, which is never committed:
Either way, Bazel authenticates through aspect as a credential helper, serving the login from step 1. aspect has to be on PATH wherever bazel runs.

​
Check it worked

To see the cache work, clear your local outputs and build again, so nothing can come from your own machine:
Or let CI build a commit first, then build the same commit locally. Open either invocation in the Build Results UI; its Cache tab shows the hit rate.

​
Your credential

It renews itself. A browser login also obtains a refresh token, so you log in again only when that expires, not every time the access token does. It lives in your OS keyring: the macOS Keychain, or the Linux kernel keyring. Where no keyring is reachable, the CLI falls back to a 0600 file at ~/.aspect/credentials.json. Set ASPECT_CREDENTIALS_FILE to store it in a file at that path instead. Profiles keep identities apart. Use them on a shared machine, or to separate a personal account from a work one:
Log out with aspect auth logout, or aspect auth logout --all for every profile. aspect auth status --output=json gives scripts and AI assistants a machine-readable view, including the exact command that fixes a logged-out entry.

​
Next