kweaver

KWeaver CLI

A command-line tool for the KWeaver platform, covering authentication, knowledge network management and queries, Agent CRUD and conversations, and data source management.

This skill replaces the old version kweaver-core, adding the Vega observability platform, BKN push/pull, and other features. The old version is still usable but no longer updated.

Installation

npm install -g @kweaver-ai/kweaver-sdk

Requires Node.js 22+. You can also use npx kweaver to run temporarily.

Usage

kweaver <command> [subcommand] [options]

Prerequisites

Authentication credentials are managed through ~/.kweaver/ , supporting automatic refresh. It is forbidden to check environment variables in advance, and forbidden to ask the user to provide a password or Token.

Authentication priority

1. KWEAVER_TOKEN + KWEAVER_BASE_URL environment variable → static Token (used first if it exists,will notrefresh automatically)
2. ~/.kweaver/ credentials (kweaver auth login written) → automatic refresh (recommended)

Command group overview

Command group	Description	Common commands	Detailed reference
auth	Authentication management	auth login <url>, auth status, auth list	references/auth.md
token	Print the current access token (auto-refresh)	token	—
bkn	BKN knowledge network management, Schema, query, Action	bkn list, bkn get <id>, bkn search <id> <query>	references/bkn.md
agent	Agent CRUD, publishing, conversation	agent list, agent get <id>, agent chat <id> -m "..."	references/agent.md
ds	Data source management	ds list, ds get <id>	references/ds.md
vega	Vega observability platform	vega health, vega catalog list, vega resource list	references/vega.md
config	Platform configuration (business domain, etc.)	config show, config set-bd <uuid>	references/config.md
context-loader	MCP hierarchical retrieval	context-loader config show, context-loader kn-search <query>	references/context-loader.md
call	Generic API calls	call <path> [-X POST] [-d '...']	references/call.md

Read on demand: when you need the complete parameters of a subcommand or an orchestration example, read the corresponding reference file.

Call examples

/kweaver 列出所有知识网络
/kweaver 查看 Vega 健康状况
/kweaver 有哪些 Agent
/kweaver 跟 Agent xxx 对话，问他"今天库存情况"
/kweaver 搜索知识网络 xxx 中关于"供应链"的内容

Notes

• Do not guess the business_domain value yourself. On first use, run kweaver config show to confirm the current business domain. If it returns bd_public (default) but the command result is empty, you may need to use kweaver config set-bd <uuid> to set the correct value (obtain it from the request header in the platform UI X-Business-Domain）
• Action execution has side effects; confirm with the user before executing
• It is forbidden to run kweaver auth status for pre-checks. Execute the target command directly; the CLI will automatically handle authentication and token refresh
• Tokens expire after 1 hour. When ~/.kweaver/ contains refresh_token(obtained via OAuth2 login), the CLI willrefresh automatically; for Playwright cookie login only (no refresh_token), the user needs to rerun kweaver auth login <url>. When a 401 error occurs, the CLI will automatically try to refresh, and only prompt the user to log in again if the refresh fails

Query strategy (important)

All object-type query calls must follow the rules below, otherwise overly large returned data will cause JSON truncation and parsing failures:

1. limit must be ≤ 30. The CLI defaults to limit=30;it is forbiddento pass a larger value (such as 50 or 100).BOM (Bill of Materials) requires particular attention: a single record has many fields, and one product may have multiple BOM versions. It is recommended to use limit ≤ 10 and use condition to filter down to a specific version number. For other wide tables (work orders, PR, PO), it is recommended to use limit ≤ 20
2. When more data is needed, use search_after pagination, do not increase the limit:

   # 第一页
   kweaver bkn object-type query <kn> <ot> '{"limit":20}'
   # → 返回 search_after: ["v1","v2","v3"]
   # 第二页
   kweaver bkn object-type query <kn> <ot> '{"limit":20,"search_after":["v1","v2","v3"]}'
   

3. Try to use condition filteringto narrow the returned set: filter precisely or fuzzily by number, name, status, etc., to avoid full table scans
4. Prefer ==、like、in operators(SQL view compatible).match/contain Only supported by OpenSearch indexes; will error under SQL views
5. Note for historical data: object types such as PR/PO/work orders/BOM may contain a large number of historical versions. When querying, limit to the current batch using conditions such as date, document number, and status, to avoid mixing in completed historical records