Running programs

Checking, running, and testing a program with pickle-cli.

vlatest

pickle-cli has a deliberately small command surface. This page documents the commands you use day to day.

The command surface

The PickleScript toolchain

Usage: pickle-cli <COMMAND>

Commands:
  check    Parse, resolve, and type-check a module
  explain  Explain a stable error code
  run      Compile a module with the JIT and run it
  test     Run the test fn items of one or more modules
  help     Print this message or the help of the given subcommand

pickle help prints the full list for the build you have installed, which is the authoritative answer for that version.

check: parse, resolve, type-check

pickle-cli check [OPTIONS] <FILE>
Option Effect
--json Emit machine-readable JSON for every diagnostic on stdout
--group Group diagnostics under their error code
pickle-cli check --json src/main.pkl

This is the command to build editor integrations around. It does not execute your code.

run: compile and execute

pickle-cli run <FILE> [-- <ARGS>...]

run lowers the program to machine code and executes it. Arguments after -- are available to the program through args().

pickle-cli run main.pkl -- --verbose input.txt

If the module has no main, run fails with:

module has no `main`; nothing to run

test: run the test items

pickle-cli test [OPTIONS] [TARGET]
Argument Meaning
[TARGET] A *.pkl file, or a directory of them. Defaults to tests/.
-f, --filter <FILTER> Only tests whose name contains this substring
--tag <TAG> Only tests carrying this tag. Repeatable, combined with --filter using AND

A directory target only picks up files named *_test.pkl or *.test.pkl.

pickle-cli test
pickle-cli test stdlib/
pickle-cli test --filter fib

The runner exits 0 when every test passes and 1 otherwise, so it drops straight into CI.

explain: error code reference

pickle-cli explain E0308
pickle-cli explain      # list every code in the catalogue

See Diagnostics and error codes for the full catalogue.

Next steps