The RBS Language

Every rbs build file is written in the RBS language, a deterministic, Python-like configuration language. Files use the .rbs extension. This page is the language reference for anyone writing build files; see Custom Rules for the rule-authoring API and External Rule Packages for ext.rbs.

File types

File	Where	Purpose
`WORKSPACE.rbs`	workspace root	Workspace identity and toolchain setup. Executed first.
`BUILD.rbs`	any directory	Declares the targets of that package (the directory containing it).
`*.rbs` modules	anywhere	Helper modules brought in with `load()` — rule definitions, shared constants, macros.
`.env.schema`	root and/or packages	An `.rbs`-language file declaring environments and environment variables (see Environments).
`ext.rbs`	workspace root	Manifest of external rule packages. Only `ext()` is available there — see External Rule Packages.

The language in .rbs files

If you know Python, you already know most of the RBS language:

# Values: None, True/False, int, float, string, list, tuple, dict
SRC_DIRS = ["src", "lib"]
CONFIG = {"debug": False, "opt": 2}

def sources(dirs):
    """Functions, default args, keyword args all work."""
    return [d + "/**/*.go" for d in dirs]  # comprehensions too

go_binary(
    name = "server",
    srcs = glob(sources(SRC_DIRS)),
)

The dialect rbs evaluates is deliberately restricted so build files stay analyzable and terminate:

No while loops and no recursion. Iterate with for over finite collections.
if and for statements only inside functions. At the top level of a file you may assign names, define functions, call rules, and load(). (Conditional expressions like x = a if cond else b are fine anywhere.)
Top-level names are assigned once — no reassigning a global.
No implicit string concatenation. Adjacent string literals are a parse error; see Gotchas.
print() writes to the build output; fail() aborts the build.

Build file structure

A directory with a BUILD.rbs is a package. A build file loads the rules it needs, then declares targets by calling them:

load("@rbs//go/rules.rbs", "go_binary", "go_library")

go_library(
    name = "greeter",
    srcs = ["greeter.go"],
)

go_binary(
    name = "hello",
    srcs = ["main.go", "greeter.go"],
    deps = [":greeter"],
)

rbs build //examples/go-hello:hello
rbs run examples/go-hello:hello
rbs query //...

load()

load("module_path", "symbol", local_name = "exported_name")

load() executes another .rbs file (once — modules are cached) and binds selected top-level names from it into the current file.

Path form	Resolves to
`@rbs//go/rules.rbs`	The embedded ruleset shipped inside the rbs binary.
`@<namespace>//jvm/rules.rbs`	An external rule package declared in `ext.rbs` under that namespace.
`//tools/defs.rbs`	Workspace-root-relative path.
`helpers.rbs`	Relative to the directory of the loading file.

If the path has no extension, rbs tries .rbs and then .rbi. Load cycles are detected and reported as errors.

load("@rbs//python/rules.rbs", "py_binary")          # embedded rules
load("//rules/env/go_service.rbs", "GO_SERVICE_ENV")  # workspace module
load("@java//jvm/rules.rbs", "java_binary")           # external package

load() bindings are file-local — they are not re-exported. A module that loads a symbol does not make it loadable from itself. An aggregator module must rebind explicitly:

# prelude.rbs — WRONG: consumers of prelude.rbs will NOT see `y`
load("x.rbs", "y")

# prelude.rbs — RIGHT: rebind to a module-level name
load("x.rbs", _y = "y")
y = _y

Predeclared symbols

Every build file executes with these names already defined — no load() needed for any of them:

Symbol	Kind	Available in
`glob()`	function	all `.rbs` files
`fail()`	function	all `.rbs` files
`platform`	struct	all `.rbs` files
`output_path`	struct	all `.rbs` files
`config_setting()`	function	all `.rbs` files
`register_toolchain()`	function	all `.rbs` files
`native`	module	all `.rbs` files
`attr`	module	all `.rbs` files — see Custom Rules
`env`	module	all `.rbs` files
`infra`	module	all `.rbs` files
`workspace()`	function	`WORKSPACE.rbs` only
`struct()`	function	loaded modules only (not directly in `BUILD.rbs`/`WORKSPACE.rbs`)

In addition, every registered rule is predeclared by its bare name — built-in rules like genrule, task, and filegroup can be called without the native. prefix, and a rule defined with native.define_rule in a loaded module is callable wherever it is loaded.

env and infra are predeclared in every .rbs file. There is no @rbs//env/... or similar module to load — writing such a load() is an error.

platform

A struct describing the platform being built for:

platform.os      # "linux", "darwin", "windows"
platform.arch    # "amd64", "arm64"
platform.name    # full name, e.g. "darwin-arm64"
platform.host    # the machine running the build (for build-time tools)
platform.target  # the platform being built for (differs when cross-compiling)

Supported platform names: linux-amd64, linux-arm64, darwin-amd64, darwin-arm64, windows-amd64.

output_path

A struct of workspace output directories (all live under .rbs/):

output_path.out            # generic action outputs
output_path.bin            # built binaries and runfiles
output_path.testlogs       # test logs
output_path.toolchains     # installed toolchains
output_path.external_deps  # resolved external packages

glob()

glob(include, exclude = [], exclude_directories = False)

Returns a sorted list of files matching the patterns, as paths relative to the current package directory.

Parameter	Type	Description
`include`	`list[string]`	Glob patterns to match. Required.
`exclude`	`list[string]`	Patterns to remove from the result. Matched against the basename and against the full relative path (with `**` support).
`exclude_directories`	`bool`	When `True`, directories matched by simple patterns are filtered out. Patterns containing `**` only ever match files.

Pattern syntax: * (any characters except /), ? (one character), [...] (character class), ** (any files and directories, recursively).

glob(["*.py"])                                    # Python files in this package
glob(["**/*.go"], exclude = ["**/*_test.go"])     # all Go files, minus tests
glob(["src/**/*.ts", "lib/**/*.ts"])              # multiple roots

fail()

fail(msg)

Stops evaluation and fails the build with the message (exit code 1).

if not ctx.file.exists(go_mod):
    fail("go.mod is required for hermetic module builds")

config_setting()

config_setting(key, value)

Stores a global configuration value under key. value may be any plain value — a bool, number, string, list, or dict.

config_setting(key = "build.strict", value = True)

register_toolchain()

register_toolchain(name, kind = ..., **attributes)

Registers a toolchain by name with arbitrary attributes (kind or toolchain_type classifies it). Rules reference a registered toolchain via their toolchain = parameter, and rule implementations read its attributes through ctx.toolchain. In practice most workspaces use a language toolchain rule instead of calling this directly:

# WORKSPACE.rbs
load("@rbs//go/toolchain.rbs", "go_toolchain")

go_toolchain(
    name = "go",
    version = "1.24.3",   # rbs downloads it; no system Go needed
)

workspace()

workspace(name)

WORKSPACE.rbs only. Declares the workspace’s identity. The name must be letters, digits, ., - or _, starting with a letter or digit, and may only be declared once.

workspace(name = "my-service")

Attributes every rule accepts

Beyond each rule’s own attributes, these work on every target:

Attribute	Type	Description
`name`	`string`	Required. The target’s name within its package.
`env`	`dict[string, string]`	Environment variables for the target’s actions. Accepted by every rule — including ones whose definition never declared it — and usually produced by `env.vars([...])` or `env.all()`.
`target_compatible_with`	`list[string]`	Platform names the target builds for, e.g. `["linux-amd64", "darwin-arm64"]`. Empty means all platforms.

go_binary(
    name = "worker",
    srcs = ["main.go"],
    env = env.vars(["DATABASE_URL"], override = {"GOMAXPROCS": "4"}),
    target_compatible_with = ["linux-amd64", "linux-arm64"],
)

Labels

Targets are addressed by label:

Label	Meaning
`:greeter`	Target in the same package.
`//services/api:server`	Absolute: package path from the workspace root, then target name.
`//services/api`	Shorthand for `//services/api:api` on the command line.
`//...`	All targets in the workspace (command line, e.g. `rbs query //...`).
`@external://<package>:<version>`	An external ecosystem dependency (npm, pip, …) in a rule’s `deps`, e.g. `@external://react:19.0.0`. Resolved by the language rules, not a build-graph edge.

@rbs//... and @<namespace>//... are load paths for rule modules, not target labels.

Environments: the `env` module

