Configuration¶

Stout uses a TOML configuration file for customization.

Configuration File¶

The configuration file is located at:

macOS/Linux: ~/.stout/config.toml

Stout creates a default configuration on first run.

Full Configuration Reference¶

[index]
# Base URL for the package index
base_url = "https://raw.githubusercontent.com/neul-labs/stout-index/main"

# Automatically check for index updates
auto_update = true

# Minimum seconds between auto-updates (default: 30 minutes)
update_interval = 1800

[install]
# Path to the Cellar (where packages are installed)
cellar = "/opt/homebrew/Cellar"

# Path to the prefix (where symlinks are created)
prefix = "/opt/homebrew"

# Number of parallel downloads (1-8)
parallel_downloads = 4

# Default behavior for building from source
build_from_source = false

[cache]
# Maximum cache size (bytes or human-readable)
max_size = "2GB"

# Formula cache TTL in seconds (default: 1 day)
formula_ttl = 86400

# Download cache TTL in seconds (default: 7 days)
download_ttl = 604800

# Cache directory (default: ~/.stout/cache)
# directory = "~/.stout/cache"

[security]
# Require Ed25519 signatures on index updates
require_signature = true

# Allow unsigned packages (not recommended)
allow_unsigned = false

# Maximum age for signatures in seconds (default: 7 days)
max_signature_age = 604800

# Custom trusted public keys (in addition to built-in)
# trusted_keys = ["base64-encoded-public-key"]

[analytics]
# Enable anonymous usage analytics
enabled = false

[output]
# Enable colored output
color = true

# Show progress bars
progress = true

# Verbosity level: "quiet", "normal", "verbose"
verbosity = "normal"

Configuration Sections¶

Index Settings¶

Control how Stout fetches package information.

[index]
base_url = "https://raw.githubusercontent.com/neul-labs/stout-index/main"
auto_update = true
update_interval = 1800

Setting	Description	Default
`base_url`	Index repository URL	GitHub stout-index
`auto_update`	Check for updates automatically	`true`
`update_interval`	Seconds between auto-updates	`1800` (30 min)

Private Index:

For enterprise use, point to your private index:

[index]
base_url = "https://internal.example.com/stout-index"

Installation Settings¶

Configure package installation behavior.

[install]
cellar = "/opt/homebrew/Cellar"
prefix = "/opt/homebrew"
parallel_downloads = 4
build_from_source = false

Setting	Description	Default
`cellar`	Where packages are installed	`/opt/homebrew/Cellar`
`prefix`	Where symlinks are created	`/opt/homebrew`
`parallel_downloads`	Concurrent download count	`4`
`build_from_source`	Build instead of using bottles	`false`

Linux Paths:

On Linux, the defaults are typically:

[install]
cellar = "/home/linuxbrew/.linuxbrew/Cellar"
prefix = "/home/linuxbrew/.linuxbrew"

Cache Settings¶

Manage disk usage for cached data.

[cache]
max_size = "2GB"
formula_ttl = 86400
download_ttl = 604800

Setting	Description	Default
`max_size`	Maximum cache size	`2GB`
`formula_ttl`	Formula cache lifetime (seconds)	`86400` (1 day)
`download_ttl`	Download cache lifetime (seconds)	`604800` (7 days)

Size Format:

Use human-readable sizes: 500MB, 2GB, 10GB

Security Settings¶

Configure security policies.

[security]
require_signature = true
allow_unsigned = false
max_signature_age = 604800

Setting	Description	Default
`require_signature`	Require Ed25519 signatures	`true`
`allow_unsigned`	Allow unsigned packages	`false`
`max_signature_age`	Max signature age (seconds)	`604800` (7 days)

Security Recommendation

Keep require_signature = true and allow_unsigned = false for production use.

Custom Trusted Keys:

Add additional trusted public keys:

[security]
trusted_keys = [
    "your-base64-encoded-ed25519-public-key"
]

Output Settings¶

Control terminal output.

[output]
color = true
progress = true
verbosity = "normal"

Setting	Description	Default
`color`	Colored output	`true`
`progress`	Show progress bars	`true`
`verbosity`	Output level	`"normal"`

Verbosity Levels:

quiet - Only errors
normal - Standard output
verbose - Detailed output

Environment Variables¶

Stout respects these environment variables:

Variable	Description
`STOUT_PREFIX`	Override default prefix
`STOUT_CELLAR`	Override Cellar location
`STOUT_CACHE_DIR`	Override cache directory
`STOUT_CONFIG`	Custom config file path
`STOUT_INDEX_URL`	Override index URL
`STOUT_MIRROR`	Use a mirror for packages
`STOUT_NO_COLOR`	Disable colored output
`STOUT_VERBOSE`	Enable verbose output
`STOUT_QUIET`	Enable quiet mode

Environment variables override config file settings.

Per-Project Configuration¶

Create a .stout.toml in your project directory for project-specific settings:

# .stout.toml
[install]
prefix = "./.stout"
cellar = "./.stout/Cellar"

Stout checks for .stout.toml in the current directory and parent directories.

Viewing Current Configuration¶

Show the active configuration:

stout config

Show configuration file location:

stout config --path

Example Configurations¶

Minimal (Defaults)¶

# Empty file uses all defaults

Development Setup¶

[output]
verbosity = "verbose"
progress = true

[cache]
max_size = "5GB"

CI/CD Environment¶

[output]
color = false
progress = false
verbosity = "quiet"

[analytics]
enabled = false

[index]
auto_update = false

Air-Gapped Environment¶

[index]
base_url = "file:///mnt/mirror/stout-index"
auto_update = false

[security]
require_signature = true

Enterprise with Private Index¶

[index]
base_url = "https://packages.internal.company.com/stout-index"
update_interval = 3600

[security]
require_signature = true
trusted_keys = [
    "your-company-public-key-base64"
]

Configuration Precedence¶

When the same setting is defined in multiple places, stout resolves it in the following order, with later sources overriding earlier ones:

Compiled-in defaults
~/.stout/config.toml (or the path in STOUT_CONFIG)
Nearest .stout.toml walking up from the current directory
Environment variables (STOUT_*)
Command-line flags (--prefix, --mirror, --verbose, ...)

This mirrors the precedence rules used by clap with the env feature enabled in Cargo.toml, so flag parity is automatic for any setting the binary exposes both as a flag and an env var.

Inspecting Effective Settings¶

stout config prints the merged configuration after applying every layer above, which is the quickest way to verify what the binary is actually using at runtime:

stout config            # human-readable summary
stout config --path     # location of the loaded config file

The output includes the resolved prefix, cellar, cache directory, index URL, signature policy, and the list of trusted public keys — useful when diagnosing enterprise rollouts that depend on a private index.

Storage Layout¶

By default, stout keeps everything under ~/.stout/:

~/.stout/
├── config.toml         # user configuration (this file)
├── state.db            # SQLite state: installed packages, pins, history
├── cache/
│   ├── index/          # downloaded SQLite index + signature
│   ├── bottles/        # cached bottle tarballs (TTL: download_ttl)
│   └── formula/        # individual formula JSON (TTL: formula_ttl)
└── logs/               # optional audit log target

Override the cache directory with STOUT_CACHE_DIR or by adding directory = "..." under the [cache] table.