Configuration Management Tutorial#

This tutorial covers managing scafctl’s application configuration using the config CLI commands.

Overview#

scafctl uses a YAML configuration file to control application behavior including logging, HTTP client settings, resolver timeouts, catalog locations, and more.

Command	Description
`config init`	Create config file
`config view`	View current config
`config get/set`	Read/write values
`config validate`	Validate config
`config schema`	View JSON schema
`config paths`	Show XDG paths

Quick Start#

1. Initialize Configuration#

Create a new config file:

Bash

# Create minimal config
scafctl config init

# Create with all options documented
scafctl config init --full

# Preview without writing
scafctl config init --dry-run

# Write to custom path
scafctl config init --output ./my-config.yaml

PowerShell

# Create minimal config
scafctl config init

# Create with all options documented
scafctl config init --full

# Preview without writing
scafctl config init --dry-run

# Write to custom path
scafctl config init --output ./my-config.yaml

2. View Configuration#

See the current effective configuration:

Bash

# Full config (YAML format)
scafctl config view

# As JSON
scafctl config view -o json

# Filter with CEL expression
scafctl config view -e '_.settings'

# Interactive TUI explorer
scafctl config view -i

PowerShell

# Full config (YAML format)
scafctl config view

# As JSON
scafctl config view -o json

# Filter with CEL expression
scafctl config view -e '_.settings'

# Interactive TUI explorer
scafctl config view -i

3. Show Config Sources#

See where each value comes from (file, environment, default):

Bash

scafctl config show

PowerShell

scafctl config show

Getting and Setting Values#

Read Values#

Use dot notation to read specific config values:

Bash

# Get logging level
scafctl config get logging.level

# Get default catalog
scafctl config get settings.defaultCatalog

# Get HTTP timeout
scafctl config get httpClient.timeout

PowerShell

# Get logging level
scafctl config get logging.level

# Get default catalog
scafctl config get settings.defaultCatalog

# Get HTTP timeout
scafctl config get httpClient.timeout

Write Values#

Bash

# Set logging level
scafctl config set logging.level debug

# Set HTTP timeout
scafctl config set httpClient.timeout 60s

# Set resolver concurrency
scafctl config set resolver.concurrency 8

# Enable a boolean
scafctl config set httpClient.caching.enabled true

PowerShell

# Set logging level
scafctl config set logging.level debug

# Set HTTP timeout
scafctl config set httpClient.timeout 60s

# Set resolver concurrency
scafctl config set resolver.concurrency 8

# Enable a boolean
scafctl config set httpClient.caching.enabled true

Reset to Default#

Bash

# Reset a value to its default
scafctl config unset logging.level

# Reset HTTP configuration
scafctl config unset httpClient.timeout

PowerShell

# Reset a value to its default
scafctl config unset logging.level

# Reset HTTP configuration
scafctl config unset httpClient.timeout

Managing Catalogs#

Add a Catalog#

Bash

# Add a local filesystem catalog
scafctl config add-catalog my-catalog --type filesystem --path ~/my-solutions

# Add an OCI registry catalog
scafctl config add-catalog company --type oci --url ghcr.io/myorg/scafctl-catalog

# Add and set as default
scafctl config add-catalog primary --type filesystem --path ~/catalogs/main --default

PowerShell

# Add a local filesystem catalog
scafctl config add-catalog my-catalog --type filesystem --path ~/my-solutions

# Add an OCI registry catalog
scafctl config add-catalog company --type oci --url ghcr.io/myorg/scafctl-catalog

# Add and set as default
scafctl config add-catalog primary --type filesystem --path ~/catalogs/main --default

Remove a Catalog#

Bash

scafctl config remove-catalog my-catalog

PowerShell

scafctl config remove-catalog my-catalog

Set Default Catalog#

Bash

scafctl config use-catalog my-catalog

PowerShell

scafctl config use-catalog my-catalog

Validation#

Validate Config File#

Bash

# Validate current config
scafctl config validate

# Validate a specific file
scafctl config validate path/to/config.yaml

PowerShell

# Validate current config
scafctl config validate

# Validate a specific file
scafctl config validate path/to/config.yaml

View Config Schema#

Bash

# Pretty-printed JSON Schema
scafctl config schema

# Minified (for piping)
scafctl config schema --compact

PowerShell

# Pretty-printed JSON Schema
scafctl config schema

# Minified (for piping)
scafctl config schema --compact

