{"slug":"cli-reference","title":"CLI reference","path":"cli-reference.md","markdown":"# CLI reference\n\n```text\nkobold-cli \u003csection\u003e \u003caction\u003e [flags]\n```\n\nGlobal flags on every action:\n\n| Flag | Meaning |\n| ---- | ------- |\n| `-base-url` | API base URL (default `https://api.insulalabs.io` or `KOBOLD_BASE_URL`) |\n| `-api-key` | API key (default `KOBOLD_API_KEY`) |\n| `-insecure` | Skip TLS certificate verification |\n\nOutput: indented JSON on stdout, unless noted. Empty successes often print `{\"ok\": true}`. `files content` writes raw bytes to stdout or `-out`.\n\n---\n\n## health\n\n| Action | Flags | Notes |\n| ------ | ----- | ----- |\n| `check` | (globals only) | No API key required |\n\n```bash\nkobold-cli health check\n```\n\n---\n\n## echo\n\n| Action | Flags | Notes |\n| ------ | ----- | ----- |\n| `send` | `-message` (required) | Auth probe |\n\n```bash\nkobold-cli echo send -message hello\n```\n\n---\n\n## stats\n\n| Action | Flags | Notes |\n| ------ | ----- | ----- |\n| `get` | (globals only) | Plan ceilings and current usage |\n\n```bash\nkobold-cli stats get\n```\n\n---\n\n## kb\n\n| Action | Flags | Notes |\n| ------ | ----- | ----- |\n| `list` | `-offset`, `-limit` | Default limit `50` |\n| `create` | `-name`, `-description` | Both required |\n| `get` | `-id` | Knowledgebase id |\n| `patch` | `-id`, `-name`, `-description` | At least one of name/description |\n| `delete` | `-id` | |\n\n```bash\nkobold-cli kb list\nkobold-cli kb list -offset 0 -limit 20\nkobold-cli kb create -name notes -description \"project notes\"\nkobold-cli kb get -id kb_qc0rp0gz\nkobold-cli kb patch -id kb_qc0rp0gz -name \"project notes\"\nkobold-cli kb patch -id kb_qc0rp0gz -description \"updated blurb\"\nkobold-cli kb delete -id kb_qc0rp0gz\n```\n\n---\n\n## files\n\nAll file actions require `-kb` (knowledgebase id).\n\n| Action | Flags | Notes |\n| ------ | ----- | ----- |\n| `tree` | `-kb` | Recursive directory snapshot |\n| `usage` | `-kb` | Aggregate file counts/bytes |\n| `mkdir` | `-kb`, `-path` | Creates parents as needed |\n| `ingest` | `-kb`, `-file`, `-filename`, `-dest-dir` | `-file -` reads stdin; `-filename` required with stdin |\n| `rename` | `-kb`, `-from`, `-to` | Move/rename within the KB |\n| `delete` | `-kb`, `-path`, `-recursive` | Non-empty dirs need `-recursive` |\n| `content` | `-kb`, `-path`, `-offset`, `-length`, `-out` | Raw bytes; `-out` writes a file |\n\n```bash\nkobold-cli files tree -kb kb_qc0rp0gz\nkobold-cli files usage -kb kb_qc0rp0gz\nkobold-cli files mkdir -kb kb_qc0rp0gz -path docs/notes\nkobold-cli files ingest -kb kb_qc0rp0gz -file ./guide.md\nkobold-cli files ingest -kb kb_qc0rp0gz -filename guide.md -dest-dir docs -file ./guide.md\nkobold-cli files ingest -kb kb_qc0rp0gz -filename note.md -file -\nkobold-cli files rename -kb kb_qc0rp0gz -from docs/old.md -to docs/new.md\nkobold-cli files delete -kb kb_qc0rp0gz -path docs/new.md\nkobold-cli files delete -kb kb_qc0rp0gz -path docs -recursive\nkobold-cli files content -kb kb_qc0rp0gz -path docs/guide.md\nkobold-cli files content -kb kb_qc0rp0gz -path docs/guide.md -offset 0 -length 4096 -out ./chunk.bin\n```\n\nIf `-filename` is omitted on ingest, the CLI uses the basename of `-file`.\n\n---\n\n## index\n\n| Action | Flags | Notes |\n| ------ | ----- | ----- |\n| `status` | `-kb` | Index progress and per-file state |\n| `sync` | `-kb` | Request an immediate sync check |\n\n```bash\nkobold-cli index sync -kb kb_qc0rp0gz\nkobold-cli index status -kb kb_qc0rp0gz\n```\n\n---\n\n## search\n\n| Action | Flags | Notes |\n| ------ | ----- | ----- |\n| `query` | `-kb`, `-query`, `-limit`, `-min-score`, `-mode`, `-byte-length` | `-mode` is `sparse` or `full` |\n\n```bash\nkobold-cli search query -kb kb_qc0rp0gz -query \"billing\"\nkobold-cli search query -kb kb_qc0rp0gz -query \"billing\" -mode sparse -limit 10\nkobold-cli search query -kb kb_qc0rp0gz -query \"billing\" -mode full\nkobold-cli search query -kb kb_qc0rp0gz -query \"billing\" -mode full -byte-length 1024\n```\n\nFor `-mode full`, if you omit `-byte-length`, the CLI sends `512`. Valid range is `1`–`1024`.\n\n---\n\n## agents\n\n| Action | Flags | Notes |\n| ------ | ----- | ----- |\n| `list` | (globals only) | Site agents available for schedules |\n\n```bash\nkobold-cli agents list\n```\n\n---\n\n## schedules\n\n| Action | Flags | Notes |\n| ------ | ----- | ----- |\n| `intervals` | (globals only) | Fixed interval presets |\n| `list` | `-offset`, `-limit` | |\n| `get` | `-id` | Schedule id (`sch_…`) |\n| `create` | `-agent`, `-kb`, `-prompt`, `-interval`, `-hooks` | `-prompt` is text or a local file path; `-hooks` is a JSON file |\n| `enable` | `-id` | |\n| `disable` | `-id` | |\n| `delete` | `-id` | |\n\n```bash\nkobold-cli schedules intervals\nkobold-cli schedules list\nkobold-cli schedules create -agent ag_7k2m9x4q -kb kb_qc0rp0gz -prompt ./prompt.md -interval daily_09_00\nkobold-cli schedules create -agent ag_7k2m9x4q -kb kb_qc0rp0gz -prompt \"Summarize new files\" -interval every_hour -hooks ./hooks.json\nkobold-cli schedules enable -id sch_7k2m9x4q\nkobold-cli schedules disable -id sch_7k2m9x4q\nkobold-cli schedules delete -id sch_7k2m9x4q\n```\n\nHooks file shape:\n\n```json\n{\n  \"onComplete\": {\n    \"type\": \"webhook\",\n    \"webhook\": { \"url\": \"https://example.com/hook\", \"headers\": { \"Authorization\": \"Bearer …\" } }\n  },\n  \"onFail\": {\n    \"type\": \"webhook\",\n    \"webhook\": { \"url\": \"https://example.com/fail\" }\n  }\n}\n```\n\n---\n\n## HTTP mapping (quick)\n\n| CLI | HTTP |\n| --- | ---- |\n| `health check` | `GET /health` |\n| `echo send` | `POST /v1/echo` |\n| `stats get` | `GET /v1/stats` |\n| `agents list` | `GET /v1/agents` |\n| `schedules intervals` | `GET /v1/schedules/intervals` |\n| `schedules list` | `GET /v1/schedules` |\n| `schedules create` | `POST /v1/schedules` |\n| `schedules get` | `GET /v1/schedules/{schId}` |\n| `schedules enable` | `POST /v1/schedules/{schId}/enable` |\n| `schedules disable` | `POST /v1/schedules/{schId}/disable` |\n| `schedules delete` | `DELETE /v1/schedules/{schId}` |\n| `kb list` | `GET /v1/knowledgebases` |\n| `kb create` | `POST /v1/knowledgebases` |\n| `kb get` | `GET /v1/knowledgebases/{kbId}` |\n| `kb patch` | `PATCH /v1/knowledgebases/{kbId}` |\n| `kb delete` | `DELETE /v1/knowledgebases/{kbId}` |\n| `files tree` | `GET /v1/knowledgebases/{kbId}/files/tree` |\n| `files usage` | `GET /v1/knowledgebases/{kbId}/files/usage` |\n| `files mkdir` | `POST /v1/knowledgebases/{kbId}/files/mkdir` |\n| `files ingest` | `POST /v1/knowledgebases/{kbId}/files/ingest` |\n| `files rename` | `PATCH /v1/knowledgebases/{kbId}/files` |\n| `files delete` | `DELETE /v1/knowledgebases/{kbId}/files` |\n| `files content` | `GET /v1/knowledgebases/{kbId}/files/content` |\n| `index status` | `GET /v1/knowledgebases/{kbId}/status` |\n| `index sync` | `POST /v1/knowledgebases/{kbId}/sync` |\n| `search query` | `POST /v1/knowledgebases/{kbId}/search` |\n"}