Tutorials on scafctl

Getting Started

Mon, 01 Jan 0001 00:00:00 +0000

Getting Started with scafctl#

This guide will help you get up and running with scafctl in under 10 minutes.

What is scafctl?#

scafctl is a CLI tool for declarative configuration and workflow automation. It uses:

Resolvers to gather and transform data
Actions to perform side effects
Providers as the execution primitives for both

Think of it as a way to define “what you want” (data + operations) in YAML, and let scafctl figure out “how to do it” (dependency order, parallelization, error handling).

Solution Scaffolding Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

Solution Scaffolding Tutorial#

This tutorial covers using scafctl new solution to quickly scaffold new solution files with the correct structure, providers, and best practices.

Overview#

The new solution command generates a complete, valid solution YAML file based on your inputs. Instead of writing YAML from scratch (and getting field names wrong), scaffolding gives you a working starting point.

flowchart LR
 A["Parameters<br/>(name, etc)"] --> B["scafctl<br/>new solution"] --> C["Solution<br/>YAML File"]

1. Quick Start#

Generate a Basic Solution#

Bash

scafctl new solution \
 --name my-app \
 --description "My application configuration" \
 --output my-app.yaml

PowerShell

scafctl new solution `
 --name my-app `
 --description "My application configuration" `
 --output my-app.yaml

This generates a valid solution file with:

Resolver Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

Resolver Tutorial#

This tutorial walks you through using scafctl resolvers to dynamically resolve configuration values. You’ll learn how to define resolvers, use different providers, handle dependencies, and implement common patterns.

Prerequisites#

scafctl installed and available in your PATH
Basic familiarity with YAML syntax
Understanding of environment variables

Your First Resolver#

Let’s create a simple solution with one resolver that returns a static value.

Run Resolver Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

Run Resolver Tutorial#

This tutorial covers the scafctl run resolver command — a debugging and inspection tool for executing resolvers without running actions. You’ll learn how to run all resolvers, target specific resolvers, inspect execution metadata, skip phases, and visualize dependencies.

Prerequisites#

scafctl installed and available in your PATH
Familiarity with resolvers
A solution file with defined resolvers

Table of Contents#

Run All Resolvers
Run Specific Resolvers
Execution Metadata
Skipping Phases
Dependency Graph
Snapshots
Output Formats
Debugging Dependencies
Working with Parameters
Common Workflows

A note on __execution metadata: When using JSON or YAML output, run resolver automatically includes an __execution key containing execution metadata (timing, dependency graph, provider stats). Throughout this tutorial, examples use --hide-execution to keep output focused on resolver values. See Execution Metadata for details on this feature.

Run Provider Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

Run Provider Tutorial#

This tutorial covers the scafctl run provider command — a tool for executing individual providers directly without a solution or resolver file. This is useful for testing, debugging, and exploring providers in isolation.

Prerequisites#

scafctl installed and available in your PATH
Familiarity with providers

Table of Contents#

Basic Usage
Passing Inputs
File-Based Inputs
Capabilities
Dry Run
Output Formats
Plugin Providers
Discovering Providers
Common Examples

Basic Usage#

The scafctl run provider command takes a provider name as its first argument. Provider inputs can be passed as positional key=value arguments or via the traditional --input flag:

Actions Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

Actions Tutorial#

This tutorial introduces the Actions feature in scafctl, which enables executing side-effect operations as a declarative action graph.

Overview#

Actions are the execution phase of a scafctl solution. While resolvers compute and gather data, actions perform work based on that data.

flowchart LR
 A["Resolvers<br/>(compute)"] --> B["Actions<br/>(execute)"] --> C["Results<br/>(outputs)"]

Key Principles:

Resolvers compute data, actions perform work
All resolvers evaluate before any action executes
Actions can depend on other actions
Actions can access results from completed actions

Quick Start#

1. Hello World#

The simplest action workflow. Create a file called hello-actions.yaml:

Authentication Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

Authentication Tutorial#

This tutorial walks you through setting up and using authentication in scafctl. You’ll learn how to authenticate with Microsoft Entra ID, GitHub, and Google Cloud Platform, manage credentials, and use authenticated HTTP requests in your solutions.

Prerequisites#

scafctl installed and available in your PATH
For Entra: Access to a Microsoft Entra ID tenant
For GitHub: A GitHub account (or GitHub Enterprise Server instance)
For GCP: A Google Cloud account
A web browser for completing the device code flow

Table of Contents#

Understanding Auth in scafctl
Logging In
Checking Auth Status
Listing and Sorting Cached Tokens
Using Auth in HTTP Providers
Getting Tokens for Debugging
Configuration
Logging Out
Auth Diagnostics
Troubleshooting

Understanding Auth in scafctl#

Authentication in scafctl follows these principles:

Docker Credential Helper Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

Docker Credential Helper Tutorial#

This tutorial shows how to use scafctl as a Docker/Podman credential helper, exposing scafctl’s AES-256-GCM encrypted credential store to the container ecosystem.

Prerequisites#

scafctl installed and available in your PATH
Docker, Podman, or Buildah installed
Familiarity with Authentication Tutorial

Table of Contents#

Overview
Quick Setup
Manual Setup
Per-Registry Configuration
How It Works
Using with Podman/Buildah
Verification
Composing with catalog login
Uninstall
Troubleshooting

Overview#

The Docker credential helper protocol allows external programs to manage registry credentials for Docker, Podman, and Buildah. By using scafctl as a credential helper, you get:

GCP Custom OAuth Client Setup

Mon, 01 Jan 0001 00:00:00 +0000

GCP Custom OAuth Client Setup#

By default, scafctl auth login gcp runs a native browser OAuth flow using Google’s well-known ADC client credentials — the same ones used by gcloud auth application-default login. This works out of the box with no gcloud installation required.

You may want to set up your own OAuth client if:

Your organization restricts which OAuth client IDs are allowed
You need specific OAuth consent screen branding or approval
You want full control over the client lifecycle and scopes

Note: If you were previously seeing invalid_grant - reauth related error (invalid_rapt) errors, upgrading scafctl to the latest version resolves this — the native browser OAuth flow is no longer affected by gcloud’s RAPT token expiry.

Eval Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

Eval Tutorial#

This tutorial covers using the scafctl eval command group to test CEL expressions, render Go templates, and validate solution files — all without running a full solution.

Overview#

The eval commands are developer tools for quick iteration:

eval cel — Evaluate CEL expressions with inline or file-based data
eval template — Render Go templates against JSON/YAML data

For solution file validation, use the separate scafctl lint command (covered in Section 3 below).

Linting Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

Linting Tutorial#

This tutorial covers using scafctl’s lint commands to validate solution files, explore available lint rules, and understand how to fix issues.

Overview#

scafctl includes a built-in linter that checks solution YAML files for:

Schema violations — Invalid field names, wrong types, missing required fields
Best practices — Missing descriptions, unused resolvers, naming conventions
Correctness — Broken resolver references, invalid CEL expressions, circular dependencies

flowchart LR
 A["Solution<br/>YAML"] --> B["scafctl<br/>lint"] --> C["Findings<br/>(warnings, errors)"]

1. Linting a Solution#

Basic Lint#

Bash

scafctl lint -f solution.yaml

PowerShell

scafctl lint -f solution.yaml

If your solution file is in a well-known location (solution.yaml, scafctl.yaml, etc. in the current directory or scafctl//.scafctl/ subdirectories), you can omit -f:

CEL Expressions Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

CEL Expressions Tutorial#

This tutorial covers using CEL (Common Expression Language) expressions in scafctl for data transformation, conditional logic, and dynamic configuration.

Overview#

CEL is used throughout scafctl for dynamic evaluation:

Resolver transforms — Compute derived values from other resolvers
Action inputs — Build dynamic commands and configurations
Conditions — Conditionally skip actions with when
forEach — Generate iteration lists dynamically

flowchart LR
 A["Resolver<br/>Data"] -- "_ namespace" --> B["CEL<br/>Expression"] --> C["Result<br/>Value"]

Key principle: In CEL expressions, all resolved values are available under the _ namespace (e.g., _.appName, _.config.port).

REST API Server Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

REST API Server#

scafctl includes a built-in REST API server that exposes all major CLI features as HTTP endpoints. The server uses chi for routing and Huma for OpenAPI-compliant endpoint registration.

Starting the Server#

# Start with defaults (port 8080, host 127.0.0.1)
scafctl serve

# Start on a custom port
scafctl serve --port 9090

# Start with TLS
scafctl serve --enable-tls --tls-cert cert.pem --tls-key key.pem

# Custom API version prefix
scafctl serve --api-version v2

Configuration#

The server reads its configuration from the apiServer section of the scafctl config file:

Go Templates Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

Go Templates Tutorial#

This tutorial walks you through using Go templates in scafctl to generate structured text output like configuration files, documentation, and code scaffolding. You’ll start with a simple template and progressively learn conditionals, loops, whitespace control, file-based templates, custom delimiters, and multi-file generation.

Prerequisites#

scafctl installed and available in your PATH
Basic familiarity with YAML syntax
Completion of the Resolver Tutorial and Actions Tutorial

Table of Contents#

Your First Template
Using Conditionals
Iterating Over Lists
Iterating Over Maps
Controlling Whitespace
Loading Templates from Files
Handling Missing Keys
Injecting Additional Data
Using Custom Delimiters
Using tmpl for Dynamic Inputs
Generating Multiple Files with ForEach
Rendering Template Directories
Putting It All Together: README Generator
Using Sprig Functions
Converting Data to HCL with toHcl
Serializing and Parsing YAML with toYaml / fromYaml
DNS-Safe Strings with slugify / toDnsString
Filtering Lists with where / selectField
Inline CEL with cel
Debugging Template Type Errors
Discovering Available Functions

Overview#

scafctl supports Go templates in two ways:

Catalog Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

Catalog Tutorial#

This tutorial walks you through using scafctl’s local catalog to build, version, inspect, export, and share solutions. You’ll start by building your first solution into the catalog and progressively work through versioning, cleanup, air-gapped transfers, remote registries, tagging, and advanced bundling with file dependencies.

Prerequisites#

scafctl installed and available in your PATH
Basic familiarity with YAML syntax
Completion of the Resolver Tutorial

Table of Contents#

Building Your First Solution
Running from the Catalog
Listing and Inspecting
Managing Multiple Versions
Deleting and Pruning
Exporting and Importing
Tagging Artifacts
Remote Registries
Bundling File Dependencies
Verifying and Extracting Bundles
Comparing Bundle Versions

Building Your First Solution#

Let’s build a simple solution and store it in the local catalog so you can run it by name from anywhere.

MCP Server Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

MCP Server Tutorial#

This tutorial walks you through setting up scafctl’s Model Context Protocol (MCP) server so that AI agents — GitHub Copilot, Claude, Cursor, Windsurf, and others — can discover and invoke scafctl tools programmatically.

Prerequisites#

scafctl installed and on your $PATH (scafctl version should work)
An MCP-compatible AI client (VS Code with Copilot, Claude Desktop, Cursor, or Windsurf)

What Is the MCP Server?#

The MCP server is a local process that translates between the AI agent’s JSON-RPC protocol and scafctl’s Go library functions. When an AI agent decides to use a tool (e.g., “lint this solution”), it sends a structured request to the MCP server, which calls the same code that the CLI commands use and returns structured JSON results.

Security Hardening

Mon, 01 Jan 0001 00:00:00 +0000

Security Hardening Guide#

This guide covers scafctl’s built-in security protections and how to configure them for production environments.

HTTP Provider Security#

Response Body Size Limits#

The HTTP provider limits the amount of data it will read from any single response to prevent denial-of-service via unbounded responses. The default limit is 100 MB.

# config.yaml — adjust the limit
httpClient:
 maxResponseBodySize: 104857600 # 100 MB (default)

The limit applies to both direct requests and each page in paginated requests. If a response exceeds the limit, the provider returns an error rather than consuming unbounded memory.

REST API Server Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

REST API Server Tutorial#

This tutorial walks you through starting scafctl’s REST API server and interacting with its endpoints. The API mirrors all major CLI features — solutions, providers, catalogs, schemas, eval, config, and more — over HTTP with OpenAPI documentation.

Prerequisites#

scafctl installed and on your $PATH (scafctl version should work)
curl or any HTTP client for testing

Quick Start#

Start the Server#

scafctl serve

The server starts on http://localhost:8080 by default.

Validation Patterns Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

Validation Patterns Tutorial#

Learn how to validate resolver outputs, enforce constraints on inputs, and use schema validation to catch issues early.

Overview#

scafctl offers multiple validation layers that work together to ensure configuration correctness:

block-beta
 columns 4
 block:top:4
 A["Solution YAML"]
 end
 B["Lint<br/>Rules"] C["Schema<br/>Helper Tags"] D["Validate<br/>Provider"] E["Result<br/>Schema"]
 block:bottom:4
 F["Runtime Validation (CEL + Regex)"]
 end

Schema helper tags — provider-level input constraints (type, length, pattern, enum)
Validation provider — runtime regex and CEL-based checks on resolver values
Result schemas — JSON Schema validation of action outputs
Lint rules — static analysis at scafctl lint time

1. Schema-Level Validation with Provider Inputs#

Provider schemas use JSON Schema constraints to reject invalid input before execution.

Provider Output Shapes

Mon, 01 Jan 0001 00:00:00 +0000

Provider Output Shapes#

Quick reference for what each built-in provider returns in resolver output — the data shape you can access via _.resolverName in CEL expressions and Go templates.

How Provider Output Works#

When a resolver uses a provider, the resolved value becomes accessible to other resolvers. The output shape determines what fields are available:

flowchart LR
 A["Resolver: api_data<br/>provider: http<br/>output: body, statusCode, headers"] --> B["Resolver: summary<br/>expr: _.api_data<br/>.body.items | size()"]

Tip: Use the MCP tool get_provider_output_shape to query output schemas programmatically, or get_provider_schema for full provider documentation.

Message Provider Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

Message Provider Tutorial#

This tutorial covers using the message provider for rich terminal output during solution execution — styled messages with icons, colors, and dynamic interpolation via tmpl:/expr: ValueRefs.

Overview#

The message provider replaces awkward exec + echo patterns with first-class terminal messaging that integrates with scafctl’s --quiet, --no-color, and --dry-run flags.

flowchart LR
 A["Resolver<br/>Data"] --> B["Message<br/>Provider"]
 B -- "styled output" --> C["Terminal<br/>(stdout/stderr)"]
 B -- "data" --> D["Output<br/>{success, message}"]

Key features:

Built-in message types: success, warning, error, info, debug, plain
Custom styling: colors (hex or named), bold, italic, custom icons/emoji
Contextual labels: dimmed [label] prefixes for step tracking (e.g., [step 2/5], [deploy])
Dynamic interpolation via framework tmpl: and expr: ValueRefs (with automatic dependency detection)
Respects --quiet flag (messages suppressed in quiet mode)
Trailing newline control via the newline field
Dry-run awareness via --dry-run

Quick Start#

Step 1: Create the Solution File#

Create a file called message-basics.yaml:

Snapshots Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

Snapshots Tutorial#

This tutorial covers using execution snapshots for debugging, testing, and comparing solution runs.

Overview#

Snapshots capture the state of resolver execution — values, timing, status, errors, and parameters — as a JSON file. They’re useful for:

Debugging — Inspect what every resolver produced
Testing — Compare before/after to catch regressions
Auditing — Record what ran and what it produced
Sharing — Send a snapshot to a teammate for review (with redaction for secrets)

flowchart LR
 A["render<br/>solution"] --> B["Snapshot<br/>(JSON)"] --> C["show / diff<br/>commands"]

When to Use Snapshots#

Snapshots are flag-triggered (--snapshot), never automatically created. Here are the real-world scenarios where they provide value:

Functional Testing

Mon, 01 Jan 0001 00:00:00 +0000

Functional Testing#

Functional testing lets you define automated tests for your solutions directly in the solution YAML. Tests execute scafctl commands in isolated sandboxes and validate output using assertions, snapshots, and CEL expressions.

This tutorial walks through every feature of scafctl test functional — from basic tests to advanced CI integration.

Writing Your First Test#

Add a testing section to your solution’s spec. Create a file called solution.yaml:

apiVersion: scafctl.io/v1
kind: Solution
metadata:
 name: my-solution
spec:
 resolvers:
 greeting:
 description: A greeting message
 resolve:
 with:
 - provider: static
 inputs:
 value: Hello, World!

 testing:
 cases:
 render-basic:
 description: Verify solution renders successfully
 command: [render, solution]
 assertions:
 - expression: __exitCode == 0
 - contains: greeting

Run the test:

Solution Diff Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

This tutorial covers comparing two solution files structurally to understand what changed between versions. The soldiff package detects additions, removals, and modifications across metadata, resolvers, actions, and testing sections.

Overview#

Solution diffing answers the question: “What structurally changed between two versions of a solution?” Unlike git diff which shows text changes, soldiff understands the solution schema and reports meaningful structural differences.

┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ solution-v1 │ │ soldiff │ │ Result │
│ .yaml │ ──► │ .Compare() │ ──► │ (changes, │
│ │ │ │ │ summary) │
│ solution-v2 │ ──► │ │ │ │
│ .yaml │ │ │ │ │
└──────────────┘ └──────────────┘ └──────────────┘

When to Use Solution Diff#

Use Case	Scenario
Code review	Review structural impact of solution YAML changes before merging
Configuration drift	Detect when a deployed solution has drifted from the expected baseline
Refactoring validation	Confirm a refactor didn’t accidentally add/remove resolvers or actions
Version comparison	Compare v1 and v2 of a solution to document what changed

CLI Usage#

Basic Comparison#

Bash

scafctl solution diff -f solution-v1.yaml -f solution-v2.yaml

PowerShell

scafctl solution diff -f solution-v1.yaml -f solution-v2.yaml

Output:

Dry-Run Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

Dry-Run Tutorial#

This tutorial covers using --dry-run to preview what a solution execution would do without performing any side effects.

Overview#

Dry-run mode resolves all values and builds an action execution plan, but never executes actions. This gives you a complete picture of what would happen:

flowchart LR
 A["Solution<br/>(.yaml)"] --> B["Dry-Run Generator<br/>⚠️ No side effects!"] --> C["Report<br/>(resolvers, actions, phases)"]

When to Use Dry-Run#

Use Case	Scenario
Pre-flight check	Verify all resolvers produce expected values before executing actions
Action plan review	See the execution order, phases, and dependencies before running
CI validation	Assert resolver outputs in a pipeline without side effects
Debugging	Understand why a solution behaves unexpectedly by inspecting resolved values
Documentation	Generate a report of what a solution does for review or audit

CLI Usage#

Dry-Run a Full Solution#

Bash

scafctl run solution -f solution.yaml --dry-run

PowerShell

scafctl run solution -f solution.yaml --dry-run

This resolves all values and shows the action plan without executing any actions.

Output Directory Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

Output Directory Tutorial#

This tutorial walks you through using the --output-dir flag to redirect action output to a specific directory. You’ll learn the phase-based directory model, how resolvers and actions differ in path handling, and how to reference the original working directory with __cwd.

Prerequisites#

scafctl installed and available in your PATH
Basic familiarity with YAML syntax and solution files
Completion of the Getting Started tutorial

Table of Contents#

Overview
Phase-Based Directory Model
Basic Usage
Using __cwd for Original Directory Access
Combining with Dry-Run
Per-Provider Usage
Default via Configuration
Absolute Paths Are Never Rewritten
Affected Providers
Common Patterns

Overview#

By default, actions resolve relative paths against the current working directory (CWD). The --output-dir flag changes this so actions write to a designated output directory instead, while resolvers continue reading from CWD.

Auto-Discovery Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

Auto-Discovery Tutorial#

This tutorial explains how scafctl automatically discovers solution files, making the -f flag optional for most commands.

Prerequisites#

scafctl installed and available in your PATH
Basic familiarity with YAML syntax and solution files
Completion of the Getting Started tutorial

Table of Contents#

Overview
How Auto-Discovery Works
Search Order
Supported Commands
Examples
Interaction with --cwd
When Auto-Discovery Fails
Best Practices

Overview#

Many scafctl commands accept a -f / --file flag to specify the solution file path. When this flag is omitted, scafctl searches the current directory (or the --cwd target) for a solution file using a well-defined search order.

Configuration Management

Mon, 01 Jan 0001 00:00:00 +0000

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:

File Provider Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

File Provider Tutorial#

This tutorial walks you through using the file provider to read, write, check existence, delete files, and write multiple files at once with write-tree. You’ll learn how to use conflict strategies, backups, append with deduplication, and dry-run mode.

Prerequisites#

scafctl installed and available in your PATH
Basic familiarity with YAML syntax and solution files

Table of Contents#

Reading Files
Writing Files
Checking File Existence
Deleting Files
Writing Multiple Files (write-tree)
Conflict Strategies
Append with Deduplication
Backups
Per-Entry Overrides in write-tree
CLI Flags
Dry-Run Mode
Common Patterns

Reading Files#

The read operation reads the contents of a file. Create a file called read-file.yaml:

Exec Provider Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

Exec Provider Tutorial#

This tutorial walks you through using the exec provider to run shell commands cross-platform. You’ll learn how the embedded POSIX shell works, how to use pipes, environment variables, timeouts, and when to use external shells like bash or PowerShell.

Prerequisites#

scafctl installed and available in your PATH
Basic familiarity with YAML syntax and solution files
(Optional) bash and/or pwsh installed for external shell examples

Table of Contents#

How It Works
Running Simple Commands
Pipes and Shell Features
Arguments
Environment Variables
Working Directory
Standard Input
Timeouts
Shell Types
Cross-Platform Patterns
Error Handling
Common Patterns

How It Works#

The exec provider uses an embedded POSIX shell (powered by mvdan.cc/sh ) as its default execution engine. This means:

Directory Provider Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

Directory Provider Tutorial#

This tutorial walks you through using the directory provider to list, scan, create, remove, and copy directories. You’ll learn how to use filtering, recursive traversal, content reading, and checksums for filesystem-oriented workflows.

Prerequisites#

scafctl installed and available in your PATH
Basic familiarity with YAML syntax and solution files
A local directory with some files to experiment with

Table of Contents#

Listing Directory Contents
Recursive Traversal
Filtering with Globs and Regex
Reading File Contents
Computing Checksums
Creating Directories
Removing Directories
Copying Directories
Dry Run Mode
Common Patterns

Listing Directory Contents#

The simplest use of the directory provider is listing files and directories in a given path. Create a file called list-dir.yaml:

Logging & Debugging

Mon, 01 Jan 0001 00:00:00 +0000

Logging & Debugging Tutorial#

This tutorial covers controlling scafctl’s log output — verbosity, format, destination, and environment variable overrides.

Overview#

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

When you need to see what’s happening under the hood — debugging a solution, reporting a bug, or feeding structured logs to a log aggregation system — scafctl gives you full control over log verbosity, format, and destination.

HCL Provider Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

HCL Provider Tutorial#

This tutorial walks you through using the hcl provider to parse Terraform and OpenTofu configuration files. You’ll learn how to extract variables, resources, modules, outputs, and other block types from HCL content.

Prerequisites#

scafctl installed and available in your PATH
Basic familiarity with YAML syntax and solution files
Basic understanding of Terraform/OpenTofu configuration syntax

Table of Contents#

Parsing Inline HCL Content
Parsing HCL Files
Multi-File and Directory Support
Extracting Variables
Extracting Resources
Working with Modules
Terraform Block Extraction
Combining with CEL Expressions
Transform Capability
Expression Handling
Common Patterns
Formatting HCL Content
Validating HCL Syntax
Generating HCL from Structured Data
Generating Terraform JSON (.tf.json)

Parsing Inline HCL Content#

The simplest way to use the HCL provider is with inline content. Create a file called parse-hcl.yaml:

Telemetry (Traces, Metrics, Logs)

Mon, 01 Jan 0001 00:00:00 +0000

Telemetry Tutorial#

scafctl emits all three OpenTelemetry signals — logs, traces, and metrics. By default, telemetry is silent (noop providers). When you point scafctl at an OTLP endpoint every signal is exported for backend analysis.

Overview#

Signal	Default output	With `--otel-endpoint`
Logs	slog text/JSON → stderr (via `--log-level`)	Also batched via OTLP gRPC
Traces	Disabled (noop)	Exported via OTLP gRPC
Metrics	Prometheus `/metrics` (MCP server)	Also pushed via OTLP gRPC

Configuration#

Flags (per-invocation)#

Bash

# Point at a local OTel Collector
scafctl run solution -f solution.yaml \
 --otel-endpoint localhost:4317 \
 --otel-insecure # disable TLS (development only)

# Override with environment variable instead
OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4317 \
 scafctl run solution -f solution.yaml

PowerShell

# Point at a local OTel Collector
scafctl run solution -f solution.yaml `
 --otel-endpoint localhost:4317 `
 --otel-insecure # disable TLS (development only)

# Override with environment variable instead
$env:OTEL_EXPORTER_OTLP_ENDPOINT = 'localhost:4317'
scafctl run solution -f solution.yaml

Flag	Env override	Default	Description
`--otel-endpoint`	`OTEL_EXPORTER_OTLP_ENDPOINT`	(none)	OTLP gRPC endpoint. When unset, tracing is disabled (noop).
`--otel-insecure`	(none)	`false`	Skip TLS verification. Use in local dev only.

Signals in Detail#

Logs#

Logs use the go-logr/logr interface throughout the codebase. The underlying sink is a multiSink that fans out to:

Template Directory Rendering

Mon, 01 Jan 0001 00:00:00 +0000

Template Directory Rendering Tutorial#

This tutorial walks you through the recommended pattern for rendering a directory tree of Go templates into output files while preserving the directory structure. You’ll learn how to combine three providers — directory, go-template, and file — in a single solution to scaffold entire projects from templates.

Prerequisites#

scafctl installed and available in your PATH
Basic familiarity with solution files and Go template syntax

Table of Contents#

Overview
Setting Up Templates
Reading Templates with the Directory Provider
Batch Rendering with render-tree
Writing Files with write-tree
Path Transformation with outputPath
Putting It All Together
Advanced Patterns

Overview#

A common scaffolding task is:

Cache Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

Managing the Cache#

This tutorial covers how to use scafctl’s cache management commands to view and clear cached data.

What is Cached?#

scafctl caches certain data to improve performance:

Cache Type	Description	Use Case
HTTP Cache	Responses from HTTP provider requests	Avoid repeated network calls
Build Cache	Incremental build fingerprints	Skip unchanged solution rebuilds
Remote Artifact Cache	Auto-cached artifacts from remote catalogs	Offline access to previously fetched solutions

Caching reduces network latency, speeds up builds, and allows offline access to previously fetched resources.

Provider Reference

Mon, 01 Jan 0001 00:00:00 +0000

Provider Reference#

This document provides a reference for all built-in providers in scafctl.

Note: All YAML examples in this reference show only the relevant resolver or action snippet. To use them, place each snippet inside a complete solution file with apiVersion, kind, metadata, and spec sections. See the Getting Started tutorial for the full solution structure.

Overview#

Providers are execution primitives used by resolvers and actions. Each provider has capabilities that determine where it can be used:

Extension Concepts

Mon, 01 Jan 0001 00:00:00 +0000

Extension Concepts#

scafctl is built on two types of extensions: providers and auth handlers. Each can be delivered as a builtin (compiled into the scafctl binary) or as a plugin (a standalone binary communicating over gRPC).

This page defines the core terminology and links to the detailed development guides.

Terminology#

Term	Definition
Provider	A stateless execution unit that performs a single operation: fetching data (`from`), transforming values (`transform`), validating inputs (`validation`), executing side effects (`action`), or authenticating requests (`authentication`). Providers are the building blocks used inside solution resolvers.
Auth Handler	A stateful authentication manager that handles identity verification, credential storage, token acquisition, and request injection. Auth handlers manage OAuth flows, cache tokens across invocations, and are used by providers (like `http`) to authenticate outgoing requests.
Builtin	An extension compiled directly into the scafctl binary. Builtin extensions are registered at startup and require no external binaries. Contributing a builtin extension means adding code to the scafctl repository.
Plugin	An extension delivered as a standalone executable that communicates with scafctl over gRPC using hashicorp/go-plugin . Plugins run as separate processes, can be written in any gRPC-capable language, and are distributed independently via OCI catalogs, Go modules, or binary releases.
Extension	Umbrella term for any provider or auth handler, whether builtin or plugin.
Capability	A declared feature of a provider (e.g., `from`, `transform`, `action`) or auth handler (e.g., `scopes_on_login`, `tenant_id`). Capabilities let scafctl adapt behavior dynamically without hardcoded knowledge of each extension.

Extension Matrix#

	Builtin	Plugin
Provider	Compiled into scafctl; 16 built-in providers (http, cel, exec…)	Standalone gRPC binary; auto-fetched from OCI catalogs
Auth Handler	Compiled into scafctl; 3 built-in handlers (entra, github, gcp)	Standalone gRPC binary; auto-fetched from OCI catalogs

When to Choose Builtin vs Plugin#

Factor	Builtin	Plugin
Distribution	Ships with scafctl	Distributed independently
Language	Go only	Any language with gRPC support
Dependency management	Part of scafctl’s `go.mod`	Isolated dependencies
Process isolation	Runs in-process	Separate process (crash isolation)
Update cycle	Tied to scafctl releases	Independent release cadence
Use case	Core functionality, general-purpose	Third-party integrations, proprietary logic
Contributing	PR to scafctl repo	Publish to any OCI registry

Key Differences: Providers vs Auth Handlers#

Aspect	Provider	Auth Handler
Interface	2 methods: `Descriptor()`, `Execute()`	8+ methods: `Login()`, `Logout()`, `Status()`, `GetToken()`, `InjectAuth()`, …
State	Stateless — each execution is independent	Stateful — manages cached tokens, refresh tokens, sessions
Used by	Solution resolvers (via `from`, `transform`, etc.)	Providers (e.g., `http` provider calls `InjectAuth()` on requests)
Registry	`provider.Registry` (versioned, overwrite-protected)	`auth.Registry` (name-keyed)
Capabilities	`from`, `transform`, `validation`, `action`, `authentication`	`scopes_on_login`, `scopes_on_token_request`, `tenant_id`, `hostname`, `federated_token`
Plugin artifact kind	`provider`	`auth-handler`

Plugin Communication#

Both provider plugins and auth handler plugins use hashicorp/go-plugin with gRPC:

Provider Development Guide

Mon, 01 Jan 0001 00:00:00 +0000

Provider Development Guide#

This guide explains how to create custom providers for scafctl. Providers are the building blocks that perform operations like fetching data, transforming values, validating inputs, and executing actions.

Providers can be delivered in two ways:

	Builtin	Plugin
Where it lives	Compiled into the scafctl binary	Separate executable (any language with gRPC)
Registration	`registry.Register(...)` in `builtin.go`	Discovered at runtime from plugin cache or catalog
Crash isolation	Shares process with scafctl	Isolated process — plugin crash doesn’t take down CLI
Distribution	Ships with scafctl releases	OCI catalog artifact (`kind: provider`) or standalone binary
Interface	`provider.Provider` (2 methods)	`plugin.ProviderPlugin` (3 methods)

Prerequisite: Read the Extension Concepts page for terminology (provider vs plugin vs auth handler).

Auth Handler Development Guide

Mon, 01 Jan 0001 00:00:00 +0000

Auth Handler Development Guide#

This guide explains how to create custom auth handlers for scafctl. Auth handlers manage identity verification, credential storage, and token acquisition for identity providers (e.g., Entra ID, GitHub, GCP, Okta, AWS SSO).

Auth handlers can be delivered in two ways:

	Builtin	Plugin
Where it lives	Compiled into the scafctl binary	Separate executable (any language with gRPC)
Registration	`authRegistry.Register(...)` in `root.go`	Discovered at runtime from plugin cache or catalog
Credential storage	Uses `pkg/secrets` (OS keychain)	Plugin manages its own credential storage
Crash isolation	Shares process with scafctl	Isolated process — plugin crash doesn’t take down CLI
Distribution	Ships with scafctl releases	OCI catalog artifact (`kind: auth-handler`) or standalone binary
Interface	`auth.Handler` (8 methods)	`plugin.AuthHandlerPlugin` (7 methods)

Prerequisite: Read the Extension Concepts page for terminology (provider vs auth handler vs plugin).

Plugin Development Guide

Mon, 01 Jan 0001 00:00:00 +0000

Plugin Development Guide#

This page is an overview. Detailed plugin development instructions are now part of each extension type’s development guide.

What is a Plugin?#

A plugin is a standalone executable that extends scafctl by communicating over gRPC using hashicorp/go-plugin . Plugins run in separate processes, providing crash isolation and independent distribution.

scafctl supports two types of plugins:

Plugin Type	Artifact Kind	Interface	Guide
Provider Plugin	`provider`	`plugin.ProviderPlugin` (3 methods)	Provider Development Guide — Delivering as a Plugin
Auth Handler Plugin	`auth-handler`	`plugin.AuthHandlerPlugin` (7 methods)	Auth Handler Development Guide — Delivering as a Plugin

Architecture#

flowchart LR
 A["scafctl<br/>- Discovers plugin<br/>- Calls extension<br/>- Manages lifecycle"] <-- "gRPC" --> B["Your Plugin<br/>- Implements gRPC<br/>- Exposes handlers<br/>- Handles execution"]

Each plugin binary exposes one extension type (provider OR auth handler). The handshake cookie determines which type the host expects.

Plugin Auto-Fetching

Mon, 01 Jan 0001 00:00:00 +0000

Plugin Auto-Fetching from Catalogs#

This tutorial explains how scafctl automatically fetches plugin binaries from remote catalogs at runtime. You can declare plugin dependencies in your solution, and scafctl will resolve, download, cache, and load them without a prior build step.

Overview#

The plugin auto-fetch flow:

Solution declares Catalog chain Plugin cache Provider
plugin dependencies → resolves version → checks cache → registration
 (local → remote) (cache hit/miss) (gRPC plugin)

Declare plugin dependencies in your solution’s bundle.plugins section
Resolve — scafctl looks up the plugin version in the catalog chain (local first, then remote OCI registries)
Cache — if the binary is already cached locally, it’s reused; otherwise it’s fetched and written to the cache
Load — the cached binary is launched as a gRPC plugin and its providers are registered

Declaring Plugin Dependencies#

Add a bundle.plugins section to your solution:

Multi-Platform Plugin Build Tutorial

Mon, 01 Jan 0001 00:00:00 +0000

Multi-Platform Plugin Build Tutorial#

This tutorial walks through building and distributing multi-platform plugin artifacts using OCI image indexes.

Overview#

Plugin artifacts (providers, auth handlers) are platform-specific binaries. To distribute a single plugin that works on multiple OS/architecture combinations, scafctl stores them as an OCI image index (also called a “fat manifest”). At runtime, scafctl automatically selects the correct binary for the current platform.

Supported Platforms#

Platform	Description
`linux/amd64`	Linux x86-64
`linux/arm64`	Linux ARM64 (e.g. AWS Graviton)
`darwin/amd64`	macOS Intel
`darwin/arm64`	macOS Apple Silicon
`windows/amd64`	Windows x86-64

Prerequisites#

scafctl CLI installed
Go toolchain (for cross-compilation)
Plugin source code that builds for multiple platforms

Step 1: Cross-Compile the Plugin#

Use Go’s cross-compilation to build binaries for each target platform: