Using knot.* Libraries

The knot.* namespace provides libraries for interacting with Knot from scripts. These libraries work differently depending on where your script is running.

Execution Contexts

Built-in

Scripts running inside Knot (startup scripts, shutdown scripts, MCP tools, space scripts) have automatic access to all libraries:

import knot.space as space

# List all spaces
spaces = space.list()
for s in spaces:
    status = "running" if s['is_running'] else "stopped"
    print(f"{s['name']}: {status}")

No configuration is needed - the library uses the execution context for authentication.

Knot CLI

When running scripts locally with the Knot CLI, the knot.* libraries are fetched from the Knot server and make API calls automatically:

knot run-script myscript.py

The libraries use the API token from ~/.knot/config for authentication.

import knot.space as space

# List all spaces - automatically uses ~/.knot/config
spaces = space.list()
for s in spaces:
    status = "running" if s['is_running'] else "stopped"
    print(f"{s['name']}: {status}")

External Scriptling

For standalone scriptling scripts using the knot.zip package, explicit configuration is required:

import knot.api
import knot.space

# Configure the connection first
knot.api.configure("https://knot.example.com", "your-api-token")

# List all spaces
spaces = knot.space.list()
for s in spaces:
    status = "running" if s['is_running'] else "stopped"
    print(f"{s['name']}: {status}")

This is useful for scripts running outside of the Knot environment.

scriptling --package=https://knot.example.com/packages/knot.zip myscript.py

Available Libraries