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 per-machine configuration, see Multi-Device Config.

local rb = require("rootbeer")

rb.profile

string? — The active configuration profile, or nil when no profile was passed on the command line. Set via rb apply <profile>.

API Reference

ini(table)

Serializes a two-level table to an INI/gitconfig-formatted string. Top-level keys must be tables and become [section] headers. Scalar values within a section are emitted as key = value. Nested table values become subsections ([section "subsection"]). Nesting beyond two levels is ignored.

tabletable<string, table<string, boolean|string|number|table>>

The table to serialize.

string — INI-encoded string.

json(table)

Serializes a Lua table to a JSON string with 2-space indentation. Tables with consecutive integer keys starting at 1 are encoded as arrays. All other tables are encoded as objects.

tabletable

The table to serialize.

string — JSON-encoded string.

toml(table)

Serializes a Lua table to a TOML string. Top-level scalar keys become key-value pairs. Nested tables become [section] headers. Arrays of scalars use inline syntax; arrays of tables use [[array]] syntax.

tabletable

The table to serialize.

string — TOML-encoded string.

op(reference)

Reads a secret from 1Password via the op CLI.

referencestring

The op:// reference (e.g. "op://vault/item/field").

string — secret value.

exec(cmd, args)

Executes a command in the source directory. The command is deferred until the apply stage.

cmdstring

The command to run (e.g. "brew").

argsstring[]?

Optional arguments passed to the command.

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.

pathstring

The destination file path.

contentstring

The content to write.

is_dir(path)

Checks whether a path is a directory. Supports ~ expansion and relative paths.

pathstring

The path to check.

boolean

is_file(path)

Checks whether a path is a regular file. Supports ~ expansion and relative paths.

pathstring

The path to check.

boolean

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.

srcstring

Source path (supports ~ expansion).

dststring

Destination path (supports ~ expansion).

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.

srcstring

Source path relative to the script directory.

dststring

Destination path (supports ~ expansion).

path_exists(path)

Checks whether a path exists (file, directory, or symlink). Supports ~ expansion and relative paths.

pathstring

The path to check.

boolean

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.

urlstring

The desired remote URL (any git URL).