What are casks?

While standard stout formulas manage command-line tools and libraries, casks handle graphical applications: the .app bundles on macOS, and AppImage or Flatpak packages on Linux. stout’s cask support lets you install, update, and remove GUI applications from the terminal with the same speed and determinism you get for CLI tools.

Installing your first cask

Cask installation works just like formula installation, with the --cask flag:

stout install --cask firefox

On macOS, this downloads the Firefox .dmg, extracts the .app bundle, moves it to /Applications, and registers it with stout for future updates. On Linux, stout fetches the appropriate AppImage or Flatpak, depending on your system configuration.

You can also install multiple casks in parallel:

stout install --cask firefox kitty visual-studio-code slack discord

stout downloads all five applications simultaneously and installs them in parallel, finishing in a fraction of the time a sequential approach would take.

Searching for casks

Find available casks with stout search:

# Search by name
stout search --cask firefox

# Search with a broader query
stout search --cask "video editor"

# List all available casks (pipe to grep or fzf for filtering)
stout search --cask --all | fzf

Get detailed information about a cask before installing:

stout info --cask firefox
# firefox: 133.0 (Mozilla Firefox)
# https://www.mozilla.org/firefox/
# Installed: /Applications/Firefox.app (289.4 MB)
# Auto-updates: yes (managed by application)
# Requires: macOS >= 12.0

Managing installed casks

Listing installed casks

# List all installed casks
stout list --cask

# Include version and size information
stout list --cask --versions
# discord         0.0.314    156.2 MB
# firefox         133.0      289.4 MB
# kitty           0.38.1      23.8 MB
# slack           4.41.98    211.0 MB
# visual-studio-code  1.96.2  392.1 MB

Upgrading casks

# Check for available upgrades
stout outdated --cask

# Upgrade a specific cask
stout upgrade --cask firefox

# Upgrade all casks
stout upgrade --cask

Some applications manage their own updates (like Firefox and VS Code). stout tracks this via the auto_updates flag in cask definitions. By default, stout upgrade --cask skips auto-updating applications. To include them:

stout upgrade --cask --include-auto-updates

Uninstalling casks

stout uninstall --cask firefox

This removes the application, clears the download cache for that cask, and removes any associated metadata. On macOS, stout also runs the cask’s uninstall stanza, which may remove preference panes, kernel extensions, or launchd services associated with the application.

Casks on Linux

On Linux, stout supports two distribution formats for GUI applications:

AppImage

stout downloads the AppImage file, makes it executable, creates a desktop entry for your application launcher, and symlinks the binary into your PATH:

stout install --cask obsidian
# ==> Downloading Obsidian-1.7.7.AppImage [128 MB]
# ==> Installing to ~/.local/share/stout/casks/obsidian/
# ==> Created desktop entry: ~/.local/share/applications/obsidian.desktop
# ==> Symlinked: obsidian -> ~/.local/bin/obsidian
# ==> Installed [email protected] (1.4s)

Flatpak integration

For applications distributed as Flatpaks, stout delegates to the Flatpak runtime but manages the lifecycle:

stout install --cask --format flatpak gimp

stout automatically detects whether the cask has an AppImage or Flatpak available and chooses the best option for your system. Override this with --format:

# Force AppImage format
stout install --cask --format appimage obsidian

# Force Flatpak format
stout install --cask --format flatpak obsidian

Cask options and customization

Custom install locations

By default, stout installs casks to /Applications on macOS and ~/.local/share/stout/casks/ on Linux. Override this per-cask or globally:

# Install to a custom directory
stout install --cask --appdir ~/Applications firefox

# Set a global default
stout config set cask.appdir ~/Applications

Requiring specific versions

Install a specific version of a cask:

stout install --cask [email protected]

List available versions for a cask:

stout info --cask firefox --versions
# firefox 133.0, 132.0.2, 132.0, 131.0.3, 131.0.2, ...

Quarantine handling (macOS)

macOS marks downloaded applications with a quarantine attribute, which triggers the “this app was downloaded from the internet” dialog on first launch. stout preserves this behavior by default for security, but you can disable it:

# Remove quarantine during install
stout install --cask --no-quarantine firefox

# Remove quarantine from an already-installed cask
stout cask unquarantine firefox

Using casks in Brewfiles

Casks work in Brewfiles exactly as they do with Homebrew:

# Brewfile
tap "homebrew/cask-fonts"

# CLI tools
brew "git"
brew "neovim"
brew "ripgrep"

# GUI applications
cask "firefox"
cask "kitty"
cask "visual-studio-code"
cask "slack"
cask "discord"
cask "rectangle"

# Fonts (from the cask-fonts tap)
cask "font-jetbrains-mono-nerd-font"
cask "font-fira-code"

Install everything at once:

stout bundle install --file Brewfile

stout resolves formulas and casks together, downloads everything in parallel, and installs them concurrently. A Brewfile with 10 formulas and 8 casks that takes Homebrew over five minutes typically completes in under 20 seconds with stout.

Writing custom cask definitions

If you need to distribute an internal application as a cask, create a TOML definition:

# casks/acme-dashboard.toml
[cask]
name = "acme-dashboard"
version = "3.2.0"
description = "Acme Corp internal monitoring dashboard"
homepage = "https://wiki.internal.acme.com/dashboard"

[source.macos]
url = "https://artifacts.internal.acme.com/dashboard/v3.2.0/AcmeDashboard-3.2.0.dmg"
sha256 = "a1b2c3d4..."
type = "dmg"
app = "Acme Dashboard.app"

[source.linux]
url = "https://artifacts.internal.acme.com/dashboard/v3.2.0/AcmeDashboard-3.2.0.AppImage"
sha256 = "e5f6a7b8..."
type = "appimage"

[requirements]
macos = ">= 13.0"
linux_glibc = ">= 2.31"

[uninstall]
quit = ["com.acme.dashboard"]
delete = ["/Applications/Acme Dashboard.app"]

Add this to a private index (see the Private Index guide) and your team can install it with:

stout install --cask acme-dashboard

Troubleshooting cask issues

Application does not appear in Spotlight or app launcher: Run stout cask relink <name> to recreate symlinks and desktop entries.

“Application is damaged” on macOS: This usually means the quarantine attribute was not properly handled. Remove quarantine with stout cask unquarantine <name> and verify the cask’s SHA-256 matches with stout cask verify <name>.

Cask upgrade leaves the old version behind: Some casks install to versioned paths. Run stout cleanup --cask to remove old versions and reclaim disk space.

Linux desktop entry has the wrong icon: Run stout cask rebuild-desktop-entry <name> to regenerate the .desktop file with the correct icon path.

Managing Casks with stout