HTML docs · raw markdown

CLI reference

kobold-cli <section> <action> [flags]

Global flags on every action:

Flag	Meaning
`-base-url`	API base URL (default `https://api.insulalabs.io` or `KOBOLD_BASE_URL`)
`-api-key`	API key (default `KOBOLD_API_KEY`)
`-insecure`	Skip TLS certificate verification

Output: indented JSON on stdout, unless noted. Empty successes often print {"ok": true}. files content writes raw bytes to stdout or -out.

health

Action	Flags	Notes
`check`	(globals only)	No API key required

kobold-cli health check

echo

Action	Flags	Notes
`send`	`-message` (required)	Auth probe

kobold-cli echo send -message hello

stats

Action	Flags	Notes
`get`	(globals only)	Plan ceilings and current usage

kobold-cli stats get

kb

Action	Flags	Notes
`list`	`-offset`, `-limit`	Default limit `50`
`create`	`-name`, `-description`	Both required
`get`	`-id`	Knowledgebase id
`patch`	`-id`, `-name`, `-description`	At least one of name/description
`delete`	`-id`

kobold-cli kb list
kobold-cli kb list -offset 0 -limit 20
kobold-cli kb create -name notes -description "project notes"
kobold-cli kb get -id kb_qc0rp0gz
kobold-cli kb patch -id kb_qc0rp0gz -name "project notes"
kobold-cli kb patch -id kb_qc0rp0gz -description "updated blurb"
kobold-cli kb delete -id kb_qc0rp0gz

files

All file actions require -kb (knowledgebase id).

Action	Flags	Notes
`tree`	`-kb`	Recursive directory snapshot
`usage`	`-kb`	Aggregate file counts/bytes
`mkdir`	`-kb`, `-path`	Creates parents as needed
`ingest`	`-kb`, `-file`, `-filename`, `-dest-dir`	`-file -` reads stdin; `-filename` required with stdin
`rename`	`-kb`, `-from`, `-to`	Move/rename within the KB
`delete`	`-kb`, `-path`, `-recursive`	Non-empty dirs need `-recursive`
`content`	`-kb`, `-path`, `-offset`, `-length`, `-out`	Raw bytes; `-out` writes a file

kobold-cli files tree -kb kb_qc0rp0gz
kobold-cli files usage -kb kb_qc0rp0gz
kobold-cli files mkdir -kb kb_qc0rp0gz -path docs/notes
kobold-cli files ingest -kb kb_qc0rp0gz -file ./guide.md
kobold-cli files ingest -kb kb_qc0rp0gz -filename guide.md -dest-dir docs -file ./guide.md
kobold-cli files ingest -kb kb_qc0rp0gz -filename note.md -file -
kobold-cli files rename -kb kb_qc0rp0gz -from docs/old.md -to docs/new.md
kobold-cli files delete -kb kb_qc0rp0gz -path docs/new.md
kobold-cli files delete -kb kb_qc0rp0gz -path docs -recursive
kobold-cli files content -kb kb_qc0rp0gz -path docs/guide.md
kobold-cli files content -kb kb_qc0rp0gz -path docs/guide.md -offset 0 -length 4096 -out ./chunk.bin

If -filename is omitted on ingest, the CLI uses the basename of -file.

index

Action	Flags	Notes
`status`	`-kb`	Index progress and per-file state
`sync`	`-kb`	Request an immediate sync check

kobold-cli index sync -kb kb_qc0rp0gz
kobold-cli index status -kb kb_qc0rp0gz

search

Action	Flags	Notes
`query`	`-kb`, `-query`, `-limit`, `-min-score`, `-mode`, `-byte-length`	`-mode` is `sparse` or `full`

kobold-cli search query -kb kb_qc0rp0gz -query "billing"
kobold-cli search query -kb kb_qc0rp0gz -query "billing" -mode sparse -limit 10
kobold-cli search query -kb kb_qc0rp0gz -query "billing" -mode full
kobold-cli search query -kb kb_qc0rp0gz -query "billing" -mode full -byte-length 1024

For -mode full, if you omit -byte-length, the CLI sends 512. Valid range is 1–1024.

agents

Action	Flags	Notes
`list`	(globals only)	Site agents available for schedules

kobold-cli agents list

schedules

Action	Flags	Notes
`intervals`	(globals only)	Fixed interval presets
`list`	`-offset`, `-limit`
`get`	`-id`	Schedule id (`sch_…`)
`create`	`-agent`, `-kb`, `-prompt`, `-interval`, `-hooks`	`-prompt` is text or a local file path; `-hooks` is a JSON file
`enable`	`-id`
`disable`	`-id`
`delete`	`-id`

kobold-cli schedules intervals
kobold-cli schedules list
kobold-cli schedules create -agent ag_7k2m9x4q -kb kb_qc0rp0gz -prompt ./prompt.md -interval daily_09_00
kobold-cli schedules create -agent ag_7k2m9x4q -kb kb_qc0rp0gz -prompt "Summarize new files" -interval every_hour -hooks ./hooks.json
kobold-cli schedules enable -id sch_7k2m9x4q
kobold-cli schedules disable -id sch_7k2m9x4q
kobold-cli schedules delete -id sch_7k2m9x4q

Hooks file shape:

{
  "onComplete": {
    "type": "webhook",
    "webhook": { "url": "https://example.com/hook", "headers": { "Authorization": "Bearer …" } }
  },
  "onFail": {
    "type": "webhook",
    "webhook": { "url": "https://example.com/fail" }
  }
}

HTTP mapping (quick)

CLI	HTTP
`health check`	`GET /health`
`echo send`	`POST /v1/echo`
`stats get`	`GET /v1/stats`
`agents list`	`GET /v1/agents`
`schedules intervals`	`GET /v1/schedules/intervals`
`schedules list`	`GET /v1/schedules`
`schedules create`	`POST /v1/schedules`
`schedules get`	`GET /v1/schedules/{schId}`
`schedules enable`	`POST /v1/schedules/{schId}/enable`
`schedules disable`	`POST /v1/schedules/{schId}/disable`
`schedules delete`	`DELETE /v1/schedules/{schId}`
`kb list`	`GET /v1/knowledgebases`
`kb create`	`POST /v1/knowledgebases`
`kb get`	`GET /v1/knowledgebases/{kbId}`
`kb patch`	`PATCH /v1/knowledgebases/{kbId}`
`kb delete`	`DELETE /v1/knowledgebases/{kbId}`
`files tree`	`GET /v1/knowledgebases/{kbId}/files/tree`
`files usage`	`GET /v1/knowledgebases/{kbId}/files/usage`
`files mkdir`	`POST /v1/knowledgebases/{kbId}/files/mkdir`
`files ingest`	`POST /v1/knowledgebases/{kbId}/files/ingest`
`files rename`	`PATCH /v1/knowledgebases/{kbId}/files`
`files delete`	`DELETE /v1/knowledgebases/{kbId}/files`
`files content`	`GET /v1/knowledgebases/{kbId}/files/content`
`index status`	`GET /v1/knowledgebases/{kbId}/status`
`index sync`	`POST /v1/knowledgebases/{kbId}/sync`
`search query`	`POST /v1/knowledgebases/{kbId}/search`