openbkn

openbkn CLI

Unified command-line tool for the BKN platform — one binary, with the operations surface consolidated into openbkn admin subcommands. Pure backend, no Web UI.

Hard gate for third-party Agent business Q&A

• Business Q&A must be managed: each round first call bkn_start_interaction, must pass question、agent_name(same name each round) and conversation_mode: for the first round use new and do not pass conversation_id, for subsequent rounds use continue and pass the conversation_id。
• Use only authoritative IDs: business tools must use verbatim the conversation_id and interaction_idreturned by start; do not fabricate, guess, or reuse example values.
• Keep business calls managed: access OpenBKN only through the Context Loader tool carrying the above IDs; Operation, retries, and evidence closure are managed by the platform.
• Submit the current round's result: after the answer is generated, call bkn_finish_interaction; it submits only the current Interaction's result and does not close the Conversation.
• Stop on error: return the original error and follow required_action; do not fall back to CLI, Vega, ontology-query, or calls without a managed context.

See the detailed contract at context.md。

Installation

npm install -g @openbkn/bkn-sdk      # 提供 `openbkn` 命令

Requires Node.js 22.19.0+. You can also use npx @openbkn/bkn-sdk to run temporarily.

Usage

openbkn [--base-url <url>] [--token <tok>] [--user <id|name>] \
        [--json | --compact] [-k|--insecure] <group> <sub> [options]

• Default output ishuman-readable table；--json(or --compact) outputs precise JSON that can be parsed by scripts.
• -k/--insecure disables TLS verification (self-signed platform).auth login -k is remembered per platform, so subsequent commands for that platform need not include it; verification exemption applies only to requests for that platform, does not touch process globals, and requires no NODE_TLS_REJECT_UNAUTHORIZED。
• based on the live --help . openbkn --help to see the grouped command map,openbkn <group> <sub> --help to see exact parameters.Do not guess parameters。
• By default, check whether the SDK and platform base versions match, ignoring RC and build suffixes:0.2.0 can match 0.2.0-rc.1 or 0.2.0-rc.2. Across base versions or when the platform reports a placeholder version, the CLI can explicitly add --skip-version-check; the SDK can set BKN_SKIP_VERSION_CHECK=1。

Authentication (credentials are stored hierarchically by platform/user in ~/.bkn/, can be overridden with BKN_CONFIG_DIR )

Priority:

1. Global --token + --base-url(or environment BKN_BASE_URL / active platform) → one-off stateless, does not read or write ~/.bkn/。
2. Environment BKN_TOKEN + BKN_BASE_URL → static token.
3. ~/.bkn/ credentials (openbkn auth login written) → recommended; multi-user hierarchical.
4. Global --user <id|name>(or BKN_USER) → among multiple users already stored for that platform, specify which one to use this time; effective only this time, does not change the active user.BKN_PROFILE → switch the entire profile.

openbkn auth login <url> --token "$TOKEN"      # 附加已有 token（CI/headless）
openbkn auth login <url> -u <user> -p <pwd>    # headless 凭据登录（device-code，无浏览器）
openbkn auth login <url>                        # 打开浏览器批准 device code
openbkn auth login <url> --device               # 只打印 URL+code，在任意机器批准
openbkn auth status | whoami | token | list | use <url> | switch <url> <user> | logout

Command group overview

