CLI Reference

Scriptling includes a command-line interface for running scripts, interactive mode, and HTTP/MCP server.

Installation

Homebrew (macOS & Linux)

brew install paularlott/tap/scriptling

GitHub Releases

Download pre-built binaries from GitHub Releases:

Platform	Architectures
Linux	AMD64, ARM64
macOS	AMD64, ARM64
Windows	AMD64, ARM64

Go Install

If you have Go installed:

go install github.com/paularlott/scriptling/scriptling-cli@latest

Build from Source

    
    
  
# Clone the repository
git clone https://github.com/paularlott/scriptling.git
cd scriptling

# Build for current platform
make build
# or use Task: task build

# Build for all platforms
make build-all
# or use Task: task build-all

Basic Usage

Run a Script

scriptling script.py

Pipe Script

    
echo 'print("Hello")' | scriptling
cat script.py | scriptling

Interactive Mode

scriptling --interactive

Command Line Options

    
    
  
Usage: scriptling [options] [script.py]

Options:
  -i, --interactive         Start interactive mode
  -S, --server ADDR         Start HTTP server on address (host:port)
  --mcp-tools DIR           Enable MCP tools from directory
  --script-mode MODE        Script mode: safe or full (default: full)
  --bearer-token TOKEN      Bearer token for authentication
  --tls-cert FILE           TLS certificate file
  --tls-key FILE            TLS key file
  --tls-generate            Generate self-signed TLS certificate
  --libdir DIR              Custom library directory
  --log-level LEVEL         Log level: trace|debug|info|warn|error
  --log-format FORMAT       Log format: console|json
  -h, --help                Show help

HTTP Server

Basic Server

scriptling --server :8000 script.py

With TLS

scriptling --server :8443 --tls-generate script.py

With Authentication

scriptling --server :8000 --bearer-token secret123 script.py

With MCP Tools

scriptling --server :8000 --mcp-tools ./tools script.py

MCP Server

Scriptling can run as an MCP (Model Context Protocol) server for LLM integration:

scriptling --server :8000 --mcp-tools ./tools script.py

MCP tools are Scriptling scripts that define tool metadata and handlers.

Safe Mode

Run scripts in a restricted sandbox:

scriptling --script-mode safe script.py

Safe mode disables:

File system access
Network access
Subprocess execution

Environment Variables

Scriptling automatically loads environment from a .env file in the current directory if it exists. You can also set environment variables:

    
export API_KEY="your-api-key"
scriptling script.py

Access in scripts:

    
import os
api_key = os.getenv("API_KEY")

Custom Libraries

Load libraries from a custom directory:

scriptling --libdir ./mylibs script.py

Examples

REST API Client

scriptling api_client.py

    
    
  
# api_client.py
import json
import requests

response = requests.get("https://api.example.com/users")
if response.status_code == 200:
    users = response.json()
    for user in users:
        print(user["name"])

HTTP Server with Routes

scriptling --server :8000 server.py

    
    
  
# server.py
import scriptling.runtime.http as http

@http.route("/api/hello", methods=["GET"])
def hello(request):
    return http.json({"message": "Hello, World!"})

@http.route("/api/echo", methods=["POST"])
def echo(request):
    return http.json(request["body"])

MCP Tool

scriptling --server :8000 --mcp-tools ./tools server.py

    
    
  
# ./tools/calculator.py
def add(a, b):
    """Add two numbers together."""
    return a + b

# Tool metadata
__mcp_tool__ = {
    "name": "calculator_add",
    "description": "Add two numbers",
    "parameters": {
        "a": {"type": "number", "description": "First number"},
        "b": {"type": "number", "description": "Second number"}
    }
}

Navigation