Pkl Blog

Building CLI Tools with Pkl

2026-05-13T00:00:00.000Z

by Jen Basch on May 13th, 2026

Some Pkl use cases require evaluation to be parameterized by data supplied at runtime by a user, such as code generation or dataset analysis tools. External property (prop:) resources provide a mechanism for soliciting user input, but they’re limited and using them can be a clunky experience. Pkl 0.31 introduced the pkl run command and pkl:Command standard library module to provide a framework for building CLI tools that look, feel, and work like good tools should: standard flag syntax, input validation, subcommands, generated help text, and shell completion.

CLI tools written in Pkl provide the same basic I/O capabilities that normal Pkl evaluation does: writing to standard output and the filesystem and reading resources, including via external readers, but there are a couple key differences from regular evaluation:

File output is relative to the command’s working directory, not --multiple-file-output-path.
Imports may be specified dynamically in terms of CLI options using Command.Import.

These capabilities have enabled rewriting the code generation tools for pkl-swift and pkl-go. We now publish them purely as Pkl modules inside their respective packages instead of separately distributed binaries written in each target language that must function cooperatively with the Pkl portion of the code generator. This reduces the complexity of our code, our release processes, and adoption requirements for downstream users.

Running Commands

Running CLI tools built with Pkl is simple:

pkl run  [command options]

Every command has automatically generated CLI help via the --help/-h flag.

Pkl commands distributed inside dependencies of a Project may also be executed directly using the dependency’s alias:

pkl run @/

On *nix systems, commands in local files may also use a shebang to allow direct script execution:

my-command.pkl

#!/usr/bin/env -S pkl run
// ...

chmod +x my-command.pkl
./my-command.pkl

In this execution mode, a shell-completion subcommand can be used to generate autocomplete scripts for the bash, zsh, and fish shells.

Building Commands

Commands are defined declaratively by extending the pkl:Command module. The module’s output determines the command’s behavior:

output.bytes (by default, derived from output.text or output.value) is produced to standard output.
output.files entries are written to the filesystem. Unlike pkl eval, file paths are relative to the working directory, not a specified output path.

Command options, both named flags and positional arguments, are defined by the declared class on the module’s options property. Any class or module type may be used for options, so commands can easily share and inherit options. When a command is executed, its options property is overridden with the actual parsed option values.

Each property of the command’s options class (excluding hidden and local properties) becomes an option of the command. A property’s name becomes its name on the command line, its doc comment becomes its CLI help text, and its type determines how the raw user-provided value is parsed as a Pkl value. Properties with nullable types or default values become optional. Option behavior is determined by annotating option properties with one of several annotations: @Argument for positional arguments, @Flag for named flags, @BooleanFlag for --/--no- pairs, and @CountedFlag counts how many times the flag as passed.

For @Argument and @Flag, all of Pkl’s primitive types (String, Boolean, and numerics) are all supported, plus more complex types like Listing/List, Mapping/Map, Set, Pair, and string literal unions. Arbitrary types may be also supported through further customization of the option’s behavior using the annotations' convert and transformAll properties.

Here’s an example command that shows a variety of different options usage:

my-command.pkl

extends "pkl:Command"

options: Options

class Options {
  /// Maximum number of tries to attempt operation before giving up.
  `max-tries`: UInt (1)

  /// Whether to use cache data locally.
  @BooleanFlag
  cache: Boolean = true (2)

  /// Log verbosity.
  @CountedFlag { shortName = "v" }
  verbose: Int(this <= 3) (3)

  /// File paths to operate on.
  @Argument { completionCandidates = "paths" }
  path: Listing<String> (4)

  /// Duration after which operation will be timed out.
  @Flag { convert = module.convertDuration; metavar = "duration" }
  `connection-timeout`: Duration? (5)
}

1	Flag `--max-tries=` (no annotation is equivalent to annotating with `@Flag`); `UInt` validates the input is an integer `>= 0`; Flag is required.
2	Flags `--cache` and `--no-cache` correspond to `true` and `false` values, respectively; Flag is optional and defaults to `true`.
3	Flag `--verbose`/`-v` may be specified multiple times, each increasing the option’s value; Flag is optional and defaults to `0`.
4	Argument accepts multiple string values; shell completion suggests file/directory paths as possible values; Argument is optional and defaults to an empty `Listing`.
5	Flag `--connection-timeout=` accepts a string matching Pkl’s `Duration` syntax and converts it to a `Duration` value; The metavar displayed in the CLI help text is `"duration"`; Flag is optional.

This command’s generated CLI help looks like this:

$ pkl run my-command.pkl
Usage: my-command.pkl [] []...  []...

Options:
  --max-tries=    Maximum number of tries to attempt operation before
                        giving up.
  --cache / --no-cache  Whether to use cache data locally.
  -v, --verbose         Log verbosity.
  --connection-timeout=
                        Duration after which operation will be timed out.
  -h, --help            Show this message and exit

Arguments:
    File paths to operate on.

Commands:
  shell-completion  Generate a completion script for the given shell

Subcommands

Commands may also have subcommands. Subcommands are also Pkl modules that extend pkl:Command.

my-command.pkl

extends "pkl:Command"

command {
  subcommands {
    import("my-subcommand.pkl")
  }
}

// ...

my-subcommand.pkl

extends "pkl:Command"

import "my-command.pkl"

parent: `my-command`

// ...

Like root commands, when a subcommand is executed, its options property is overridden with the actual parsed option values. Similarly, the parent property is set to the instantiated parent command module with its options property set (and parent, if applicable). Overriding the type of the parent property is optional; it asserts that there is a parent command and the parent is a specific command, which can simplify code for complex CLIs. The root property may be overridden similarly.

This subcommand can then be executed:

pkl run my-command.pkl [root command options] my-subcommand [subcommand options]

Dynamic Imports

One of the key differentiators between regular Pkl evaluation and CLI commands is that commands offer a form of dynamic importing. Normal Pkl import statements (import "") and expressions (import("")) only accept string literals, not arbitrary expressions. Command options may return Import values from option convert and transformAll functions to trigger dynamic imports.

One example of using dynamic imports is the pkl-swift code generator. This command must accept arbitrary Module values and analyze them to generate Swift code. Here, Argument.convert is set to a function that directly converts the raw string value to a directive to import the module by URI:

/// The Pkl modules to generate as Swift.
@Argument {
  convert = (it) -> new Import { uri = it }
  completionCandidates = "paths"
}
pklInputModules: Listing<Module>?

Advanced Patterns

These capabilities compose to enable some patterns that may not be obvious but are extremely useful!

Option reuse

Many command line tools use a common set of options across several subcommands. Pkl’s own CLI exhibits this pattern: many options are shared by pkl eval, pkl test, and other subcommands.

There are two main approaches available for option reuse:

Parent commands contain shared options, subcommands access parent.options.

my-command.pkl

extends "pkl:Command"

command {
  subcommands {
    import("my-subcommand.pkl")
  }
}

options: Options

class Options {
  @Flag
  `parent-flag`: String
}

my-subcommand.pkl

extends "pkl:Command"

options: Options

class Options {
  @Flag
  `subcommand-only-flag`: String
}

On the command line, --parent-flag and its value must precede the subcommand name.

Options classes directly inherit from a shared base class.

BaseOptions.pkl

open module BaseOptions
import "pkl:Command"

@Command.Flag
`shared-flag`: String

my-subcommand.pkl

extends "pkl:Command"
import "BaseOptions.pkl"

options: Options

class Options extends BaseOptions { (1)
  @Flag
  `subcommand-only-flag`: String
}

On the command line, --shared-flag and its value must follow the subcommand name.

Import fallback to a well-known path

In some cases, it may be desirable to pass a Pkl config file to a command. Often, command line tools will load such configurations from well known paths in the working directory or home directory.

This example, also from pkl-swift, loads a GeneratorSettings from the path specified. If no path is specified but a generator-settings.pkl exists in the working directory, that file will be loaded instead.

/// The generator-settings.pkl file to use. (default: ./generator-settings.pkl if present)
@Flag {
  convert = (it) -> new Import { uri = it } (1)
  transformAll = (values) ->
    values.firstOrNull (2)
      ?? if (read?("file://\(pwd)/generator-settings.pkl") != null) (3)
        new Import { uri = "./generator-settings.pkl" }
      else
        new GeneratorSettings {} (4)
  completionCandidates = "paths"
}
`generator-settings`: GeneratorSettings

1	If a value is supplied, direct Pkl to import it.
2	If any value is supplied, use it, otherwise fall back to checking the working directory.
3	If the file exists in the working directory, import it. Note that the absolute `file:` URI is used here because `read` is relative to the enclosing module URI and this command is most frequently executed from inside the `pkl.swift` package.
4	Otherwise, fall back to an empty/default value.

Testing Commands

