minks - Minimal KonsolScript

minks is a command line interface that runs KonsolScript (.ks) files via libkonsolscript and manages the KonsolScript plugin environment

minks script.ks              # run a script
minks                        # interactive REPL
minks --check script.ks      # validate without running
minks --debug script.ks      # trace execution to stderr
minks --sandbox script.ks    # audit: log File:/OS:/Konsol:Run calls to stderr
minks --version              # print version and exit

Exit codes

REPL

Run minks with no arguments to enter the interactive prompt:

$ minks
minks REPL  (Ctrl+D or 'exit' to quit)
>>> Var:Number x = 2;
>>> Var:Number _ret
>>> Math:Power(x, 10, _ret);
=> 1024
>>> function double(n) { return n * 2; }
>>> double(7);
=> 14
>>> exit

• >>> is the primary prompt; ... appears when inside an open block ({).
• _ret is printed automatically with => when it changes after a statement.
• All variables and function definitions persist across lines for the session.
• Errors are reported with source context and stack trace; the session continues.
• All Konsol: methods are available as bare names — Print(x), Log(x), Input(v), Chr(n), Asc(s), IsNumeric(x), Delay(ms), Run(cmd), Exit(code) — so you don't have to prefix them.

Managing installed plugins

minks install <name>          install plugin from current directory or exe directory
minks remove  <name>          delete it from the user plugin dir
minks list                    list all installed plugins

minks install searches for <name>.dll / .so / .dylib (then lib<name>…) in two places in order:

1. Exe directory — the folder containing the minks binary itself (convenient when the plugin is bundled alongside minks)
2. Working directory — wherever you ran minks install from

Installed plugins live in ~/.minks/plugins/ (Linux/macOS) or %APPDATA%\minks\plugins\ (Windows) and are available to all scripts without any flags.

If the plugin ships a manifest (<name>.json alongside the DLL), minks install automatically installs any required system library using the appropriate package manager:

cd curl_plugin
minks install kse_curl
# installed curl -> ~/.minks/plugins/curl.dll
# This plugin requires libcurl.
# Running: sudo apt install libcurl4-openssl-dev

Adding a search directory (CLI)

minks --plugin-path ./my_libs script.ks

--plugin-path can be repeated. Added dirs are checked before the defaults.

Sandbox mode

minks --sandbox script.ks

Logs every File:, OS:, and Konsol:Run call to stderr before it executes — useful for auditing what an untrusted script does with the filesystem or shell. The script still runs normally; calls are not blocked.

[sandbox] File:Open on line 12
[sandbox] OS:System on line 34

Check mode

minks --check script.ks      # or: minks -c script.ks

Parses and validates the script without executing it. Exits 0 if valid, 1 on errors. Useful for CI linting.

Debug mode

minks --debug script.ks      # or: minks -d script.ks

Prints a trace of each statement to stderr as it executes.

Version / help

minks --version              # or: minks -V
minks --help                 # or: minks -h

Shebang

Scripts may start with a shebang line — minks ignores it:

#!/usr/bin/env minks
Konsol:Print("Hello!");

Make the file executable (chmod +x script.ks) and run it directly on Linux/macOS.

Low-level explicit load (legacy / debug)

minks --plugin ./myplugin.dll script.ks
minks --plugin lib1.dll --plugin lib2.dll script.ks
minks -p ./kse_mysql.so -p ./kse_audio.so game.ks

--plugin (or -p) can be repeated. Libraries are loaded in the order given before the script runs. Prefer #include "name" in scripts over this flag for portability.

Working example — sample plugin

sample_plugin/kse_sample.cpp exposes a Sample class with six byRefMethod entries and one voidMethod. Build, install, and use:

# from sample_plugin/
make
minks install kse_sample   # searches cwd for kse_sample.dll/.so

# In your .ks script:
#include "kse_sample"

Or for a quick test without installing (explicit load by path):

minks --plugin sample_plugin\kse_sample.dll tests\20_plugin.ks   # Windows
minks --plugin ./sample_plugin/kse_sample.so tests/20_plugin.ks  # Linux

Available plugins

All plugins follow the ByRef convention — non-void methods write their result to the last argument, which must be a pre-declared variable.

Plugin exceptions extend Exception and expose e.message (String) and e.code (Number) in catch blocks.

curl — HTTP client

Requires: libcurl (installed automatically by minks install) Source: curl_plugin/kse_curl.cpp

cd curl_plugin && make
minks install kse_curl

#include "curl"

Curl:SetHeader("Authorization", "Bearer mytoken");
Var:String body;
Var:Number status;

try {
    Curl:Get("https://api.example.com/users", body);
} catch (CurlException e) {
    Konsol:Print("Error: ${e.message}");
}

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

sqlite — SQLite database

Requires: nothing — SQLite amalgamation is compiled directly into the plugin Source: sqlite_plugin/kse_sqlite.cpp Note: place sqlite3.c and sqlite3.h from sqlite.org/download.html (amalgamation zip) in sqlite_plugin/ before building

cd sqlite_plugin && make
minks install kse_sqlite

#include "sqlite"

Var:Number db;
Var:Boolean ok;
Var:String rows;

try {
    SQLite:Open("data.db", db);
} catch (SQLiteException e) {
    Konsol:Print("Error: ${e.message}");
}

SQLite:Exec(db, "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)", ok);
SQLite:Exec(db, "INSERT INTO users (name) VALUES ('Alice')", ok);
SQLite:Query(db, "SELECT * FROM users", rows);
Konsol:Print(rows);   // JSON array: [{"id":1,"name":"Alice"}]
SQLite:Close(db);

Query results are returned as a JSON string — use the Json: module to parse them.

mysql — MySQL database

Requires: libmysqlclient (installed automatically by minks install) Source: mysql_plugin/kse_mysql.cpp Note: update MYSQL_DIR in the Makefile to your MySQL Connector/C path on Windows

cd mysql_plugin && make
minks install kse_mysql

#include "mysql"

Var:Number db;
Var:Boolean ok;
Var:String rows;

try {
    MySQL:Connect("localhost", "root", "secret", "mydb", db);
} catch (MySQLException e) {
    Konsol:Print("Connect failed (${e.code}): ${e.message}");
}

MySQL:Exec(db, "INSERT INTO users (name) VALUES ('Alice')", ok);
MySQL:Query(db, "SELECT * FROM users", rows);
Konsol:Print(rows);   // JSON array
MySQL:Close(db);

Query results are returned as a JSON string — use the Json: module to parse them.

zip — Zip archives

Requires: libzip (installed automatically by minks install) Source: zip_plugin/kse_zip.cpp

cd zip_plugin && make
minks install kse_zip

#include "zip"

Var:Number z;
Var:Boolean ok;
Var:String content;

try {
    Zip:Open("archive.zip", z);
} catch (ZipException e) {
    Konsol:Print("Error: ${e.message}");
}

Zip:AddText(z, "hello.txt", "Hello from minks!", ok);
Zip:AddFile(z, "data/config.json", "config.json", ok);
Zip:Close(z);

Zip:Open("archive.zip", z);
Zip:Read(z, "hello.txt", content);
Konsol:Print(content);
Zip:Close(z);

net — TCP networking

Requires: nothing — uses OS sockets (Winsock2 on Windows, BSD sockets on macOS/Linux)

Build:

cd net_plugin
make          # produces kse_net.dll / kse_net.so

#include "net"

Var:Number conn;
try {
    Net:Host("server", 4, "game", conn)
} catch (NetException e) {
    Konsol:Print("Host failed: ${e.message}")
    return
}
Konsol:Print("Hosting on port 2310, handle: ${conn}")

Var:String sender, msg;
Var:Boolean got;
while (true) {
    Net:Check(conn)
    Net:GetMessage(conn, sender, msg, got)
    if (got) { Konsol:Print("${sender}: ${msg}") }
}

→ To extend the engine or write a plugin, see contributing.md