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
| Component | Minimum | Needed for |
|---|---|---|
| Node.js | 20+ | The CLI itself and API commands. |
| PHP | 8.0+ | Running the Kaonic PHP API locally. |
| Composer | 2.x | composer install in the backend. |
| Docker | Optional | The 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:
| Variable | Overrides |
|---|---|
KAONIC_API_URL | apiUrl |
KAONIC_API_KEY | apiKey |
KAONIC_ENGINE | engine — auto | local | remote |
OLLAMA_HOST | ollamaHost — a local Ollama instance |
KAONIC_DEBUG | Enables debug logging on stderr |
NO_COLOR | Disables coloured output |
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
| Service | Default port | Role |
|---|---|---|
frontend | 3000 | Next.js console. |
backend | 8000 | Laravel API — migrates and seeds on first boot. |
engine | 8001 | Kaonic AI Engine (FastAPI), internal only. |
postgres | 5432 | pgvector database. |
redis | 6379 | Cache, 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
| Code | Meaning |
|---|---|
0 | Success. |
1 | Generic failure. |
2 | Usage error — bad flags or a missing argument. |
3 | The API answered with an error. |
4 | The API is unreachable — start it with kaonic serve. |
5 | Configuration error. |
6 | The backend does not implement that command yet. |
Next steps
- API keys & auth — the key the CLI sends as
Authorization: Bearer. - Integrations & SDKs — WordPress plugin, PHP SDK and webhooks.
- Endpoint reference — call the same surface over plain HTTP.