View System Paths#

See where scafctl stores files on your system:

Bash

# Show all XDG paths
scafctl config paths

# As JSON
scafctl config paths -o json

# Show paths for a different platform
scafctl config paths --platform linux

PowerShell

# Show all XDG paths
scafctl config paths

# As JSON
scafctl config paths -o json

# Show paths for a different platform
scafctl config paths --platform linux

Typical output:

 💡 scafctl Paths
Platform: darwin/arm64
Config:      ~/.config/scafctl/config.yaml
Secrets:     ~/.local/share/scafctl/secrets
Data:        ~/.local/share/scafctl
Catalog:     ~/.local/share/scafctl/catalog
Cache:       ~/.cache/scafctl
HTTP Cache:  ~/.cache/scafctl/http-cache
State:       ~/.local/state/scafctl
Override paths with XDG environment variables or SCAFCTL_SECRETS_DIR.

Configuration Reference#

Key Settings#

Key	Type	Default	Description
`logging.level`	string	`none`	Log level: `none`, `error`, `warn`, `info`, `debug`, `trace`, or numeric V-level
`logging.format`	string	`console`	Log format: `console` (colored), `json` (structured)
`settings.defaultCatalog`	string	`local`	Default catalog name
`httpClient.timeout`	duration	`30s`	HTTP request timeout
`httpClient.retry.maxRetries`	int	`3`	Max HTTP retries
`httpClient.caching.enabled`	bool	`true`	Enable HTTP response caching
`httpClient.maxResponseBodySize`	int	`104857600`	Max HTTP response body size (bytes, default 100 MB)
`httpClient.allowPrivateIPs`	bool	`false`	Allow requests to private/loopback IPs (SSRF protection)
`settings.requireSecureKeyring`	bool	`false`	Fail if OS keyring unavailable instead of insecure fallback
`resolver.timeout`	duration	`5m`	Overall resolver timeout
`resolver.concurrency`	int	`4`	Max parallel resolver execution
`action.timeout`	duration	`10m`	Overall action timeout
`action.concurrency`	int	`4`	Max parallel action execution
`auth.entra.*`	object	—	Entra (Azure AD) auth handler config
`auth.github.hostname`	string	`github.com`	GitHub hostname (or GHES hostname)
`auth.github.clientId`	string	built-in	OAuth App client ID
`auth.github.defaultScopes`	[]string	`[gist, read:org, repo, workflow]`	Default OAuth scopes

Config File Location#

The config file is located at the XDG config path:

Platform	Default Location
macOS	`~/.config/scafctl/config.yaml`
Linux	`~/.config/scafctl/config.yaml`
Windows	`%APPDATA%\scafctl\config.yaml`

Override with the --config flag on any command:

Bash

scafctl run solution my-solution --config ./custom-config.yaml

PowerShell

scafctl run solution my-solution --config ./custom-config.yaml

Examples#

Minimal Config#

See examples/config/minimal-config.yaml :

version: 1
settings:
  defaultCatalog: "local"
logging:
  level: "none"
catalogs:
  - name: local
    type: filesystem
    path: ~/scafctl-catalog/

Full Config#

See examples/config/full-config.yaml for a complete reference with all options documented.

Common Workflows#

Initial Setup#

Bash

# 1. Initialize config
scafctl config init

# 2. Set up a catalog
scafctl config add-catalog local --type filesystem --path ~/scafctl-catalog --default

# 3. Verify
scafctl config view
scafctl config validate

PowerShell

# 1. Initialize config
scafctl config init

# 2. Set up a catalog
scafctl config add-catalog local --type filesystem --path ~/scafctl-catalog --default

# 3. Verify
scafctl config view
scafctl config validate

Switch Environments#

Bash

# Use staging catalog
scafctl config use-catalog staging

# Increase logging for debugging
scafctl config set logging.level debug

# After debugging, reset
scafctl config unset logging.level

PowerShell

# Use staging catalog
scafctl config use-catalog staging

# Increase logging for debugging
scafctl config set logging.level debug

# After debugging, reset
scafctl config unset logging.level

Next Steps#

Authentication Tutorial — Set up GitHub and Entra authentication
Exec Provider Tutorial — Cross-platform shell execution
Logging & Debugging Tutorial — Control log verbosity, format, and output
Cache Tutorial — Manage cached data
Catalog Tutorial — Build and manage solutions in the catalog