Kaonic CLI & engine

kaonic is the terminal entry point to a Kaonic Ai Beta deployment. It installs offline (no runtime dependencies), starts the local stack — Laravel API, Next.js front end and the queue worker — talks to the Kaonic AI Engine, and can call the same API you reach over HTTP. Everything below runs from a shell: no control panel required.

Requirements

ComponentMinimumNeeded for
Node.js20+The CLI itself and API commands.
PHP8.0+Running the Kaonic PHP API locally.
Composer2.xcomposer install in the backend.
DockerOptionalThe one-command container stack instead of kaonic serve.

Step 1 — Install the CLI

The CLI lives in kaonic-mvp/cli. Build it and link the binary onto your path:

cd kaonic-mvp/cli
npm install
npm run build
npm link

npm link makes kaonic available globally. If you would rather not link it, run the compiled binary directly:

node bin/kaonic.js --help

Step 2 — Verify the install

kaonic doctor checks PHP version, composer.json, backend/vendor, backend/.env, database and Redis reachability, storage writability, the API and the configured AI providers. It prints a pass/warn/fail table and exits non-zero when anything fails.

kaonic --help
kaonic doctor

Step 3 — Configure

kaonic init writes kaonic.config.json with defaults. Point apiUrl at your Kaonic API (including the /api suffix) and paste a private API key from the developer dashboard.

kaonic init
kaonic config:set apiUrl http://127.0.0.1:8000/api
kaonic config:set apiKey GK_A31D9C4E7B2F8065...

Configuration resolves from defaults, then .env, then ~/.kaonic/config.json, then kaonic.config.json, then the real environment. Environment variables win:

VariableOverrides
KAONIC_API_URLapiUrl
KAONIC_API_KEYapiKey
KAONIC_ENGINEengine — auto | local | remote
OLLAMA_HOSTollamaHost — a local Ollama instance
KAONIC_DEBUGEnables debug logging on stderr
NO_COLORDisables coloured output
Setting KAONIC_ENGINE=local forbids every outbound call. Use it when the deployment must answer from the on-box engine only.

Step 4 — Start the server and engine

kaonic serve boots the local stack: the Kaonic API, the web front end and a queue worker. Child output is prefixed ([api], [web]) and written to stderr so stdout stays clean. Ctrl+C stops everything.

kaonic serve
kaonic serve --api-only --port=8080
kaonic serve --web-only
kaonic serve --no-queue

Missing composer install or node_modules are reported instead of crashing the command.

Container stack instead

To run the same topology in Docker — Postgres, Redis, the FastAPI engine, the Laravel API, a queue worker and the Next.js front end:

cd kaonic-mvp
docker compose up -d --build
docker compose logs -f backend
ServiceDefault portRole
frontend3000Next.js console.
backend8000Laravel API — migrates and seeds on first boot.
engine8001Kaonic AI Engine (FastAPI), internal only.
postgres5432pgvector database.
redis6379Cache, queues and sessions.

Step 5 — Models and agents

kaonic models:list
kaonic models:add --name "Claude" --provider anthropic --key claude-3-5-sonnet
kaonic agent:create --name "Support Bot" --prompt "You answer support tickets."
kaonic agent:create --name "Coder" --tools code --tools search

models:add signs in with admin.email / admin.password and calls the API when those are configured; otherwise it records the model locally and says so. agent:create scaffolds agents/<slug>.json.

Step 6 — Generate from the terminal

kaonic chat "Explain pgvector in one paragraph"
kaonic code "Add type hints" --file src/app.ts --out app.ts
kaonic image "a kente-cloth pattern, flat vector" --out pattern.png
kaonic voice "Karibu Kaonic" --language sw --out welcome.mp3
kaonic train --dataset data/faq.jsonl --epochs 3

chat streams the reply and accepts --model, --project, repeatable --mode think|code|search|research, --conversation, --no-stream and --json. image and voice submit a job, poll it and download the result.

Every API command performs a real HTTP request. If the API cannot be reached the command fails with a clear message and exit code 4 — it never prints fabricated output.

Config commands

kaonic config:list
kaonic config:get apiUrl
kaonic config:set --global engine local

Exit codes

CodeMeaning
0Success.
1Generic failure.
2Usage error — bad flags or a missing argument.
3The API answered with an error.
4The API is unreachable — start it with kaonic serve.
5Configuration error.
6The backend does not implement that command yet.

Next steps