zuke.tools.homebrew

class BrewAuditSettings(BrewCommandSettings)

• formulae(*names: str) -> Self

  Formulae to audit; repeatable.

• strict() -> Self

  Run the additional, stricter checks (--strict).

• online() -> Self

  Run the additional checks that need the network (--online).

• new() -> Self

  Run the checks for a formula new to Homebrew (--new), which imply --strict and --online.

• formula() -> Self

  Treat every name as a formula, not a cask (--formula).

class BrewCommandSettings(BrewSettings)

class BrewInfoSettings(BrewCommandSettings)

• formulae(*names: str) -> Self

  Formulae to describe; repeatable.

• formula() -> Self

  Treat every name as a formula, not a cask (--formula).

• installed() -> Self

  Describe every installed formula (--installed), instead of naming them.

class BrewInstallSettings(BrewCommandSettings)

• formulae(*names: str) -> Self

  Formulae to install (required); repeatable.

• formula() -> Self

  Treat every name as a formula, not a cask (--formula).

• build_from_source() -> Self

  Compile from source even when a bottle exists (--build-from-source).

• force() -> Self

  Install without checking for keg-only or unmigrated versions (--force).

• verbose() -> Self

  Print the verification and post-install steps (--verbose).

class BrewLivecheckSettings(BrewCommandSettings)

• formulae(*names: str) -> Self

  Formulae to check; repeatable.

• json() -> Self

  Print the result as JSON (--json).

• newer_only() -> Self

  Report only versions newer than the installed one (--newer-only).

• formula() -> Self

  Check only formulae, not casks (--formula).

class BrewRepositorySettings(BrewCommandSettings)

• tap(name: str) -> Self

  The tap whose directory to print, user/repo.

class BrewSettings(SubcommandSettings)

class BrewStyleSettings(BrewCommandSettings)

• targets(*values: str) -> Self

  Files, taps or formulae to check; repeatable.

• fix() -> Self

  Correct what RuboCop can correct (--fix).

class BrewTapNewSettings(BrewCommandSettings)

• name(tap: str) -> Self

  The tap to create (required), user/repo.

• no_git() -> Self

  Do not initialise a git repository for it (--no-git).

• branch(name: str) -> Self

  Initialise git on this branch, with its CI workflows (--branch=).

class BrewTapSettings(BrewCommandSettings)

• name(tap: str, url: str | None=None) -> Self

  The tap to add (required), user/repo — brew clones github.com/user/homebrew-repo — and optionally the URL to clone it from instead.

• force() -> Self

  Tap a core tap even under API mode (--force).

class BrewTasks

• static async run(ctx: ServiceContext, configure: Callable[[BrewSettings], BrewSettings] | None=None) -> ExecResult

  Run any brew command, built with .command(...)/.flag(...).

• static async install(ctx: ServiceContext, configure: Callable[[BrewInstallSettings], BrewInstallSettings]) -> ExecResult

  Install formulae (brew install).

• static async uninstall(ctx: ServiceContext, configure: Callable[[BrewUninstallSettings], BrewUninstallSettings]) -> ExecResult

  Uninstall formulae (brew uninstall).

• static async test(ctx: ServiceContext, configure: Callable[[BrewTestSettings], BrewTestSettings]) -> ExecResult

  Run installed formulae's test do blocks (brew test).

• static async audit(ctx: ServiceContext, configure: Callable[[BrewAuditSettings], BrewAuditSettings] | None=None) -> ExecResult

  Audit formulae against Homebrew's rules (brew audit).

• static async style(ctx: ServiceContext, configure: Callable[[BrewStyleSettings], BrewStyleSettings] | None=None) -> ExecResult

  Check formulae against Homebrew's RuboCop style (brew style).

• static async livecheck(ctx: ServiceContext, configure: Callable[[BrewLivecheckSettings], BrewLivecheckSettings] | None=None) -> ExecResult

  Look for newer upstream versions (brew livecheck).

