AI Commands

Everything under kis ai is one consistent interface to many model providers. Learn the shared flags once and all nineteen subcommands feel the same.

kis ai --help

Before using these, make sure a provider is set up, see Providers & authentication. The default provider is ollama (local), so most examples work key-free if Ollama is running.

Flags shared by most AI commands

Flag	Meaning
-p, --provider	Provider (default ollama)
-m, --model	Model id (provider-specific)
-k, --api-key	API key (or set the provider’s env var)
-e, --endpoint	Override the provider’s base URL
-j, --json	Full response as JSON
--max-tokens	Max output tokens (default 1024)
-T, --temperature	Sampling temperature
--timeout	Request timeout, seconds (default 120)
--max-retries	Retries on transient errors (default 2)

The pages below note only what’s special about each command.

kis ai chat

What it is. The everyday “send a prompt, get a reply” command.

Why it exists. It’s the front door to text generation, Q&A, summarizing, rewriting, translation, vision, without writing any provider-specific code.

When to reach for it. Any time you want a model’s freeform text answer. If you need the answer to be valid JSON, use structured instead; if you need fields voted across runs, use extract.

How to use it. The prompt comes from the arguments, or from stdin if you pass none.

kis ai chat "what is 2+2?"
kis ai chat -p openai -m gpt-4o "summarize this"
echo "translate to French: hello" | kis ai chat
kis ai chat --stream "write a haiku about go"

Vision, attach images with -I (repeatable; file path or URL):

kis ai chat -p ollama -m qwen3-vl:8b -I photo.jpg "what is in this image?"

Reusable prompts and saved conversations:

kis ai chat --prompt-file prompts.yaml --prompt summarize -v [email protected]
kis ai chat --session proj-42 "remember my name is Sam"   # saved + resumable
kis ai chat -i --session proj-42                          # interactive REPL, resumes

Notable flags: -s/--system (system prompt), -i/--interactive (streamed REPL), --stream, --session / --sessions-dir, --reasoning off|low|medium|high|on, --allow-unset (leave unresolved {{vars}} in place instead of erroring).

kis ai embed

What it is. Turns text into embeddings, vectors of numbers whose distance encodes meaning.

Why it exists. Embeddings are the foundation of semantic search, clustering, deduplication, and retrieval-augmented generation (RAG). You need them whenever “how similar are these two texts?” is the question.

When to reach for it. Building search/RAG, or grouping similar items. Use --compare for a quick “are these alike?” check without wiring up a vector store.

How to use it. Each argument is one input; with no arguments it reads inputs one-per-line from stdin.

kis ai embed "hello world"
kis ai embed -p openai -m text-embedding-3-small "a" "b" --compare
printf "first\nsecond\n" | kis ai embed --json

• --compare, print the pairwise cosine-similarity matrix instead of raw vectors.

kis ai chunk

What it is. Splits a document into smaller, model-sized pieces (“chunks”).

Why it exists. Models have context limits, and retrieval works better on focused passages than on whole documents. Chunking is step one of almost every RAG pipeline.

When to reach for it. Before embedding a long document, or any time you need to feed a large file to a model in parts. Pick the strategy to match the content’s structure.

How to use it.

kis ai chunk README.md --strategy markdown --max-tokens 512
kis ai chunk paper.txt --strategy semantic -p ollama -m nomic-embed-text
kis ai chunk notes.txt --strategy recursive --overlap 64 --json

Flag	Meaning
--strategy	recursive (default), window, markdown, html, semantic
--max-tokens / --min-tokens	Size bounds per chunk
--overlap	Shared tokens between adjacent chunks (preserves context across boundaries)

Tip

The semantic strategy embeds sentences to find topic boundaries, so it uses the -p/-m flags as the embedder. The other strategies are purely structural and ignore them.

kis ai extract

What it is. Pulls fields matching a JSON Schema out of free text, with optional N-run consensus.

Why it exists. A single model pass over messy input (scanned forms, emails, notes) can be inconsistent. Running the extraction several times and taking a per-field majority vote turns a flaky call into a stable one, and tells you how confident to be (how many runs agreed on each field).

When to reach for it. Structured data extraction from noisy or high-stakes text. For clean input where one pass is enough, --runs 1 (the default) behaves like structured with a voting wrapper.

How to use it. Input is args, stdin, or --input (literal, or @path).

kis ai extract --schema loan.json --input @./application.txt --runs 5
echo "$DOC" | kis ai extract --schema fields.json -p openai --runs 3 --json
kis ai extract --schema loan.json --prompt-file prompts.yaml --prompt extract_note -v [email protected] --runs 5

• --schema, JSON Schema (file path or inline JSON).
• -n/--runs, number of independent runs to vote across.

Tip

