Getting Started

This page takes you from zero to a working setup, install, verify, configure a provider, log in, then the handful of conventions every command reuses. New to kis? Start with the Introduction for the big picture and the full command map.

Tip

Read this page top to bottom, then skim Core Concepts before diving into the command reference. Everything after that is lookup-friendly, jump straight to the command you need.

Install with kvm

kis is installed and kept up to date by kvm, the kis.ai version manager. kvm downloads platform components (the CLI tools and the backend services), manages versions, and handles your license. It installs to ~/.kisai/bin/ by default (personal), or system-wide to /usr/local/bin/ with --system.

Prerequisites

You need kvm itself and a valid kis.ai license before installing components. kvm self-installs (kvm install), and access to components is gated by your license entitlement (kvm license).

# 1. Put ~/.kisai/bin on your PATH (kvm prints the right line for your shell)
eval "$(kvm env)"
# or persist it (zsh on macOS):
kvm env >> ~/.zshrc && source ~/.zshrc

# 2. Activate your license, then confirm it
kvm license activate <your-license-key>
kvm license status

# 3. Install the CLI bundle (kis + its plugins)
kvm install kis-cli

# 4. Verify
kis version

Components are grouped into bundles, install one to get a whole set:

kvm bundles            # list available bundles
kvm list               # list installed components

Bundle	What it installs
kis-cli	All kis.ai command-line tools (the kis CLI + plugins)
kis-platform	Complete platform: BaaS + AI + dev tools
baas-core / baas-full	Backend-as-a-Service services (incl. iam.svc)
ai-full	All AI services

You can also install a single component by name, e.g. kvm install iam.svc (the IAM service) or kvm install baas/iam.svc to be explicit.

Inspecting & keeping current:

kvm info <artifact>    # detailed info for a component
kvm buckets            # show available buckets from the embedded registry
kvm download <dir>     # download components to a directory (without installing)
kvm update             # update installed components
kvm self-update        # update kvm itself
kvm uninstall <name>   # remove a component

The full kvm command set: install, uninstall, update, self-update, list, bundles, buckets, download, info, env, license (activate, status), version.

Note

kvm lives at ~/.kisai/bin/kvm. If kvm isn’t found, that directory isn’t on your PATH yet, run the kvm env step above (or add export PATH="$HOME/.kisai/bin:$PATH" to your shell profile).

Verify your install

which kis              # → /Users/you/.kisai/bin/kis
kis version            # CLI binary + every installed plugin version
kis --help             # lists every top-level command

If which kis prints nothing, ~/.kisai/bin isn’t on your PATH, re-run eval "$(kvm env)" (above).

The mental model: one launcher, several plugins

This is the single most important thing to understand before you start, because it explains a convention you’ll meet in the first five minutes.

kis is not one monolithic program, it’s a launcher that dispatches to several underlying plugin binaries. You always type kis …; you never call the plugins directly. Because the plugins are built separately, their global flags are not perfectly identical, most visibly, the flag that controls logging.

Command group	Examples	Logging flag
Core	find, query, test, cron, encrypt	--log-level (+ --log-to, --log-format)
AI	kis ai chat, kis ai embed	-l, --loglevel
Data / Forge	db, write-entity, read-entity	-l, --loglevel
Documents / Rules	rules, bbox, ocr, hocr2bbox	-l, --loglevel
Dev tooling	spec, flow, script, yaml, code, login, services	--log-level

Caution

The logging flag differs across groups. --log-level works for core and dev-tooling commands, but the AI, Forge, and Rules plugins expect -l, --loglevel instead. If a logging flag is rejected with an “unknown flag” error, run kis <command> --help and use the spelling it lists. The rest of the CLI is uniform.

The practical takeaway: when in doubt, --help the exact command you’re running. Its flag list is always authoritative.

kis ai chat --help     # flags + examples for one specific command

The five conventions used everywhere

Almost every command is built from the same five ideas. Learn them once and the whole CLI gets predictable.

1. Help is always one flag away

kis <command> --help
kis <command> <subcommand> --help

Every example in these docs was generated from this help output.

2. Variables, -v key=value

Many commands accept repeatable variables:

kis flow -f release.yaml -v env=staging -v version=1.4.0

For AI commands specifically, a variable value can also pull from a file or from stdin, a small superpower you’ll use constantly:

-v docs=@./onboarding.txt    # @file, substitute the file's contents
-v note=@-                   # @-    substitute whatever is on stdin

3. Prompt files, reusable, version-controlled prompts

Instead of pasting long prompts on the command line, store them in YAML as named entries with a system and user part, using {{placeholders}}:

prompts.yaml

summarize:
  system: "You are a concise technical summarizer."
  user: "Summarize this for an engineer:\n{{content}}"

Then call the named prompt and fill its placeholders:

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

4. Environments, -e env.yaml -n <name>

Workflow- and test-style commands read values from an environment file. One file can hold several named environments; pick one with -n:

env.yaml

default:
  url: http://localhost:8080
staging:
  url: https://staging.example.com

kis test -t tests/ -e env.yaml -n staging

5. JSON output, -j / --json

Most commands can emit machine-readable JSON for piping into other tools:

kis ai providers --json | jq '.[].name'

These five, help, vars, prompt files, environments, JSON, recur on almost every page. The reference notes only the exceptions.

Set flag defaults once, kis env

Tired of typing -p openai -m gpt-4o every time? kis env stores flag defaults in ~/.kisai/env.yaml. Keys are flag long-names exactly as shown in --help (lowercase, no --), and a stored value simply becomes that flag’s default, still overridable on the command line.

kis env set model=opus-4.8        # set a default
kis ai chat "hello"               # now uses model=opus-4.8
kis ai chat "hello" --model haiku # one-off override still wins

kis env list                      # show all defaults (dotted keys)
kis env get model                 # print one
kis env unset model               # remove it
kis env path                      # where the file lives
kis env edit                      # open it in $EDITOR

Resolution order: explicit flag on the command line > kis env value > the flag’s built-in default. A dotted key nests in the file (log.level → log: {level: …}).

Tip

Most commands also accept --env-file <path> to use a different defaults file for one run instead of ~/.kisai/env.yaml, handy for per-project defaults.

Your first commands

# Ask a model a question (defaults to the local "ollama" provider)
kis ai chat "What is kis.ai in one sentence?"

# Stream the answer as it's generated
kis ai chat --stream "Write a haiku about command lines"

# Generate some throwaway test data
kis synthetic sentence -c 3

# Preview a safe, format-preserving edit to a YAML file (no write yet)
kis yaml set --file config.yml --path '$.app.name' --value 'demo' --dry-run

---

Next: Core Concepts →, the platform’s mental model (spec, entities, tenancy). For the full command map, see the Introduction.