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 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 (or nil).
• 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(), and ctx.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

srcstring

Source path relative to the script directory.

dststring

Destination path (supports ~ expansion).

rootbeer.exec(cmd, args)

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

Parameters

cmdstring

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

argsstring[]optional

Optional arguments passed to the command.

rootbeer.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

pathstring

The destination file path.

contentstring

The content to write.

rootbeer.is_dir(path)

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

Parameters

pathstring

The path to check.

Returns

boolean

rootbeer.is_file(path)

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

Parameters

pathstring

The path to check.

Returns

boolean

rootbeer.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

Source path (supports ~ expansion).

dststring

Destination path (supports ~ 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

srcstring

Source path relative to the script directory.

dststring

Destination path (supports ~ expansion).

rootbeer.path_exists(path)

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

Parameters

pathstring

The path to check.

Returns

boolean

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

The desired remote URL (any git URL).

rootbeer.Secret.op(reference)

Reads a secret from 1Password via the op CLI.

Parameters

referencestring

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

Returns

string — The secret value.