kweaver-core

KWeaver CLI

Command-line tool for the KWeaver platform, covering authentication, platform business domains (config), knowledge network management and query, Agent CRUD and conversations, data source management.

Installation

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

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

Usage

kweaver [--user <userId|username>] <command> [subcommand] [options]

The complete subcommands and parameters are subject to the currently installed CLI: run kweaver --help(or -h) to view the usage list synchronized with the code; to check the version use kweaver --version / -V / kweaver version. For subcommand details use kweaver <group> <subcommand> --help(for example kweaver auth --help、kweaver bkn push --help）。

Under this skill, references/*.md is aligned with CLI behavior;tables and reference are for quick lookup, and newly added flags (such as auth the --alias、BKN validate/push encoding options) are described in the reference.

Aliases：kweaver curl is equivalent to kweaver call；kweaver context is equivalent to kweaver context-loader。

Business domain: most requests depend on x-business-domain。kweaver auth login after that, kweaver config showshould be executed first; when the list is empty, use config list-bd to view the platform's available domains, then config set-bd <uuid>. See references/config.md。

Prerequisites

Authentication credentials are managed via ~/.kweaver/ . Default behavior: when refresh_token exists, use OAuth2 refresh_token authorization to exchange for a new access_token(executed automatically when expired or near expiry, no additional parameters needed). 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 (if present, use it first;will notuse refresh to exchange)
2. ~/.kweaver/ credentials (kweaver auth login written) → defaultuse refresh_token to exchange for access_token (recommended)
3. KWEAVER_USER environment variable (or global --user parameter) → use the specified user's credentials without switching the active user

Business domain priority (independent of authentication)

1. KWEAVER_BUSINESS_DOMAIN environment variable
2. Current platform config.json in businessDomain（kweaver config set-bd）
3. Default bd_public(after the first login the CLI may have automatically written a more appropriate value)

Command group overview

Command group	Description	Common commands	Detailed reference
auth	Authentication management (supports multiple accounts)	auth login <url> [--alias name](short form:auth <url> [--alias …]); optional -u/-p or --playwright；auth list(tree display of all platforms and users);auth users(list usernames);auth switch --user <username>(switch by username); global --user <name> can use the specified user's credentials without switching (env: KWEAVER_USER）；auth use / status / logout / delete supports platform URL or alias	references/auth.md
token	Print the current access token (auto-refresh)	token	—
config	Platform business domain (takes priority over most bkn/agent/ds operations)	config show, config list-bd, config set-bd <uuid>	references/config.md
bkn	BKN knowledge network management, Schema, query, Action	bkn validate/push default detection .bkn Encode and normalize to UTF-8, available --no-detect-encoding or --source-encoding gb18030; also pull、object-type、search、create-from-ds/create-from-csv etc., see references/bkn.md	references/bkn.md
agent	Agent CRUD, publishing, conversation, Trace, templates, categories	agent list, agent get <id>, agent create --name <n> --profile <p> --config <json>, agent publish <id> --category-id <cid>, agent chat <id> -m "..."、agent category-list, agent template-list, agent template-get <tpl_id>、agent sessions <agent_id>、agent history <conversation_id>、agent trace <conversation_id>	references/agent.md
ds	Data source management	ds list, ds get <id>, ds import-csv <ds_id> --files <glob> [--recreate]	references/ds.md
dataview	Atomic/custom data views (mdl-data-model)	dataview list、find --name、get、query（SQL / mdl-uniquery）、delete	references/dataview.md
skill	Skill registration, marketplace lookup, progressive reading, download and installation	skill list、market、register --zip-file、content、read-file、install	references/skill.md
vega	Vega observability platform	vega health, vega catalog list, vega resource list	references/vega.md
context-loader	MCP hierarchical retrieval	context-loader config show, context-loader kn-search <query>	references/context-loader.md
call	Generic API calls	call <url> [-X POST] [-d '...'](available curl alias; supports --url、--data-raw etc., see kweaver --help）	references/call.md

Operation guide

Scenario	Description	Detailed reference
Confirm business domain after login	config show; if abnormal or the list is empty → config list-bd → config set-bd <uuid>	references/config.md
Build KN from database/CSV	Connect data source → CSV import → create KN → build index → query verification → bind Agent	references/build-kn-from-db.md
CLI troubleshooting quick reference	Permissions, pull, build, import, dataview SQL, etc.	references/troubleshooting.md
List/query data views	list browse;find --name search by name (--exact/--wait）；query run SQL against the view	references/dataview.md
Trace data analysis	agent trace <conversation_id> get trace data, build evidence chain	—
Manage Skill	list / market find Skill;content / read-file progressive reading;install download and extract for local use	references/skill.md

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

Invocation examples

/kweaver-core 列出所有知识网络
/kweaver-core 查看 Vega 健康状况
/kweaver-core 有哪些 Agent
/kweaver-core 跟 Agent xxx 对话，问他"今天库存情况"
/kweaver-core 搜索知识网络 xxx 中关于"供应链"的内容
/kweaver-core 用 dataview find 模糊搜索名字含 BOM 的数据视图
/kweaver-core 列出所有 Agent 模板
/kweaver-core 基于 "数据分析助手" 模板创建一个新的 Agent
/kweaver-core 在 skill market 里查找名字包含 kweaver 的 skill
/kweaver-core 读取 skill xxx 的 SKILL.md 并保存到本地目录

Notes

• Do not guess the business_domain value yourself. On first use, run kweaver config show or kweaver config list-bd 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 (you can also use config list-bd to list from the platform and then set-bd, or obtain it from the platform UI request headers X-Business-Domain）
• Action execution has side effects; confirm with the user before executing
• Do not run kweaver auth status for pre-checks. Execute the target command directly; the CLI will automatically handle authentication and token refresh
• Token expires in 1 hour. When ~/.kweaver/ contains refresh_token(obtained via OAuth2 login), the CLI willautomatically refresh; with only Playwright cookie login (no refresh_token), the user needs to rerun kweaver auth login <url>. When encountering a 401 error, the CLI will automatically attempt to refresh, and only prompts the user to log in again if the refresh fails

Query strategy (object-type query)

When calling object-type query you must limit limit, use search_after for pagination, use condition for filtering, to avoid wide-table JSON truncation. For complete rules and examples, see references/bkn.md。