scafctl

scafctl

Alpha — scafctl is under active development. APIs and CLI commands may change between releases. Breaking changes are documented in release notes. Questions? Open an issue or start a Discussion.

Define, discover, and deliver configuration as code using CEL-powered solutions.

scafctl is a CLI tool that lets you declaratively gather data from any source (APIs, files, environment, Git, and more), transform it with CEL expressions, and execute side-effect workflows — all defined in a single Solution file.

Core Concepts

• Solution — A YAML file that declares what data to gather and what work to do. Solutions are versionable, composable, and shareable via OCI registries.
• Resolver — A named unit that gathers or computes a value using one or more providers. Resolvers can depend on each other and execute in parallel when possible.
• Action — A side-effect operation (run a command, call an API, write a file) organized into a dependency graph with support for parallelism, retries, conditions, and forEach loops.
• Provider — A pluggable backend that does the actual work (e.g. http, exec, file, cel). scafctl ships with 10 built-in providers and 10 official plugin providers that auto-resolve from OCI catalogs.

Installation

Homebrew (macOS / Linux)

brew install oakwood-commons/tap/scafctl

From Release Binaries

Download the latest binary for your platform from the GitHub Releases page.

macOS / Linux

# Download (replace VERSION and OS/ARCH as needed)
curl -LO https://github.com/oakwood-commons/scafctl/releases/latest/download/scafctl_VERSION_OS_ARCH.tar.gz
tar xzf scafctl_*.tar.gz
sudo mv scafctl /usr/local/bin/

macOS note: You may need to remove the quarantine attribute before running:

xattr -dr 'com.apple.quarantine' /usr/local/bin/scafctl

Windows

Download the .zip archive for your architecture from GitHub Releases, extract it, and add the directory to your PATH.

From Source

go install github.com/oakwood-commons/scafctl/cmd/scafctl@latest

Shell Completion

Generate completions for your shell and add them to your profile:

# Bash
scafctl completion bash > /usr/local/etc/bash_completion.d/scafctl

# Zsh
scafctl completion zsh > "${fpath[1]}/_scafctl"

# Fish
scafctl completion fish > ~/.config/fish/completions/scafctl.fish

# PowerShell
scafctl completion powershell | Out-String | Invoke-Expression

Restart your shell (or source the file) for completions to take effect. Zsh users must have compinit loaded before the completion file is sourced.

Features

• Resolvers: Gather and transform configuration data from multiple sources
• Actions: Execute side-effect operations as a declarative action graph
• CEL Integration: Use Common Expression Language for dynamic evaluation
• Providers: 10 built-in + 10 official plugin providers (HTTP, exec, file, directory, git, CEL, and more)
• Catalog: Publish, version, and share reusable solutions via OCI registries
• Secrets: Encrypted secrets management with OS keyring integration
• Plugins: Extend scafctl with custom providers via a plugin system
• Snapshots: Capture and diff resolver output over time
• Linting: Validate solution files for correctness before execution
• Logging: Quiet by default with user-controlled verbosity, format, and file output

Quick Start

Resolvers: Compute Data

Resolvers gather and transform configuration data:

apiVersion: scafctl.io/v1
kind: Solution
metadata:
  name: my-config
  version: 1.0.0

spec:
  resolvers:
    environment:
      type: string
      resolve:
        with:
          - provider: env
            inputs:
              name: ENVIRONMENT
              default: development

Run: scafctl run solution -f config.yaml

Actions: Execute Work

Actions perform side-effect operations based on resolver data:

apiVersion: scafctl.io/v1
kind: Solution
metadata:
  name: deploy-workflow
  version: 1.0.0

spec:
  resolvers:
    targets:
      type: array
      resolve:
        with:
          - provider: static
            inputs:
              value: ["server1", "server2"]

  workflow:
    actions:
      deploy:
        provider: exec
        forEach:
          in:
            expr: "_.targets"
        inputs:
          command:
            expr: "'deploy.sh ' + __item"

Run: scafctl run solution -f deploy.yaml

Built-in Providers

scafctl ships with 16 providers. Use scafctl explain provider <name> to see full schema and examples.

See the Provider Reference and Provider Development tutorials.

Documentation

Tutorials