• static async tap(ctx: ServiceContext, configure: Callable[[BrewTapSettings], BrewTapSettings]) -> ExecResult

  Add a tap (brew tap).

• static async untap(ctx: ServiceContext, configure: Callable[[BrewUntapSettings], BrewUntapSettings]) -> ExecResult

  Remove taps (brew untap).

• static async tap_new(ctx: ServiceContext, configure: Callable[[BrewTapNewSettings], BrewTapNewSettings]) -> ExecResult

  Generate a new local tap (brew tap-new).

• static async trust(ctx: ServiceContext, configure: Callable[[BrewTrustSettings], BrewTrustSettings]) -> ExecResult

  Trust a non-official tap's formulae, casks or commands (brew trust).

• static async repository(ctx: ServiceContext, configure: Callable[[BrewRepositorySettings], BrewRepositorySettings] | None=None) -> object

  The directory of Homebrew's repository, or of a tap (brew --repository [tap]), as a path with the trailing newline removed.

• static async info(ctx: ServiceContext, configure: Callable[[BrewInfoSettings], BrewInfoSettings]) -> object

  Describe formulae (brew info --json=v2), parsed into a BrewInfo: names, versions and the installed versions.

class BrewTestSettings(BrewCommandSettings)

• formulae(*names: str) -> Self

  Installed formulae to test (required); repeatable.

• force() -> Self

  Test even when the formula is unlinked (--force).

• keep_tmp() -> Self

  Keep the temporary files the test created (--keep-tmp).

• retry() -> Self

  Retry once if the test fails (--retry).

class BrewTrustSettings(BrewCommandSettings)

• targets(*names: str) -> Self

  What to trust: taps, formulae, casks or commands by name; repeatable.

• tap() -> Self

  The names are taps (--tap).

• formula() -> Self

  The names are formulae (--formula).

• cask() -> Self

  The names are casks (--cask).

• external_command() -> Self

  The names are external commands (--command).

class BrewUninstallSettings(BrewCommandSettings)

• formulae(*names: str) -> Self

  Formulae to uninstall (required); repeatable.

• formula() -> Self

  Treat every name as a formula, not a cask (--formula).

• force() -> Self

  Delete every installed version (--force).

• ignore_dependencies() -> Self

  Uninstall even when another formula depends on it (--ignore-dependencies).

class BrewUntapSettings(BrewCommandSettings)

• taps(*names: str) -> Self

  Taps to remove (required), user/repo; repeatable.

• force() -> Self

  Uninstall the tap's formulae first, rather than refusing (--force).

class FormulaBinarySettings(Settings)

• os(value: Literal['macos', 'linux']) -> Self

  The operating system the archive runs on (required).

• arch(value: Literal['arm', 'intel']) -> Self

  The CPU family the archive runs on (required).

• url(value: str) -> Self

  Where Homebrew downloads the archive (required; must be https).

• sha256(value: str) -> Self

  The archive's SHA-256 (required; 64 lowercase hex digits).

class FormulaSettings(Settings)

• name(value: str) -> Self

  The formula name (required), e.g. app or app@2: a lowercase letter, then lowercase letters, digits, -, _, ., + or @. The Ruby class name is derived from it exactly as Homebrew does — app-cli defines AppCli, app@2 defines AppAT2.

• description(text: str) -> Self

  The one-line description (desc, required), held to brew audit's rules: at most 80 characters, starting with a capital letter, not with an article or the formula's name, and with no trailing period.

• homepage(url: str) -> Self

  The project's homepage (required; must be https).

• version(value: str) -> Self

  The version, e.g. 1.2.3 — set it only when Homebrew cannot read it from the archive URLs. Homebrew detects a formula's version from its URL, and brew audit rejects a version line that repeats what it detected ("version … is redundant with version scanned from URL"). A GitHub release asset such as …/releases/download/v1.2.3/app-aarch64-apple-darwin.tar.gz carries it, so leave this unset there; expectVersion() in the test still works, against the detected version. Set it for a URL with no version in it, such as a …/releases/latest/download/… link or a content-addressed store.

