brew

Install tools using Homebrew package manager on macOS and Linux.

Tools using the brew installation method automatically declare a dependency on brew, ensuring that if a tools/brew.tool.ts is configured in the project, Homebrew is provisioned first on virgin machines before formula installation.

Homebrew-installed tools are externally managed: Homebrew owns the files, and .bin() names the executables it provides so dotfiles can shim them (see .bin() runtime behavior).

Basic Usage

import { defineTool } from "@alexgorbatchev/dotfiles";

export default defineTool((install) => install("brew", { formula: "ripgrep" }).bin("rg"));

Parameters

Parameter	Description
formula	Formula or cask name (defaults to tool name)
cask	Set true for cask installation
tap	Tap(s) to add before installing (brew tap <target>)
trust	Tap(s) or formula(s) to explicitly trust before tapping/installing (brew trust <target>). Set true to auto-trust configured tap(s). Defaults to false.
args	Additional CLI flags passed directly to brew install (e.g. ['--HEAD'], ['--build-from-source'])
force	Pass --force to brew install. Defaults to false.
service	Run brew services <action> <formula> after install; true means start, a string is used as the action (e.g. 'start', 'run')
link	Run brew link after install: true links, { force?: boolean, overwrite?: boolean } adds the matching flags, false or omitted never links
versionArgs	Arguments for version check (e.g., ['--version']); without them the version comes from brew info
versionRegex	Regex to extract version from output (string or RegExp)

Examples

Homebrew Cask

install("brew", {
  formula: "visual-studio-code",
  cask: true,
});

With Tap Trust & Custom Tap

install("brew", {
  formula: "borders",
  tap: "FelixKratz/formulae",
  trust: true, // Automatically trusts "FelixKratz/formulae" before tapping
});

Background Service & Keg-Only Linking

install("brew", {
  formula: "redis",
  service: "start",
  link: { overwrite: true },
});

Build Flags

install("brew", {
  formula: "custom-tool",
  args: ["--build-from-source"],
});

Update Checks

An update check runs brew info --json=v2 <formula> (with --cask for a cask, and without it when the cask query fails). Homebrew’s own outdated verdict decides, since formula versions carry revision suffixes such as 1.2.3_1 that are not semantic versions. brew info describes a formula or cask that is not installed as not outdated, so a tool dotfiles installed whose package has no installed version fails the check, as does a query that fails or names no version. A tool dotfiles never installed is not checked; tool check reports it as not installed.

Platform Support

Platform	Support
macOS	Full (formulas + casks)
Linux	Formulas only
Windows	Not supported