Core API
The core module provides the low-level primitives that all other modules build on — writing files, creating symlinks, and serializing data formats.
For system information, see rb.host. For secrets (1Password and friends), see Secrets. For per-machine configuration, see Profiles.
local rb = require("rootbeer")rb.profile
The first-class profile system. See the Profiles guide for the complete walkthrough. The module exposes:
rb.profile.define({ strategy, profiles })— declare profiles + the resolution strategy in one call.rb.profile.current()— the active profile name (ornil).rb.profile.select(map)/when(names, fn)/config(map)— branch on the active profile.- Custom strategy functions receive
ctx.match(value),ctx.cli(),ctx.hostname(), andctx.user()for explicit strategy composition.
API Reference
rootbeer.copy_file(src, dst)
Copies a file from the script directory to the destination, but only if the destination does not already exist. Useful for seeding configuration files that the user (or an application) is expected to modify after the initial bootstrap (e.g. an editor config that records UI state). The source path is relative to the script directory and must exist. The destination supports ~ expansion. If the destination already exists, the operation is reported as skip.
Parameters
srcstringdststring~ expansion).rootbeer.exec(cmd, args)
Executes a command in the source directory. The command is deferred until the apply stage.
Parameters
cmdstring"brew").argsstring[]optionalrootbeer.file(path, content)
Writes content to a file. Parent directories are created automatically. Paths starting with ~ are expanded to $HOME; relative paths resolve from the script directory.
Parameters
pathstringcontentstringrootbeer.is_dir(path)
Checks whether a path is a directory. Supports ~ expansion and relative paths.
Parameters
pathstringReturns
booleanrootbeer.is_file(path)
Checks whether a path is a regular file. Supports ~ expansion and relative paths.
Parameters
pathstringReturns
booleanrootbeer.link(src, dst)
Creates a symbolic link between arbitrary paths. Both paths support ~ expansion and relative path resolution. Unlike link_file, the source is not restricted to the script directory. The source must exist at plan time.
Parameters
srcstring~ expansion).dststring~ expansion).rootbeer.link_file(src, dst)
Creates a symbolic link from a file in the script directory. The source path is relative to the script directory and must exist. The destination supports ~ expansion. Idempotent — existing correct links are skipped, stale links are replaced.
Parameters
srcstringdststring~ expansion).rootbeer.path_exists(path)
Checks whether a path exists (file, directory, or symlink). Supports ~ expansion and relative paths.
Parameters
pathstringReturns
booleanrootbeer.read_file(path)
Reads a file from disk at plan time and returns its contents as a string. Useful for inlining shell snippets, templates, or any other text resource alongside your Lua configuration (the Nix builtins.readFile equivalent). Paths starting with ~ are expanded to $HOME; relative paths resolve from the script directory. Reads happen immediately during plan, not during apply.
Parameters
pathstringReturns
string — content — The file's contents.rootbeer.remote(url)
Sets the origin remote URL for the rootbeer source directory. The change is deferred until the apply stage. Idempotent — skipped when the current URL already matches.
Parameters
urlstring