You are an AI coding agent working on a .kilnx project. Kilnx is a declarative backend language that was not in your training data. Do not infer syntax. Do not invent keywords. The catalog at the bottom of this file is the only source of truth, regenerated from the compiler on every release.
- Before writing any
.kilnx code, run kilnx docs --list to see what exists.
- Before using a keyword or attribute, run
kilnx docs <name> for its syntax, scope, and constraints.
- After every edit, run
kilnx check <file> and fix every error before continuing. The analyzer catches type errors, undeclared fields, illegal scopes, security misuse, and migration data-loss risks.
- If
kilnx docs <name> returns "no entity named", the construct does not exist. Do not invent it. Pick a real one from --list or rephrase the design.
- Reference docs at
docs/devs/reference/ are authoritative. Source-driven, regenerated on every merge.
Read these in this order before touching code. Time investment: roughly 20 minutes total.
README.md: one-page overview with a complete working app.docs/devs/concepts/mental-model.md: how to think in Kilnx (declarative, indent-significant, AST-driven runtime).docs/devs/concepts/models-and-data.md: tables, fields, migrations.docs/devs/concepts/pages-actions-fragments.md: the HTTP layer.docs/devs/concepts/auth-and-permissions.md: identity, sessions, authorization.docs/devs/concepts/jobs-and-schedules.md: background work and cron.docs/devs/tutorials/01-todo-app.md: hands-on Todo CRUD.docs/devs/tutorials/02-auth-and-sessions.md: add login and roles.docs/devs/tutorials/03-background-jobs.md: add a schedule and a job.
The reference under docs/devs/reference/ is a lookup, not a read-through. Jump to it when you need details on one keyword or attribute.
plan -> read concept -> kilnx docs <name> -> edit .kilnx -> kilnx check -> kilnx run
Repeat the loop in small steps. The compiler is your fastest feedback channel.
- Indentation is significant. Two spaces per level. Mixed tabs and spaces are rejected.
- No
main, no router, no handler signature. Routes exist because you wrote page /path or action /path. Adding a function in Go is the wrong instinct.
- Templates are not Go
html/template. Curly-brace expressions like {field} are field lookups; {{if cond}}...{{end}} are control flow. See the html attribute docs.
- Secrets via env vars only. Templates read environment variables as
:env.NAME. Do not paste credentials into .kilnx files.
- Migrations are additive.
kilnx migrate never drops or alters columns destructively. Drift is reported as warnings; the author resolves manually.
fetch is the only escape hatch. When a primitive does not exist, model the call as an outbound HTTP request via fetch, not as a custom Go module.
kilnx docs --list: every keyword and attribute with one-line summaries.kilnx docs --search <query>: full-text search across names and descriptions.kilnx docs <name>: complete entry for one construct (syntax, scope, defaults, since).kilnx check <file>: full analyzer pass, exit non-zero on diagnostics.kilnx run <file>: dev server with migrations applied on startup.kilnx build <file> -o <bin>: standalone binary, single-file deploy.kilnx version: print version and build date.
The remainder of this document is auto-generated from the compiler's spec registry.
| Keyword |
Summary |
Since |
action |
Declare a state-changing endpoint (POST/PUT/DELETE). |
0.1.0 |
agent |
Agentic loop running as a claude CLI subprocess. |
0.1.3 |
api |
Declare a JSON endpoint. |
0.1.0 |
auth |
Configure email/password authentication. |
0.1.0 |
config |
Application-wide configuration. |
0.1.0 |
fragment |
Return partial HTML (no document wrapper) for htmx or includes. |
0.1.0 |
job |
Asynchronous background task triggered by enqueue. |
0.1.0 |
layout |
Define a reusable HTML wrapper for pages. |
0.1.0 |
limit |
Rate-limit requests matching a path pattern. |
0.1.0 |
llm |
Call an LLM. Choose response (single-shot / chat) or agent (subprocess loop with tools). |
0.1.3 |
log |
Configure runtime logging output. |
0.1.0 |
model |
Declare a database table with typed fields and constraints. |
0.1.0 |
page |
Define an HTTP route and its view. |
0.1.0 |
permissions |
Role-based access control rules. |
0.1.0 |
query |
Run a SQL query and bind its result. Used both top-level (named query) and inside bodies. |
0.1.0 |
response |
Single-shot / chat / streaming Messages API call. |
0.1.3 |
schedule |
Background task executed on a fixed interval or cron expression. |
0.1.0 |
socket |
WebSocket endpoint for bidirectional real-time messaging. |
0.1.0 |
stream |
Server-Sent Events (SSE) endpoint that pushes data on an interval. |
0.1.0 |
test |
End-to-end browser-style test scenario. |
0.1.0 |
translations |
i18n translation strings keyed by language and key. |
0.1.0 |
webhook |
Receive external events (Stripe, GitHub, etc.) at a path. |
0.1.0 |
Recognized inside model blocks: bigint, bool, date, decimal, email, file, float, image, int, json, option, password, phone, reference, richtext, tags, text, timestamp, url, uuid.
Recognized as field modifiers: auto, auto_update, default, max, min, required, unique.
Each section lists the attributes valid inside that parent keyword. An attribute appearing in multiple scopes is listed in each.
| Attribute |
Summary |
Since |
broadcast |
Push a message to all clients in a websocket room. |
0.1.0 |
enqueue |
Enqueue an asynchronous job with named parameters. |
0.1.0 |
fetch |
Make an HTTP request to an external API. |
0.1.0 |
generate |
Generate a PDF from a template and a data query. |
0.1.0 |
html |
Render an inline HTML template block. |
0.1.0 |
method |
Restrict the HTTP method for the parent route. |
0.1.0 |
on |
Conditional or event handler. |
0.1.0 |
redirect |
Redirect to another URL. |
0.1.0 |
requires |
Require authentication or a specific role/permission. |
0.1.0 |
respond |
Return a partial HTML response, a status code, or a file from disk. |
0.1.0 |
send |
Send an email. |
0.1.0 |
validate |
Validate input against a model or per-field rules. |
0.1.0 |
| Attribute |
Summary |
Since |
cwd |
Working directory for the agent subprocess. |
0.1.3 |
max-budget-usd |
Hard cost cap in USD per agent invocation. |
0.1.3 |
max-turns |
Maximum agentic turns before forced stop. |
0.1.3 |
mcp |
Comma-separated names of MCP servers declared in config mcp <name>. |
0.1.3 |
on-progress |
Handler block run on each progress event while an agent runs. |
0.1.4 |
permission-mode |
Tool-use permission policy: plan, acceptEdits, or bypassPermissions. |
0.1.3 |
pool |
Reserved: number of warm claude subprocesses to keep alive (not yet implemented). |
0.1.3 |
pool-idle-ttl |
Reserved: idle TTL before pooled subprocesses are killed (not yet implemented). |
0.1.3 |
resume |
Resume an existing claude session by UUID (supports :param). |
0.1.3 |
show-tools |
Stream tool_use/tool_result frames in addition to assistant text. |
0.1.3 |
tools |
Comma-separated list of tools the agent may use. |
0.1.3 |
| Attribute |
Summary |
Since |
broadcast |
Push a message to all clients in a websocket room. |
0.1.0 |
enqueue |
Enqueue an asynchronous job with named parameters. |
0.1.0 |
fetch |
Make an HTTP request to an external API. |
0.1.0 |
generate |
Generate a PDF from a template and a data query. |
0.1.0 |
html |
Render an inline HTML template block. |
0.1.0 |
method |
Restrict the HTTP method for the parent route. |
0.1.0 |
on |
Conditional or event handler. |
0.1.0 |
requires |
Require authentication or a specific role/permission. |
0.1.0 |
respond |
Return a partial HTML response, a status code, or a file from disk. |
0.1.0 |
send |
Send an email. |
0.1.0 |
validate |
Validate input against a model or per-field rules. |
0.1.0 |
| Attribute |
Summary |
Since |
after_login |
Default redirect target after successful login. |
0.1.0 |
forgot |
Path for the forgot-password flow. |
0.1.0 |
identity |
Field used as the unique login identifier. |
0.1.0 |
login |
Path served as the login form. |
0.1.0 |
logout |
Path that terminates the session. |
0.1.0 |
password |
Field storing the bcrypt password hash. |
0.1.0 |
register |
Path served as the registration form. |
0.1.0 |
reset |
Path for the password-reset confirmation page. |
0.1.0 |
superuser |
Identity that bypasses role checks. |
0.1.0 |
table |
Name of the model storing user accounts. |
0.1.0 |
| Attribute |
Summary |
Since |
cors |
Comma-separated list of allowed CORS origins. |
0.1.0 |
database |
Database connection URL. |
0.1.0 |
default_language |
Fallback language code for translations. |
0.1.0 |
detect_language |
How to detect the user's language at request time. |
0.1.0 |
name |
Human-readable application name. |
0.1.0 |
port |
TCP port to listen on. |
0.1.0 |
secret |
Secret key for session cookies and CSRF tokens. |
0.1.0 |
serve-roots |
Directories from which respond file may serve. |
0.1.5 |
static |
Filesystem path served as static assets. |
0.1.0 |
upload-extensions |
Extend or replace the upload extension whitelist. |
0.1.5 |
uploads |
Filesystem path and max size (MB) for user uploads. Form bindings serialise as JSON array of /_uploads/... paths (use json_each). |
0.1.0 |
workspace-root |
Filesystem root for agent cwd resolution and tmp dirs. |
0.1.3 |
| Attribute |
Summary |
Since |
broadcast |
Push a message to all clients in a websocket room. |
0.1.0 |
enqueue |
Enqueue an asynchronous job with named parameters. |
0.1.0 |
fetch |
Make an HTTP request to an external API. |
0.1.0 |
generate |
Generate a PDF from a template and a data query. |
0.1.0 |
html |
Render an inline HTML template block. |
0.1.0 |
on |
Conditional or event handler. |
0.1.0 |
respond |
Return a partial HTML response, a status code, or a file from disk. |
0.1.0 |
send |
Send an email. |
0.1.0 |
validate |
Validate input against a model or per-field rules. |
0.1.0 |
| Attribute |
Summary |
Since |
broadcast |
Push a message to all clients in a websocket room. |
0.1.0 |
enqueue |
Enqueue an asynchronous job with named parameters. |
0.1.0 |
fetch |
Make an HTTP request to an external API. |
0.1.0 |
generate |
Generate a PDF from a template and a data query. |
0.1.0 |
html |
Render an inline HTML template block. |
0.1.0 |
on |
Conditional or event handler. |
0.1.0 |
respond |
Return a partial HTML response, a status code, or a file from disk. |
0.1.0 |
retry |
Maximum retry attempts before the job is marked failed. |
0.1.0 |
send |
Send an email. |
0.1.0 |
validate |
Validate input against a model or per-field rules. |
0.1.0 |
| Attribute |
Summary |
Since |
html |
Render an inline HTML template block. |
0.1.0 |
| Attribute |
Summary |
Since |
delay |
Seconds to delay over-budget requests before responding. |
0.1.0 |
message |
Custom error message returned when the limit is exceeded. |
0.1.0 |
requests |
Rate-limit budget (in limit) or request log strategy (in log). |
0.1.0 |
| Attribute |
Summary |
Since |
max-tokens |
Maximum tokens to generate in the response. |
0.1.3 |
system |
System prompt for this llm call. |
0.1.3 |
temperature |
Sampling temperature (0.0-1.0). |
0.1.3 |
| Attribute |
Summary |
Since |
errors |
Error reporting strategy. Append stacktrace to include stacks. |
0.1.0 |
level |
Minimum severity to log (debug, info, warn, error). |
0.1.0 |
requests |
Rate-limit budget (in limit) or request log strategy (in log). |
0.1.0 |
slow_query |
Threshold above which a SQL query is logged as slow. |
0.1.0 |
| Attribute |
Summary |
Since |
auto |
Auto-populate the field on insert. |
0.1.0 |
auto_update |
Auto-populate on insert and update. |
0.1.0 |
custom |
Load custom field definitions from an external manifest. |
0.1.0 |
default |
Default value when no value is supplied. |
0.1.0 |
dynamic_fields |
Allow fields to be defined at runtime via the database. |
0.1.0 |
index |
Non-unique composite index for query performance. |
0.1.0 |
max |
Maximum value (numeric) or length (string). |
0.1.0 |
min |
Minimum value (numeric) or length (string). |
0.1.0 |
required |
Field must have a non-null value. |
0.1.0 |
tenant |
Scope all rows of this model to a tenant. |
0.1.0 |
unique |
Field value must be unique across all rows. |
0.1.0 |
| Attribute |
Summary |
Since |
broadcast |
Push a message to all clients in a websocket room. |
0.1.0 |
enqueue |
Enqueue an asynchronous job with named parameters. |
0.1.0 |
fetch |
Make an HTTP request to an external API. |
0.1.0 |
generate |
Generate a PDF from a template and a data query. |
0.1.0 |
html |
Render an inline HTML template block. |
0.1.0 |
method |
Restrict the HTTP method for the parent route. |
0.1.0 |
on |
Conditional or event handler. |
0.1.0 |
redirect |
Redirect to another URL. |
0.1.0 |
requires |
Require authentication or a specific role/permission. |
0.1.0 |
respond |
Return a partial HTML response, a status code, or a file from disk. |
0.1.0 |
send |
Send an email. |
0.1.0 |
title |
Set the HTML document title. |
0.1.0 |
validate |
Validate input against a model or per-field rules. |
0.1.0 |
| Attribute |
Summary |
Since |
history |
SQL query whose rows become the message history. |
0.1.3 |
stream-swap |
Hyperstream swap style (append, inner, outer, ...). |
0.1.3 |
| Attribute |
Summary |
Since |
broadcast |
Push a message to all clients in a websocket room. |
0.1.0 |
enqueue |
Enqueue an asynchronous job with named parameters. |
0.1.0 |
every |
Cadence at which the parent task runs. |
0.1.0 |
fetch |
Make an HTTP request to an external API. |
0.1.0 |
generate |
Generate a PDF from a template and a data query. |
0.1.0 |
html |
Render an inline HTML template block. |
0.1.0 |
on |
Conditional or event handler. |
0.1.0 |
respond |
Return a partial HTML response, a status code, or a file from disk. |
0.1.0 |
send |
Send an email. |
0.1.0 |
validate |
Validate input against a model or per-field rules. |
0.1.0 |
| Attribute |
Summary |
Since |
broadcast |
Push a message to all clients in a websocket room. |
0.1.0 |
on |
Conditional or event handler. |
0.1.0 |
| Attribute |
Summary |
Since |
event |
SSE event name to emit on each tick. |
0.1.0 |
every |
Cadence at which the parent task runs. |
0.1.0 |
| Attribute |
Summary |
Since |
as |
Run subsequent steps as a given role or user. |
0.1.0 |
expect |
Assert a condition on the current state. |
0.1.0 |
fill |
Fill a form field with a value. |
0.1.0 |
submit |
Submit the current form. |
0.1.0 |
visit |
Navigate to a URL. |
0.1.0 |
| Attribute |
Summary |
Since |
broadcast |
Push a message to all clients in a websocket room. |
0.1.0 |
enqueue |
Enqueue an asynchronous job with named parameters. |
0.1.0 |
fetch |
Make an HTTP request to an external API. |
0.1.0 |
generate |
Generate a PDF from a template and a data query. |
0.1.0 |
html |
Render an inline HTML template block. |
0.1.0 |
on |
Conditional or event handler. |
0.1.0 |
respond |
Return a partial HTML response, a status code, or a file from disk. |
0.1.0 |
send |
Send an email. |
0.1.0 |
validate |
Validate input against a model or per-field rules. |
0.1.0 |
Most recent first. Use this to understand the surface area added in each release.
Attributes: serve-roots, upload-extensions
Attributes: on-progress
Keywords: agent, llm, response
Attributes: cwd, history, max-budget-usd, max-tokens, max-turns, mcp, permission-mode, pool, pool-idle-ttl, resume, show-tools, stream-swap, system, temperature, tools, workspace-root
Keywords: action, api, auth, config, fragment, job, layout, limit, log, model, page, permissions, query, schedule, socket, stream, test, translations, webhook
Attributes: after_login, as, auto, auto_update, broadcast, cors, custom, database, default, default_language, delay, detect_language, dynamic_fields, enqueue, errors, event, every, expect, fetch, fill, forgot, generate, html, identity, index, level, login, logout, max, message, method, min, name, on, password, port, redirect, register, requests, required, requires, reset, respond, retry, secret, send, slow_query, static, submit, superuser, table, tenant, title, unique, uploads, validate, visit