What causes "Usage: pkl test [ ] ... Error: missing argument " in apple/pkl?

Pass test modules explicitly: `pkl test myTests.pkl` (or multiple modules).

apple/pkl · error · CliException

Usage: pkl test [<options>] <modules>... Error: missing arg

Error message

Usage: pkl test [<options>] <modules>...

Error: missing argument <modules>

What it means

`pkl test` requires test modules to run. If no modules were given on the command line and the project (PklProject) does not declare any `tests` entries, CliTestRunner.evalTest throws this CliException mimicking clikt's missing-argument error. It exists because modules can come either from CLI args or project config, which clikt cannot validate on its own.

Source

Thrown at pkl-cli/src/main/kotlin/org/pkl/cli/CliTestRunner.kt:55

  private val errWriter: Writer = System.err.writer(),
) : CliCommand(options) {

  override fun doRun() {
    val builder = evaluatorBuilder()
    try {
      evalTest(builder)
    } finally {
      Closeables.closeQuietly(builder.moduleKeyFactories)
      Closeables.closeQuietly(builder.resourceReaders)
    }
  }

  private fun evalTest(builder: EvaluatorBuilder) {
    val sources =
      options.normalizedSourceModules.ifEmpty { project?.tests?.map { it.toUri() } }
        ?:
        // keep in sync with error message thrown by clikt
        throw CliException(
          """
          Usage: pkl test [<options>] <modules>...

          Error: missing argument <modules>
          """
            .trimIndent()
        )

    val evaluator = builder.build()
    evaluator.use {
      var failed = false
      var isExampleWrittenFailure = true
      val moduleNames = mutableSetOf<String>()
      val reporter =
        when (testOptions.reporter) {
          TestReporter.SPEC -> SpecReporter(useColor)
          TestReporter.MINIMAL -> MinimalReporter(useColor)
        }

View on GitHub (pinned to f3efcbfc9b)

Solutions

Pass test modules explicitly: `pkl test myTests.pkl` (or multiple modules).
Declare tests in PklProject under `tests: { ... }` so bare `pkl test` has modules to run.
Run from the project root (where PklProject lives) so project.tests is picked up.

Example fix

# before
$ pkl test
Error: missing argument <modules>

# after (option 1)
$ pkl test tests/myTests.pkl

# after (option 2: PklProject.pkl)
tests {
  "tests/myTests.pkl"
}

Defensive patterns

Strategy: validation

Validate before calling

# before running pkl test, ensure modules exist either on CLI or in project
if [ -z "$MODULES" ] && ! grep -q 'tests' PklProject.pkl; then
  echo "error: no test modules given and PklProject declares no tests" >&2; exit 2
fi
pkl test $MODULES

Try / catch

// pkl test exits non-zero with this message; check exit code in scripts
pkl test "$@" || { echo "pkl test: supply <modules> or declare tests in PklProject"; exit 1; }

Prevention

Always declare `tests` in PklProject.pkl so bare `pkl test` works.
In CI, pass explicit module paths rather than relying on ambient project config.
Run from the project root so PklProject is discovered.

When it happens

Trigger: Running `pkl test` with zero positional <modules> arguments while the current project's `tests` list in PklProject is empty or absent.

Common situations: Developer runs `pkl test` at a directory without a PklProject defining tests, expecting auto-discovery; CI script dropped the module arguments; project migrated and the `tests` block was removed from PklProject.

Understand the failure class

Background: "no subcommand specified" and "... is required": CLI errors when a required argument is missing — this error's family across 13 libraries.

Related errors

AI-assisted analysis of apple/pkl@f3efcbfc9b (2026-09-08). Data as JSON: /api/errors/562448efd2b9ba24. Report an issue: GitHub.