Pkl commands are defined by writing regular modules, which means they can also be tested just like regular Pkl modules! Test code may import a command module and instantiate it, directly overriding options and/or parent as needed to mock out user input:

amends "pkl:test"

import "my-command.pkl"
import "my-subcommand.pkl"

examples {
  ["Test my-command"] {
    (`my-command`) {
      options {
        // Set my-command options here...
      }
    }.output.text
  }
  ["Test my-subcommand"] {
    (`my-subcommand`) {
      parent { // this amends `my-command`
        options {
          // Set my-command options here...
        }
      }
      options {
        // Set my-subcommand options here...
      }
    }.output.text
  }
}

Class-as-a-Function Pattern

2024-08-13T00:00:00.000Z

by Jen Basch on August 13th, 2024

In many languages, function and method parameters may be assigned default values allowing the argument to be omitted in calls. Many languages also offer named parameters, which aid in API self-documentation. Pkl methods do not provide either feature, but one way to achieve similar results is the "class-as-a-function" (CaaF) pattern.

Usage

In the class-as-a-function pattern, a class is created that accepts "input" properties and has one or more fixed "output" properties.

Input properties are normal class properties. They are named, may have a type annotation, and may be defined with default values. Default values can be static values or may be derived from other properties.

Output properties derive their value from the input properties. They are typically marked as fixed so they may not be overridden when amending instances of the class.

Example

class GreetingFunction {
  /// The name that should be greeted.
  name: String (1)

  /// The phrase used to greet [name].
  greeting: String = "Hello" (2)

  /// The derived greeting.
  fixed message: String = "\(greeting), \(name)!" (3)
}

greetPigeon: String = new GreetingFunction { name = "Pigeon" }.message (4)

greetHawk: String = new GreetingFunction { name = "Hawk"; greeting = "Good day" }.message (5)

1	A required input property.
2	An optional input property with a default value.
3	An output property, calculated from the input properties.
4	result: `"Hello, Pigeon!"`
5	result: `"Good day, Hawk!"`

Tips

Despite the name, the pattern can also be applied using a module.
The CaaF pattern is especially compelling in cases where multiple outputs will be derived from the same set of inputs. Instead of defining multiple methods that accept the same parameters, a single class may be defined with multiple output properties.

In some cases, it may make sense to use CaaF in conjunction with output converters. This allows the "un-called" function instance to be used in place of the result data and enables amending the arguments to the function while still producing the desired output type and value, eg.:

greetPigeon: GreetingFunction|String = "こんばんは、鳩さん" (1)

greetHawk: GreetingFunction|String = new GreetingFunction { name = "Hawk" } (2)

farewellHawk = (greetHawk) {
  greeting = "Bye" (3)
}

output {
  renderer {
    converters {
      [GreetingFunction] = (it) -> it.message (4)
    }
  }
}

1	A fully custom greeting not using `GreetingFunction`.
2	result: `"Hi, Hawk!"`
3	result: `"Bye, Hawk!"`
4	Configuring a converter for `GreetingFunction` causes instances to be "evaluated" in the rendered output.

Multi-directional Functions

Pkl’s system of property default values and late binding enables using class-as-a-function to concisely express inverse and even circular relationships between properties. This allows the same property to be both input and output, depending on how the function type is used.

Using this technique entails declaring properties with default values derived from the other properties of the type in a cyclic fashion. Ordinarily, a circular data reference of this kind would result in a stack overflow error, but instantiating the type with the appropriate input(s) overridden with concrete values breaks the circular reference.

class Temperature {
  fahrenheit: Float = celsius * 9 / 5 + 32
  celsius: Float = kelvin - 273.15
  kelvin: Float = (fahrenheit - 32) / 9 * 5 + 273.15
}

fToK = new Temperature { fahrenheit = 72.0 }.kelvin
fToC = new Temperature { fahrenheit = 72.0 }.celsius
kToF = new Temperature { kelvin = 300.0 }.fahrenheit
kToC = new Temperature { kelvin = 300.0 }.celsius
cToF = new Temperature { celsius = 20.0 }.fahrenheit
cToK = new Temperature { celsius = 20.0 }.kelvin

Building Abstractions

The class-as-a-function pattern can be used to build abstraction layers that provide simple APIs resulting in more complex configurations. This is sometimes called "embedding" a class.

Kubernetes is an example of a system that requires a lot of configuration to use. Often, deploying applications in Kubernetes requires repeating very similar configurations with only names and a few values changed. Here is an example of a CaaF module that uses class embedding to build a simple but extensible abstraction for basic web services:

module SimpleApplication

import "package://pkg.pkl-lang.org/pkl-k8s/k8s@1.1.0#/K8sResource.pkl"
import "package://pkg.pkl-lang.org/pkl-k8s/k8s@1.1.0#/api/apps/v1/Deployment.pkl"
import "package://pkg.pkl-lang.org/pkl-k8s/k8s@1.1.0#/api/core/v1/Service.pkl"
import "package://pkg.pkl-lang.org/pkl-k8s/k8s@1.1.0#/api/networking/v1/Ingress.pkl"

// input properties:
/// Web application name
name: String

/// Container image tag
image: String

/// Application Pod replica count
replicas: Int32? = 1

/// HTTP listen port
port: UInt16 = 8080

/// URL Path to use for liveness checking
livenessPath: String? = "/livez"

/// URL Path to use for readiness checking
readinessPath: String? = "/readyz"

// output properties:
local app = this (1)

/// Kubernetes labels used for all output resources and selectors
labels: Mapping<String, String> = new { (2)
  ["app.kubernetes.io/name"] = name
}

/// Kuberetes [Deployment] that manages the application Pods.
deployment: Deployment = new { (3)
  metadata {
    name = app.name
    labels = app.labels
  }
  spec {
    replicas = app.replicas
    template {
      metadata {
        labels = app.labels
      }
      spec {
        containers {
          new {
            name = app.name
            image = app.image
            when (livenessPath != null) {
              livenessProbe {
                httpGet {
                  port = app.port
                  path = livenessPath
                }
              }
            }
            when (readinessPath != null) {
              readinessProbe {
                httpGet {
                  port = app.port
                  path = readinessPath
                }
              }
            }
          }
        }
      }
    }
  }
}

/// Kubernetes [Service] that provides a cluster-internal VIP for the application.
service: Service = new { (3)
  metadata {
    name = app.name
    labels = app.labels
  }
  spec {
    selector = app.labels
    ports {
      new {
        name = "http"
        port = app.port
      }
    }
  }
}

/// Kubernetes [Ingress] that exposes a VIP for the application outside the cluster.
ingress: Ingress = new { (3)
  metadata {
    name = app.name
    labels = app.labels
  }
  spec {
    defaultBackend {
      service {
        name = app.service?.metadata?.name!!
        port  {
          number = app.service.spec?.ports!![0].port
        }
      }
    }
  }
}

/// All Kubernetes resources needed to deploy the application.
resources: Listing<K8sResource> = new { (4)
  deployment
  service
  ingress
}

1	This "captures" the `SimpleApplication` instance so its properties can be unambiguously referred to.
2	The `labels` property is an "intermediary" property that serves as a customization point, it is calculated from inputs by default but is not itself an output.
3	The `deployment`, `service`, and `ingress` properties are the module’s primary output properties.
4	For convenience, the `resources` property combines all of the above outputs into a single `Listing`.

Notably, this example does not mark its output properties as fixed, which enables easy customization of these properties beyond what the module configures by default. Here are a few examples of using the SimpleApplication module:

import "SimpleApplication.pkl"
import "package://pkg.pkl-lang.org/pkl-k8s/k8s@1.1.0#/K8sResource.pkl"
import "package://pkg.pkl-lang.org/pkl-k8s/k8s@1.1.0#/api/networking/v1/NetworkPolicy.pkl"

/// The most basic [SimpleApplication] usage.
///
/// The application image is expected to listen on port 8080 and provide `/livez` and `/readyz` paths
app1: Listing<K8sResource> = new SimpleApplication {
  name = "app1"
  image = "myregistry/app1:latest"
}.resources

/// Usage of [SimpleApplication] with additional input properties overridden.
app2: Listing<K8sResource> = new SimpleApplication {
  name = "app2"
  image = "myregistry/app2:latest"
  replicas = 3
  port = 9090
  livenessPath = null
  readinessPath = "/healthz"
}.resources

/// Advanced [SimpleApplication] usage where output properties are amended.
///
/// This example amends [deployment] directly to set properties not exposed by [SimpleApplication]'s simple API.
/// It also amends [resources] to add an additional resource required specifically by this application.
app3: Listing<K8sResource> = new SimpleApplication {
  name = "app3"
  image = "myregistry/app3:latest"
  labels {
    ["app.kubernetes.io/instance"] = "\(name)-staging"
  }
  deployment {
    spec {
      template {
        spec {
          securityContext {
            runAsNonRoot = true
          }
          initContainers {
            new {
              name = "my-init-container"
              // ...
            }
          }
        }
      }
    }
  }
  resources {
    new NetworkPolicy {
      // ...
    }
  }
}.resources

