Command Line Options

Command Line Options

The network policy flag has its own page with the policy file reference.

Loading Plugins

Plugins come from two places, and both can be repeated:

• --plugin-dir scans a directory and loads every executable in it.
• --plugin loads one plugin: an executable path, or the http:///https:// URL of a plugin server, where the plugin protocol speaks JSON-RPC over POST instead of stdio (the same plugin either way; a PHP example shows how little it takes to serve one).

A --plugin value is used literally, so a path containing spaces needs nothing beyond ordinary shell quoting:

scriptling --plugin "/Applications/Knot.app/Contents/MacOS/knot" script.py

Arguments for a plugin come from --plugin-arg, applied in the order given:

scriptling --plugin /usr/local/bin/knot \
           --plugin-arg scriptling-server \
           --plugin-arg=--alias=testing \
           script.py

Values that begin with - need the --plugin-arg=value form, otherwise the parser reads them as another flag.

With one --plugin, every --plugin-arg belongs to it. With several, qualify each argument as <plugin>=<arg>, where <plugin> is the executable’s base name or its full path:

scriptling --plugin /usr/local/bin/knot --plugin /usr/local/bin/vault-helper \
           --plugin-arg knot=scriptling-server \
           --plugin-arg vault-helper=--role=reader \
           script.py

An unqualified argument with more than one plugin is an error rather than a guess. A value whose text before = matches no --plugin is treated as a plain argument, so ordinary flags like --alias=testing pass through unqualified.

Environment variables reach an executable plugin with --plugin-env, binding exactly like --plugin-arg with KEY=VALUE payloads:

scriptling --plugin /usr/local/bin/knot            --plugin-env KNOT_DB=/var/lib/knot            --plugin-env LOG=debug            script.py

The entries layer on top of the inherited environment, so a variable already set is overridden and everything else passes through. They apply to executable plugins, which the host spawns; a plugin server owns its own environment, since the host connects to it.

An HTTP plugin that needs authentication takes headers with --plugin-header, binding like the other plugin flags (bare with one plugin, <plugin>= qualified with several); the value keeps its own equals sign, so bearer tokens pass through whole. The token does not belong on the command line, where it is visible in process listings: prefer the environment variable or the config file, both of which accept the same values:

export SCRIPTLING_PLUGIN_HEADER="Authorization=Bearer $PLUGIN_TOKEN"
scriptling --plugin https://plugins.internal:8443 script.py

# scriptling.toml
[plugins]
paths = ["https://plugins.internal:8443"]
headers = ["Authorization=Bearer eyJ..."]

The flag form exists for quick tests:

scriptling --plugin https://plugins.internal:8443 \
           --plugin-header "Authorization=Bearer $PLUGIN_TOKEN" \
           script.py

Username and password can also ride the URL itself, as HTTP Basic auth:

scriptling --plugin https://user:pass@plugins.internal:8443 script.py

The credentials travel as the Authorization header and never appear in the request line or Host header; an explicit --plugin-header Authorization=... wins over URL credentials.

For https plugin URLs whose certificate is self-signed (development, internal networks), --plugin-insecure names the URLs to load without certificate verification, so one self-signed endpoint never weakens the others:

scriptling --plugin https://plugins.internal:8443 \
           --plugin-insecure https://plugins.internal:8443 \
           script.py

Explicit --plugin entries load before --plugin-dir scans. Plugin identity is the resolved executable path, so the same binary found in a scanned directory is skipped — the explicit entry and its arguments win. Plugins register under the library name they declare in their handshake, however they were loaded.

Plugins only start when the invocation can use them. --lint, --list-libs, and the pack, unpack and cache subcommands never spawn plugin processes.

Configuration File

Scriptling looks for scriptling.toml in the following locations (in order):

1. Current directory (.)
2. $HOME/
3. $HOME/.config/scriptling/

Use --config (or -C) to specify a different path explicitly.

All flags that have a config path can be set in the file. The TOML structure mirrors the config paths shown in the flags table above:

# scriptling.toml

# Root-level options must appear before the first [table].
libpath = ["/shared/libs", "/company/libs"]
packages = ["./mypackage.zip", "https://example.com/lib.zip"]
insecure = false

[log]
level = "debug"
format = "console" # console, json, or null

[plugins]
dirs = ["/usr/local/lib/scriptling/plugins"]
paths = ["/usr/local/bin/knot"]
args = ["scriptling-server", "--alias=testing"]
env = ["KNOT_DB=/var/lib/knot"]
headers = ["Authorization=Bearer token"]
insecure = ["https://plugins.internal:8443"]

[server]
address = ":8000"
web_root = "./public"
bearer_token = "secret"

[mcp]
tools = "./tools"
exec_script = false
resources = "./resources"
prompts = "./prompts"

[security]
allowed_paths = "/tmp/data,./uploads"
network_policy = "./network-policy.toml"
disable_libs = ["subprocess", "os"]

[kv]
storage = "/var/lib/scriptling/kv"

[container]
docker_host = "unix:///Users/paul/.lima/docker/sock/docker.sock"
podman_host = "unix:///run/user/1000/podman/podman.sock"

[secret]
config = "/etc/scriptling/secrets.toml"

[tls]
cert = "/etc/scriptling/tls.crt"
key = "/etc/scriptling/tls.key"
generate = false

[cache]
dir = "/var/cache/scriptling"

[lint]
format = "text"

Priority order (highest to lowest): command-line flag > environment variable > config file > default.

Container Endpoints

When using the scriptling.container library, Docker and Podman endpoints can be configured via flags or environment variables. Both accept any of the following forms:

Podman does not expose a plain TCP endpoint: use a Unix socket path or URI. For remote Podman, use podman system service with SSH tunnelling and point the socket at the local tunnel endpoint.

scriptling --docker-host unix:///Users/paul/.lima/docker/sock/docker.sock script.py
scriptling --docker-host tcp://192.168.1.10:2375 script.py
scriptling --podman-host unix:///run/user/1000/podman/podman.sock script.py