Homebrew Cask

Homebrew Cask is an extension of Homebrew that provides a CLI workflow for installing and managing prebuilt software artifacts on macOS and Linux. This includes GUI applications, CLI tools, fonts, plugins, and other packaged software distributed by upstream vendors.

To use Homebrew Cask, you must have Homebrew already installed on your system.

You can install applications (casks) directly from the terminal using the brew install command followed by the name of the cask. This automates downloading, verifying, and moving applications to the appropriate directories (e.g., /Applications).

% brew install alfred

Homebrew Cask is a tap, so running brew update pulls the latest cask definitions.

To manage installed applications:

• brew outdated --cask: Lists casks that have newer versions available.
• brew upgrade --cask: Upgrades all outdated casks.

Note on Greedy Casks: Many applications update themselves automatically. These are ignored by brew outdated and brew upgrade. To force Homebrew to manage these, add the --greedy flag.

$ brew update
$ brew outdated --cask
$ brew upgrade --cask
$ brew upgrade --cask --greedy

Homebrew Cask has specific workflows for requests:

• New Casks: Do not open issues to request new casks. Instead, submit a pull request to add the cask to the main repositories.
• Feature Requests: Use the official feature request template on the Homebrew core repository.

You can set persistent default options for cask installations using the HOMEBREW_CASK_OPTS environment variable in your shell profile (.profile, .bash_profile, or .zprofile).

Commonly configured options include:

• --appdir=<path>: Changes the directory where applications are moved (default: /Applications).
• --fontdir=<path>: Changes the path for fonts (default: ~/Library/Fonts).

Command-line flags will override these environment variable settings.

# Specify your defaults in this environment variable
export HOMEBREW_CASK_OPTS="--appdir=~/Applications --fontdir=/Library/Fonts"

A checksum mismatch error indicates that the downloaded file does not match the expected hash defined in the Cask. This usually means:

1. The download was incomplete or corrupted.
2. The Cask is outdated and needs to be updated to match a new version of the software.

Error: Checksum for Cask 'your-cask' does not match.

Expected: 3dbc6c2205af35db5370c7642b9a2b833668880569b9c64a7f5a670bf9911130
Actual: 526d747d99a93b760f7965e25a57ed61de9b93d566a0ba0c5f1c7e83719b20fd

Before reporting a bug, follow these steps to ensure the issue is not caused by an outdated local setup:

1. Reset and update your taps and Homebrew state:

   brew update-reset && brew update

2. Try your command again.
3. Search existing issues on GitHub to see if the problem is already known.

If the problem persists, common errors include curl errors, Permission denied errors, Checksum does not match errors, and source is not there errors.

If you encounter a Permission denied error when installing a Cask, the issue is related to system-level permissions on your macOS installation, not a bug in Homebrew Cask.

Error: Permission denied - (/usr/local/Caskroom/someapp/0.1/Someapp.app, /Applications/Someapp.app)

If you see a curl error (e.g., 403 Forbidden), the issue is related to the download process rather than Homebrew Cask itself. This is typically caused by:

1. The software vendor's server or the specific file being unavailable.
2. An outdated Cask definition.
3. Local network or connection issues.

curl: (22) The requested URL returned error: 403 Forbidden

An error stating wrong number of arguments (e.g., 1 for 4) typically indicates that the software you are attempting to install is incompatible with your current version of macOS.

Error: wrong number of arguments (1 for 4)

If you see an error stating the App source is not there, it means the directory structure inside the application's archive has changed. This is a Cask definition issue that requires a fix within the Homebrew Cask repository.

It seems the App source '/usr/local/Caskroom/someapp/0.1/Someapp.app' is not there.