How we manage GitHub Actions

2026-01-15T00:00:00.000Z

by Dan Chao on January 15th, 2026.

The Pkl project comprises multiple repositories on GitHub (23 at the time of this writing). These repositories are built in different ways, and thus require different CI configurations.

At the same time, we have common patterns that are applied across codebases. Some of these are:

Every repo should have different workflows for "prb", "build", and "release".
We want to avert security issues:
- Calling into actions should pin to the checksum (e.g. actions/checkout@abc123… instead of actions/checkout@v6).
- Running actions/checkout should, by default, set persist-credentials: false
We want our workflows to be typechecked, and minimize the chances of creating invalid workflows.
We want our builds to publish test reports.

Naturally, we turn to Pkl to help us address all of these problems!

Defining workflows using the `com.github.actions` package

To define workflows, we start by using the com.github.actions Pkl package.

This package defines the classes and types that go into authoring the eventual workflow YAML files.

This package was originally forked from https://github.com/stefma/pkl-gha. Thanks to StefMa for his work!

At a basic level, defining a workflow in Pkl is similar to defining a workflow in YAML, but includes the benefits of Pkl’s rich toolings: code-completion, documentation, and typechecking.

The com.github.actions package provides some extra goodies when defining workflows.

Actions catalog

The com.github.actions includes a "catalog" of GitHub’s core actions (actions that are within the actions org).

These actions have their schema also defined in Pkl, which means that you have all the goodies you might expect, including typechecking and documentation.

Additionally, the typings for some properties has been improved. For example, the paths property of the upload-artifacts action is really just a list, represented as a newline-separated string. Our catalog provides a property called pathList, which defines this as a Listing and joins it back to a string for you before rendering.

import "@com.github.actions/catalog.pkl"

local uploadAction = (catalog.`upload-artifact@v5`) {
  with {
    // Pkl will error if you specify an int or a boolean here.
    name = "build-results"

    // no need to use a newline-separated string!
    // Pkl will fuse this back into a string for you.
    pathList {
      "*.sh"
      "*.bin"
    }
  }
}

Creating your own typed actions

The catalog contains typed steps; steps whose input properties have fine-grained types. However, it only contains definitions for things within the core actions repo. But, no worries! You can create your own typed steps either by hand-rolling their definitions, or by generating them.

To generate a typed step for your action, use the generate-action Pkl script.

For example:

pkl eval package://pkg.pkl-lang.org/pkl-pantry/com.github.actions.contrib@1.0.6#/generate-action.pkl \
  -m .github \
  -p action-name=docker/build-push-action@v5 \
  # Specify the simple name of your GitHub Actions package
  -p action-package-name=com.github.actions

This will generate a file at path .github/docker/build-push-action/v5/BuildPushAction.pkl.

You can also use the ActionGenerator API for finer-grained control. For example, this provides a way to specialize the types for this action’s inputs.

You can even create your own catalog which extends the upstream catalog:

.github/catalog.pkl

extends "@com.github.actions/catalog.pkl"

import "docker/build-push-action/v5/BuildPushAction"

`docker/build-push-action@v5`: BuildPushAction

Pinning actions to git SHAs

Actions versions are typically specified as tags or branches (e.g. uses: actions/checkout@v6). However, doing so leaves your pipelines vulnerable to a supply chain attack: if an attacker gains write access to an action’s repository, they can swap out your build definition and inject malicious code. This has compromised many pipelines in the past. For example, see CVE-2025-30066.

One mitigation is to pin to a git SHA. This causes GitHub to look up an immutable commit, instead of a mutable tag or branch.

-uses: actions/checkout@v6
+uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6

To help with this, we’ve created a template called DependabotManagedActions.

This template replaces each action’s version with its resolved git SHA. Additionally, it uses a fake workflow called __lockfile__.yml to help it generate your workflows. The module contains the following logic:

Load the existing lockfile if it exists.
For each action, look up its resolved version in the existing lockfile
- If the action does not exist in the lockfile, or if the lockfile does not exist, resolve it from GitHub and add it to the lockfile.
- Remove any actions from the lockfile if they aren’t being used in any workflows.
Create all workflow YAML files, replacing any uses with the resolved git SHA, and a YAML comment with the original version.
Create the new lockfile (no-op if no actions have changed).
Create a .github/dependabot.yml that is configured to update GitHub Actions.

This module is published to pkl-pantry, and available for anybody to use!

To use it, you would typically create a .github/PklProject with com.github.actions and pkl.github.dependabotManagedActions as dependencies.

.github/PklProject

amends "pkl:Project"

dependencies {
  ["com.github.actions"] {
    uri = "package://pkg.pkl-lang.org/pkl-pantry/com.github.actions@1.3.0"
  }
  ["pkl.github.dependabotManagedActions"] {
    uri = "package://pkg.pkl-lang.org/pkl-pantry/pkl.github.dependabotManagedActions@1.0.0"
  }
}

Then resolve the project. This creates a PklProject.deps.json file that also should be checked into version control. This command only needs to be run when dependencies have changed.

pkl project resolve

With that setup out of the way, you then create a root entrypoint module that contains all of your workflows. Typically, this is called .github/index.pkl.

.github/index.pkl

amends "@pkl.github.dependabotManagedActions/DependabotManagedActions.pkl"

import "@com.github.actions/catalog.pkl"

workflows {
  ["workflows/build.yml"] =
    // define your workflows as normal!
    // they can either be defined inline, or imported from elsewhere.
    import("build.pkl")
}

You then use pkl eval to turn Pkl into the resulting YAML files:

cd .github
pkl eval -m . index.pkl

# or if you're in the project root
pkl eval --project-dir .github/ -m .github/ .github/index.pkl

Defining shared workflows and creating our own abstraction

We have some common workflows that we want pretty much every one of our repositories to have. Having a consistent CI experience across every repo improves the contributor experience and streamlines maintenance. For example, there are:

prb.yml — The workflow that gets triggered when users submit or commit to pull requests.
build (main).yml — The workflow that gets triggered when commits land on the main branch.

Additionally, we want our workflows to publish test results to be made available within our GitHub Actions.

To address these needs, we’ve defined an abstraction just for our purposes. It does quite a lot; some of the things it does include:

Define pull request and push triggers for each different type of workflows.
Define permissions that make sense for each type of workflow.
Add additional steps for uploading test report artifacts.
Add additional job for processing test reports.
Add a workflow for processing test reports just for pull requests (this is how EnricoMi/publish-unit-test-result-action works).
Pass all of these workflows to DependabotManagedActions for version locking.

There’s quite a lot going on in PklCI, but the actual API surface area is quite small.

For example, on the consumption side, it looks something like this:

.github/index.pkl

amends "@pkl.impl.ghactions/PklCI.pkl"

import "@com.github.actions/Workflow.pkl"

local myWorkflow: Workflow = new {
  jobs {
    ["build"] {
      module.catalog.`actions/checkout@v6`
      new {
        run = "make build"
      }
    }
  }
}

// run the same build definition when running pull request builds,
// and when building the main branch.
prb = myWorkflow

main = myWorkflow

// add steps to each workflow to publish unit test results.
// look for JUnit test reports within directory build/test-reports.
testReports {
  junit {
    "build/test-reports/**/*.xml"
  }
}

If you’re curious about how our stuff works, our source code is publicly available for all to browse.

Updating all of our repositories

Pkl is a large project, and it’s pretty untenable to be manually updating all 23 repos every time one of our library dependencies change. So, when we adjust the logic in our abstraction layer, we use helper scripts to generate, review, and merge pull requests.

These are:

update_downstream_ci.sh: generate pull requests for every repository.
approve_downstream_prs.sh: approve pull requests for each repository.
merge_downstream_prs.sh‎: merge approved pull requests with passing checks for each repository.

Try it out yourself

Try writing your own actions using Pkl!

Here is a quickstart guide:

Set up your local environment
- Install the Pkl plugin for your editor of choice.
- Install the pkl CLI for your machine.

Create your PklProject

.github/PklProject

amends "pkl:Project"

dependencies {
  ["com.github.actions"] {
    uri = "package://pkg.pkl-lang.org/pkl-pantry/com.github.actions@1.3.0"
  }
  // optional; use this if you want your actions to be locked to git SHAs.
  ["pkl.github.dependabotManagedActions"] {
    uri = "package://pkg.pkl-lang.org/pkl-pantry/pkl.github.dependabotManagedActions@1.0.0"
  }
}

Run pkl project resolve .github to create your PklProject.deps.json

Write Pkl-based workflows

Create new Pkl modules that amend Workflow.pkl

.github/build.pkl

amends "@com.github.actions/Workflow.pkl"

on {
  push {}
}

jobs {
  ["build"] {
    steps {
      // etc
    }
  }
}

If not using index.pkl (see the next step): eval this into YAML:
```
cd .github
pkl eval build.pkl -o workflows/build.yml
```

(Optional) Create an entrypoint with DependabotManagedActions.

Create your index.pkl file

.github/index.pkl

amends "@pkl.github.dependabotManagedActions/DependabotManagedActions.pkl"

workflows {
  ["workflows/build.yml"] = import("build.pkl")
}

Run pkl eval
```
cd .github/
pkl eval -m . index.pkl
```

Acknowledgments

Thanks to @StefMa for creating the original pkl-gha package, and also thanks to the folks at typesafegithub for providing typings for existing actions!

Introducing Pkl, a programming language for configuration

2024-02-01T00:00:00.000Z

by the Pkl Team on February 1st, 2024

We are delighted to announce the open source first release of Pkl (pronounced Pickle), a programming language for producing configuration.

When thinking about configuration, it is common to think of static languages like JSON, YAML, or Property Lists. While these languages have their own merits, they tend to fall short when configuration grows in complexity. For example, their lack of expressivity means that code often gets repeated. Additionally, it can be easy to make configuration errors, because these formats do not provide any validation of their own.

To address these shortcomings, sometimes formats get enhanced by ancillary tools that add special logic. For example, perhaps there’s a need to make code more DRY, so a special property is introduced that understands how to resolve references, and merge objects together. Alternatively, there’s a need to guard against validation errors, so some new way is created to validate a configuration value against an expected type. Before long, these formats almost become programming languages, but ones that are hard to understand and hard to write.

On the other end of the spectrum, a general-purpose language might be used instead. Languages like Kotlin, Ruby, or JavaScript become the basis for DSLs that generate configuration data. While these languages are tremendously powerful, they can be awkward to use for describing configuration, because they are not oriented around defining and validating data. Additionally, these DSLs tend to be tied to their own ecosystems. It is a hard sell to use a Kotlin DSL as the configuration layer for an application written in Go.

We created Pkl because we think that configuration is best expressed as a blend between a static language and a general-purpose programming language. We want to take the best of both worlds; to provide a language that is declarative and simple to read and write, but enhanced with capabilities borrowed from general-purpose languages. When writing Pkl, you are able to use the language features you’d expect, like classes, functions, conditionals, and loops. You can build abstraction layers, and share code by creating packages and publishing them. Most importantly, you can use Pkl to meet many different types of configuration needs. It can be used to produce static configuration files in any format, or be embedded as a library into another application runtime.

We designed Pkl with three overarching goals:

To provide safety by catching validation errors before deployment.
To scale from simple to complex use-cases.
To be a joy to write, with our best-in-class IDE integrations.

A Quick Tour of Pkl

We created Pkl to have a familiar syntax to developers, and to be easy to learn. That is why we’ve included features like classes, functions, loops, and type annotations.

For example, here is a Pkl file (module) that defines a configuration schema for an imaginary web application.

This file defines types, and not data. This is a common pattern in Pkl, and we call this a template.

Application.pkl

module Application

/// The hostname that this server responds to.
hostname: String

/// The port to listen on.
port: UInt16

/// The environment to deploy to.
environment: Environment

/// The database connection for this application
database: Database

class Database {
  /// The username for this database.
  username: String

  /// The password for this database.
  password: String

  /// The remote host for this database.
  host: String

  /// The remote port for this database.
  port: UInt16

  /// The name of the database.
  dbName: String
}

typealias Environment = "dev"|"qa"|"prod"

And here is how configuration data might be defined:

localhost.pkl

amends "Application.pkl"

hostname = "localhost"

port = 3599

environment = "dev"

database {
  host = "localhost"
  port = 5786
  username = "admin"
  password = read("env:DATABASE_PASSWORD") (1)
  dbName = "myapp"
}

1	Built-in read expression for reading external resources.

It is easy to create variations of the same base data by amending. For example, let’s imagine that we want to run four databases locally, as sidecars. This uses a for generator to produce four variations, each of which amends the base db and specifies a different port.

sidecars.pkl

import "Application.pkl"

hidden db: Application.Database = new {
  host = "localhost"
  username = "admin"
  password = read("env:DATABASE_PASSWORD")
  dbName = "myapp"
}

sidecars {
  for (offset in List(0, 1, 2, 3)) {
    (db) {
      port = 6000 + offset
    }
  }
}

Pkl programs can be easily rendered to common formats.

YAML
JSON
XML

$ export DATABASE_PASSWORD=hunter2
$ pkl eval --format yaml sidecars.pkl

sidecars:
- username: admin
  password: hunter2
  host: localhost
  port: 6000
  dbName: myapp
- username: admin
  password: hunter2
  host: localhost
  port: 6001
  dbName: myapp
- username: admin
  password: hunter2
  host: localhost
  port: 6002
  dbName: myapp
- username: admin
  password: hunter2
  host: localhost
  port: 6003
  dbName: myapp

$ export DATABASE_PASSWORD=hunter2
$ pkl eval --format json sidecars.pkl

{
  "sidecars": [
    {
      "username": "admin",
      "password": "hunter2",
      "host": "localhost",
      "port": 6000,
      "dbName": "myapp"
    },
    {
      "username": "admin",
      "password": "hunter2",
      "host": "localhost",
      "port": 6001,
      "dbName": "myapp"
    },
    {
      "username": "admin",
      "password": "hunter2",
      "host": "localhost",
      "port": 6002,
      "dbName": "myapp"
    },
    {
      "username": "admin",
      "password": "hunter2",
      "host": "localhost",
      "port": 6003,
      "dbName": "myapp"
    }
  ]
}

$ export DATABASE_PASSWORD=hunter2
$ pkl eval --format xml sidecars.pkl



  
    
      admin
      hunter2
      localhost
      6000
      myapp
    
    
      admin
      hunter2
      localhost
      6001
      myapp
    
    
      admin
      hunter2
      localhost
      6002
      myapp
    
    
      admin
      hunter2
      localhost
      6003
      myapp

Built-in Validation

Configuration is about data. And data needs to be valid.

In Pkl, validation is achieved using type annotations. And, type annotations can optionally have constraints defined on them.

Here is an example, that defines the following constraints:

age must be between 0 and 130.
name to not be empty.
zipCode must be a string with five digits.

Person.pkl

module Person

name: String(!isEmpty)

age: Int(isBetween(0, 130))

zipCode: String(matches(Regex("\\d{5}")))

A failing constraint causes an evaluation error.

alessandra.pkl

amends "Person.pkl"

name = "Alessandra"

age = -5

zipCode = "90210"

Evaluating this module fails:

$ pkl eval alessandra.pkl
–– Pkl Error ––
Type constraint `isBetween(0, 130)` violated.
Value: -5

5 | age: Int(isBetween(0, 130))
             ^^^^^^^^^^^^^^^^^
at Person#age (file:///Person.pkl)

5 | age = -5
          ^^
at alessandra#age (file:///alessandra.pkl)

106 | text = renderer.renderDocument(value)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
at pkl.base#Module.output.text (https://github.com/apple/pkl/blob/0.25.0/stdlib/base.pkl#L106)

Constraints are arbitrary expressions. This allows you to author types that can express any type of check that can be expressed in Pkl. Here is a sample type that must be a string with an odd length, and whose first letter matches the last letter.

name: String(length.isOdd, chars.first == chars.last)

Pkl provides the ability to publish packages, and to import them as dependencies in a project. This provides an easy way to share Pkl code that can be used in other projects.

It is easy to create your own package and publish them as GitHub releases, or to upload them anywhere you wish.

Packages can be imported via the absolute URI:

import "package://pkg.pkl-lang.org/pkl-pantry/pkl.toml@1.0.0#/toml.pkl"

output {
  renderer = new toml.Renderer {}
}

Alternatively, they can be managed as dependencies of a project. Using a project allows Pkl to resolve version conflicts between different versions of the same dependency within a dependency graph. It also means that you can import packages by a simpler name.

PklProject

amends "pkl:Project"

dependencies {
  ["toml"] { uri = "package://pkg.pkl-lang.org/pkl-pantry/pkl.toml@1.0.0" }
}

myconfig.pkl

import "@toml/toml.pkl"

output {
  renderer = new toml.Renderer {}
}

A set of packages are maintained by us, the Pkl team. These include:

pkl-pantry — a monorepo that publishes many different packages.
pkl-k8s — templates for defining Kubernetes descriptors.

Language Bindings

Pkl can produce configuration as textual output, and it can also be embedded as a library into other languages via our language bindings.

When binding to a language, Pkl schema can be generated as classes/structs in the target language. For example, the Application.pkl example from above can be generated into Swift, Go, Java, and Kotlin. Pkl even includes documentation comments in the target language.

Swift
Go
Java
Kotlin

import PklSwift

public enum Application {}

extension Application {
    public enum Environment: String, CaseIterable, Decodable, Hashable {
        case dev = "dev"
        case qa = "qa"
        case prod = "prod"
    }

    public struct Module: PklRegisteredType, Decodable, Hashable {
        public static var registeredIdentifier: String = "Application"

        /// The hostname that this server responds to.
        public var hostname: String

        /// The port to listen on.
        public var port: UInt16

        /// The environment to deploy to.
        public var environment: Environment

        /// The database connection for this application
        public var database: Database

        public init(hostname: String, port: UInt16, environment: Environment, database: Database) {
            self.hostname = hostname
            self.port = port
            self.environment = environment
            self.database = database
        }
    }

    public struct Database: PklRegisteredType, Decodable, Hashable {
        public static var registeredIdentifier: String = "Application#Database"

        /// The username for this database.
        public var username: String

        /// The password for this database.
        public var password: String

        /// The remote host for this database.
        public var host: String

        /// The remote port for this database.
        public var port: UInt16

        /// The name of the database.
        public var dbName: String

        public init(username: String, password: String, host: String, port: UInt16, dbName: String) {
            self.username = username
            self.password = password
            self.host = host
            self.port = port
            self.dbName = dbName
        }
    }
}

Application.pkl.go

package application

type Application struct {
	// The hostname that this server responds to.
	Hostname string `pkl:"hostname"`

	// The port to listen on.
	Port uint16 `pkl:"port"`

	// The environment to deploy to.
	Environment environment.Environment `pkl:"environment"`

	// The database connection for this application
	Database *Database `pkl:"database"`
}

Database.pkl.go

// Code generated from Pkl module `Application`. DO NOT EDIT.
package application

type Database struct {
	// The username for this database.
	Username string `pkl:"username"`

	// The password for this database.
	Password string `pkl:"password"`

	// The remote host for this database.
	Host string `pkl:"host"`

	// The remote port for this database.
	Port uint16 `pkl:"port"`

	// The name of the database.
	DbName string `pkl:"dbName"`
}

environment/Environment.pkl.go

// Code generated from Pkl module `Application`. DO NOT EDIT.
package Environment

import (
	"encoding"
	"fmt"
)

type Environment string

const (
	Dev  Environment = "dev"
	Qa   Environment = "qa"
	Prod Environment = "prod"
)

// String returns the string representation of Environment
func (rcv Environment) String() string {
	return string(rcv)
}

import java.lang.Object;
import java.lang.Override;
import java.lang.String;
import java.lang.StringBuilder;
import java.util.Objects;
import org.pkl.config.java.mapper.Named;
import org.pkl.config.java.mapper.NonNull;

public final class Application {
  /**
   * The hostname that this server responds to.
   */
  public final @NonNull String hostname;

  /**
   * The port to listen on.
   */
  public final int port;

  /**
   * The environment to deploy to.
   */
  public final @NonNull Environment environment;

  /**
   * The database connection for this application
   */
  public final @NonNull Database database;

  public Application(@Named("hostname") @NonNull String hostname, @Named("port") int port,
      @Named("environment") @NonNull Environment environment,
      @Named("database") @NonNull Database database) {
    this.hostname = hostname;
    this.port = port;
    this.environment = environment;
    this.database = database;
  }

  public static final class Database {
    /**
     * The username for this database.
     */
    public final @NonNull String username;

    /**
     * The password for this database.
     */
    public final @NonNull String password;

    /**
     * The remote host for this database.
     */
    public final @NonNull String host;

    /**
     * The remote port for this database.
     */
    public final int port;

    /**
     * The name of the database.
     */
    public final @NonNull String dbName;

    public Database(@Named("username") @NonNull String username,
        @Named("password") @NonNull String password, @Named("host") @NonNull String host,
        @Named("port") long port, @Named("dbName") @NonNull String dbName) {
      this.username = username;
      this.password = password;
      this.host = host;
      this.port = port;
      this.dbName = dbName;
    }
  }

  public enum Environment {
    DEV("dev"),

    QA("qa"),

    PROD("prod");

    private String value;

    private Environment(String value) {
      this.value = value;
    }

    @Override
    public String toString() {
      return this.value;
    }
  }
}

import kotlin.Int
import kotlin.Long
import kotlin.String

data class Application(
  /**
   * The hostname that this server responds to.
   */
  val hostname: String,
  /**
   * The port to listen on.
   */
  val port: Int,
  /**
   * The environment to deploy to.
   */
  val environment: Environment,
  /**
   * The database connection for this application
   */
  val database: Database
) {
  data class Database(
    /**
     * The username for this database.
     */
    val username: String,
    /**
     * The password for this database.
     */
    val password: String,
    /**
     * The remote host for this database.
     */
    val host: String,
    /**
     * The remote port for this database.
     */
    val port: Int,
    /**
     * The name of the database.
     */
    val dbName: String
  )

  enum class Environment(
    val value: String
  ) {
    DEV("dev"),

    QA("qa"),

    PROD("prod");

    override fun toString() = value
  }
}

Using code generation is just one of the many ways to embed Pkl within an application. Our language bindings also provide evaluator APIs to control Pkl evaluation at a low level, and users are free to interact with Pkl at the abstraction level that makes the most sense for their application.

Editor Support

We believe that a programming language is only as good as the experience of writing it. That is why we aim to provide best-in-class editor support. When writing Pkl in an editor, users are guided through the process of filling in configuration data from a given template. Additionally, the editors provide instant feedback if any values are invalid, and documentation is immediately available when called upon.

We are also releasing our IntelliJ plugin, which provides rich support for JetBrains editors, including IntelliJ, Webstorm, GoLand, and PyCharm. These plugins are able to analyze a Pkl program and provide features like autocompletion, go-to-definition, and refactoring support.

Here are some of the features that are available:

Autocompletion
Navigation
Validation

In addition, we are also planning on supporting the Language Server Protocol, which will provide a similar level of integration in other editors.

As of 2024/10/10, The Pkl Language Server has been released. This enables rich editor support for our VS Code and Neovim plugins.

Next Steps

We hope you like what we’ve shown you so far. For a more in-depth guide, take a look at our tutorial. To learn more about the language itself, read through our language reference. To connect with us, feel free to submit a topic on GitHub Discussions.

Additionally, feel free to browse our sample repositories to get an idea for what it’s like to use Pkl:

To try out Pkl locally, try downloading our CLI by following our installation guide. Additionally, try installing one of our various editor plugins to get a glimpse of what it’s like to write Pkl yourself.

We’re so excited to share Pkl with you, and we are just getting started. We are looking forward to seeing what you might do with it!

Know Your Place

2025-01-24T00:00:00.000Z

by Philip Hölzenspies on January 24th, 2025

Configuration generally, and Pkl code especially, tends to be organized hierarchically. When configurations grow, they typically spread across files in a directory structure along similar hierarchical organization. To make one more ergonomically fit the other, Pkl offers a few mechanisms that can be used in module definitions for, for example, validating that modules are organized as expected, or to populate default values.

Application, Environment, Cluster

There are many examples of large configurations that can be organized in file hierarchies in such a way that the whole configuration is easily accessible (you’ll find what you’re looking for where you expect it), DRY, and reliable (you can have confidence many mistakes are detected before you deploy the configuration). One such example concerns the Kubernetes manifests for a collection of services (or "apps"). The AppEnvCluster template was developed for such an example. Let’s see how it uses file location in its definition to simplify its use.

This template assumes a three-level configuration hierarchy: application, environment, and cluster. Modules at the root of the configuration hierarchy directly amend this module. All other modules amend their parent.

— Documentation of AppEnvCluster.pkl

Example

As an example, consider the Imaginary Service Company (ISC), which is running three services; login, chat, and share. All of these services are deployed across prod, dev, and qa environments, in regions in the US, Europe, and Asia-Pacific. ISC used to maintain a K8s manifest for each and every instance, but they want to improve their configuration to be non-repetitive (DRY), less error-prone, and clear, so they decide to use AppEnvCluster.

They have a single repository describing the deployments of all of their services. The base configuration — shared between all services — is defined in module ./iscApp.pkl. There is one top-level directory per service (so ./login/, ./chat/, and ./share/), each containing one directory per environment, which finally contain a directory for every region to deploy in. In short, the repository looks like this:

.
├── iscApp.pkl (1)
├── chat
│   ├── iscApp.pkl (2)
│   ├── dev
│   │   ├── iscApp.pkl (2)
│   │   ├── ap-east-1
│   │   │   └── iscApp.pkl (3)
│   │   └── us-east-1
│   │       └── iscApp.pkl
│   ├── prod
│   │   ├── ap-east-1
│   │   │   └── iscApp.pkl
│   │   ├── ap-east-2
│   │   ...
│   └── qa
│       ├── eu-east-1
│       │   └── iscApp.pkl
│       └── us-west-1
│           └── iscApp.pkl
├── login
│   ...
└── share
    ...

1	A "root" module, which `amends "package://pkg.pkl-lang.org/pkl-pantry/k8s.contrib.appEnvCluster@1.0.2#/AppEnvCluster.pkl"`.
2	Every app (and environment) can define a `iscApp.pkl` that (`amends "…"` and) expresses configuration shared among all its instances.
3	Every instance has a `iscApp.pkl` file which `amends "…"` (and often nothing else).

Simply running pkl eval -m out/ **/*.pkl in their repository produces all the K8s manifests ISC needs to deploy all their services everywhere. Unless an instance requires specific configuration, the leaf modules only contain amends "…" and are used solely to declare the existence of the instance.

AppEnvCluster.pkl uses this file organisation to determine which modules to produce output for (only those iscApp.pkl files that are in an app/env/cluster subdirectory) and it automatically derives values for the corresponding properties in these modules.

Implementation

How does AppEnvCluster.pkl accomplish this?

import "pkl:reflect"

hidden app: String = path[0]
hidden env: String = path[1]
hidden cluster: String = path[2]

hidden path: List<String> = findRootModule(reflect.Module(module)).relativePathTo(module)

local function findRootModule(mod: reflect.Module): Module =
  let (supermodule = mod.supermodule)
    if (supermodule == null || !supermodule.isAmend) mod.reflectee
    else findRootModule(supermodule)

It only introduces one "new" concept and that is the concept of a "root" node. For AppEnvCluster.pkl, the root node is the one amending the AppEnvCluster.pkl module from the appEnvCluster package. The function findRootModule finds this, by taking the reflection of module, and following the amends-chain, until it finds a module, whose supermodule does not amends anything. When it finds that, it reflects back (mod.reflectee) to return the Module object. In pkl:base, Module is defined with a method relativePath, which returns the path of module relative to this module. The path is represented as a List, with one String per directory — no file name at the end.

So far, you’ve seen how AppEnvCluster.pkl derives path information, but evaluating chat/dev/iscApp.pkl should now produce an error if you try to read its cluster property. Given that you can safely run pkl eval -m out/ **/*.pkl, the template must find a way to prevent this. Here is how:

function isLeafModule(): Boolean = path.length == 3 (1)

output {
  value = if (isLeafModule())
      module.toMap().values.flatMap((it) -> it.toMap().values) (2)
    else
      List() (3)
}

1	A "leaf" module is on that has a `path.length` of precisely `3`.
2	For leaf modules, the top-level structure of `AppEnvCluster.pkl` is flattened.
3	Any non-leaf modules do not produce any output.

This means that modules in deeper subdirectories are ignored (their path.length is greater than 3). This is design choice in AppEnvCluster.pkl; another would be to provide an error for modules in the wrong place. Leaf nodes are flattened, because all of their properties express K8s objects that are expressed as their own K8s manifest (one file each, when producing multiple file output).

Example (revisited)

You can see AppEnvCluster.pkl in operation by writing out (a minimal subset) of the example above. As seen from the top-level directory of the repository you can define iscApp.pkl as follows:

amends "package://pkg.pkl-lang.org/pkl-pantry/k8s.contrib.appEnvCluster@1.0.2#/AppEnvCluster.pkl"

Next, define chat/dev/app-east-1/iscApp.pkl as follows:

amends "..."

secrets {
  ["hush"] {
    stringData {
      ["application"] = module.app
      ["environment"] = module.env
      ["cluster"] = module.cluster
    }
  }
}

When you run pkl eval */*/*/iscApp.pkl, you now see that AppEnvCluster.pkl resolved app, env, and cluster as expected:

apiVersion: v1
kind: Secret
metadata:
  name: hush
stringData:
  application: chat
  environment: dev
  cluster: app-east-1

Pkl Evolution

2024-04-29T00:00:00.000Z

by Dan Chao on April 29th, 2024

Today, we launch Pkl Evolution, a new repository that holds Suggested Pkl Improvements, Changes, or Enhancements (SPICEs) for Pkl’s language, tooling, and ecosystem.

The purpose of the Pkl Evolution repository is to provide visibility to the community how design decisions are made in Pkl. Additionally, it is a place for the Pkl maintainers to get feedback as in-flight proposals are being considered.

Process for SPICEs

The process for a SPICE is:

The SPICE is authored, and submitted as a pull request.
When authoring a SPICE, determine your SPICE number by adding one to the latest SPICE (inclusive of open pull requests).
The contents of the SPICE are discussed and reviewed in the pull request.
It is then either accepted or rejected.
The status of the SPICE is updated, and the pull request is merged. Both accepted and rejected SPICEs get merged into the main branch.

The acceptance of a SPICE does not need to block any implementation work. On the contrary, it can be quite useful to have an implementation ready to go during the process of review.

The acceptance of a SPICE depends on consensus from the Pkl maintainers.

Contributing to Pkl Evolution

There are two main ways you can participate and contribute to Pkl Evolution.

The first way is to participate in the pull request discussion for a SPICE. Your thoughts and opinions are valuable to us, and can help shape the direction of the language.

The second way is to author SPICEs of your own. If you would like to contribute your own SPICE, we recommend you first the idea to GitHub Discussions to solicit feedback. This can help shape the direction of the SPICE before too much work goes in. It can also potentially filter out ideas that are non-starters.

Status of Pkl Evolution

Some of you might recognize how similar this is to Swift Evolution. If you’ve noticed that, you’re totally right! We borrowed much of this from the Swift folks.

Compared to Swift Evolution, we are choosing to keep our process relatively light-weight. There is no review manager, and no designated review period. This is an intentional choice on our part, and we expect that our own process will evolve over time.

Testing in Pkl

2024-04-09T00:00:00.000Z

by Dan Chao on April 9th, 2024

Pkl files are programs that get evaluated to produce a result. Like any other program, it can be useful to have tests that verify their business logic. To address this, Pkl provides tooling for writing and running tests.

Writing Tests

Tests in Pkl are modules that amend standard library module pkl.test.

These modules can describe facts, and examples.

Facts

Facts are boolean assertions. They are useful for unit tests, where the behavior of functions, types, or any expression can be tested.

If an expression evaluates to false, the test case is considered failing.

Below is a naïve test about the qualities of the integer 1, where the last expression fails.

math.pkl

amends "pkl:test"

facts {
  ["one"] {
    1.isOdd
    1.isBetween(0, 3)
    1 + 5 == 3
  }
}

Running this test provides a report about the failing test.