Environment handling is schema-driven. A .env.schema file (written in the same build language) declares environments and variables; plain dotenv files supply the values (.env base, .env.<name> per-environment overlay, .env.local personal, gitignored); targets bind an allow-list with env.vars(). The environment is selected with -e <name> / RBS_ENV, and an undeclared name is a hard error. Validation happens at analysis time — a missing required variable fails the build, not the process at runtime.

env.var()

env.var(type = "string", default = None, required = False, secret = False,
        values = [], doc = "", source = None)

Declares one variable. Returns a value usable in env.schema(vars = {...}).

Parameter	Type	Description
`type`	`string`	`"string"` (default), `"int"`, `"bool"`, `"url"`, or `"enum"`.
`default`	`string`	Default value. All env values are strings — quote numbers. `None` (no default) and `""` are different.
`required`	`bool`	May be computed, e.g. `required = env.name() == "prod"`.
`secret`	`bool`	Marks the value secret: redacted in output, digest-cached instead of stored in plaintext.
`values`	`list[string]`	Allowed values for `type = "enum"`.
`doc`	`string`	Documentation string.
`source`	`env.source`	Where the value comes from, instead of the env files — see Value sources.

env.schema()

env.schema(vars = {}, extends = [])

Composes variables into a schema. Called from a .env.schema file it registers as that package’s schema; assigned to a name in a shared module it becomes a reusable standard. Calling env.schema() twice in one .env.schema is an error — compose with extends instead. Conflicting declarations of the same variable across extends are an error unless the extending schema restates the variable explicitly.

# rules/env/go_service.rbs — a shared standard
GO_SERVICE_ENV = env.schema(
    vars = {
        "PORT":         env.var(type = "int", default = "8080"),
        "LOG_LEVEL":    env.var(type = "enum",
                                values = ["debug", "info", "warn", "error"],
                                default = "info"),
        "DATABASE_URL": env.var(type = "url", required = True, secret = True),
    },
)

# services/controlplane/.env.schema — inherit and extend
load("//rules/env/go_service.rbs", "GO_SERVICE_ENV")

env.schema(
    extends = [GO_SERVICE_ENV],
    vars = {
        "WORKOS_API_KEY": env.var(secret = True, required = env.name() == "prod"),
    },
)

env.environment() and env.files()

env.environment(name, extends = "", infra = "")
env.files(pattern)

The root .env.schema declares which environments exist — rbs hardcodes none. extends layers another environment’s overlay file underneath; infra links the environment to an infra.environment(). env.files() overrides the overlay filename pattern (default .env.{env}); the pattern must contain {env}, and one workspace has one pattern.

# .env.schema (workspace root)
env.environment("dev")
env.environment("staging", extends = "dev")
env.environment("prod")

env.files(pattern = ".env.{env}")   # the default

env.vars() and env.all()

env.vars(names, override = {})   # allow-list — the documented default
env.all(override = {})           # every declared variable — escape hatch

Both return a plain dict[string, string] for a target’s env attribute. env.vars() binds exactly the named, schema-declared variables — only those reach the process and only those enter its cache key. A name not declared in any reachable schema is an analysis-time error listing the declared names. override layers literal values on top (they win over files). env.all() injects every declared variable, at the cost of a wider cache key.

go_binary(
    name = "controlplane",
    srcs = glob(["*.go"]),
    env = env.vars(["DATABASE_URL", "PORT"]),
)

env.name()

env.name()

Returns the selected environment name (-e / RBS_ENV), so schemas can make declarations conditional.

Value sources

A variable’s value normally comes from the env files. source = points it elsewhere:

Source	Signature	Value comes from
`env.infra(ref)`	`ref` is `"<resource>.<output>"`	An applied infra resource output, e.g. `env.infra("maindb.connection_string")`.
`env.host(name = "")`	optional host variable name	The host process environment — the only passthrough; the value is hashed into the cache key.
`env.command(argv)`	non-empty `list[string]`	Stdout of a command, e.g. `env.command(["git", "rev-parse", "HEAD"])`.
`env.managed(name = "")`	optional name	A value the platform delivers to the node. Unlike other sources it is a fallback: an env file the developer writes wins over it.
`env.source(resolver, **args)`	resolver name + string kwargs	A custom resolver registered with `env.define_source()`.

env.define_source(name, impl)

registers a custom resolver (Vault, cloud secret managers, …) at module top level.

"BUILD_SHA": env.var(source = env.command(["git", "rev-parse", "HEAD"])),
"DB_PASS":   env.var(secret = True, source = env.source("vault", key = "prod/db")),

Infrastructure: the `infra` module

infra is predeclared everywhere and is the surface for infrastructure-as-code definitions. Its members, grouped:

Group	Members
Providers	`infra.register_provider`, `infra.provider_config`, `infra.register_native_provider`, `infra.define_provider_adapter`
Resource types	`infra.define_resource_type`, `infra.define_native_resource`, `infra.define_native_data_source`, `infra.attribute`, `infra.block`
Declarations	`infra.resource`, `infra.component`, `infra.module`, `infra.workspace`, `infra.environment`, `infra.var`
Policy & mapping	`infra.define_policy`, `infra.define_equivalence`, `infra.resolve`, `infra.define_value_map`, `infra.map_value`
Data & outputs	`infra.data`, `infra.lookup`, `infra.output`, `infra.get_output`, `infra.apply`, `infra.all`, `infra.secret`, `infra.is_unknown`, `infra.is_secret`
Values & references	`infra.format`, `infra.join`, `infra.depends`, `infra.ref`
HTTP helpers	`infra.http_get`, `infra.http_post`, `infra.http_put`, `infra.http_delete`
Utility	`infra.generate_id`

See the infrastructure guides for end-to-end usage; this page only records that the module exists in every file with these members.

The `native` module

native exposes every built-in rule and SDK function. All of them are also predeclared by bare name, so genrule(...) and native.genrule(...) are the same call.

Built-in target rules

Rule	Declares
`genrule`	A shell command (or build-language function) producing declared outputs.
`run_tool`	A registered tool invocation producing declared outputs.
`task`	A runnable command target (no cached outputs required).
`filegroup`	A named collection of files.
`http_file(name, url, sha256 = "", executable = False, output_name = "")`	Downloads a single file into the toolchain area.
`http_archive(name, url, sha256 = "", strip_prefix = "", build_file = "", platform = "")`	Downloads and extracts an archive.
`tool_binary(...)`	Declares a downloadable tool binary.
`oci_image(...)`	Builds an OCI container image.
`external_dep(name, ecosystem, package, version, resolver = "", host = False)`	Resolves an external ecosystem package (and its transitive deps); referenced as `@external://<package>`.
`scaffolding(...)`	Code-generation template target.
`lsp_provider(...)`	Declares an LSP server for a language.
`lint(...)`	Lint target using a defined linter.
`ai_task(...)`	AI-driven task/test target.
`migration_database(...)`	Database migration target.

genrule

genrule(name, outs, cmd = "", action_fn = None, srcs = [], tools = [],
        deps = [], env = {}, message = "", executable = False,
        local = False, visibility = [], testonly = False)

Parameter	Type	Description
`name`	`string`	Target name. Required.
`outs`	`list[string]`	Declared outputs. Required.
`cmd`	`string`	Shell command to run. Exactly one of `cmd` / `action_fn` must be given.
`action_fn`	`callable`	Build-language function executed instead of a shell command.
`srcs`	`list[string]`	Input files.
`tools`	`list[string]`	Tools the command needs.
`deps`	`list[string]`	Target dependencies.
`env`	`dict`	Environment for the action (pairs with `env.vars()`).
`message`	`string`	Progress message.
`executable`	`bool`	Mark the output executable.
`local`	`bool`	Run locally (never remotely).
`visibility`, `testonly`		Standard metadata.

genrule(
    name = "version_file",
    outs = ["version.txt"],
    cmd = "git rev-parse HEAD > version.txt",
)

run_tool

run_tool(name, tool, outs, args = [], srcs = [], deps = [], env = {},
         message = "", local = False, visibility = [], testonly = False)

Like genrule, but invokes a registered tool by name with an argument list instead of a shell string.

task

task(name, command, deps = [], outputs = [], description = "",
     working_dir = "", toolchain = "")

A runnable command. command is a list[string] argv. Run it with rbs run //pkg:name.

task(
    name = "dev",
    command = ["npm", "run", "dev"],
    description = "Start the dev server",
)

filegroup

filegroup(name, srcs = [], deps = [], data = [], visibility = [],
          testonly = False, executable = False, output_group = None)

