CLI and environment

Who this is for: you are writing a systemd unit, a Dockerfile CMD, or a Kubernetes env: block and need to know what the process actually reads. What you'll have at the end: the complete argument and variable surface, with the sharp edges marked.

NativeLink's command line is deliberately tiny. Almost every decision lives in the JSON5 configuration file, not in flags, which means the interesting surface here is the environment, split across three unrelated jobs: configuring telemetry, filling in holes in the configuration file, and reaching the processes that actions run in.

The command line

nativelink <config_file>

That is the whole thing. config_file is a required positional argument, the path to a JSON5 configuration file, and there are no other arguments. The binary is a clap parser with version, about and author derived, so --help and --version work and nothing else does.

No --port, no --log-level, no --config-from-env exist. If you are looking for a knob, it is in the configuration file; see the configuration reference.

Telemetry variables

These are read once, at startup, by nativelink-util's tracing initialiser. They are the only variables that change the binary's own behaviour.

The service name is fixed. Resource::builder().with_service_name("nativelink") is called unconditionally, so OTEL_SERVICE_NAME does not change what appears on your spans. service.instance.id is a fresh UUIDv4 generated per process, which means it changes on every restart: useful for telling replicas apart, useless as a stable series identity.

Variables the configuration file expands

Many configuration fields are deserialized through a shellexpand wrapper rather than directly, so their string values undergo environment substitution before the value is used.

Two forms are available:

This is what makes one configuration file work across environments:

{
  stores: [
    {
      name: "CAS_MAIN_STORE",
      memory: {
        eviction_policy: {
          max_bytes: "${NATIVELINK_CAS_MEMORY_CONTENT_LIMIT:-100mb}",
        },
      },
    },
  ],
}

Not every field is expanded; the wrapper is applied per field, so whether a given key supports substitution depends on how its struct member is annotated. Numeric, boolean, duration and data-size fields have their own expanding deserializers, which is why max_bytes above accepts the string "100mb" rather than a number. When in doubt, the configuration reference records the type each field actually deserializes from.

Variables the worker passes to actions

A worker does not forward its own environment to the commands it runs: the child is spawned with env_clear(). An action sees exactly two things: the environment_variables its own Command message carries, and whatever the worker's additional_environment map (on the local worker configuration) names explicitly.

What NativeLink does not read

Stated explicitly, because each of these is a reasonable guess that is wrong:

• No environment-based configuration. No NL_CAS_PORT or equivalent. Ports, stores, schedulers and services come from the configuration file only. The escape hatch is ${VAR} substitution inside that file.
• No NATIVELINK_CONFIG variable. The configuration path is the positional argument and nothing else.
• No Prometheus scrape configuration. The binary exports OTLP and only OTLP; the namespace, const_labels and scrape endpoint you may be looking for belong to the OpenTelemetry collector's configuration, not NativeLink's. See the metrics reference.
• No OTEL_SERVICE_NAME honouring, as above; the service name is a compile-time constant.

Reading the source

If anything here disagrees with the binary, the source wins:

• Args: the argument parser
• telemetry.rs: every telemetry variable
• serde_utils.rs: the shellexpanding deserializers
• EnvironmentSource: action environment sources

Where to go next