kweaver-core

KWeaver CLI

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

Installation

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

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

Usage

kweaver [--base-url <url>] [--token <access-token>] [--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;the tables and reference are for quick lookup, and newly added flags (such as auth the --alias、BKN validate/push encoding option) 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 which you should first run kweaver config show; 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, with no additional parameters required). Do not check environment variables in advance, and do not ask the user to provide a password or Token.

Authentication priority

1. CLI global --token + --base-url(or existing KWEAVER_BASE_URL / active platform) → Stateless flag mode (pass the token once; this call does not read or write ~/.kweaver/; an expired token will not be automatically renewed; commands that modify local credentials such as auth login / logout cannot be used)
2. KWEAVER_TOKEN + KWEAVER_BASE_URL environment variable → static Token (if present, it is used first;will notuse refresh to exchange for a new one)
3. ~/.kweaver/ credentials (kweaver auth login written) → by defaultuse refresh_token to exchange for access_token (recommended)
4. 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. In the current platform config.json the businessDomain（kweaver config set-bd）
3. default bd_public(after the first login the CLI may have already 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 --no-browser、-u/-p HTTP /oauth2/signin；initial password(401001017) under TTY you can interactively change the password; for scripts use --new-password；auth change-password [<url>] [-u …](EACP password change; both the URL and -u can be omitted, falling back to the current platform and the currently active account respectively; no token required);auth list / auth users / auth switch; global --user / KWEAVER_USER；When there is no current platform auth status / whoami env can be used as a fallback (see references/auth.md）	references/auth.md
token	Print the current access token (auto-refresh)	token	—
config	Platform business domain (takes precedence over most bkn/agent/vega operations)	config show, config list-bd, config set-bd <uuid>	references/config.md
bkn	BKN knowledge network management, Schema, query, Action,metrics	bkn validate/push By default detects .bkn encoding;bkn metric Manage/query BKN metrics and metric data/calculation, see references/metric.md; for the rest see references/bkn.md	references/bkn.md, references/metric.md
agent	Agent CRUD, publish, 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> [--view tree|perf|evidence|reasoning|all] [--full] [--json]	references/agent.md
ds	Removed(CLI); data connections moved to vega catalog, CSV workflow merged into bkn create-from-csv. The SDK still retains client.datasources as a deprecated compatibility layer.	vega catalog list/get/create/discover/resources/delete、bkn create-from-csv	references/ds.md、references/vega.md
resource	vega-backend resources (table / logicview)	resource list、find --name、get、query、delete; for BKN binding use type=resource	references/resource.md
dataflow	Dataflow document workflow	dataflow list, dataflow run <dagId> --file <path>, dataflow run <dagId> --url <remote-url> --name <filename>, dataflow runs <dagId> [--since <date-like>], dataflow logs <dagId> <instanceId> [--detail]	references/dataflow.md
model	Model factory (mf-model-manager + mf-model-api)	model llm、model small、model llm chat、model small embeddings / model small rerank; large model model_type：llm / rlm / vu(see references/model.md); offline templates:model llm --template / model small --template	references/model.md
skill	Skill registration, marketplace lookup, progressive reading, download and installation	skill list、market、register --zip-file、content、read-file、install	references/skill.md
toolbox	Platform toolbox management	toolbox create --name <n> --service-url <url>、toolbox list、toolbox publish/unpublish <id>、toolbox delete <id> [-y]	references/toolbox.md
tool	Registration and enabling/disabling of tools in the toolbox (OpenAPI);execute/debug supports --path injection {param}	tool upload --toolbox <id> <openapi-spec>、tool list --toolbox <id>、tool enable/disable --toolbox <id> <tool-id>...、tool debug --toolbox <id> <tool-id> --path '{"id":"..."}'	references/tool.md
vega	Vega observability platform	vega health, vega catalog list, vega resource list, vega query execute -d <json>, vega sql --resource-type <t> --query "<sql>" / vega sql -d <json>	references/vega.md
context-loader	MCP hierarchical retrieval	context-loader --help, context-loader <subcommand> --help, context-loader search-schema <kn-id> <query>(also supports --kn-id <id> flag; when omitted, falls back to the deprecated context-loader config）	references/context-loader.md
call	Generic API call	call <url> [-X POST] [-d '...'](can use curl alias; supports --url、--data-raw etc., see kweaver --help）	references/call.md

Operation guide

Scenario	Description	Detailed reference
Confirm the business domain after login	config show; if abnormal or the list is empty → config list-bd → config set-bd <uuid>	references/config.md
Build a KN from a 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, resource query, etc.	references/troubleshooting.md
List/query vega-backend resources	list browse;find --name search by name (--exact/--wait）；query paginate to fetch data rows	references/resource.md
Manage Dataflow document workflows	list view the DAG;run trigger a local file or remote URL;runs --since view natural-day run records;logs --detail query step payloads	references/dataflow.md
Model factory / small model adapter	TS CLI：`model llm	small …、model llm chat、model small embeddings/model small rerank；Python SDK：client.models（CRUD/test + invocation.chat/embedding/rerank）；--adapter-code-file注册 Pythonmain` adapter
Python SDK (application code)	Use PyPI kweaver-sdk：KWeaverClient, authentication, pagination and troubleshooting; complementary to the CLI/MCP integration guide	docs/guides/python-sdk-guide.md · Chinese version
Trace data analysis	agent trace <cid> --view tree|perf|evidence|reasoning|all: the SDK already includes four views (call topology / performance breakdown / tool hit evidence chain / LLM reasoning process), no more manual assembly needed.--full turn off truncation of each message;--json get raw spans.	references/agent.md
Manage Skill	list / market find Skill;content / read-file progressive reading;install Download and extract for local use	references/skill.md
Register external tools	toolbox create Create box → tool upload Upload OpenAPI → tool list Get tool_id → tool enable Enable → toolbox publish Switch to published	references/toolbox.md · references/tool.md

Read on demand: when you need the full 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 用 resource find 模糊搜索名字含 BOM 的资源
/kweaver-core 列出所有 dataflow
/kweaver-core 触发 dataflow 123，上传本地文件 ./demo.pdf
/kweaver-core 查看 dataflow 123 在 2026-04-01 的运行记录
/kweaver-core 查看 dataflow 123 的实例 456 日志，并展开 input output
/kweaver-core 列出所有 Agent 模板
/kweaver-core 基于 "数据分析助手" 模板创建一个新的 Agent
/kweaver-core 在 skill market 里查找名字包含 kweaver 的 skill
/kweaver-core 读取 skill xxx 的 SKILL.md 并保存到本地目录
/kweaver-core 创建一个名为 weather-svc 的 toolbox，对接 https://weather.example.com
/kweaver-core 把 ./openapi.json 上传到 toolbox 1234567890 并启用所有工具，最后发布

Notes

• Do not guess the business_domain value. 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; on a 401 error the CLI will automatically attempt a refresh, and only if the refresh fails will it prompt the user to rerun kweaver auth login <url>

Query strategy (object-type query)

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