Command group	Description	Common commands
auth	Authentication / session / multi-user	login（--token / -u -p / browser / --device, all via device-code),status/whoami/token/list/use/switch/users/export、change-password
config	Platform CLI configuration	config show / config set <key> <value>
appkey	User self-issued AppKey (bak_ long-term credential, only available to Context Loader)	list、create --name <s> [--expire-days <n> | --expires-at <rfc3339> | --never-expire](plaintext key returned only once）、regenerate <id>(rotation: a new key is issued for the same id, the old key is invalidated immediately),revoke <id>、admin list [--owner-id]/admin revoke <id>
bkn	Knowledge network + Schema + query + local package	list/get/search/stats/export、object-type/relation-type/action-type list/get/create/update/delete、action-type query/execute、metric …、concept-group …、capability list/attach/detach、action-log/action-schedule …、subgraph、relation-type-paths、resources、push <dir>/pull <kn> [dir]、validate <dir>、create-from-catalog <catalog> --name … --pk-map t:col
resource	Vega-backend resources	list/get/find --name/query/delete
vega	Catalog + resources + index build + SQL	catalog list/get/stats、catalog resources、resource create/update/delete/build、build-task list/get/start/stop/delete、connector-type list/get、index-capabilities、sql --query "<sql>"(direct connection to MySQL/PG/OpenSearch, SQL uses {{resource-id}} placeholder)
context	Context Loader (MCP retrieval)	info/tools <kn>、kn-detail/object-types/relation-types、search-schema <kn> "<q>"、query-object-instance/query-instance-subgraph/explore-subgraph/query-metric/get-logic-properties/get-action-info --args '<json>'、run-cypher --query、run-sql --sql、search-capabilities、tool-call <kn> <tool> --args、conversation [--forget]. For third-party Agent business Q&A, use MCP bkn_start_interaction/bkn_finish_interaction; when the CLI has no managed context, open a managed session itself and remember it
mcp	Registered MCP Server	list/get/tools read-only discovery; does not include Market, registration, publishing, or invocation
model	Model factory	llm/small list/get/add/edit/delete/test、llm chat <name|id> -m "…" [--stream](id is automatically resolved to name),small embeddings/rerank <name|id>(id is automatically resolved to name),llm set-default/unset-default <id>、small set-default/unset-default <id>、small get-default [--type embedding|reranker]
skill	Skill registration/market/lifecycle/sandbox execution	list/market/get/names <id...>/content/read-file/files [path] [--tree]/history/set-status、execute <id> --entry '<shell>'、register <dir>/download/install、update-metadata/update-package、republish/publish-history；content/read-file with --raw(want the body rather than the object storage URL);content/read-file/files/download with --draft(read the draft version rather than the published version)
toolbox	Toolbox container	list/create --name <n> [--type openapi|function] [--service-url <url>]/publish/unpublish/delete/export/import。execute requires the container to have been publish(unpublished/offline returns 400 ToolNotAvailable），debug not required
sandbox	Temporary code (does not register anything)	run <file> --event '<json>' [--timeout <s>] [--pass-token]、infer-schema、deps、versions、template、generate <type> [--timeout <s>]/prompt <type>(platform model generates code/parameter metadata, client waits 300 seconds by default, default gateway times out with 504 after 60 seconds). The entry function must be named handler; success or failure is determined by exit_code not the HTTP code; long tasks run here
function	Registered function tools (--type function container)	create <file> --toolbox <id> --name <n>/list/get/update/delete、enable/disable、debug/execute(result is in body.result). Flow create → enable → toolbox publish → execute; invocation via the toolbox is cut off after about 30 seconds (200 + result: null）
api	Registered OpenAPI tools (--type openapi container)	import <spec> --toolbox <id>（JSON/YAML，failure_count non-zero means non-zero exit)/list/get/update/delete、enable/disable、debug/execute. Flow import → enable → toolbox publish → execute
tool	Type-agnostic advanced entry point (compatible with legacy automation)	create <file> --toolbox <id> [--type openapi]/upload <spec>/list/get/update/delete、enable/disable、execute/debug; new flows should prefer function / api
trace	BKN Trace	get、search、diagnose <conv> [--llm](symbol rules + LLM rubric + synthesizer),scan <conv,…>、eval-set build <queries>、schema validate <file>
admin	Operations	org/user/role … CRUD + reset-password、row-filter get/apply/delete/explain(enterprise edition row filtering policy),license show/import/receipt/activate/remove/fingerprint(cluster authorization),audit list、llm/small-model …、auth …、config、call
call(alias curl）	Generic API passthrough	call <url> [-X POST] [-d '<json>']

Go deeper on demand: when you need the full parameters of a command, run openbkn <group> <sub> --help, or read the corresponding quick reference.

• Before configuring the full-text index, use vega index-capabilities to query the analyzers supported by the deployment; returns the list and check time, see vega.md。
• bkn metric validate for details. Success or failure of valid；false is determined by the returned data_properties . The object-type bkn.md。

This CLI does not yet cover the platform capabilities of(don't guess commands, directly use openbkn call to hit the raw API):

• Agent runtime bkn-agent（/api/bkn-agent/v1/agents、/chat、/run、/tasks、/prompts）
• Execute the write, Market, and invocation surfaces of Factory MCP (/api/agent-operator-integration/v1/mcp）
• Skill index build task (/api/agent-operator-integration/v1/skills/index/build）
• openbkn call /api/<service>/v1/... [-X POST] [-d '<json>'] will automatically inject authentication headers.
• The API documentation is in https://openbkn-ai.github.io/bkn-foundry/ — interactive, module-grouped OpenAPI (bkn-backend / context-loader / ontology-query / vega-backend / execution-factory / agent-observability / bkn-agent). First check the exact path and request body there, then call, and do not guess paths.

Note: there is no such thing as "whole-network construction" for a knowledge network. First use openbkn vega resource update <resource-id> to save the index configuration, then use openbkn vega resource build <resource-id> to create the BuildTask.

Detailed reference (references/)

Topic	File
Authentication / Session / Multi-user	auth.md
AppKey issuance / revocation (bak_）	appkey.md
Knowledge Network + Schema + Query + Network Construction	bkn.md
Model Factory	model.md
Vega Catalog + Index Construction	vega.md
vega-backend resources	resource.md
Context Loader（MCP）	context.md
Registered MCP Server (read-only discovery)	mcp.md
Skill registration / lifecycle	skill.md
Write a Skill package / sandbox function (bkn-osdk)	create-skill skills
Toolbox / API / Tool	toolbox.md
Sandbox / Function (code→function tool)	function.md
Read the knowledge network in Python (bkn-osdk)	osdk.md
BKN Trace（diagnose / eval-set）	trace.md
Operations (org/user/role/row-filter/audit)	admin.md
Generic API passthrough	call.md

Operation Guide

Scenario	Reference
Build a knowledge network end-to-end from Vega Catalog (CSV must first be loaded into a data source)	build-kn.md
Repeatedly fetch data within one Q&A / sandbox code needs to read the knowledge network	osdk.md — switch to Python; business Q&A still stays attached to the current turn
Troubleshooting quick reference (401 / retry / empty list / 403 / audit permissions / no trace data)	troubleshooting.md

Invocation examples

/openbkn 列出所有知识网络
/openbkn 搜索知识网络 xxx 中关于"供应链"的内容
/openbkn 从 Vega catalog vcat-1 建一个名为 customers 的知识网络并构建索引
/openbkn 把本地 ./my-bkn 目录校验后 push 上去
/openbkn 诊断会话 conv-123 的 trace，带 LLM 判定
/openbkn 在 skill market 里找名字含 retrieval 的 skill 并安装到 ./out
/openbkn 把 ./openapi.json 上传到 toolbox 1234567890
/openbkn 列出组织结构；给用户 u-1 重置密码

Notes

• Do not pre-check: directly execute the target command; authentication is handled by the CLI (in token mode it does not auto-renew;~/.bkn/ credentials can be refreshed).
• Do not guess parameters: use real-time --help; if the list is empty, first confirm the current account's permissions and whether the target resource exists.
• Do not guess request body fields: for commands with --body / --body-file , its --body description states which module of https://openbkn-ai.github.io/bkn-foundry/ to check the shape in (for definition changes see bkn-backend, for data fetching/execution see ontology-query, for skill/tool see execution-factory, for managed interactions see agent-observability).context 's --args exception: the shape is the MCP tool's own input schema, retrieve it with context tools <kn-id> .
• Destructive operations（bkn/admin 's delete,admin user reset-password, Action execution) act on production; confirm with the user before execution.
• trace diagnose --llm, rubric/synthesizer uselocal claude CLI to make judgments;claude automatically degrades to pure symbols when not in PATH.
• Wide-table query (object-type query / context query-object-instance) must limit limit, and use pagination and condition filtering to avoid JSON truncation.