Core Concepts

The command reference assumes you understand a few ideas that cut across many commands. This page explains them once, in plain language, so the reference pages can stay focused on doing. If a command page says “see Core Concepts,” this is where it points.

The plugin architecture

What it is. kis is a launcher that bundles several independently-built plugin binaries (kis-ai, kis-forge, kis-rules, kis-dev, and the core). A command like kis ai chat is dispatched to the kis-ai plugin; kis rules goes to kis-rules; and so on.

Why it matters. You never invoke the plugins directly, but the seams show in two places:

• Logging flags differ by group (covered in Getting Started, --log-level vs -l, --loglevel).
• kis version reports each plugin’s version separately, which is how you tell whether, say, the AI plugin is out of date relative to the core.

kis version

When you care. Almost never day-to-day, but when a global flag is rejected or a feature seems missing, remembering “this is a separate plugin” tells you to check that command’s own --help rather than assuming the whole CLI changed.

Providers & authentication

What it is. Every AI command talks to a provider, a backend that runs models. kis speaks one consistent interface to many of them, so switching from a local model to a hosted one is usually just a -p change.

Supported providers (use with -p):

ollama  openai  anthropic  gemini  groq  xai  vllm  llamacpp
deepgram  stability  cohere  gateway  tei  whispercpp

The default is ollama, a local model runner. That means you can try AI with no API key if you have Ollama running locally:

ollama pull llama3.2:3b
kis ai chat "hello!"            # uses ollama by default, no key needed

For a hosted provider, set the matching API-key environment variable and pass -p (and usually -m for the model):

export OPENAI_API_KEY=sk-...
kis ai chat -p openai -m gpt-4o "hello!"

export ANTHROPIC_API_KEY=sk-ant-...
kis ai chat -p anthropic -m claude-sonnet-4-6 "hello!"

Tip

You rarely need -k/--api-key. If the provider’s env var is set (e.g. OPENAI_API_KEY, ANTHROPIC_API_KEY), the CLI picks it up automatically. Reach for -k only to override it for a single call.

Discover what’s available before you commit to a model:

kis ai providers            # every provider + its capabilities
kis ai models -p anthropic  # one provider's model catalog

Caution

Some providers (vllm, ollama, llamacpp) ship no static model catalog, so kis ai models -p ollama may return little or nothing. That’s expected, just pass -m with the model you’re actually running.

Note

The gateway provider routes through the platform’s AI gateway service (ai-gateway.svc, installed via kvm), a single endpoint that fronts multiple upstream providers, configured by ~/.kisai/ai-gateway.yaml and ~/.kisai/apikeys.yaml.

Variables, prompts & environments

What it is. Three layered ways to pass data into a command without hard-coding it. They show up together constantly, so it’s worth seeing how they relate.

• Variables (-v key=value) are the raw inputs. For AI commands a value can be @file (read a file) or @- (read stdin).
• Prompt files (--prompt-file x.yaml --prompt name) are reusable prompt templates with {{placeholder}} slots that variables fill.
• Environment files (-e env.yaml -n name) supply a named set of values, typically connection details that change between local/staging/production.

Recommended, keep prompts in a file, pass only the changing bits as vars:

kis ai chat --prompt-file prompts.yaml --prompt summarize -v [email protected]

Avoid

Pasting a 40-line prompt inline on every call and editing it by hand. It can’t be reviewed, diffed, or reused, and you’ll eventually paste a subtly different version. Put it in a prompt file once.

Precedence. Where a command merges several sources (notably datapipes), inline --vars win, then the env file, then a .env file, then defaults baked into the flow. Each command page states its own precedence where it differs.

Entities & datastores

What it is. The platform’s data model. You describe your data shape as an entity (a YAML definition of fields and validations), and you describe where records live as a datastore (a backing database such as PostgreSQL). The write-entity and read-entity commands move records in and out.

A minimal entity:

entities/faq.yaml

version: v1
entities:
- name: faq
  inherits:
  - kisai.id              # adds an id + timestamps to every record
  fields:
  - name: question
    type: string
    validations:
    - type: required
      message: question is required
  - name: count
    type: int

A datastore that holds it:

datastores/buddydb.yaml

version: v1
defaultdatastore: buddydb
datastores:
- name: buddydb
  prefix: buddy_
  database: { type: postgresql, version: "16" }
  tenancy: { mode: single }

Why two files? The entity defines shape (and is reusable across stores); the datastore defines where and how it’s persisted. Keeping them separate lets the same entity target different databases per environment.

Flows, pipelines & scripts

What it is. Three overlapping ways to make kis do multi-step work. They share a calling convention, so the question is mostly “which fits the job.”

Tool	Use it for	Page
script	A single unit of logic in JS/Lua/Go/Starlark/CEL/expr/WASM	Automation
flow	A multi-step task graph (call a model, run a script, branch)	Automation
datapipes	Data-movement pipelines with tenant/cluster/dotenv conveniences	Data & Entities

The key connecting fact: a script that runs inside a flow’s script: task runs identically under kis script run. Same engine, same calling convention, so you can develop and test a script standalone, then drop it into a flow unchanged.

Tenancy & contexts

What it is. Two separate notions that both scope your work:

• Tenant, a data-isolation boundary. Many commands accept --tenant (core) or -t/--tenant (entity commands) to act within one tenant’s data. Datastores declare a tenancy: { mode: single } (or otherwise) to say how records are partitioned.
• Context, a named local credential profile created by kis login -k <context>. Contexts let you keep separate logins (e.g. work vs personal) side by side on one machine.

With these concepts in hand, the command reference will make sense. Start with AI or jump to any command from the command map.