Core API

Write files, create symlinks, run commands, and manage packages from your Lua config.

For system information, see rb.host. For secrets from 1Password, see Secrets. For per-machine configuration, see Profiles. For managed packages and lockfile modes, see Packages.

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.

Package declarations

rb.packages({ "ripgrep", "jq" }) declares a package list. rb.package("ripgrep") accepts one entry. Add @version to choose an exact version. Rootbeer saves package versions in rootbeer.lock.

Find packages or follow the package guide to get started.

API Reference

rootbeer.bin_dir()

Returns the configuration profile's stable binary directory without checking installation.

Returns

string — path — Configuration profile binary directory.

rootbeer.bin_path(bin)

Returns a command's stable path in the configuration profile without checking installation. Declare the package before using this path in a deferred exec() call.

Parameters

binstring

Exported command name.

Returns

string — path — Configuration profile command path.

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.env_export(shell)

Writes a shell environment file and returns its path. Source this file from your shell configuration to use installed commands.

shell:
   | "sh"
   | "bash"
   | "zsh"

Parameters

shell"bash"|"sh"|"zsh"optional

Shell syntax to generate. Defaults to "sh".

Returns

string

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.package(spec, opts)

Installs a command-line tool, such as "ripgrep". Use "name@version" to choose an exact version. Package versions are saved in rootbeer.lock. You can also use github:owner/repo@tag for a GitHub release's asset.

Parameters

specstring|rootbeer.PackageRequestSpec

Package request, or a request with options.

optsrootbeer.PackageOptionsoptional

Asset options for github: requests.

rootbeer.package_catalog(path)

Builds packages from a checkout of recipes, laid out like the package index with packages/<name>.lua and host.lua. A name the checkout defines comes from its recipe instead of the index, and everything else still comes from the index. A build the index publishes under the same key is downloaded, and the rest builds on this machine.

Parameters

pathstring

The checkout, relative to the config.

rootbeer.packages(specs)

Declares a dense package list in order. Accepts the same entries as package(). Validates every entry before adding operations; errors identify the invalid index.

Parameters

specs(string|rootbeer.PackageRequestSpec)[]

Package declarations.

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.read_file(path)

Reads a UTF-8 file during planning. Relative paths resolve from the source directory; paths starting with ~ expand to the home directory.

Parameters

pathstring

File to read.

Returns

string — content — File contents, including whitespace.

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.which(bin)

Returns the stable Rootbeer profile path for a managed binary, or nil when the binary is not provided by the current plan/profile. This never searches the host PATH.

Parameters

binstring

Binary name.

Returns

string

rootbeer.PackageOptions

assetstringoptional

Exact GitHub release asset filename. Required when platform selection is ambiguous.

binstable<string, string>optional

Binary name → relative path in the GitHub asset. Defaults to executable discovery for archives, or the repository name for raw binaries.

rootbeer.PackageRequestSpec

assetstringoptional

Exact release asset filename for a github: request.

binstable<string, string>optional

Exported command name → relative path for a github: request.

requeststring

Package name, name@version, or github:owner/repo@tag.