> ## Documentation Index > Fetch the complete documentation index at: https://site.aspect.build/llms.txt > Use this file to discover all available pages before exploring further. # aspect setup bazelrc > Write a Bazel rc that points vanilla bazel invocations at an Aspect deployment's remote cache, BES and remote execution, with every flag in a named --config group. `aspect setup bazelrc` writes a Bazel rc so that **vanilla `bazel` calls** pick up the same configuration `aspect ` injects for itself. ```shell theme={null} aspect setup bazelrc ``` **Requires Aspect CLI [v2026.39.10](https://github.com/aspect-build/aspect-cli/releases/tag/v2026.39.10) or newer**, the release that added the two-rc split, --home and --remote. Pin it in .aspect/version.axl; see [version pinning](/docs/cli/version-pinning). An `aspect build` knows about your configured deployments; a `bazel build` started from the same shell doesn't. This command writes the equivalent flags where Bazel finds them. `aspect ci bazelrc` is an older name for the same command. ## Two rcs, two jobs Which rc it writes depends on where it runs. | | Repository rc | Machine rc | | ---------------------- | ----------------------------------------------------------- | ---------------------------------------------------- | | **Written to** | `/.aspect/bazelrc` | `~/.aspect/bazelrc` | | **Imported from** | the repo's `.bazelrc` | `~/.bazelrc` | | **Declares** | what's *available*: every `--config` section, enabling none | what's *in effect on this machine*: the enable lines | | **Committed** | yes, both files | never | | **Written by default** | off CI | on CI | Either way the importing file gains a `try-import` line at its **top**, added once and only if absent, so the file's own lines come after it and win. A repository rc is shared by everyone who builds the repo, so it names what could be turned on and turns nothing on. A machine rc belongs to one host, so that's where anything gets enabled. Nothing machine-specific reaches a repository rc. The credential helper is named by tool name rather than by path, the CI host's group is left out, and the compact execution log is placed through %workspace%. The file is safe to commit and to use on a colleague's machine. ### What each context gets | Where it runs | Writes | Holding | | ---------------------------------- | ----------------- | ------------------------------------------------------------------- | | A developer's machine | the repository rc | every section, enabling none | | CI, no committed repository rc | the machine rc | the CI host's group and the default deployment's endpoints, enabled | | CI, with a committed repository rc | the machine rc | the CI host's group, plus enable lines naming that file's sections | | An Aspect Workflows runner | the machine rc | the runner's own endpoints and paths, enabled | With a committed repository rc, the machine rc defines only the CI host's group, and everything else is enable lines pointing at the repository's own file. What the repository edited in stays in force, and CI still gets the cache. The committed rc must define the sections those lines name, because Bazel fails on a `--config` no rc defines. If it doesn't, the command writes the machine rc it would write with no committed rc, and names the missing section. ## What it writes Every flag sits in a named `--config` group, so `bazel build --announce_rc` tells you which group set what. | Group | Holds | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `aspect-common` | Tuning that presumes no endpoint | | `aspect-cache` | Remote cache, plus the tuning a cache justifies | | `aspect-bes` | Build event streaming and the results URL, so vanilla `bazel` calls show up in the [Build Results UI](/docs/aspect-workflows/platform/features/webui) next to your task runs | | `aspect-exec-log` | The compact execution log the diagnostics upload uses | | `aspect-exec` | Remote execution. Never enabled by default; opt in per call | | `aspect-runner` | The runner's output paths and repository cache | | `aspect-` | `--color=yes` on CI hosts where Bazel's `--color=auto` misdetects. Written only in a machine's own rc | The CI host groups are: | CI host | Group | | -------------- | ----------------------- | | GitHub Actions | `aspect-github-actions` | | CircleCI | `aspect-circleci` | | GitLab CI | `aspect-gitlab` | Buildkite needs no host tweak, so its rc has no host group. A repository rc also gets an opt-in section per deployment: ```shell theme={null} bazel build //... --config=aspect-cloud # Aspect Cloud's cache + BES bazel build //... --config=aspect-acme # a configured deployment bazel build //... --config=aspect-acme-exec # ... and its remote execution ``` Each section chains the common and CI-host groups and whatever tuning its endpoints justify. No section is written for the *default* deployment, because [`aspect auth use`](/docs/aspect-workflows/enterprise/connect/local-setup) could change what that means under a committed file. **--config=aspect-cloud works before you've logged in.** Aspect Cloud's Bazel-facing endpoints are built into the CLI, so the section is correct on a machine that has never run aspect auth login. The build itself still needs a credential. ## Which endpoints it turns on `--remote` decides, in the same grammar as `aspect build --remote`: `cache` and `bes` are on unless subtracted with `no-cache` or `no-bes`, and `exec` is off unless named. The full table is in [Aspect Cloud local setup](/docs/aspect-workflows/cloud/local-setup). Here the default is `auto`: | Form | Enables | | --------------- | ----------------------------------------------------------------------- | | `--remote=auto` | The default. Cache and build events on CI; nothing off CI | | `--remote` | Cache and build events | | `--remote=exec` | Cache, build events and remote execution | | `--remote=none` | Nothing. The rc still defines each `--config`, for a build to opt in to | Remote execution is never implied, on a runner or off it. Asking for `exec` where the deployment serves no executor prints a warning and leaves it out. **auto won't enable an endpoint this machine can't authenticate to:** no ASPECT\_API\_TOKEN and no login on record. Bazel fails a build when a credential helper returns no token, so the rc leaves that endpoint defined but off. An explicit --remote is honored either way. Only a machine rc enables anything. Whatever `--remote` says, a repository rc's sections stay opt-in. ## Authentication The generated sections name `aspect` as the Bazel [credential helper](https://github.com/bazelbuild/proposals/blob/main/designs/2022-06-07-bazel-credential-helpers.md), which Bazel resolves on `PATH`. It serves the credential from your `aspect auth login` and refreshes it as needed, so a vanilla `bazel build` authenticates with nothing more to set up. The command warns if `aspect` isn't on `PATH` where it runs. If you authenticate with a long-lived token instead, put the helper in your own `~/.bazelrc` and set `--remote_header` there. On a deployment using [your own identity provider](/docs/aspect-workflows/enterprise/connect/local-setup#if-the-deployment-uses-your-own-identity-provider), CI supplies its own credential helper rather than the `aspect` one. ## Options | Flag | Default | What it does | | -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--home` | `auto` | Which rc to write. `auto` is the machine rc on CI and the repository rc elsewhere. Bare `--home` or `--home=true` forces the machine rc; `--home=false` forces the repository rc, including on CI, for a job that regenerates the committed file | | `--remote` | `auto` | Which endpoints the rc turns on. See [above](#which-endpoints-it-turns-on) | | `--force` | off | Regenerate an rc that's already there, discarding whatever was edited into it | | `--output ` | none | Write the rc somewhere other than the default. Can't be combined with `--home=true` | | `--import-into ` | none | The rc that receives the `try-import` line | | `--omit-bazel-flag ` | none | Drop a tuning flag from whichever group holds it. Repeatable | Without `--force` an existing rc is left alone: a repository's is a starting point the repository owns, and a machine's may belong to a persistent runner someone set up by hand. A Workflows runner clears `~/.aspect` before every job, so there it's written fresh either way. `--omit-bazel-flag` names the flag as Aspect spells it, and any `=value` is ignored: ```shell theme={null} aspect setup bazelrc --omit-bazel-flag=--heap_dump_on_oom ``` Set it once per repository in `.aspect/config.axl`: ```python title=".aspect/config.axl" theme={null} def config(ctx: ConfigContext): ctx.tasks["setup/bazelrc"].args.omit_bazel_flags = ["--heap_dump_on_oom"] ``` Emptying a group removes it along with the lines that named it. Endpoints, credentials, the `--config` chains and the runner's output paths can't be omitted. **--bes\_backend and --bes\_results\_url can be omitted.** Bazel reads the workspace rc before the home rc, so a repository that sends vanilla builds to a different build event backend keeps it with --omit-bazel-flag=--bes\_backend. Tasks have their own knob, [--bazel-flags:omit](/docs/cli/reference/features#bazelflags), since vanilla bazel and tasks may want different omissions. ## On a Workflows runner The generated rc reflects what the runner's environment advertises. These are opt-in rather than automatic: * **Remote execution.** Where the runner advertises an executor, the `aspect-exec` group carries it and nothing enables it. Pass `--config=aspect-exec` on a vanilla `bazel` call to use it. * **Cache compression.** Where the runner's cache accepts compressed blobs, the rc leaves compression to the repository. Where it doesn't, the rc sets `--noremote_cache_compression`, because Bazel errors when a repository asks for compression from a cache that lacks it. ## Build events from tasks and from Bazel Tasks don't read rc files: the CLI starts Bazel with `--ignore_all_rc_files` and passes the expanded options itself. On a Workflows runner `--nohome_rc` also keeps `~/.bazelrc` out of tasks. Elsewhere `~/.bazelrc` is parsed, and when the resulting `--bes_backend` matches the CLI's own build event stream, the CLI leaves the streaming to Bazel and logs `Not streaming …`. The invocation is streamed once either way. ## Related * [`aspect setup tools-bazel-wrapper`](/docs/cli/tasks/setup_tools_bazel_wrapper): installs the `tools/bazel` wrapper so your team keeps typing `bazel`. * [Aspect Cloud local setup](/docs/aspect-workflows/cloud/local-setup): logging in, and the `--remote` flag for Aspect CLI tasks. * [CI setup](/docs/aspect-workflows/enterprise/connect/ci-setup): how the rc reaches a runner, and what the CI setup integrations do.