Team Knowledge Base CLI

@nzpr/kb is a package for managing a knowledge base that agents can read from and that humans can keep curated.

The core idea is simple:

• initialize a knowledge base
• propose knowledge
• publish approved knowledge
• search the current knowledge
• ask grounded questions against it

At the product level, a knowledge base is just a collection of documents, and each document should stay minimal:

• title
• text

Everything else is implementation detail.

Public API

The public surface of @nzpr/kb is the kb CLI.

• kb init-repo Initialize a knowledge base workspace. Use kb init-repo --interactive for a guided setup flow. Use --layout repo-root when this repository is itself the KB.

• kb create --title TEXT --text TEXT Propose a new knowledge document or a substantial update.

• kb publish Make the current approved documents become the live knowledge base.

• kb search "<query>" Return the closest matching knowledge documents.

• kb ask "<question>" Return a grounded answer from the closest matching knowledge.

• kb list List the current knowledge documents.

• kb catalog Return the current knowledge inventory in a machine-friendly form.

• kb doctor Check whether the knowledge base is healthy and queryable.

Lifecycle

The intended workflow is:

1. Initialize a knowledge base.
2. Propose knowledge.
3. Review and approve knowledge.
4. Publish knowledge.
5. Query knowledge.

Install

From npm:

npm install -g @nzpr/kb
kb --help

From source:

npm install
npm link

Commands

• kb init-repo [--dir PATH] [--repo OWNER/REPO]
• kb search "<terms>"
• kb ask "<question>"
• kb list
• kb catalog [--json]
• kb create --title TEXT --text TEXT [--path RELATIVE_PATH]
• kb publish --docs-root PATH

Knowledge Repo Workflow

In practice, the live knowledge usually lives in a separate repository that owns:

• kb/docs/
• the review flow for proposed knowledge
• the publish automation

Bootstrap that repo with:

kb init-repo --dir /path/to/knowledge-repo

If you want the CLI to walk you through setup and tell you what to do next:

kb init-repo --interactive

Layout options:

• --layout repo-root puts documents in docs/
• --layout nested-kb puts documents in kb/docs/

For a dedicated knowledge repository, prefer --layout repo-root.

Or bootstrap and configure it in one step:

export GITHUB_TOKEN=...
kb init-repo \
  --dir /path/to/knowledge-repo \
  --repo owner/knowledge-repo \
  --database-url postgresql://kb:kb@host:5432/kb \
  --embedding-mode bge-m3-openai \
  --embedding-api-url https://embeddings.example.com/v1/embeddings \
  --embedding-model BAAI/bge-m3

Inside that knowledge repo, the normal flow is:

1. Run kb init-repo once to scaffold the repo. If you provide --repo, --database-url, and GITHUB_TOKEN, it also configures the target repo and preflights the database.
2. Open or update a knowledge proposal issue.
3. Review and approve it there.
4. Materialize it into the configured docs directory.
5. After merge, that repo's CI runs kb publish against that docs directory.

kb init-repo is safe to rerun. It reports bootstrap status for:

• local scaffold creation
• knowledge document layout selection
• database preflight and schema initialization
• GitHub repo labels, variables, and secrets

In interactive mode it also:

• asks which repo and directory you want to initialize
• asks whether to wire GitHub setup now
• asks whether to verify the database now
• collects embedding settings if you want remote embeddings
• prints the next actions after initialization

If one remote step fails, the scaffold still stays in place and the command tells you what to rerun.

Runtime

Node.js 20+ is required.

Query commands need:

export KB_DATABASE_URL=postgresql://kb:kb@localhost:5432/kb

Higher-quality retrieval can use a self-hosted embeddings service:

export KB_EMBEDDING_MODE=bge-m3-openai
export KB_EMBEDDING_API_URL=https://embeddings.example.com/v1/embeddings
export KB_EMBEDDING_MODEL=BAAI/bge-m3
export KB_EMBEDDING_API_KEY=...

If KB_EMBEDDING_MODE is omitted, the CLI uses local hash embeddings for development.

Publishing needs one more privileged environment variable:

export KB_GITHUB_REPO=owner/repo
export GITHUB_TOKEN=...

Publishing is allowed when the provided GITHUB_TOKEN has write access to KB_GITHUB_REPO. Normal readers do not need GitHub credentials.

When kb init-repo is given --repo, it uses the same token to:

• enable issues in the target repo
• create or update the kb-entry and kb-approved labels
• write repository secrets and variables
• verify and initialize the target database schema if --database-url is provided

If you run kb init-repo without the repo or database inputs, it still scaffolds the knowledge repo and prints exactly which remote bootstrap inputs are still pending.

Quick Start

export KB_DATABASE_URL=postgresql://kb:kb@localhost:5432/kb
export KB_GITHUB_REPO=owner/repo
export GITHUB_TOKEN=...
docker compose -f docker-compose.pgvector.yml up -d
kb publish --docs-root ./docs
kb catalog --json
kb search "deployment rule"

Each Markdown file is indexed as one document and one vector row. Keep documents simple: one title and one body.

Optional Split Mode

If you later want separate entities, isolated databases, or a dedicated content repo, you can use kb create with:

export KB_GITHUB_REPO=org/knowledge-content
export GITHUB_TOKEN=...

That path is optional. The default assumption is that you work in one repo.

npm Release

The package is published as @nzpr/kb.

• local validation: npm test
• local package preview: npm pack --dry-run
• GitHub Actions publish: push a tag like v0.1.0 or run the npm-publish workflow manually
• npm authentication: use npm trusted publishing with GitHub Actions OIDC, not a long-lived publish token
• required npm setup: in npm package settings, configure trusted publishing for nzpr/kb and workflow file .github/workflows/npm-publish.yml

Using From A Knowledge Repo

The knowledge-authority repo should install this package in CI and use it to sync its configured docs directory into the vector database. For a dedicated KB repo with --layout repo-root, that directory is docs/:

npm install -g @nzpr/kb
export KB_GITHUB_REPO=owner/repo
export GITHUB_TOKEN=...
kb publish --docs-root ./docs

Or scaffold that repo first:

kb init-repo --dir .

If you want init to configure the target repo too:

export GITHUB_TOKEN=...
export KB_REPO_AUTOMATION_TOKEN=...
kb init-repo \
  --dir . \
  --repo owner/knowledge-repo \
  --database-url postgresql://kb:kb@host:5432/kb \
  --embedding-mode bge-m3-openai \
  --embedding-api-url https://embeddings.example.com/v1/embeddings \
  --embedding-model BAAI/bge-m3 \
  --embedding-api-key YOUR_KEY