{"slug":"getting-started","title":"Getting started","path":"getting-started.md","markdown":"# Getting started\n\n## 1. Get an API key\n\nCreate an API key in the Insula Labs product UI. Treat it like a password: anyone with the key can act as you on this API.\n\n## 2. Configure the CLI\n\n```bash\nexport KOBOLD_API_KEY='your-key-here'\n```\n\nOptional:\n\n```bash\nexport KOBOLD_BASE_URL='https://api.insulalabs.io'   # default if unset\n```\n\nYou can also pass credentials per command:\n\n```bash\nkobold-cli stats get -api-key 'your-key-here'\nkobold-cli stats get -base-url 'https://api.insulalabs.io'\n```\n\n| Flag | Env fallback | Default |\n| ---- | ------------ | ------- |\n| `-api-key` | `KOBOLD_API_KEY` | required for all `/v1` calls |\n| `-base-url` | `KOBOLD_BASE_URL` | `https://api.insulalabs.io` |\n| `-insecure` | — | `false` (skip TLS verify; local/dev only) |\n\n## 3. Build `kobold-cli`\n\nFrom the `web-api` checkout:\n\n```bash\nmake build\n./build/kobold-cli\n```\n\nOr from the monorepo root, after a full build, use `build/kobold-cli`.\n\nInvocation shape:\n\n```text\nkobold-cli \u003csection\u003e \u003caction\u003e [flags]\n```\n\nMost commands print indented JSON on stdout. Errors go to stderr and exit with status `1`.\n\n## 4. Smoke tests\n\n### Health (no API key)\n\n```bash\nkobold-cli health check\n```\n\n```json\n{\n  \"ok\": true\n}\n```\n\nHTTP equivalent: `GET /health` → `200` empty body. The CLI prints `{\"ok\": true}` after a successful empty response.\n\n### Echo (checks auth)\n\n```bash\nkobold-cli echo send -message hello\n```\n\n```json\n{\n  \"message\": \"hello\"\n}\n```\n\nHTTP: `POST /v1/echo` with `Authorization: Bearer …` and body `{\"message\":\"hello\"}`.\n\n### Stats\n\n```bash\nkobold-cli stats get\n```\n\nReturns your current plan ceilings (`limits`) and live counters (`usage`) for storage, knowledgebases, API keys, requests, uploads, downloads, tasks, and tokens. Use this to see where you stand before large uploads or many creates.\n\n### List knowledgebases\n\n```bash\nkobold-cli kb list\n```\n\nEmpty account:\n\n```json\n[]\n```\n\nOtherwise an array of knowledgebase objects (see [Knowledgebases](knowledgebases.md)).\n\n## Auth rules\n\n- Every path under `/v1/` requires a valid Bearer API key.\n- `/health` does not.\n- Missing or invalid keys → `401`.\n- The CLI reads the key from `-api-key` or `KOBOLD_API_KEY` and sends `Authorization: Bearer \u003ckey\u003e` for you.\n\n## Next steps\n\n- [CLI reference](cli-reference.md) — full command list\n- [Knowledgebases](knowledgebases.md) — create your first collection\n- [Files](files.md) — upload and organize content\n- [Index and search](index-and-search.md) — make content searchable\n"}