When --runs > 1, temperature defaults to 0.4 so the runs vary enough to make voting meaningful. Override with -T if you need to.

kis ai structured

What it is. Gets a single JSON object that conforms to a JSON Schema.

Why it exists. “Reply in JSON” prompts are unreliable, models add prose, trail commas, or drift from the shape. This command constrains and validates the output, and can self-repair on a parse failure.

When to reach for it. Any time a downstream program will parse the result. Use extract instead when you want multi-run voting for confidence.

How to use it. Input is args or stdin; the schema is a file path or inline JSON.

kis ai structured --schema person.json "John Smith, 42, lives in NYC"
echo "$INVOICE" | kis ai structured --schema ./invoice.json -p openai

• --strict, request strict schema conformance.
• --repair N, retry up to N times, feeding the parse error back, on failure (default 2).

kis ai image

What it is. Generates images from a text prompt.

When to reach for it. Quick image generation from the terminal. Providers: openai, stability.

kis ai image -p openai "a watercolor fox" -o fox.png
kis ai image -p stability "an isometric office" --width 1024 --height 1024

• -o/--out (output file, or prefix when --n > 1), --width, --height, --n, --format (default png), --negative (negative prompt, where supported).

kis ai transcribe

What it is. Speech-to-text (STT), converts an audio file to text.

When to reach for it. Transcribing calls, meetings, voice notes. Providers: openai, groq, deepgram, whispercpp.

kis ai transcribe -p openai call.mp3
kis ai transcribe -p whispercpp -e http://localhost:8080/v1 audio.wav --json
kis ai transcribe -p groq -m whisper-large-v3 interview.m4a --timestamps

• --language (BCP-47 hint), --timestamps (segment times), --translate (to English where supported).

kis ai tts

What it is. Text-to-speech (TTS), synthesizes spoken audio from text.

When to reach for it. Generating voice output. Providers: openai, deepgram.

kis ai tts -p openai "hello there" --voice alloy -o hello.mp3
echo "good morning" | kis ai tts -p deepgram -o gm.mp3

• --voice (provider-specific), --format (default mp3), --speed (rate multiplier; 0 = default), -o/--out (default speech.<format>).

kis ai rerank

What it is. Re-orders a set of documents by how relevant each is to a query.

Why it exists. Embedding-based retrieval is fast but coarse; a reranker is a second, more precise pass that pushes the truly relevant results to the top. It’s the quality step in a good RAG pipeline.

When to reach for it. After an initial retrieval, to sharpen ranking before you show results or feed them to a model. Providers: cohere, tei.

kis ai rerank -p cohere "best laptop for dev" "MacBook Pro" "Chromebook" "ThinkPad"
kis ai rerank -p tei -e http://localhost:8080 "query" "doc a" "doc b" --top-n 1

• --top-n N, return only the top N (0 = all).

kis ai rag

What it is. Retrieval-augmented generation over a vector store, three subcommands covering the whole loop: ingest (chunk, embed and store documents), retrieve (fetch the most relevant chunks for a query), and answer (retrieve context and answer the query, grounded in the store).

Why it exists. chunk, embed and rerank give you the pieces of a RAG pipeline; rag is the assembled pipeline, one command family to build a knowledge base and ask questions against it, no glue code.

When to reach for it. “Answer questions from my documents.” For one-off similarity checks, plain embed --compare is lighter; for tuning a retrieval stage you own, use the individual commands.

How to use it. The store is chosen by --dsn:

DSN	Store
memory:	In-process (per command; not shared across runs, the default)
pgvector://user:pass@host/db	Postgres + pgvector
chroma://host:8000	Chroma
qdrant://host:6333	Qdrant
duckdb:///path/to.db	DuckDB (only if the binary was built -tags duckdb)

