rune

    Environment variables

    Set for every script

    Rune sets these after every other layer, so they are always the values below.

    VariableValue
    RUNE_SCRIPT_NAMEThe name passed to rune run
    RUNE_ROOTThe directory holding the config that defined the script
    RUNE_PACKAGE_DIRThe package directory the run started from

    A script uses them to find repository-relative paths without hard-coding ../..:

    build: {
  command: 'node "$RUNE_ROOT/scripts/build.mjs"',
}

    Read by Rune

    VariableEffect
    npm_config_script_shellThe shell every command is spawned through. Arrives automatically when Rune runs from a package-manager script
    PATHThe base that node_modules/.bin directories are prepended to
    CIDecides rune.isCI in a config, once rune is imported. Any value other than empty, 0 or false counts as CI
    NO_COLORAny value turns off colour in Rune's own prefixes
    FORCE_COLORForwarded to piped members of a parallel group, so their colour survives the pipe. A value already set wins
    RUNE_BINARY_PATHPoints the npm wrapper at a specific native binary instead of resolving one

    Read by a config

    A config sees the process environment through rune.env, and every read is recorded so it enters the cache key. Import the object first — it is an export of the package Rune supplies, not a global.

    import { rune } from '@gio-labs/rune';

const registry = rune.env.NPM_REGISTRY ?? 'https://registry.npmjs.org';

    A variable the config read invalidates the cache when it changes. A variable it never read has no effect on caching.

    The reserved prefix

    Names beginning with RUNE_ cannot be set from an envFile or from a script's env map. An attempt is ignored and reported:

    warning: `RUNE_ROOT` from this script's `env` was ignored: `RUNE_` is reserved for rune's own variables

    The reason is that a script reading RUNE_ROOT has to be able to trust it. A config that could overwrite it would make the value mean something different per script.

    RUNE_BINARY_PATH

    The npm wrapper resolves a platform package and spawns the binary inside it. RUNE_BINARY_PATH replaces that resolution:

    RUNE_BINARY_PATH=./target/release/rune pnpm test

    When the path is set and the file does not exist, the wrapper fails immediately rather than falling back, so a typo does not silently run the published binary instead of the local build.

    It outranks every other step, including the rune a repository installs for itself. Pointing at a build is a deliberate instruction and nothing overrules it quietly. See Platforms for the full order.