# Command Reference
Complete reference for all Stout commands.
---
## Package Management
### install
Install one or more packages.
```bash
stout install <package>...
```
**Options:**
| `--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:**
```bash
# Install a package
stout install jq
# Install multiple packages
stout install jq yq gron
# Install a specific version
stout install python@3.11
# Build from source
stout install --build-from-source neovim
# Install from git HEAD (bleeding edge)
stout install --HEAD neovim
```
---
### uninstall
Remove installed packages.
```bash
stout uninstall <package>...
```
**Options:**
| `--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:**
```bash
stout uninstall jq
stout uninstall --force python
```
---
### reinstall
Reinstall a package.
```bash
stout reinstall <package>...
```
**Options:**
| `--HEAD` | Reinstall from git HEAD |
| `--build-from-source` | Compile from source |
| `--keep-bottles` | Keep downloaded bottles after installation |
**Examples:**
```bash
# 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.
```bash
stout upgrade [package]...
```
Without arguments, upgrades all outdated packages.
**Options:**
| `--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:**
```bash
# 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.
```bash
stout update
```
Downloads the latest package index from the stout-index repository.
**Options:**
| `--force` | Force update even if recently updated |
---
### sync
Synchronize stout state with Homebrew Cellar and Caskroom.
```bash
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:**
| `-n, --dry-run` | Show what would change without modifying state |
| `-y, --yes` | Apply all changes without prompting |
| `-v, --verbose` | Show detailed output |
**Examples:**
```bash
# Check for drift
stout sync --dry-run
# Sync without prompting
stout sync --yes
```
---
### import
Import existing Homebrew packages into stout's tracking.
```bash
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:**
| `-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:**
```bash
# 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.
```bash
stout outdated
```
**Options:**
| `--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:**
```bash
# 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.
```bash
stout autoremove
```
**Options:**
| `--dry-run` | Preview what would be removed |
---
## Discovery & Information
### search
Search for packages.
```bash
stout search <query>
```
Uses FTS5 full-text search for fast results.
**Options:**
| `--desc` | Search in descriptions |
| `--cask` | Search casks only |
| `--formula` | Search formulas only |
| `--json` | Output as JSON |
**Examples:**
```bash
stout search json
stout search --desc "image processing"
stout search --cask browser
```
---
### info
Show package information.
```bash
stout info <package>
```
**Options:**
| `--json` | Output as JSON |
| `--installed` | Only show installed packages |
| `--cask` | Show cask info |
| `--formula` | Show formula info |
**Examples:**
```bash
stout info jq
stout info --json python@3.11
```
---
### list
List installed packages.
```bash
stout list
```
**Options:**
| `--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:**
```bash
# 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.
```bash
stout deps <package>
```
**Options:**
| `--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:**
```bash
stout deps python@3.11
stout deps --tree ffmpeg
stout deps --graph imagemagick > deps.dot
```
---
### uses
Show packages that depend on a package (reverse dependencies).
```bash
stout uses <package>
```
**Options:**
| `--recursive` | Show indirect dependents |
| `--installed` | Only show installed dependents |
---
### why
Explain why a package is installed.
```bash
stout why <package>
```
Shows the dependency chain that led to installation.
---
### home
Open package homepage in browser.
```bash
stout home <package>
```
---
## Package Control
### pin
Prevent a package from being upgraded.
```bash
stout pin <package>...
```
---
### unpin
Allow a pinned package to be upgraded.
```bash
stout unpin <package>...
```
---
### link
Create symlinks for a package.
```bash
stout link <package>
```
**Options:**
| `--overwrite` | Overwrite existing symlinks |
| `--force` | Allow linking keg-only packages |
| `--dry-run` | Preview what would be linked |
---
### unlink
Remove symlinks for a package.
```bash
stout unlink <package>
```
The package remains installed but is not in PATH.
---
### switch
Switch between installed versions.
```bash
stout switch <package> <version>
```
**Example:**
```bash
stout switch python 3.11
```
---
### rollback
Rollback to a previous version.
```bash
stout rollback <package>
```
Reverts to the previously installed version.
---
## System & Maintenance
### cleanup
Remove old versions and cached downloads.
```bash
stout cleanup
```
**Options:**
| `--dry-run` | Preview what would be removed |
| `--prune=<days>` | Remove downloads older than days |
| `-s` | Scrub the cache |
---
### doctor
Check system for potential problems.
```bash
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:**
| `--fix` | Automatically fix issues (sync, relocate, re-sign, reinstall corrupted packages) |
**Examples:**
```bash
# Check system health
stout doctor
# Check and auto-fix issues
stout doctor --fix
```
---
### config
Show or modify configuration.
```bash
stout config
```
Displays current configuration settings.
---
### services
Manage background services.
```bash
stout services <command> [service]
```
**Subcommands:**
| `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.
```bash
stout tap [user/repo]
```
**Subcommands:**
| `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.
```bash
stout history <package>
```
---
### completions
Generate shell completions.
```bash
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
```bash
stout cask install <cask>...
```
Use instead: `stout install --cask <cask>...`
### cask uninstall
```bash
stout cask uninstall <cask>...
```
Use instead: `stout uninstall --cask <cask>...`
**Options:**
| `--zap` | Remove all associated files |
### cask search
```bash
stout cask search <query>
```
Use instead: `stout search --cask <query>`
### cask info
```bash
stout cask info <cask>
```
Use instead: `stout info --cask <cask>`
### cask list
```bash
stout cask list
```
Use instead: `stout list --cask`
### cask outdated
```bash
stout cask outdated
```
Use instead: `stout outdated --cask`
### cask upgrade
```bash
stout cask upgrade [cask]...
```
Use instead: `stout upgrade --cask [cask]...`
---
## Bundle & Snapshot
### bundle
Work with Brewfiles.
```bash
stout bundle <command>
```
**Subcommands:**
| `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:**
```bash
# Install from Brewfile
stout bundle install
# Create Brewfile
stout bundle dump > Brewfile
# Check status
stout bundle check
```
---
### snapshot
Save and restore system state.
```bash
stout snapshot <command>
```
**Subcommands:**
| `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.
```bash
stout lock <command>
```
**Subcommands:**
| `generate` | Generate lockfile from installed packages |
| `install` | Install packages from lockfile |
| `show` | Display lockfile contents |
**Examples:**
```bash
# 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.
```bash
stout audit [package]...
```
Without arguments, scans all installed packages.
**Options:**
| `--severity=<level>` | Minimum severity (low, medium, high, critical) |
| `--json` | Output as JSON |
---
## Offline & Mirroring
### mirror
Manage offline mirrors.
```bash
stout mirror <command>
```
**Subcommands:**
| `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:**
```bash
# 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.
```bash
stout prefix <command>
```
**Subcommands:**
| `create <path>` | Create new prefix |
| `list` | List prefixes |
| `info <path>` | Show prefix information |
| `default <path>` | Set default prefix |
| `remove <path>` | Remove a prefix |
**Examples:**
```bash
# 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.
```bash
stout bottle <command> [package]
```
**Subcommands:**
| `create <package>` | Create bottle from installed package |
| `info <bottle>` | Show bottle information |
| `verify <bottle>` | Verify bottle integrity |
---
### create
Create a formula from a URL.
```bash
stout create <url>
```
Generates a formula template from a source archive.
---
### test
Run package tests.
```bash
stout test <package>
```
Runs the test block defined in the formula.
---
### analytics
Manage usage analytics.
```bash
stout analytics <command>
```
**Subcommands:**
| `status` | Show analytics status |
| `on` | Enable analytics |
| `off` | Disable analytics |
| `what` | Show what data is collected |
---
## Global Options
These options work with most commands:
| `--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 |