• license(spdx: str) -> Self

  The SPDX license identifier, e.g. MIT.

• binary(configure: Callable[[FormulaBinarySettings], FormulaBinarySettings]) -> Self

  Add a prebuilt archive for one OS and CPU family. Call once per platform; at least one is required, and each OS/arch pair at most once.

• install(*files: str) -> Self

  Files from the archive to place in the formula's bin (bin.install); at least one is required. Plain file names only — no directory part.

• caveats(text: str) -> Self

  Text Homebrew prints after installing (def caveats).

• test(configure: Callable[[FormulaTestSettings], FormulaTestSettings]) -> Self

  The formula's test do block, which brew test runs. Without one, brew test (and so HomebrewTasks.verify) fails.

class FormulaTestSettings(Settings)

• binary(name: str) -> Self

  Which installed binary to run. Defaults to the first one the formula installs; it must be one of them.

• command(*args: str) -> Self

  The arguments to run the binary with, e.g. "--version".

• expect_version() -> Self

  Require the output to contain the formula's version.

• expect_output(text: str) -> Self

  Require the output to contain text.

class HomebrewPublishSettings(Settings)

• tap(value: str) -> Self

  The tap (required): its GitHub repository owner/homebrew-x, or brew's short form owner/x, which names the same repository.

• formula(name: str, source: str) -> Self

  The formula to publish (required): its name, which becomes the file Formula/<name>.rb, and its Ruby source — typically what HomebrewTasks.formula rendered.

• token(value: str) -> Self

  The token to write with — needs contents: write on the tap repository. Defaults to GITHUB_TOKEN, which only works when the tap is the repository the job runs in; a separate tap needs its own token.

• branch(name: str) -> Self

  The branch to commit on. Defaults to the tap's default branch.

• message(text: str) -> Self

  The commit message. Defaults to <name>: update formula.

• base_url(url: str) -> Self

  The API root, for GitHub Enterprise.

class HomebrewTasks

• static async formula(ctx: ServiceContext, configure: Callable[[FormulaSettings], FormulaSettings]) -> object

  The Ruby source of a formula that installs prebuilt binaries — one archive per OS and CPU family. Pure: nothing is read or written.

• static async publish(ctx: ServiceContext, configure: Callable[[HomebrewPublishSettings], HomebrewPublishSettings]) -> object

  Write Formula/<name>.rb into a tap repository on GitHub, or leave it alone — reporting unchanged — when the tap already holds exactly that source.

• static async verify(ctx: ServiceContext, configure: Callable[[HomebrewVerifySettings], HomebrewVerifySettings]) -> None

  Install a formula file through a throwaway local tap, trusted first, run its test, then uninstall it and remove the tap — the cleanup runs whether or not the install and test succeeded.

• static async verify_job(ctx: ServiceContext, configure: Callable[[HomebrewVerifyJobSettings], HomebrewVerifyJobSettings]) -> object

  The CI job that runs a verifying target across macOS and Linux runners, ready to list in cicd({ invokes: [...] }).

class HomebrewVerifyJobSettings(Settings)

• target(value: object) -> Self

  The target to run (required) — one that calls HomebrewTasks.verify, or otherwise installs, tests and uninstalls the formula.

• runners(*labels: str) -> Self

  The runner labels to verify on, replacing the default macos-latest and ubuntu-latest — e.g. "macos-15", "macos-15-intel", "ubuntu-latest" to cover both Mac CPU families. GitHub's ARM Linux runners (ubuntu-24.04-arm) ship without Homebrew, so they cannot verify a formula without installing it first.

class HomebrewVerifySettings(Settings)

• formula_file(path: str) -> Self

  The formula's Ruby source on disk (required), e.g. dist/app.rb.

• name(value: str) -> Self

  The formula's name (required) — the class the file defines is derived from it, and it is installed and tested under it.

• tool_path(path: str) -> Self

  The brew to run, when it is not on PATH — on a GitHub Linux runner Homebrew is installed but not on PATH: /home/linuxbrew/.linuxbrew/bin/brew.