Core API

The core API is available via require("rootbeer") and provides the primitives for writing files, creating symlinks, and querying system info.

local rb = require("rootbeer")

Writing Files

Write content to any path. Parent directories are created automatically, and ~ expands to $HOME.

rb.file("~/.config/starship.toml", [[
[character]
success_symbol = "[➜](bold green)"
]])

file(path, content)

Writes content to a file path. The ~ character is expanded to $HOME. Parent directories are created automatically. In dry-run mode, prints what would be written.

Parameters:

Name	Type	Description
path	string	The destination file path (supports ~ expansion).
content	string	The content to write.

Symlinking

Symlink files from your source directory into place. The source path is relative to ~/.local/share/rootbeer/source/. Idempotent — existing correct links are skipped, stale links are replaced.

rb.link_file("config/gitconfig", "~/.gitconfig")
rb.link_file("config/nvim", "~/.config/nvim")

link_file(src, dest)

Creates a symlink from a source file to a destination path. The source is relative to the rootbeer source directory (~/.local/share/rootbeer/source/). The destination supports ~ expansion. Idempotent — existing correct links are left alone, stale links are replaced.

Parameters:

Name	Type	Description
src	string	Source path, relative to the source directory.
dest	string	Destination path (supports ~ expansion).

System Info

Query the current machine to write conditional configs that work across multiple systems.

local d = rb.data()

if d.os == "Darwin" then
    rb.file("~/.config/homebrew/env", 'export HOMEBREW_PREFIX="/opt/homebrew"\n')
end

data()

Returns a table with information about the current machine.

Returns:

• rb.DataInfo

Name	Type	Description
os	string	Operating system name (e.g. "Linux", "Darwin").
arch	string	CPU architecture (e.g. "x86_64", "arm64").
hostname	string	Machine hostname.
home	string	Home directory path.
username	string	Current username.

JSON Serialization

Generate JSON config files for tools like VS Code or Alacritty.

rb.file("~/.config/alacritty/alacritty.json", rb.to_json({
    terminal = { shell = "/bin/zsh" },
    font = { size = 14 },
}))

to_json(tbl)

Serializes a Lua table to a JSON string.

Parameters:

Name	Type	Description
tbl	table	The table to serialize.

Returns:

• string

Low-Level Primitives

These are building blocks used internally by modules. Prefer rb.file() with module renderers for most use cases.

line(str)

Appends a line (with trailing newline) to the internal output buffer. This is a low-level primitive — prefer rb.file() with module renderers like zsh.config() for most use cases.

Parameters:

Name	Type	Description
str	string	The line to append.

emit(str)

Appends raw text to the internal output buffer without a trailing newline.

Parameters:

Name	Type	Description
str	string	The text to append.

Utilities

interpolate_table(tbl, fn)

Passes a table through a transform function and returns the result.

Parameters:

Name	Type	Description
tbl	table	The input table.
fn	fun(tbl: table): table	The transform function.

Returns:

• table

register_module(name, tbl)

Registers a native Lua module under the given name. Used internally by the plugin system.

Parameters:

Name	Type	Description
name	string	The module name to register.
tbl	table	The module table.