Command Reference¶

Complete reference for all Stout commands.

Package Management¶

install¶

Install one or more packages.

stout install <package>...

Options:

Option	Description
`--HEAD`	Install from git HEAD (implies --build-from-source)
`--build-from-source`	Compile from source instead of using bottles
`--force`	Install even if already installed
`--ignore-dependencies`	Skip dependency installation
`--cask`	Treat all packages as casks
`--formula`	Treat all packages as formulas
`--no-verify`	Skip checksum verification (casks)
`--appdir=<dir>`	Custom application directory (casks)
`--dry-run`	Preview what would be installed
`--keep-bottles`	Keep downloaded bottles after installation
`-j, --jobs=<n>`	Number of parallel jobs for source builds
`--cc=<compiler>`	Use specified C compiler
`--cxx=<compiler>`	Use specified C++ compiler

Examples:

# Install a package
stout install jq

# Install multiple packages
stout install jq yq gron

# Install a specific version
stout install [email protected]

# Build from source
stout install --build-from-source neovim

# Install from git HEAD (bleeding edge)
stout install --HEAD neovim

uninstall¶

Remove installed packages.

stout uninstall <package>...

Options:

Option	Description
`--force`	Delete all installed versions
`--ignore-dependencies`	Don't fail if dependents exist
`--cask`	Treat as cask (application)
`--formula`	Treat as formula
`--zap`	Remove all files including preferences (casks only)

Examples:

stout uninstall jq
stout uninstall --force python

reinstall¶

Reinstall a package.

stout reinstall <package>...

Options:

Option	Description
`--HEAD`	Reinstall from git HEAD
`--build-from-source`	Compile from source
`--keep-bottles`	Keep downloaded bottles after installation

Examples:

# Reinstall a package
stout reinstall jq

# Reinstall as HEAD build
stout reinstall --HEAD neovim

# Reinstall from source
stout reinstall --build-from-source neovim

upgrade¶

Upgrade installed packages.

stout upgrade [package]...

Without arguments, upgrades all outdated packages.

Options:

Option	Description
`--dry-run`	Show what would be upgraded
`--fetch-HEAD`	Fetch upstream repository for HEAD installs
`--greedy`	Upgrade casks with auto-updates
`--cask`	Upgrade casks only
`--formula`	Upgrade formulas only

Examples:

# Upgrade specific package
stout upgrade python

# Upgrade all packages
stout upgrade

# Preview upgrades
stout upgrade --dry-run

# Check HEAD packages for updates
stout upgrade --fetch-HEAD

update¶

Update the formula index.

stout update

Downloads the latest package index from the stout-index repository.

Options:

Option	Description
`--force`	Force update even if recently updated

sync¶

Synchronize stout state with Homebrew Cellar and Caskroom.

stout sync

Detects drift between stout's tracked packages and what's actually installed in Homebrew's Cellar/Caskroom, then applies changes to bring state into sync.

Options:

Option	Description
`-n, --dry-run`	Show what would change without modifying state
`-y, --yes`	Apply all changes without prompting
`-v, --verbose`	Show detailed output

Examples:

# Check for drift
stout sync --dry-run

# Sync without prompting
stout sync --yes

import¶

Import existing Homebrew packages into stout's tracking.

stout import [package]...

Scans the Homebrew Cellar and imports packages into stout's state. Also relocates Homebrew placeholders to work with stout's prefix.

Options:

Option	Description
`-n, --dry-run`	Show what would be imported without modifying state
`--overwrite`	Re-import packages already tracked by stout
`-v, --verbose`	Show detailed output for each package

Examples:

# Import all untracked packages from Cellar
stout import

# Import specific packages
stout import jq wget curl

# Re-import already tracked packages
stout import --overwrite jq

outdated¶

List packages with available updates.

stout outdated

Options:

Option	Description
`--fetch-HEAD`	Check HEAD packages for updates
`--json`	Output as JSON
`--quiet`	Only show package names
`--cask`	Check casks only
`--formula`	Check formulas only

Examples:

# List outdated packages
stout outdated

# Check HEAD packages for updates
stout outdated --fetch-HEAD

# JSON output
stout outdated --json

autoremove¶

Remove packages installed as dependencies that are no longer needed.

stout autoremove

Options:

Option	Description
`--dry-run`	Preview what would be removed

Discovery & Information¶

search¶

Search for packages.

stout search <query>

Uses FTS5 full-text search for fast results.

Options:

Option	Description
`--desc`	Search in descriptions
`--cask`	Search casks only
`--formula`	Search formulas only
`--json`	Output as JSON

Examples:

stout search json
stout search --desc "image processing"
stout search --cask browser

info¶

Show package information.

stout info <package>

Options:

Option	Description
`--json`	Output as JSON
`--installed`	Only show installed packages
`--cask`	Show cask info
`--formula`	Show formula info

Examples:

stout info jq
stout info --json [email protected]

list¶

List installed packages.

stout list

Options:

Option	Description
`--versions`	Show installed versions
`--pinned`	Only show pinned packages
`--cask`	List installed casks
`--formula`	List installed formulas
`--json`	Output as JSON
`-1`	One package per line
`--source <src>`	Filter by source: stout, brew, unknown
`--requested`	Show only explicitly installed packages
`--deps`	Show only packages installed as dependencies

Examples:

# List all packages
stout list

# Show packages installed by Homebrew (not stout)
stout list --source brew

# Show only explicitly installed packages
stout list --requested

deps¶

Show package dependencies.

stout deps <package>

Options:

Option	Description
`--tree`	Show as dependency tree
`--graph`	Output DOT graph format
`--installed`	Only show installed dependencies
`--all`	Show all dependencies recursively
`--json`	Output as JSON

Examples:

stout deps [email protected]
stout deps --tree ffmpeg
stout deps --graph imagemagick > deps.dot

uses¶

Show packages that depend on a package (reverse dependencies).

stout uses <package>

Options:

Option	Description
`--recursive`	Show indirect dependents
`--installed`	Only show installed dependents

why¶

Explain why a package is installed.

stout why <package>

Shows the dependency chain that led to installation.

home¶

Open package homepage in browser.

stout home <package>

Package Control¶

pin¶

Prevent a package from being upgraded.

stout pin <package>...

unpin¶

Allow a pinned package to be upgraded.

stout unpin <package>...

link¶

Create symlinks for a package.

stout link <package>

Options:

Option	Description
`--overwrite`	Overwrite existing symlinks
`--force`	Allow linking keg-only packages
`--dry-run`	Preview what would be linked

unlink¶

Remove symlinks for a package.

stout unlink <package>

The package remains installed but is not in PATH.

switch¶

Switch between installed versions.

stout switch <package> <version>

Example:

stout switch python 3.11

rollback¶

Rollback to a previous version.

stout rollback <package>

Reverts to the previously installed version.

System & Maintenance¶

cleanup¶

Remove old versions and cached downloads.

stout cleanup

Options:

Option	Description
`--dry-run`	Preview what would be removed
`--prune=<days>`	Remove downloads older than days
`-s`	Scrub the cache

doctor¶

Check system for potential problems.

stout doctor

Runs diagnostics and reports issues: - stout data directory - Configuration file - Formula index - Homebrew prefix and Cellar - Installed packages state - Homebrew drift (packages in Cellar/Caskroom not tracked by stout) - Unrelocated Homebrew placeholders - Code signatures on all Mach-O binaries (macOS)

Options:

Option	Description
`--fix`	Automatically fix issues (sync, relocate, re-sign, reinstall corrupted packages)

Examples:

# Check system health
stout doctor

# Check and auto-fix issues
stout doctor --fix

config¶

Show or modify configuration.

stout config

Displays current configuration settings.

services¶

Manage background services.

stout services <command> [service]

Subcommands:

Command	Description
`list`	List all services
`start <service>`	Start a service
`stop <service>`	Stop a service
`restart <service>`	Restart a service
`run <service>`	Run in foreground
`info <service>`	Show service information
`cleanup`	Remove unused service files

tap¶

Manage third-party repositories.

stout tap [user/repo]

Subcommands:

Command	Description
`stout tap`	List tapped repositories
`stout tap <user/repo>`	Add a tap
`stout tap remove <user/repo>`	Remove a tap

history¶

Show version history for a package.

stout history <package>

completions¶

Generate shell completions.

stout completions <shell>

Shells: bash, zsh, fish

Cask Commands¶

