CLI Libraries
Library Loading
Scriptling automatically searches for libraries in the same directory as the running script: matching Python’s behaviour. For interactive mode or stdin, the current working directory is used.
# Libraries in ./myproject/ are found automatically
scriptling ./myproject/script.py
# Interactive mode: libraries in cwd are found automatically
scriptling --interactiveUse --libpath (repeatable, alias -L) to add extra search directories. The script directory (or cwd) is always searched first:
# Search script dir first, then /shared/libs
scriptling --libpath /shared/libs script.py
# Multiple extra directories
scriptling --libpath /shared/libs --libpath /company/libs script.py
# Via environment variable
SCRIPTLING_LIBPATH=/shared/libs scriptling script.pyLibraries follow Python-style folder organisation:
myproject/
script.py
utils.py # import utils
knot/
groups.py # import knot.groups
roles.py # import knot.roles# In script.py: no --libpath needed, same directory is searched automatically
import utils # Loads from myproject/utils.py
import knot.groups # Loads from myproject/knot/groups.pyFor nested imports like knot.groups, the loader checks:
dir/knot/groups.py(folder structure: preferred)dir/knot.groups.py(flat file: legacy fallback)
Disabling and Listing Libraries
List Available Libraries
Use --list-libs to print the CLI’s built-in library inventory and exit:
scriptling --list-libsThe list covers the standard libraries (including msgpack) and the top-level extension libraries, but it is not exhaustive: some libraries the CLI registers are not printed. They include the scriptling.runtime sub-libraries (scriptling.runtime.http, .kv, .sync, .sandbox, .jsonrpc, .mcp, .plugin), tempfile, shutil, zipfile, tarfile, scriptling.find and scriptling.ai.memory. Each of these can still be disabled by name.
When combined with --disable-lib, named libraries are excluded from the reported inventory:
scriptling --disable-lib subprocess --list-libsDisable Specific Libraries
Use --disable-lib (repeatable) to prevent specific built-in libraries from loading:
# Disable a single library
scriptling --disable-lib subprocess script.py
# Disable multiple libraries, and also stop scripts loading executable plugins
scriptling --disable-lib subprocess --disable-lib os script.py
# Via environment variable
SCRIPTLING_DISABLE_LIB=subprocess scriptling script.pyIf a script attempts to import a disabled library, it raises ImportError, which can be caught with try / except.
The runtime sub-libraries can be disabled one at a time, leaving the rest of the runtime family in place. A disabled sub-library is also absent as an attribute of the parent, so hasattr(scriptling.runtime, "kv") is False:
# Keep background tasks and the HTTP server, but no key-value store
scriptling --disable-lib scriptling.runtime.kv script.py
# Remove scriptling.runtime and its http, kv, sync, sandbox, jsonrpc and mcp sub-libraries
scriptling --disable-lib scriptling.runtime script.pyscriptling.runtime.plugin is registered separately and is disabled only by its own name.
Script Filesystem Controls
--allowed-paths constrains filesystem operations made through participating Scriptling libraries. It is not a complete filesystem sandbox: subprocesses, plugin processes, setup scripts, TLS files, --web-root static assets, and other host-side operations are outside this library-level allowlist. Library loading is covered in one respect: the directories you name with --libpath (and the script’s own directory) are trusted, but a library reached through a symlink in one of them is only loaded if the resolved file lies inside a library directory or an allowed path, so a link planted in a library directory cannot pull in a file from elsewhere. With no --allowed-paths the loader follows symlinks as it always has.
| Mode | Flag | Participating library access |
|---|---|---|
| Unrestricted | (default) | Any path |
| Allowlisted | --allowed-paths /path1,/path2 |
Only specified paths |
| Deny library I/O | --allowed-paths - |
No paths |
Unrestricted Mode (default)
The CLI registers its broad library set without filesystem restrictions:
scriptling script.pyAllowlisted Mode
Participating library filesystem operations are restricted to specified paths:
# Restrict to specific directories
scriptling --allowed-paths "/tmp/data,./uploads" script.py
# Relative paths resolve from the working directory, not the script's directory
scriptling --allowed-paths "./data,../shared" script.py
# Via environment variable
SCRIPTLING_ALLOWED_PATHS="/var/www,./public" scriptling script.pyPaths are checked the way the kernel opens them: symlinks are resolved, dangling ones and ones that climb out with .. included, so a link inside an allowed directory cannot reach a file outside it. os.symlink() also refuses a target outside the allowed paths, resolving a relative target from the link’s directory.
Deny Participating Library File Access
Deny filesystem access through the libraries wired to the allowlist:
scriptling --allowed-paths - script.pyThis denies operations such as os.read_file, os.write_file, pathlib, glob, and sandbox.exec_file, along with scriptling.wait_for file(), dir() and file_content(), messaging send_file(), scriptling.container bind mounts, runtime.http.static, runtime.kv.open, scriptling.provision.fetch and scriptling.provision.file; it does not prevent an enabled subprocess, scriptling.provision.command or scriptling.provision.package from reading files with host commands. Disable that capability explicitly with --disable-lib subprocess in every mode, which removes all three.
When a script tries to access a path outside the allowed directories:
import os
# Stops the script if /etc/passwd is not in the allowed paths
content = os.read_file("/etc/passwd")The denial is a PermissionError that no try/except or with block can catch, so the run stops (after any finally blocks) with:
Error: access denied: path '/etc/passwd' is outside allowed directoriesCommon libraries (not an exhaustive inventory):
- Standard libraries:
json,msgpack,math,random,re,time,base64,hashlib,hmac,urllib datetime- Date and time operationsyaml,toml- YAML and TOML parsinghtml.parser- HTML parsingrequests- HTTP clientos- Environment variables and file operations (path-restricted)pathlib,glob- File system access (path-restricted)secrets- Cryptographic random number generationscriptling.runtime- Runtime utilities including sandbox and background taskssubprocess- Process executionscriptling.wait_for- Process monitoring- AI, agent, and MCP libraries