Command Reference¶

Complete reference for all Stout commands.

Package Management¶

install¶

Install one or more packages.

stout install <package>...

Options:

Option	Description
`--build-from-source`	Compile from source instead of using bottles
`--force`	Install even if already installed
`--ignore-dependencies`	Skip dependency installation
`--only-dependencies`	Install only dependencies, not the package
`--cask`	Install as a cask (application)
`--quiet`	Suppress output
`--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

uninstall¶

Remove installed packages.

stout uninstall <package>...

Options:

Option	Description
`--force`	Delete all installed versions
`--ignore-dependencies`	Don't fail if dependents exist
`--zap`	Remove all files (casks only)

Examples:

stout uninstall jq
stout uninstall --force python

reinstall¶

Reinstall a package.

stout reinstall <package>...

Options:

Option	Description
`--build-from-source`	Compile from source
`--force`	Reinstall even if up to date

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

Examples:

# Upgrade specific package
stout upgrade python

# Upgrade all packages
stout upgrade

# Preview upgrades
stout upgrade --dry-run

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

outdated¶

List packages with available updates.

stout outdated

Options:

Option	Description
`--json`	Output as JSON
`--quiet`	Only show package names
`--cask`	Check casks instead of formulas

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 instead of formulas
`--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

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
`--json`	Output as JSON
`-1`	One package per line

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.

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¶

Casks are macOS applications and Linux apps.

cask install¶

stout cask install <cask>...

cask uninstall¶

stout cask uninstall <cask>...

Options:

Option	Description
`--zap`	Remove all associated files

cask search¶

stout cask search <query>

cask info¶

stout cask info <cask>

cask list¶

stout cask list

cask outdated¶

stout cask outdated

cask upgrade¶

stout cask upgrade [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