knot.vars
The knot.vars library provides template variable management functions.
Execution Environment
| Environment | Behaviour |
|---|---|
Embedded (MCP tool execution, event sinks, plugin handlers, remote/space scripts, knot run-script) |
Available; authenticated automatically via the Go-provided knot.apiclient transport. |
AI scripts (run_script) |
Available, imported as variables (the short name vars would hide the builtin). |
| Health check scripts | Only when the space’s environment sets KNOT_API_PORT or KNOT_URL/KNOT_TOKEN: there is no built-in transport, so the Python knot.apiclient configures itself from the agent (as the space owner) or those variables, and calls raise otherwise. See Environment Compatibility. |
| External (standalone scripts) | Python implementation; configure knot.apiclient first (or set the KNOT_* environment variables). |
Functions
| Function | Description |
|---|---|
list() |
List all variables |
get(var_id) |
Get variable by ID or name |
create(name, value, zones=None, local=False, protected=False, restricted=False) |
Create a new variable |
set_value(var_id, value=None) |
Set variable value (None leaves it unchanged); returns True |
update(var_id, value=None, zones=None, local=None, protected=None, restricted=None) |
Update variable properties; None keeps the current value — omitting value keeps the stored value, including a protected variable’s hidden one. Returns True |
delete(var_id) |
Delete a variable; returns True |
The flags:
local- The variable is only available on the knot server where it was createdprotected- The value is stored encrypted and never returned when the variable is readrestricted- The variable is shared only between servers within a cluster, never with a leaf nodezones- Zones where the variable can be used; a!prefix excludes a zone
Usage
import knot.vars as vars
# List variables
variables = vars.list()
for v in variables:
print(f"{v['name']}: local={v['local']}, protected={v['protected']}")
# Create a variable
var_id = vars.create("API_KEY", "secret-value", protected=True)
# Get a variable (a protected variable's value reads back as "")
api_key = vars.get("API_KEY")
print(api_key['protected'], api_key['value'])
# Set a variable value
vars.set_value("API_KEY", "new-secret-value")
# Update with more options
vars.update("API_KEY", value="new-value", zones=["zone1", "zone2"])Variable Properties
list() returns:
id- Variable IDname- Variable namelocal- Whether variable is localprotected- Whether value is protected (not returned in get)restricted- Whether variable is restrictedis_managed- Whether variable is managed by the system
get() also includes:
value- Variable value (empty string if protected)zones- List of zones where variable is available
Protected Variables
Protected variables have their values hidden when retrieved via the API: get() always returns value as an empty string for a protected variable, whatever the caller’s permissions (admins included). The value is only used when templates are rendered. To keep a protected value when changing other properties, call update() without value. The REST API behaves the same way: PUT /api/templatevars/{id} keeps the stored value when value is omitted or null, while "" clears it.