$ pkl test math.pkl
module math
  facts
    ✘ one
       1 + 5 == 3 (file:///math.pkl, line 8)
         │   │
         6   false

0.0% tests pass [1/1 failed], 66.6% asserts pass [1/3 failed]

Test failures show a power assertion about the failing test (introduced in Pkl 0.31). This is a diagram that displays the values produced by sub-expressions in the test.

facts in Pkl are most useful for writing fine-grained assertions about specific behavior of your code.

The tests for module pkl.experimental.uri are a good example of facts in practice. There are multiple facts, where each fact contains multiple assertions which cover different cases of business logic:

URI.pkl#L27-L36

facts {
  ["encode"] {
    URI.encode("https://example.com/some path") == "https://example.com/some%20path"
    URI.encode(alphaLower) == alphaLower
    URI.encode(alphaUpper) == alphaUpper
    URI.encode(nums) == nums

    local safeChars = "!#$&'()*+,-./:;=?@_~"
    URI.encode(safeChars) == safeChars
    URI.encode("\u{ffff}") == "%EF%BF%BF"
    URI.encode("🏀") == "%F0%9F%8F%80"
  }

Examples

Examples are values that get compared to expected values. When first testing an example, its value gets written to a sibling file that ends in pkl-expected.pcf. The next time the test is run, the example value is then asserted to be equal to that expected value. If they are not equal, the test fails.

Here is a quick tutorial for writing an example. First, we create a test module with our example. In this case, we are checking the behavior of an imagined Person class. For simplicity’s sake, we are just declaring it as a local class.

person.pkl

amends "pkl:test"

local class Person {
  firstName: String

  lastName: String

  fullName: String = "\(firstName) \(lastName)"
}

examples {
  ["person"] {
    new Person {
      firstName = "Johnny"
      lastName = "Appleseed"
    }
  }
}

This test then gets run:

pkl test person.pkl

On the first run, Pkl tells us that the corresponding expected value was written.

module test
  examples
    ✍️ person

1 examples written

This creates a file called person.pkl-expected.pcf in the same directory. The directory tree now looks like this:

.
├── person.pkl
└── person.pkl-expected.pcf

We can inspect the contents of the pkl-expected.pcf to see what the expected value is.

person.pkl-expected.pcf

examples {
  ["person"] {
    new {
      firstName = "Johnny"
      lastName = "Appleseed"
      fullName = "Johnny Appleseed"
    }
  }
}

Running pkl test person.pkl again now shows that it passes.

module test
  examples
    ✔ person

100.0% tests pass [1 passed], 100.0% asserts pass [1 passed]

Now, we’ll change "Johnny" to "Sally", to demonstrate a test failure.

 examples {
   ["person"] {
     new Person {
-      firstName = "Johnny"
+      firstName = "Sally"
       lastName = "Appleseed"
     }
   }
 }

Running pkl test person.pkl again fails.

module test
  examples
    ✘ person
       #0: (file:///test.pkl, line 13)
         Expected: (file:///test.pkl-expected.pcf, line 3)
         new {
           firstName = "Johnny"
           lastName = "Appleseed"
           fullName = "Johnny Appleseed"
         }
         Actual: (file:///test.pkl-actual.pcf, line 3)
         new {
           firstName = "Sally"
           lastName = "Appleseed"
           fullName = "Sally Appleseed"
         }

0.0% tests pass [1/1 failed], 0.0% asserts pass [1/1 failed]

Because the test failed, Pkl writes a new file to the same directory. The directory tree now looks like this:

.
├── person.pkl
├── person.pkl-actual.pcf
└── person.pkl-expected.pcf

It can be especially useful to use diff to compare the pkl-actual.pcf file with the pkl-expected.pcf file.

diff -c person.pkl-actual.pcf person.pkl-expected.pcf

--- person.pkl-actual.pcf    2024-03-28 15:33:15
+++ person.pkl-expected.pcf  2024-03-28 15:15:00
@@ -1,9 +1,9 @@
 examples {
   ["person"] {
     new {
-      firstName = "Sally"
+      firstName = "Johnny"
       lastName = "Appleseed"
-      fullName = "Sally Appleseed"
+      fullName = "Johnny Appleseed"
     }
   }
 }

For intentional changes, add the --overwrite flag. This will overwrite the expected output file, and also remove the pkl-actual.pcf file.

$ pkl test person.pkl --overwrite
module test
  examples
    ✍️ person

1 examples written

Pattern: Testing JSON, YAML and other module output

A common pattern is to use examples to test how Pkl renders into static configuration.

Pkl is idiomatically split between schema and data. Base Pkl modules define schema and rendering logic (colloquially called templates), and downstream modules amend those base modules with just data.

Here is an imagined Pkl template for configuring a logger. It defines some converters for DataSize and Duration, and also sets the output renderer to YAML.

Logger.pkl

module Logger

/// The list of targets to send log output to.
targets: Listing<LogTarget>

abstract class LogTarget {
  /// The logging level to write at.
  logLevel: "info"|"warn"|"error"
}

class RotatingFileTarget extends LogTarget {
  /// The max file size
  maxSize: DataSize?

  /// The directory to write log lines to.
  directory: String
}

class NetworkLogTarget extends LogTarget {
  /// The network URL to send log lines to.
  connectionString: Uri

  /// The timeout before the connection gets killed.
  timeout: Duration?
}

output {
  renderer = new YamlRenderer {
    converters {
      [DataSize] = (it) -> "\(it.unit)\(it.value)"
      [Duration] = (it) -> it.isoString
    }
  }
}

After having written this template, we’d like to test to see what our YAML output actually looks like. We’d also like to provide some sample code for our users, that demonstrate how to use our template.

To do this, we’ll first create some examples modules, in an examples/ directory.

examples/rotatingLogger.pkl

amends "../Logger.pkl"

targets {
  new RotatingFileTarget {
    maxSize = 5.mb
    directory = "/vat/etc/log"
  }
}

examples/networkLogger.pkl

amends "../Logger.pkl"

targets {
  new NetworkLogTarget {
    timeout = 5.s
    connectionString = "https://example.com/foo/bar"
  }
}

With this set up, we can now use them as test examples.

tests/Logger.pkl

module tests.Logger

amends "pkl:test"

import* "../examples/*.pkl" as allExamples

examples {
  for (key in allExamples.keys) { (1)
    [key.drop("../examples/".length).replaceLast("pkl", "yml")] { (2)
      allExamples[key].output.text
    }
  }
}

1	Iterates over the keys only as a workaround for a current bug where for-generators are eager in values. This ensures that any errors related to loading the module are captured as related to that specific example.
2	Sets the test name to `.yml`

These tests are defined as evaluating each module’s output.text property. This emulates the behavior of the Pkl CLI when it evaluates a module through pkl eval.

Furthermore, the tests uses a glob import to bulk-import these example modules. This means that if we add new modules to the examples/ directory, they are automatically added as a new test.

Running this test creates expected output:

$ pkl test tests/Logger.pkl
module tests.Logger
  examples
    ✍️ networkLogger.yml
    ✍️ rotatingLogger.yml

2 examples written

Reporting

By default, Pkl writes a simple test report to console. Optionally, it can also produce JUnit-style reports by setting the --junit-reports flag.

Example:

pkl test --junit-reports .out

Interaction with `pkl:Project`

In Pkl, a project is a directory of Pkl modules that is tied together with the presence of a PklProject file.

There are many reasons for wanting to define a project. One reason is to simplify the pkl test command. If pkl test is run without any input source modules, it will run all tests defined in the PklProject.

PklProject

amends "pkl:Project"

tests {
  ...import*("tests/**.pkl").keys
}

A note on `apiTests`

When creating a package, it is also possible to specify apiTests. These are tests for the external API of this package. The intention of this is to allow checking for breaking changes when updating a version. When publishing a new version of the same package, running apiTests of a previous package can inform whether the package’s major version needs to be bumped or not.

The apiTests are also run when the package is created via pkl project package.

Using packages in air-gapped environments

2025-11-21T00:00:00.000Z

by Dan Chao on November 21, 2025

In some cases, Pkl evaluation needs to occur in environments that do not have internet access. At the same time, these evaluations can use packages that are published to the internet. To enable using such packages, Pkl provides three approaches: HTTP proxying, mirroring, and vendoring.

HTTP proxying

Pkl can connect through an HTTP CONNECT proxy server when downloading packages (and making any other HTTP requests).

For users of the CLI, the HTTP proxy can either be configured on the OS user level, (in ~/.pkl/settings.pkl), on the project level (in PklProject), or using the --http-proxy and --http-no-proxy CLI flags.

OS user
project

~/.pkl/settings.pkl

amends "pkl:settings"

http {
  proxy {
    address = "http://my.proxy.address"
    noProxy {
      // don't proxy if the host is `localhost`
      "localhost"
      // don't proxy if the IP address starts with `127.0`
      "127.0.0.0/16"
    }
  }
}

PklProject

amends "pkl:Project"

evaluatorSettings {
  http {
    proxy {
      address = "http://my.proxy.address"
      noProxy {
        // don't proxy if the host is `localhost`
        "localhost"
        // don't proxy if the IP address starts with `127.0`
        "127.0.0.0/16"
      }
    }
  }
}

Those that use Pkl as a library in a host language have similarly named options when building the evaluator.

To read more about proxying, see the documentation.

Mirror server

It’s also possible to set up a server that mirrors the assets available from the internet.

To connect to a mirror server, the HTTP rewrites setting is used. Like proxying, this can be configured on either the OS user level, on the project level, or using the --http-rewrite CLI flag.

For example, this configures rewrites for packages from pkg.pkl-lang.org:

OS user
project

~/.pkl/settings.pkl

amends "pkl:settings"

http {
  rewrites {
    ["https://pkg.pkl-lang.org/"] = "https://my.mirror/pkg.pkl-lang.org/"
    // github rewrites are also required in order to fetch package ZIP assets.
    ["https://github.com/"] = "https://my.mirror/github.com/"
    ["https://www.github.com/"] = "https://my.mirror/github.com/"
  }
}

PklProject

amends "pkl:Project"

evaluatorSettings {
  http {
    rewrites {
      ["https://pkg.pkl-lang.org/"] = "https://my.mirror/pkg.pkl-lang.org/"
      // github rewrites are also required in order to fetch package ZIP assets.
      ["https://github.com/"] = "https://my.mirror/github.com/"
      ["https://www.github.com/"] = "https://my.mirror/github.com/"
    }
  }
}

Beneath the hood, the pkg.pkl-lang.org service simply redirects to GitHub. So, a mirror server for such packages only needs to mirror GitHub assets. Here is a simple nginx configuration that handles mirroring given the above settings.

nginx.conf

server {
  proxy_set_header Host "github.com";
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
  proxy_redirect off;

  location ~ ^/pkg\.pkl-lang\.org/github\.com/(?[^/]+)/(?[^/]+)/(?.*)$ {
    proxy_pass https://github.com/$org/$repo/releases/download/$asset/$asset;
  }

  location ~ ^/pkg\.pkl-lang\.org/(?[^/]+)/(?.*)$ {
    proxy_pass https://github.com/apple/$repo/releases/download/$asset/$asset;
  }

  location ~ ^/github\.com/(?.*)$ {
    proxy_pass https://github.com/$path;
  }
}

Note that pkg.pkl-lang.org is not a straight-up prefix replacement. Therefore, the server needs to mirror according to the same redirect scheme. Effectively, the two redirects are:

/:repo/:pkg                 -> https://github.com/apple/:repo/releases/download/:pkg/:pkg
/github.com/:org/:repo/:pkg -> https://github.com/:org/:repo/releases/download/:pkg/:pkg

Vendoring dependencies

Strictly speaking, Pkl does not have a feature for vendoring dependencies. However, it provides derivative tools to determine the coordinates of dependencies, to download these dependencies to a set path, and to tell Pkl to load packages from there.

Downloading dependencies

When using projects, the PklProject.deps.json file describes all the dependencies of the project. Using the jq, xargs, and curl tools, these dependencies can be downloaded to a vendor directory.

Here is a sample script:

#!/usr/bin/env bash

VENDOR_DIRECTORY=vendor

# Download all project dependencies based on the generated `PklProject.deps.json` file
cat PklProject.deps.json \
  | jq -r '.resolvedDependencies[] | select(.type == "remote") | .uri[7:] + "::sha256:" + .checksums.sha256' \
  | xargs -I {} pkl download-package --no-transitive {} --cache-dir "$VENDOR_DIRECTORY"

Handling directly imported packages

Sometimes, Pkl code is not evaluated within the context of a PklProject. In these cases, modules within packages are imported directly using the full package URI (e.g. import "package://…" instead of import "@myDep/…").

Without a project, there is no PklProject.deps.json. So, the pkl analyze imports command should be used instead.

It’s uncommon and generally not advised to import packages directly if there is a PklProject present. Instead, these should be imported as project dependencies.

#!/usr/bin/env bash

VENDOR_DIRECTORY=vendor

pkl analyze imports -f json config.pkl \
  | jq -r '[.resolvedImports[] | split("#/")[0] | select(startswith("package://"))] | unique | .[]' \
  | xargs -I {} pkl download-package {} --cache-dir "$VENDOR_DIRECTORY"

Configuring the cache directory

For those using the Pkl CLI, the most straightforward way to configure the cache directory is through the --cache-dir flag.

pkl eval --cache-dir vendor myModule.pkl

For those using projects, the cache directory can be set in the PklProject file. This means that you do not need to specify the --cache-dir flag during evaluation.

PklProject

amends "pkl:Project"

evaluatorSettings {
  moduleCacheDir = "vendor"
}

Those that use Pkl as a library within a host language have similarly named settings when constructing the evaluator.

Taking types to the next level

2024-10-15T00:00:00.000Z

by Islon Scherer on October 15th, 2024

One of the main points of using Pkl is to describe what your configuration looks like. An often overlooked design goal (arguably, the most important), is to forbid invalid configurations. Pkl types allow a great degree of freedom and power in constraining what your data looks like.

Some developers, especially those coming from more general purpose languages like Swift, Go, or Java, may have a pre-defined notion of how types can help them. So let’s have a look at how Pkl can go beyond most traditional types.

Beyond Strings

String is a type we tend to see everywhere. This is especially true in configuration languages, where a String can be used as a "joker" type for many different values.

Enumerating possibilities

A typical usage of Strings is to define a finite set of values that your property can take:

/// The environment where this service is running.
///
/// Valid possibilities are "dev", "qa" and "prod".
env: String

This works, but has the problem that users of your template can provide invalid data, like "foo". So let’s do better:

/// The environment where this service is running.
env: "dev"|"qa"|"prod"

Now env will reject any invalid possibility. If you’re using an IDE, like the IntelliJ plugin, this has the added benefits of providing autocomplete and telling you when a given value is invalid.

In Pkl, strings are not only values; they can also be types.

Matching values

Another typical use for strings is to allow values that have a specific shape:

/// The IPv4 to connect
serverIp: String

Again, we can do better to validate that the given ip is correct:

/// The IPv4 to connect
serverIp: String(matches(Regex(#"((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}"#))) (1)

Strings can be constrained to match specific regular expressions. The new serverIp will only allow values of a specific shape, greatly reducing the possibility of invalid configs.

More String goodies

name: String(!isBlank) (1)

email: String(contains("@")) (2)

swiftFile: String(endsWith(".swift")) (3)

contentType: "text/plain"|"text/html"|"application/json"|String (4)

1	`name` cannot be empty or a blank String.
2	`email` must contain a `@` symbol.
3	A Swift file must have the correct extension.
4	Declaring some common possibilities before the generic type is a useful pattern that results in better tooling support in IDEs.

There are plenty of ways to make our types more fine-grained than just String, but strings are not the only types we can refine in Pkl.

Constraining numbers

Pkl comes with some useful typealiases for numbers like Int16, UInt8, etc.

serverPort: UInt16 (1)

1	Will only allow values between 0 and 65535, inclusive.

Builtin typealiases are not the only way to handle such cases, though. Numbers can be constrained to any value.

volume: Float(isBetween(0.0, 11.0)) (1)

multiplier: Int(isEven) (2)

1	`volume` can only be in the range between 0 and 11.
2	`multiplier` cannot be odd.

Beyond builtins

Up to now, we only took a look at builtin functions, mostly functions of the type itself. We also limited our types to a single constraint. Pkl allows, though, for arbitrary functions as constraints, and we can provide multiple ones:

local isPrime = (n: Int) ->
  n > 1 && IntSeq(2, n - 1).toList().every((x) -> n % x != 0)

hash: Int(isPrime) (1)

region: String(startsWith("us-"), length < 10) (2)

name: String(this == capitalize()) (3)

building: String(isEmpty || toInt() <= 100) (3)

grade: Int(isBetween(0, 10))|String(matches(Regex(#"[A-F][+-]?"#))) (4)

1	User defined constraints.
2	Multiple constraints.
3	Arbitrary boolean expressions.
4	Multiple possibilities with different constraints.

Better errors

One downside of using arbitrary expressions as constraints is that, sometimes, errors messages can be a bit hard to understand:

ssn: String(matches(Regex(#"\d{3}-\d{2}-\d{4}"#))) = "123-123-123"

–– Pkl Error ––
Type constraint `matches(Regex(#"\d{3}-\d{2}-\d{4}"#))` violated.
Value: "123-123-123"

1 | ssn: String(matches(Regex(#"\d{3}-\d{2}-\d{4}"#))) = "123-123-123"
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
...

We can do better than that.

One trick to improve error messages is to create named lambdas:

local isValidSocialSecurityNumber = (str: String) ->
  str.matches(Regex(#"\d{3}-\d{2}-\d{4}"#))

ssn: String(isValidSocialSecurityNumber) = "123-123-123"

–– Pkl Error ––
Type constraint `isValidSocialSecurityNumber` violated.
Value: "123-123-123"

4 | ssn: String(isValidSocialSecurityNumber) = "123-123-123"
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^
...

That’s already better. Users now have a hint of what they did wrong.

Providing custom error messages

Sometimes, it can be useful to provide your own custom error messages. Pkl doesn’t provide a built-in way to do this, but one pattern to hack around this limitation is to use throw.

This approach can be a footgun. See Dangers of throw for details.

With the knowledge that failing constraints will throw an exception, we can provide a custom error message by throwing the exception ourselves:

local function reportSSN(ssn: String) =
  """
  Invalid social security number: \(ssn).
  Valid ones should be in the form `XXX-XX-XXXX`
  where `X` is a number between 0 and 9.
  """

ssn: String(matches(Regex(#"\d{3}-\d{2}-\d{4}"#)) || throw(reportSSN(this))) = "123-123-123"

–– Pkl Error ––
Invalid social security number: 123-123-123.
Valid ones should be in the form `XXX-XX-XXXX`
where `X` is a number between 0 and 9.

8 | ssn: String(matches(Regex(#"\d{3}-\d{2}-\d{4}"#)) || throw(reportSSN(this))) = "123-123-123"
                                                         ^^^^^^^^^^^^^^^^^^^^^^
...

Now users know exactly what the problem is and how to fix it.

Dangers of `throw`

Using throw to give a better error report is a powerful tool, but it comes with its own set of downsides that we have to be aware of.

Throwing exceptions inside constraints will short-circuit and stop execution immediately, so it doesn’t compose very well:

typealias SSN = String(matches(Regex(#"\d{3}-\d{2}-\d{4}"#)) || throw("Invalid SSN ..."))
typealias NIN = String(matches(Regex(#"[A-Z]{2}\d{6}[A-Z]"#)) || throw("Invalid NIN ..."))

taxId: SSN|NIN = "AB123456C"

–– Pkl Error ––
Invalid SSN ...

1 | typealias SSN = String(matches(Regex(#"\d{3}-\d{2}-\d{4}"#)) || throw("Invalid SSN ..."))
                                                                    ^^^^^^^^^^^^^^^^^^^^^^^^
...

That wasn’t expected.

Because of the eager nature of throw, we have to be careful when to use it and to not compose it with other constraints.