kis ai rag ingest --dsn "pgvector://app:app@localhost:5432/kb?sslmode=disable" \
    --collection notes -p ollama --embed-model nomic-embed-text notes/*.md
kis ai rag retrieve --dsn "pgvector://app:app@localhost:5432/kb?sslmode=disable" \
    --collection notes "what did we decide about X?"
kis ai rag answer --dsn "pgvector://app:app@localhost:5432/kb?sslmode=disable" \
    --collection notes -p ollama -m llama3.2:3b "what did we decide about X?"

• Shared knobs: --collection (default kb), --top-k (chunks retrieved, default 5), --embed-model (default: the provider’s).
• ingest: files as args or text on stdin; --chunk-tokens (default 512), --overlap (default 64).
• answer: --sources prints the retrieved sources to stderr; --system overrides the RAG system prompt.

Caution

The default --dsn memory: lives only for one command, an ingest followed by a separate answer finds an empty store. Cross-command RAG needs a persistent DSN (pgvector / chroma / qdrant / a duckdb file).

kis ai sample

What it is. A developer tool for running a prompt through multi-run / multi-model sampling strategies and comparing outputs.

Why it exists. It packages four common reliability/comparison patterns so you don’t hand-roll them:

Mode	Behaviour
self-consistency	Call one model N times, majority-vote the answer
best-of-n	Sample N candidates, a judge picks the best
cross-provider	Send to several models, judge the best
race	Call several models, return the first to finish

When to reach for it. Evaluating which model/prompt is best, squeezing reliability out of a hard prompt, or minimizing latency (race). It’s an experimentation aid, not something you’d put on a hot path unchanged.

kis ai sample --mode self-consistency -n 5 "tricky reasoning question"
kis ai sample --mode cross-provider --models "openai:gpt-4o,anthropic:claude-sonnet-4-6" "..."
kis ai sample --mode race --models "groq:llama-3.3-70b-versatile,openai:gpt-4o-mini" "..."

• --models, comma-separated provider:model refs (for cross-provider, race).
• --judge, model ref used to judge (defaults to the primary model).

kis ai reason

What it is. Runs a prompt through a reasoning strategy, structured prompting or an iterative multi-call algorithm, to get better answers on hard problems.

Why it exists. A plain chat call is one shot. For multi-step reasoning (math, planning, careful definitions), structured strategies and search/critique loops measurably improve quality. reason packages the well-known techniques so you don’t hand-roll them.

When to reach for it. Hard reasoning tasks where a single answer is unreliable. Pick the --mode by how much compute you’ll spend:

--mode	Strategy
cot	Chain-of-thought (“think step by step”), single call (default)
structured-cot	Phased CoT (--phases "understand,plan,solve,verify")
plan-and-solve	Plan-and-solve prompting
tot	Tree-of-Thoughts: branch + judge + beam search (--width --depth --beam)
reflexion	generate → critique → revise (--rounds, --judge as critic)
self-refine	Single-model reflexion (--rounds)
debate	N models argue, a judge decides (--models, --judge, --rounds)

The first three are single-call prompt strategies; the rest are iterative algorithms that make multiple calls.

kis ai reason --mode cot "If a train travels 60km in 1.5h, its speed?"
kis ai reason --mode tot --width 3 --depth 3 "Solve the 24 game with 4 6 7 8"
kis ai reason --mode reflexion --rounds 3 "Write a precise definition of overfitting"
kis ai reason --mode debate --models "openai:gpt-4o,anthropic:claude-sonnet-4-6" "Is P=NP likely?"

• --trace, print the full reasoning trace (for tot/reflexion/self-refine/debate).
• tot knobs: --width (branches per node, default 3), --depth (default 3), --beam (paths kept per level, default 1).
• --rounds (default 3), --judge (judge/critic model), --models (for debate), --phases (for structured-cot).

Tip

reason is the heavier cousin of sample: sample varies runs/models and votes; reason applies a thinking strategy (search, critique, debate). Reach for reason when the task needs structured reasoning, not just more samples.

kis ai solve

What it is. Has the model write a small JavaScript program for your task, then executes it in the lib-maya engine and prints the program’s result. The model plans; the engine computes, no arithmetic hallucinations.

Why it exists. Models are unreliable at exact computation (counting, statistics, joins). Generating code and running it deterministically gets the model’s flexibility with a calculator’s accuracy.

When to reach for it. Tasks with a computable answer, counting, math over a file, joining CSVs, where a chat or reason answer could silently miscalculate.

How to use it. By default the script runs in a pure sandbox (plain JavaScript only, no file, network, or shell access). Namespaces are opted in with --allowed and enforced by the engine itself, not just the prompt:

kis ai solve "how many r letters are in the word strawberry"
kis ai solve --allowed file "mean, median and mode of the salary column in /tmp/pay.csv"
kis ai solve --allowed file,db "join users.csv and orders.csv on id; top 5 by total"
cat data.txt | kis ai solve "median of the numbers in this list"   # stdin → 'input' var

Execution posture. The generated code is printed and you are asked before it executes. --exec skips the confirmation (code still shown); --silent also hides the code; --dry-run prints the code and never executes.

• --allowed, comma-separated maya namespaces the script may use (default none; all = every namespace).
• --attempts N, on script errors, feed them back to the model to fix its code and retry (default 1 = no retry).
• --var key=value, script variables (value supports @file and @- for stdin); repeatable.
• --script-timeout, script execution timeout in milliseconds (default 30000).
• --show-prompt, print the composed system prompt to stderr before calling the model.

Tip

The help suggests a code model generates better programs, e.g. -m qwen3-coder:30b (ollama). The maya engine here is the same script host behind kis script.

kis ai harness

What it is. Executes harness definitions, declarative, multi-step LLM/agent graphs, with the embedded engine. It can run them, validate the graph (including the cycle-boundedness rule), inspect the desugared graph, and resume a suspended or interrupted run from a snapshot.

Why it exists. It turns multi-step agent pipelines into reviewable data (a graph definition) instead of bespoke code, with validation and crash-resumability built in. It’s the structured, durable big brother of flow for LLM-centric graphs.

When to reach for it. Building and running repeatable agentic workflows that branch, loop (boundedly), and must survive interruption.

kis ai harness validate pipeline.yaml      # parse, expand, and validate the graph
kis ai harness graph pipeline.yaml         # emit the (desugared) graph
kis ai harness run pipeline.yaml           # execute with the embedded engine
kis ai harness resume run-snapshot.json    # resume a suspended/interrupted run

Subcommand	What it does
run	Execute a harness definition with the embedded engine
validate	Parse, expand, and validate a definition (incl. cycle-boundedness)
graph	Emit the definition’s (desugared) graph
resume	Resume a suspended or interrupted run from a snapshot

Note

Model refs in definitions resolve dev-style: provider:model builds that provider from flags/env keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, … KIS_LOKI_KEY for gateway:); a bare ref uses --provider/--model.

kis ai memory

What it is. An HTTP client for ai-smriti (ai-memory), the platform’s interaction-memory service. It records conversation turns and recalls ranked, budget-fit memory across scopes, with governance (forget/edit/exclude).

Why it exists. It gives agents durable, governed long-term memory that survives beyond a single session, including right-to-forget, user edits that take precedence, and per-scope exclusions, which compliance-sensitive assistants need.

When to reach for it. Building assistants/agents that must remember (and correctly forget) across many sessions, scoped per customer/product/env/tenant.

The subcommands group by job:

Group	Subcommands
Write	start (open a session for a subject), append (record a turn), close (end session → consolidation), event (record a memory-relevant event)
Read	recall (ranked, budget-fit memory across scopes), history (a session’s recent turns), facts (facts about a subject, current or as-of a time)
Scope	promote (re-tag a session/episode to a team scope)
Governance	forget (erase + propagate deletion), edit (correct/add/delete; user edits win), exclude (per-scope “do not remember X”)
Admin	consolidate (run consolidation on demand)

kis ai memory start --customer acme --product app "user-42"
kis ai memory append <session> "user said they prefer dark mode"
kis ai memory recall --customer acme "what are this user's UI preferences?"
kis ai memory forget <subject>             # right-to-forget

Note

Needs the ai-smriti service running (--endpoint, default http://localhost:8080, or KIS_SMRITI_ENDPOINT). The CPET identity (customer:product:env:tenant) is sent as X-Customer/X-Product/X-Env/X-Tenant headers; pass --token (JWT) and --scope-claim when the service enforces them. CPET fields default from KIS_CUSTOMER/KIS_PRODUCT/KIS_ENV/KIS_TENANT.

kis ai tokens

What it is. Counts tokens in some text.

Why it exists. Tokens drive both cost and context limits. Counting before you send avoids surprise truncation and lets you estimate spend.

When to reach for it. Sizing a prompt against a model’s window, or budgeting.

kis ai tokens "how many tokens is this?"
kis ai tokens --file ./prompt.txt -p openai -m gpt-4o
kis ai tokens --exact -p llamacpp -e http://localhost:8080/v1 --file big.txt

Caution

The default count is a heuristic, a deliberate slight over-estimate, not exact. For a precise number pass --exact against a local tokenizer (e.g. -p llamacpp pointed at a llama.cpp server’s /tokenize). Don’t treat the default as authoritative for tight budgeting.

kis ai models

What it is. Lists the models a provider advertises, with their capabilities.

kis ai models -p anthropic
kis ai models -p openai --json

Note

vllm, ollama, and llamacpp don’t ship a static catalog, this may return little for them. Pass -m with the model you’re running and use it directly.

kis ai providers

What it is. Lists every supported provider and what each can do (chat, embed, image, STT, TTS, rerank…).

When to reach for it. Deciding which provider supports the capability you need.

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

kis ai session

What it is. Persistent, file-backed conversations stored under ~/.kisai/ai/sessions.

Why it exists. It gives multi-turn chats memory that survives across invocations, the same store that kis ai chat --session <id> reads and writes.

When to reach for it. Building anything stateful on top of chat, or inspecting and managing saved conversations.

kis ai session new                 # create a new conversation id
kis ai session list                # list stored conversations
kis ai session send <id> "hi"      # append a message, print the reply
kis ai session show <id>           # print the whole conversation

Tip

session send takes --context-tokens N to auto-truncate older history once the conversation exceeds N tokens (0 = off), handy for long-running sessions that would otherwise outgrow the model’s context window.