Groups files under one label, typically fed by glob():

filegroup(
    name = "testdata",
    srcs = glob(["testdata/**"]),
)

Rule and SDK definition functions

These register capabilities rather than declaring targets. Most run at module top level in rule packages; auto-registration at top level is the mechanism — the module executes, the definition registers.

Function	Registers
`native.define_rule(...)`	A new build rule — see Custom Rules.
`native.define_external_dep_resolver(...)`	A package-ecosystem resolver (npm, pip, …).
`native.define_linter(...)`	A linter for a language.
`native.define_completion_language(...)`	Tab-completion support for a language.
`native.define_coverage_converter(...)`	A coverage-format converter.
`native.define_language_constraints(...)`	Per-language do’s/don’ts surfaced to agents.
`native.define_setup_template(...)`	A per-language setup guide.
`native.define_atlas_extractor(...)`	How a language maps into the Atlas knowledge graph.
`native.define_agent_tool(...)` / `define_agent_prompt(...)`	Agent tools and prompts.
`native.define_subagent(...)` / `define_teammate_role(...)`	Agent specialists and roles.
`native.define_skill(...)`	A slash-command skill.
`native.define_mcp_server(...)`	An external MCP tool server.
`native.register_fragment_config(name, config)`	A configuration fragment (read via `ctx.fragments`).
`native.register_language_config(language, config)`	Language configuration.
`native.create_launcher(...)`	Generates a language-agnostic launcher script.

Companion list_* functions (list_skills, list_subagents, list_mcp_servers, …) enumerate what is registered, and get_toolchain_attribute(toolchain, attribute) / toolchain_path(...) read toolchain metadata.

Utility functions

The file, directory, JSON, archive, HTTP, and tool helpers (native.file_read, native.dir_create, native.json_parse, native.archive_extract, native.http_download, native.tool_run, …) are the same operations exposed on ctx inside rule implementations, where they are documented: see Custom Rules → the ctx API.

Gotchas

No implicit string concatenation. Unlike Python, adjacent string literals do not concatenate — it is a parse error. Use + or join:

# WRONG — parse error
cmd = "echo hello " "world"

# RIGHT
cmd = "echo hello " + "world"
script = "\n".join(["set -e", "make build"])

load() does not re-export. See load() — aggregator modules must rebind (load("x.rbs", _y = "y") then y = _y). env and infra are predeclared. Never write a load() for them. env = ... works on every rule — even rules whose definition never declared an env attribute, including rules you define yourself. Control flow lives in functions. A top-level if or for statement is a parse error; wrap logic in a def and call it. struct() is only predeclared in loaded modules. Build a struct in a helper module and load it, rather than calling struct() directly in a BUILD.rbs.

CLI

Build Language

File types

The language in .rbs files

Build file structure

load()

Predeclared symbols

platform

output_path

glob()

fail()

config_setting()

register_toolchain()

workspace()

Attributes every rule accepts

Labels

Environments: the `env` module

env.var()

env.schema()

env.environment() and env.files()

env.vars() and env.all()

env.name()

Value sources

Infrastructure: the `infra` module

The `native` module

Built-in target rules

genrule

run_tool

task

filegroup

Rule and SDK definition functions

Utility functions

Gotchas

​File types

​The language in .rbs files

​Build file structure

​load()

​Predeclared symbols

​platform

​output_path

​glob()

​fail()

​config_setting()

​register_toolchain()

​workspace()

​Attributes every rule accepts

​Labels

​Environments: the env module

​env.var()

​env.schema()

​env.environment() and env.files()

​env.vars() and env.all()

​env.name()

​Value sources

​Infrastructure: the infra module

​The native module

​Built-in target rules

​genrule

​run_tool

​task

​filegroup

​Rule and SDK definition functions

​Utility functions

​Gotchas

File types

The language in .rbs files

Build file structure

load()

Predeclared symbols

platform

output_path

glob()

fail()

config_setting()

register_toolchain()

workspace()

Attributes every rule accepts

Labels

Environments: the `env` module

env.var()

env.schema()

env.environment() and env.files()

env.vars() and env.all()

env.name()

Value sources

Infrastructure: the `infra` module

The `native` module

Built-in target rules

genrule

run_tool

task

filegroup

Rule and SDK definition functions

Utility functions

Gotchas