Deprecated: stout cask <command> is deprecated. Use stout <command> --cask instead. The commands below still work but will print a deprecation warning.

Casks are macOS applications and Linux apps.

cask install¶

stout cask install <cask>...

Use instead: stout install --cask <cask>...

cask uninstall¶

stout cask uninstall <cask>...

Use instead: stout uninstall --cask <cask>...

Options:

Option	Description
`--zap`	Remove all associated files

cask search¶

stout cask search <query>

Use instead: stout search --cask <query>

cask info¶

stout cask info <cask>

Use instead: stout info --cask <cask>

cask list¶

stout cask list

Use instead: stout list --cask

cask outdated¶

stout cask outdated

Use instead: stout outdated --cask

cask upgrade¶

stout cask upgrade [cask]...

Use instead: stout upgrade --cask [cask]...

Bundle & Snapshot¶

bundle¶

Work with Brewfiles.

stout bundle <command>

Subcommands:

Command	Description
`install`	Install from Brewfile
`dump`	Create Brewfile from installed packages
`check`	Check if Brewfile is satisfied
`list`	List packages from Brewfile
`cleanup`	Remove packages not in Brewfile

Examples:

# Install from Brewfile
stout bundle install

# Create Brewfile
stout bundle dump > Brewfile

# Check status
stout bundle check

snapshot¶

Save and restore system state.

stout snapshot <command>

Subcommands:

Command	Description
`create <name>`	Create a snapshot
`list`	List snapshots
`show <name>`	Show snapshot details
`restore <name>`	Restore a snapshot
`delete <name>`	Delete a snapshot
`export <name> <file>`	Export snapshot to file
`import <file>`	Import snapshot from file

lock¶

Manage lockfiles for reproducible environments.

stout lock <command>

Subcommands:

Command	Description
`generate`	Generate lockfile from installed packages
`install`	Install packages from lockfile
`show`	Display lockfile contents

Examples:

# Generate lockfile
stout lock generate

# Install from lockfile
stout lock install

# View lockfile
stout lock show

Creates stout.lock with exact versions for reproducible environments.

Security & Audit¶

audit¶

Scan for known vulnerabilities.

stout audit [package]...

Without arguments, scans all installed packages.

Options:

Option	Description
`--severity=<level>`	Minimum severity (low, medium, high, critical)
`--json`	Output as JSON

Offline & Mirroring¶

mirror¶

Manage offline mirrors.

stout mirror <command>

Subcommands:

Command	Description
`create <path> <package>...`	Create a mirror with packages
`serve <path>`	Serve mirror via HTTP
`info <path>`	Show mirror information
`verify <path>`	Verify mirror integrity

Examples:

# Create mirror with essential tools
stout mirror create ./mirror jq curl wget git

# Serve on local network
stout mirror serve ./mirror --port 9000

# Use mirror
stout --mirror=http://localhost:9000 install jq

Multi-Prefix¶

prefix¶

Manage isolated environments.

stout prefix <command>

Subcommands:

Command	Description
`create <path>`	Create new prefix
`list`	List prefixes
`info <path>`	Show prefix information
`default <path>`	Set default prefix
`remove <path>`	Remove a prefix

Examples:

# Create project-specific environment
stout prefix create ~/project/.stout

# Install packages to prefix
stout --prefix=~/project/.stout install node@20

# Set as default
stout prefix default ~/project/.stout

Developer Commands¶

bottle¶

Create and manage binary packages.

stout bottle <command> [package]

Subcommands:

Command	Description
`create <package>`	Create bottle from installed package
`info <bottle>`	Show bottle information
`verify <bottle>`	Verify bottle integrity

create¶

Create a formula from a URL.

stout create <url>

Generates a formula template from a source archive.

test¶

Run package tests.

stout test <package>

Runs the test block defined in the formula.

analytics¶

Manage usage analytics.

stout analytics <command>

Subcommands:

Command	Description
`status`	Show analytics status
`on`	Enable analytics
`off`	Disable analytics
`what`	Show what data is collected

Global Options¶

These options work with most commands:

Option	Description
`--prefix=<path>`	Use custom prefix
`--mirror=<url>`	Use custom mirror
`--verbose`	Show detailed output
`--quiet`	Suppress output
`--json`	Output as JSON (where supported)
`--help`	Show help for command
`--version`	Show version