CLI reference

Every command takes these options:

Option	What it does
--json	Print one JSON object: {"ok": true, ...} or {"ok": false, "error": ..., "hint": ...}.
--host URL	The Kol host to talk to. Default: KOL_HOST, or the hosted Kol service.
--dir PATH	The project folder (the one with kol.json). Default: the current folder.
--help (-h)	Show help for a command.
--version (-v)	Print the version.

With --json, a command prints exactly one JSON object on standard output (logs prints one per line). Exit codes: 0 ok, 1 error, 2 not signed in.

Command	What it does
login	Sign in by approving a code in the Kol app
logout	Sign out (the token stops working)
whoami	Who you are signed in as
init	Make a new project folder
validate	Check the project
prompt	Show the instructions your AI gets
try	Talk to your AI in text
test	Run the scripted conversations in tests/
push	Save it on Kol as a draft
publish	Put it in the marketplace
list	Your AIs
status	How one AI is doing
requests	Requests your AI took
logs	Watch live events
schema	Allowed values and limits
mcp	Run the MCP server for coding agents

kol login

Shows a short code. Open the Kol app on your phone, go to Companions → Creator portal and enter it. The CLI waits until you approve it, then keeps the sign-in on this computer (in ~/.config/kol/credentials.json, never in your project). Coding agents use --no-wait to get the code at once, show it to you, then finish with --code and --device.

kol login [options]

Option	What it does
--no-wait	Print the code and stop. Finish later with --code and --device.
--code CODE	Finish a sign-in started with --no-wait.
--device SECRET	The deviceCode printed by --no-wait.
--timeout SECONDS	How long to wait for approval (default 300).

Examples

kol login
kol login --no-wait --json
kol login --code K7Q4XZ --device <deviceCode> --json

MCP tool: kol_login_start / kol_login_finish

kol logout

Revokes the token on the host and forgets it here.

kol logout

Examples

kol logout

kol whoami

Shows your Kol name and ID, and whether you have an AI key (needed for try and test).

kol whoami

Examples

kol whoami --json

MCP tool: kol_whoami

kol init

Writes kol.json, a persona.md template, knowledge/, tests/, and files for coding agents (AGENTS.md, a Claude Code skill, .mcp.json). Existing files are kept unless you pass --force.

kol init [dir] [options]

Option	What it does
--name NAME	Its name (default: from the folder name).
--kind KIND	companion (default) or service. See Concepts.
--force	Overwrite the template files.

Examples

kol init chef --name "Chef Remy"
kol init front-desk --kind service

MCP tool: kol_init

kol validate

Lists every problem by field, then asks the host to check it too. Exit code 1 when there is a problem.

kol validate [options]

Option	What it does
--offline	Only the local checks; don't contact the host.

Examples

kol validate
kol validate --json

MCP tool: kol_validate

kol prompt

The exact instructions (your persona, your knowledge and the platform rules), its greeting and its tools. Free: no AI model is called.

kol prompt [options]

Option	What it does
--as ROLE	owner (default) or standIn: as if it answers a call for its owner.

Examples

kol prompt
kol prompt --as standIn --json

MCP tool: kol_prompt

kol try

Sends a message to the project as it is on disk (nothing is saved) and prints the reply. Without a message it prints the greeting. Tools run in test mode: a request is never really sent. Uses your AI key.

kol try [message] [options]

Option	What it does
--session NAME	Continue a conversation (kept in .kol/sessions/).
--reset	Start the session over.
--as ROLE	owner (default) or standIn: as if it answers a call for its owner.
--saved	Talk to the version saved on the host (after push) instead of the files.

Examples

kol try "What can I cook with eggs and spinach?"
kol try --session s1 "Make it vegan"
kol try --session s1 --reset "Start again"

MCP tool: kol_try

kol test

Runs every tests/*.json against the project and checks each reply. Exit code 1 when a check fails. Uses your AI key.

kol test [options]

Option	What it does
--only NAME	Run only the test with this name or file.

Examples

kol test
kol test --only orders --json

MCP tool: kol_test

kol push

Creates or updates your AI on Kol and syncs its knowledge. A draft is only visible to you: talk to it by voice in the app. Nothing happens when nothing changed. If it is already published, push refuses (it would change it for everyone): use publish or --live.

kol push [options]

Option	What it does
--live	Allow changing a published AI.

Examples

kol push
kol push --json

MCP tool: kol_push

kol publish

Pushes your latest changes, then makes your AI visible to everyone in the Kol marketplace. --off takes it out (people who have it keep it).

kol publish [options]

Option	What it does
--off	Take it out of the marketplace.

Examples

kol publish
kol publish --off

MCP tool: kol_publish

kol list

Every AI you made, with installs, calls, minutes and requests.

kol list

Examples

kol list --json

MCP tool: kol_list

kol status

Published or not, version, installs, calls, minutes, requests, knowledge, and whether this folder has changes you have not pushed.

kol status [id]

Examples

kol status
kol status c-1a2b3c4d --json

MCP tool: kol_status

kol requests

Orders, bookings and messages callers asked your AI to send you (the requests skill).

kol requests [id]

Examples

kol requests --json

MCP tool: kol_requests

kol logs

Prints try-outs, voice tests and new requests as they happen. With --json, one JSON object per line.

kol logs [options]

Option	What it does
--for SECONDS	Stop after this many seconds (default: until Ctrl-C).

Examples

kol logs
kol logs --json --for 60

kol schema

The icons, colors, voices, prices and length limits kol.json accepts.

kol schema

Examples

kol schema --json

MCP tool: kol_schema

kol mcp

Serves the same operations as MCP tools over stdio, for Claude Code, Codex, Cursor and other agents. Also available as the kol-mcp command.

kol mcp

Examples

kol mcp
claude mcp add kol -- kol mcp