KonsolScript - Scripting Guide

Everything a script author needs to write, run, and extend KonsolScript (.ks) programs

• from beginner CLI tools and game scripts to AI orchestration pipelines that wire

together LLM APIs (OpenAI, Anthropic Claude, Google Gemini, Ollama) into automated, multi-model workflows.

→ Contributors and plugin authors: see Contributing

Table of Contents

1. What can you build? - app ideas you can ship with the built-in modules and plugins
2. Kookbook - full project ideas, beginner to advanced
3. Language reference
4. Standard library modules
5. OOP wrappers - object-oriented facades over the built-in modules
6. Memory model - how variables are stored and when they are destroyed
7. Running scripts - the minks CLI
8. Available plugins
9. LLM integration - full language reference and system prompt template for AI code generation

What can you build?

From beginner CLI tools to AI-powered pipelines - KonsolScript's modules and plugins cover a wide range of real-world apps:

• File organizer - rename and sort files by date (File, Path, OS)
• CSV / JSON pipeline - filter, transform, and report on datasets (CSV, JSON, List)
• LLM prompt pipeline - batch files through an AI API, collect results to CSV (kse_curl, JSON, File)
• AI log triage - scan logs with Regex, send anomalies to an LLM, output a report (Regex, kse_curl, JSON)

Quick demo - fetch a public API and parse the response:

// curl_json.ks - HTTP fetch + JSON parse demo
//
// Install once, then run:
//   minks install kse_curl    (from inside curl_plugin/)
//   minks helloworld/curl_json.ks
//
// Or load explicitly without installing:
//   minks --plugin curl_plugin\kse_curl.dll helloworld\curl_json.ks   (Windows)
//   minks --plugin ./curl_plugin/kse_curl.so helloworld/curl_json.ks  (Linux)
//   minks --plugin ./curl_plugin/kse_curl.dylib helloworld/curl_json.ks  (Mac)

#include "kse_curl"

Konsol:Print("=== Curl + JSON Demo ===");

// fetch a post from the public JSONPlaceholder API
Var:String response;
Var:Number status;

try {
    Curl:Get("https://jsonplaceholder.typicode.com/posts/1", response);
} catch (CurlException e) {
    Konsol:Print("fetch failed: ${e.message}");
    Konsol:Exit(1);
}

Curl:Status(status);
Konsol:Print("HTTP ${status}");

// parse and extract fields
JSON:Parse(response, post);

Var:Number userId;
Var:Number postId;
Var:String title;
Var:String body;

JSON:Get("userId", post, userId);
JSON:Get("id",     post, postId);
JSON:Get("title",  post, title);
JSON:Get("body",   post, body);

JSON:Free(post);

Konsol:Print("Post #${postId} by user ${userId}");
Konsol:Print("Title: ${title}");
Konsol:Print("---");
Konsol:Print(body);

→ Full test: helloworld/curl_json.ks

→ Hello World demos - fetch + JSON, AI chat, number guessing game, AI log triage

→ Full project ideas - beginner to advanced

→ LLM integration guide - full language reference and system prompt template so any LLM can generate valid KonsolScript for your app

Language reference

→ Language Reference - types, operators, control flow, functions, classes, error handling, and the full standard library module reference

Standard library modules

→ All built-in modules - Konsol, Math, String, File, Time, List, Dictionary, JSON, Path, OS, Regex, Date, Hash, CSV

→ OOP wrappers - object-oriented facades using return-type syntax instead of ByRef

Memory model

KonsolScript has no garbage collector. Memory is freed immediately and deterministically - no background collector, no pauses, no tuning knobs.

Scope boundaries

KonsolScript distinguishes memory lifetime (when storage is freed) from visibility scope (where a name can be read or written).

Memory lifetime - all variable types are freed when the enclosing function returns:

Visibility scope - if, else, while, for, and foreach blocks each create their own scope. Variables declared inside a block are not visible outside it:

if (x > 0) {
    Var:String label;
    String:Set("positive", label);
    // label is available here
}
// label is NOT available here

if (x > 0) {
    Var:String msg;
    String:Set("yes", msg);
} else {
    // msg is NOT available here - if and else have separate scopes
}

Outer-scope variables remain visible and writable inside any nested block:

Var:String result;
if (x > 0) {
    String:Set("positive", result);  // result is from the enclosing scope
}

What "destroyed" means

When a function returns, every variable in its local frame is freed immediately - scalars, class instances, and collections alike. Nothing is marked for later collection; it is freed now.

Variables declared at global scope (outside any function) live for the lifetime of the engine.

Global collections and long-running scripts

Collections declared at global scope are freed only when the engine exits. A global collection that keeps growing without being cleared holds memory for as long as the engine is alive. For long-running server scripts, clear global collections you no longer need:

Dictionary:Clear(myCache)
List:Clear(myLog)

Running scripts - the minks CLI

→ minks CLI - how to run scripts, the REPL, flags (--check, --debug, --sandbox), exit codes, and the plugin package manager (minks install / remove / list)

Available plugins

Install a plugin once with minks install kse_<name>, then load it in any script with #include "kse_<name>".

We welcome plugin contributions - see Contributing to get started.