• Getting Started — First steps with scafctl
• Resolvers — Gathering and transforming data
• Actions — Executing operations
• Authentication — Entra ID and service principals
• Catalog — Publishing and sharing solutions
• CEL Expressions — Dynamic evaluation with CEL
• Go Templates — Templating with Go templates
• Configuration — Managing application settings
• Logging — Controlling log output, formats, and destinations
• Caching — Provider result caching
• Directory Provider — Listing, scanning, and managing directories
• Snapshots — Capturing and diffing output
• Provider Development — Building providers (builtin and plugin)
• Auth Handler Development — Building auth handlers (builtin and plugin)
• Extension Concepts — Provider vs Auth Handler vs Plugin terminology
• Plugin Development — Plugin overview and discovery

Design Documents

Architecture and design decisions are documented in docs/design/.

Examples

• Resolver examples
• Action examples
• Catalog examples
• Solution examples

Authentication

scafctl supports secure authentication for accessing protected APIs. Currently supported:

• Microsoft Entra ID (Azure AD) - Device code flow and Service Principal

Quick Auth Setup

# Interactive: Authenticate with Entra ID (device code)
scafctl auth login entra

# CI/CD: Authenticate with service principal
export AZURE_CLIENT_ID="..."
export AZURE_TENANT_ID="..."
export AZURE_CLIENT_SECRET="..."
scafctl auth login entra --flow service-principal

# Check authentication status
scafctl auth status

# Use authenticated HTTP requests
scafctl run solution -f my-solution.yaml

Authenticated HTTP Requests

Use the authProvider and scope properties in HTTP providers:

spec:
  resolvers:
    me:
      type: object
      resolve:
        with:
          - provider: http
            inputs:
              url: "https://graph.microsoft.com/v1.0/me"
              method: GET
              authProvider: entra
              scope: "https://graph.microsoft.com/.default"

See the Authentication Tutorial for more details.

Catalog

The catalog system lets you publish, version, and share solutions using OCI-compatible registries:

# Package a solution into an OCI artifact
scafctl package solution -f solution.yaml

# Push to a registry
scafctl catalog push my-solution@1.0.0 --catalog ghcr.io/myorg

# Pull from a configured catalog
scafctl catalog pull my-solution@1.0.0 --catalog my-registry
scafctl catalog inspect my-solution@1.0.0

# List local catalog entries
scafctl catalog list

See the Catalog Tutorial and Catalog Design.

Configuration

scafctl stores its configuration in XDG-compliant paths. Use the config command to manage settings:

# Initialize default config
scafctl config init

# View current config
scafctl config show

# Set / get / unset values
scafctl config set defaultOutput json
scafctl config get defaultOutput
scafctl config unset defaultOutput

# Manage catalog registries
scafctl catalog remote add my-registry --type oci --url oci://ghcr.io/myorg
scafctl catalog remote remove my-registry

See the Configuration Tutorial.

Logging

By default, scafctl produces no structured log output — only styled user messages (errors, warnings, success). This keeps the CLI clean for human users and pipe-friendly for scripts.

Quick Reference

# Default: no logs, just styled errors/warnings
scafctl run solution -f solution.yaml

# Enable debug logging (human-readable console format)
scafctl run solution -f solution.yaml --debug
scafctl run solution -f solution.yaml --log-level debug

# JSON structured logs (for log aggregation / piping)
scafctl run solution -f solution.yaml --log-level info --log-format json

# Write logs to a file instead of stderr
scafctl run solution -f solution.yaml --debug --log-file /tmp/scafctl.log

# Environment variables (useful for CI/CD)
export SCAFCTL_DEBUG=1             # Enable debug logging
export SCAFCTL_LOG_LEVEL=info      # Set specific level
export SCAFCTL_LOG_FORMAT=json     # Set format
export SCAFCTL_LOG_PATH=/tmp/scafctl.log  # Log to file

Log Levels

Precedence

Flag (--log-level) > --debug > environment variable > config file > default (none)

See the Logging Tutorial for detailed examples.

Secrets

scafctl provides encrypted secrets management backed by the OS keyring or the SCAFCTL_SECRET_KEY environment variable:

# Store a secret
scafctl secrets set my-api-key

