Skip to content

CLI

Comet Blitzen Dasher Donner Prancer

This runtime provides the ability to access the language/runner via a Command Line Interface (CLI). It includes the following functionality:

  • Execute a given solution's source file, providing benchmark timing for each defined part.
  • Execute a given solutions source files test suite.
  • Execute a given script source file.
  • Load an interactive REPL environment, which can be used to quickly explore the language (Comet, Blitzen, Prancer).

Release (Comet)

Platform Release
Linux (x64) santa-lang-comet-cli-1.0.1-linux-amd64
Linux (ARM) santa-lang-comet-cli-1.0.1-linux-arm64
macOS (Intel) santa-lang-comet-cli-1.0.1-macos-amd64
macOS (ARM) santa-lang-comet-cli-1.0.1-macos-arm64
Docker ghcr.io/eddmann/santa-lang-cli:latest

Also available in: Blitzen, Dasher, Donner, Prancer

The macOS release may require you to remove the quarantine flag from the executable: xattr -d com.apple.quarantine santa-lang-comet-cli-*

External Functions

The CLI provides three runtime specific functions, these are:

puts

puts(..value)

Prints the supplied values (using their display format) to stdout.

puts("Hello", [1, 2.5, true])

read

read(path)

Reads the contents of the given path into a String. The path can either be:

  • A local directory path, absolute or relative to the source file.
  • Based on a http(s) schema being defined; a web URL location.
  • Based on a aoc schema being defined; a specific Advent of Code problem input (i.e. aoc://2015/1). In this case an external SANTA_CLI_SESSION_TOKEN environment variable must be defined which includes a valid Advent of Code session token. This can be extracted from the cookie set upon successful login to the platform.
read("input.txt")
read("https://www.example.com/input.txt")
read("aoc://2015/1")

env

env()

(REPL only) Prints the current environment's variables

Output Formats

The CLI supports three output formats:

Format Flag Description
Text (default) Human-readable output with ANSI colors
JSON -o json Single JSON object after execution completes
JSONL -o jsonl Real-time streaming with JSON Lines 
# Default human-readable output
santa-cli solution.santa

# JSON output (complete object after execution)
santa-cli -o json solution.santa

# JSONL streaming output (real-time updates)
santa-cli -o jsonl solution.santa

# JSON version output
santa-cli -o json --version
# {"reindeer":"Comet","version":"1.0.1"}

The JSON and JSONL formats are useful for integration with editors, CI systems, and other tools. JSONL provides real-time progress updates using RFC 6902 JSON Patch.

Exit Codes

Code Meaning
0 Success
1 Argument/usage error
2 Runtime/parse error
3 Test failure

Errors

If an error occurrs during execution the the program is immediately halted; with the error message and associated call stack trace presented to the user, as shown below:

CLI Errors

Profiling

Comet's CLI can be built locally (via a Cargo profile feature flag) with additional flamegraph/pprof CPU profiling output for a given solutions' execution. This can be useful when trying to determine slow areas of a given solution, to improve its overall performance.

CLI Profiler

Example

Below is example output for a successful Advent of Code solution and test execution, using the AoC runner:

CLI Runner

Below is example usage of the in-built CLI REPL environment:

CLI REPL