---
name: kb-drop
description: Cited answers from a team's own documents. Use it when the user asks what their company's documents or policies say (e.g. 'What is our refund policy?'), or to connect Slack or apps, create, query, or write code against kbDrop knowledge bases.
metadata:
  author: kbDrop
  version: "2.5.0"
  homepage: "https://kbdrop.io"
---

# Use kbDrop

## Choose the destination

For Slack or app setup, read the [integration guide](https://kbdrop.io/docs/integrations.md).
Slack uses https://kbdrop.io/integrations/slack: reuse or approve the workspace,
select multiple knowledge bases, save, check access and verify a cited Slack reply.
No CLI, API key or custom Slack app is needed. Channel selections replace the
workspace default, which also covers DMs; keep it empty for channel-only access.
Reuse connections; resume after owner approval.

Coding agents use https://kbdrop.io/integrations/cli and the CLI below.
Requires Node.js 24+ and npm; use npx without a global install. Skill installation
is optional. Teams and the hosted Claude Desktop connector are not live.

Read the [CLI contract](https://kbdrop.io/docs/api/reference.md) for fields and limits.

## Authenticate

Queries without `--knowledge-base` search the CLI's connected bases together;
choose them on its setup page. To resolve a specific name, use `knowledge-bases
list --json` if management consent already exists; follow `next_cursor`.

1. Run `npx @kbdrop/cli@latest auth status --json`. Inspect
   `data.authenticated` and `data.source`: exit `0` and `ok: true` also occur
   when logged out. Query credentials are `KB_DROP_API_KEY`, then
   `KB_DROP_MANAGEMENT_KEY` with `knowledge:query`, then saved OAuth.
   Environment keys need no keychain/login.
2. If unauthenticated, run `npx @kbdrop/cli@latest auth login` for browser
   sign-in and consent. New users can
   [register](https://kbdrop.io/register). Remote terminals can use
   `auth login --device --no-browser`.
3. OAuth requires macOS Keychain, Windows Credential Manager, or Linux Secret
   Service. On `keychain_unavailable`, configure/unlock one or use an
   environment key from a secret manager; logging in again cannot help.

Never request credentials in chat or arguments. Deletion and keys stay in the browser.

## Create a knowledge base

Only when asked; ingestion uses quota. If `auth status` shows
`data.management: null`, use `auth login --manage` for owner consent or a
secret manager's `KB_DROP_MANAGEMENT_KEY`. Save one UUID per knowledge base:

```bash
export KB_DROP_CREATE_ID="$(node -p 'crypto.randomUUID()')"
npx @kbdrop/cli@latest knowledge-bases create \
  --idempotency-key "$KB_DROP_CREATE_ID" \
  --url https://docs.example.com --name "Docs" --wait --json
```

`--file`, `--zip`, and `--video-url` take other sources. Keep
`data.knowledge_base.id`. Exit `9` means ingestion failed. On `5`, `6`, or
`10`, reuse the command and key to resume without creating duplicates.
Check `knowledge-bases status <id> --json` if waiting stalls. If
`data.ingestion_job.next_action` is `review`, first have the owner answer
`data.ingestion_job.links.review_page` in the browser; rerunning cannot
answer a review. See the management API for automated review answers.

## Ask a cited question

Use `--input-file` with a UTF-8 file. `--input -` reads stdin; literal
`printf`/`echo` commands expose the question in arguments.

Save a new UUID in `KB_DROP_REQUEST_ID` per logical question, then run:

```bash
npx @kbdrop/cli@latest ask \
  --input-file ./question.txt \
  --idempotency-key "$KB_DROP_REQUEST_ID" \
  --json
```

Retry `ask` with the saved key and unchanged input/options after a lost response.
Bound retries, then report the error and key. Never bypass `operation_failed`
or `idempotency_mismatch`; follow the contract’s recovery rules.

Parse stdout JSON and require `ok: true`. Use `data.answer` or `data.output`,
preserving `data.citations`, citation IDs, links, and locators.
Exit `8` means insufficient evidence: report
`data.insufficient_evidence` instead of inventing an answer. Errors are JSON
on stderr; retain the exit status.

Use `--response-schema <file>` for structured output; keep JSON Pointer claims
and citation IDs with the fields.

## Retrieve evidence

```bash
npx @kbdrop/cli@latest search \
  --input-file ./query.txt \
  --json
```

Repeat `--language`; use `--path-prefix` once. Check `data.results` for
supporting evidence; report `data.empty.reason` when empty.

## Direct HTTPS integration

`POST /v1/messages` and `/v1/search` use the key's connected knowledge bases
(OAuth/management key: the CLI selection). Citations identify `knowledge_base`.
Per-base URLs query one. Follow the [contract](https://kbdrop.io/docs/api/reference.md)
for authentication, JSON/SSE, limits and retry recovery. Keep credentials out of
browser code, prompts, repositories and arguments. Never log questions, excerpts,
signed URLs or input paths. Preserve idempotency keys across ambiguous retries.