# Retrieve / check / list
scafctl secrets get my-api-key
scafctl secrets exists my-api-key
scafctl secrets list

# Include internal secrets (e.g. auth tokens)
scafctl secrets list --all
scafctl secrets get scafctl.auth.entra.metadata --all

# Rotate encryption key
scafctl secrets rotate

# Import / export for migration
scafctl secrets export --file secrets.enc
scafctl secrets import --file secrets.enc

Use the secret provider to access secrets in solutions:

spec:
  resolvers:
    api_key:
      type: string
      resolve:
        with:
          - provider: secret
            inputs:
              name: my-api-key

Plugins

scafctl supports external plugins that extend the provider and auth handler systems. Plugins are standalone executables that communicate via gRPC.

See the Plugin Design, Provider Development Guide, and Auth Handler Development Guide.

Actions Overview

The Actions system enables executing operations as a declarative dependency graph:

Key Features

• Dependencies: Actions can depend on other actions
• Parallel Execution: Independent actions run in parallel
• ForEach: Iterate over arrays with concurrency control
• Conditions: Skip actions based on conditions
• Error Handling: Continue or fail on errors
• Retry: Automatic retry with backoff strategies
• Timeouts: Per-action timeout limits
• Finally: Cleanup actions that always run

Example: CI/CD Pipeline

workflow:
  actions:
    build:
      provider: exec
      inputs:
        command: "go build ./..."

    test:
      provider: exec
      dependsOn: [build]
      inputs:
        command: "go test ./..."

    deploy:
      provider: exec
      dependsOn: [test]
      forEach:
        in:
          expr: "_.servers"
        concurrency: 2
      inputs:
        command:
          expr: "'deploy.sh ' + __item"

  finally:
    notify:
      provider: http
      inputs:
        url: "https://slack.webhook/..."

CLI Commands

scafctl is organized into command groups. Run scafctl <command> --help for details on any command.

# Run a solution (resolvers + actions)
scafctl run solution -f config.yaml
scafctl run solution -f config.yaml -o json      # JSON output
scafctl run solution -f config.yaml --dry-run     # Dry run
scafctl run solution -f config.yaml --progress    # Progress output

# Run resolvers only (debugging and inspection)
scafctl run resolver -f config.yaml
scafctl run resolver db config -f config.yaml     # Specific resolvers
scafctl run resolver --verbose -f config.yaml     # Verbose mode

# Render solution to structured output
scafctl render solution -f config.yaml -o json
scafctl render solution -f config.yaml -o yaml

# Build and bundle solutions
scafctl package solution -f solution.yaml

# Catalog operations
scafctl catalog list
scafctl catalog push my-solution@1.0.0
scafctl catalog pull my-solution@1.0.0
scafctl catalog inspect my-solution@1.0.0

# Bundle diffing and extraction
# (bundle completeness is verified automatically: package fails the build if
# incomplete, and catalog pull warns by default -- use --strict to fail)
scafctl diff bundle my-solution@1.0.0 my-solution@2.0.0
scafctl extract bundle my-solution@1.0.0

# Inspect providers and solutions
scafctl explain provider http
scafctl explain solution -f solution.yaml
scafctl get provider
scafctl get resolver -f solution.yaml

# Lint and validate
scafctl lint -f solution.yaml

# Snapshots
scafctl render solution -f solution.yaml --snapshot --snapshot-file baseline.json
scafctl get snapshot baseline.json
scafctl diff snapshot --from baseline --to current

# Resolver dependency graph
scafctl run resolver -f solution.yaml --graph

# Configuration and secrets
scafctl config show
scafctl secrets list
scafctl secrets list --all  # include auth tokens

# Authentication
scafctl auth login entra
scafctl auth status

# Dependency vendoring
scafctl vendor update -f solution.yaml

# Cache management
scafctl cache info
scafctl cache clear

# Version
scafctl version

Contributing

Contributions are welcome! Please see:

• CONTRIBUTING.md — Development setup, coding standards, and contribution workflow
• CODE_OF_CONDUCT.md — Community guidelines
• SECURITY.md — Reporting security vulnerabilities

Have a question? Start a GitHub Discussion.

License

This project is licensed under the Apache License 2.0 — see the LICENSE file for details.