Quickstart

A hands-on loop you can finish in a few minutes. Everything here runs locally — no services, no deployment, no network. It is the fastest way to see how the model-driven part actually behaves before you stand anything up.

Every command and every output below was run against the CLI, not written from memory.

Before you start

You need the CLI installed — see Install.

kis version

Make a scratch directory to work in:

mkdir todo-app && cd todo-app

1. Scaffold an entity

kis spec new entity todo

✓ Created entities/todo.yaml

It writes a skeleton with the conventions already in place:

entities:
- name: todo
  fields:
  - name: id
    type: ulid
    defaultvalue: ulid()
    validations:
    - type: required
    - type: unique
    - type: final
  # Add your fields here

Note what you get for free: a ULID primary key, generated by default, marked final so it cannot be changed after creation. That is the sort of decision you would otherwise make — and occasionally get wrong — on every new table.

2. Validate it

kis spec validate entities/

✓ entities/todo.yaml

1 files validated, 0 with errors

3. Lint it

kis spec lint entities/

⚠ entities/todo.yaml
  missing description - add a description to document this resource (description-required)

1 files linted, 0 errors, 1 warnings, 0 info

This is the distinction worth internalising. The file is legal — validation passed. It is not sensible — an undescribed entity is one nobody will understand in six months. Validation asks whether the schema is satisfied; linting asks whether you have written something good.

A file can pass one and fail the other, which is why both exist and why CI should run both.

4. Fill it in

Add a description and some real fields:

entities:
- name: todo
  description: A task with a title, completion state and due date.
  fields:
  - name: id
    type: ulid
    defaultvalue: ulid()
    validations:
    - type: required
    - type: unique
    - type: final
  - name: title
    type: string
    validations:
    - type: required
  - name: done
    type: boolean
    defaultvalue: false
  - name: due
    type: date

Both checks now pass:

kis spec validate entities/ && kis spec lint entities/

✓ entities/todo.yaml

1 files validated, 0 with errors

1 files linted, 0 errors, 0 warnings, 0 info

That is the authoring loop. Scaffold, validate, lint, repeat — and with the IDE language server installed you get the same diagnostics as you type, rather than after saving.

5. Generate a JSON Schema

kis spec generate jsonschema --kind Entity --output ./schemas

✓ Generated schemas/Entity-v1.schema.json

1 schema files generated in ./schemas

Useful when something outside the platform needs to understand your definitions — an editor that is not the supplied language server, a validation step in a pipeline you do not control, a form builder driven by a schema.

6. Run a script

Custom logic runs in the Script sandbox, and you can drive it from the CLI without deploying anything. Scripts expose a main() function:

greet.js

function main(name, times) {
  return { greeting: "hello " + name, repeated: times };
}

Positional arguments after the filename become the function’s arguments:

kis script run greet.js anand 7 --debug

File: greet.js
Language: javascript
Function: main
Timeout: 5000ms

Compiled in 167.392µs

Execution time: 227.622µs
Result: {"greeting":"hello anand","repeated":7}

Tip

Without --debug you get only the timing line. Use it while developing — it prints the compiled/execution split and, more importantly, the actual return value.

Language is chosen by file extension — .js, .lua, .go, .star, .cel, .expr, .wasm — so the same command runs any of the seven supported runtimes. Restrict what a script may reach with --namespaces; see the Namespace Reference.

What you just did

Step	What it showed
Scaffold	Conventions applied by default, not by discipline
Validate	Schema conformance
Lint	Quality beyond conformance — a legal file that is still wrong
Generate	Schemas usable outside the platform
Script	Custom logic, sandboxed, runnable without a deployment

No services were involved. Everything above is the local half of the loop.

Next

To take the entity further — a live REST and GraphQL API over it, authentication, deployment — you need a running platform. Continue with Getting Started.

• Spec — the schema system behind all of this
• Data API — what your entity becomes once deployed
• Script — the sandbox, its languages and namespaces