@kweaver-ai/kweaver-sdk 0.6.10 → 0.7.2

package/README.md

@@ -31,7 +31,7 @@ export KWEAVER_BASE_URL=https://your-kweaver-instance.com
 export KWEAVER_TOKEN=your-token
 ```
 
-With both set, API commands use that token even if you never ran `auth login`. You can also run **`kweaver auth status`**, **`kweaver auth whoami`** (supports `--json`), and **`kweaver config show`** when there is **no** current platform in `~/.kweaver/`. In env-token mode, `whoami` resolves the bound identity from EACP `/api/eacp/v1/user/get` and prints `Type` (user/app), `User ID`, `Account` and `Name`; this works for both opaque and JWT tokens. If EACP is unreachable, the CLI falls back to local JWT decode and prints a short hint when the token is opaque.
+With both set, API commands use that token even if you never ran `auth login`. The same applies to **`kweaver --base-url <url> --token <access-token> <command>`** (stateless flag mode; see [Stateless token mode](#stateless-token-mode)). You can also run **`kweaver auth status`**, **`kweaver auth whoami`** (supports `--json`), and **`kweaver config show`** when there is **no** current platform in `~/.kweaver/`. In env-token mode, `whoami` resolves the bound identity from EACP `/api/eacp/v1/user/get` and prints `Type` (user/app), `User ID`, `Account` and `Name`; this works for both opaque and JWT tokens. If EACP is unreachable, the CLI falls back to local JWT decode and prints a short hint when the token is opaque.
 
 `kweaver config list-bd` lists business domains for the current user. App (service) tokens are not bound to an end-user — when the backend rejects the call with `401 invalid user_id`, the CLI re-checks the token type via EACP and, if confirmed `type:"app"`, replaces the cryptic backend body with `This command does not support app accounts.`. Use a user token (interactive `auth login`) for user-bound endpoints.
 
@@ -143,15 +143,20 @@ const rows = await client.vega.sqlQuery(
   JSON.stringify({ query: "SELECT * FROM {{res-1}} LIMIT 5", resource_type: "mysql" }),
 );
 
-// Context Loader (semantic search over a BKN via MCP)
+// Context Loader (MCP search_schema plus generic tools/call)
 const cl      = client.contextLoader(mcpUrl, "bkn-id");
-const results = await cl.search({ query: "hypertension treatment" });
+const schema  = await cl.searchSchema({ query: "hypertension treatment" });
+const rawTool = await cl.callTool("search_schema", { query: "hypertension treatment" });
 
 // Skills (registry + market + progressive read)
 const skills = await client.skills.market({ name: "kweaver" });
 const skillMd = await client.skills.fetchContent("skill-id");
 ```
 
+`searchSchema()` is the typed wrapper for the Context Loader MCP `search_schema` tool. It defaults `response_format` to `json` and accepts `query`, `response_format`, `search_scope`, `max_concepts`, `schema_brief`, and `enable_rerank`. The parsed response may contain `object_types`, `relation_types`, `action_types`, and `metric_types`.
+
+Use `callTool(name, args)` when you need native MCP `tools/call` access for newly added server tools before the SDK adds a typed wrapper. Arguments are passed through unchanged.
+
 ## CLI Reference
 
 ```
@@ -183,8 +188,10 @@ kweaver bkn action-log list/get/cancel
 kweaver agent list/get/create/update/delete/chat/sessions/history/publish/unpublish
 kweaver skill list/market/get/register/status/delete/content/read-file/download/install
 kweaver vega health/stats/inspect/sql/catalog/resource/connector-type
-kweaver context-loader config set/use/list/show
-kweaver context-loader kn-search/query-object-instance/...
+kweaver context-loader tools|resources|templates|prompts <kn-id>
+kweaver context-loader search-schema|tool-call|kn-search|kn-schema-search <kn-id> <query|name> [...]
+kweaver context-loader query-object-instance|query-instance-subgraph|get-logic-properties|get-action-info|find-skills <kn-id> ...
+kweaver context-loader config set/use/list/show                       (deprecated; <kn-id> may be omitted to fall back to saved config)
 kweaver toolbox create/list/publish/unpublish/delete
 kweaver tool upload/list/enable/disable
 kweaver call <path> [-X METHOD] [-d BODY] [-H header] [-F key=value]
@@ -246,10 +253,33 @@ kweaver tool enable --toolbox <BOX_ID> <TOOL_ID>
 | `KWEAVER_BASE_URL` | KWeaver instance URL |
 | `KWEAVER_BUSINESS_DOMAIN` | Business domain identifier |
 | `KWEAVER_TOKEN` | Access token |
+| `KWEAVER_TOKEN_SOURCE` | Internal sentinel set by the CLI when `--token` is passed; do not set manually |
 | `KWEAVER_NO_AUTH` | Set to `1`/`true`/`yes` to use no-auth sentinel when `KWEAVER_TOKEN` is unset (with `KWEAVER_BASE_URL` or active platform) |
 | `KWEAVER_TLS_INSECURE` | Set to `1` or `true` to skip TLS certificate verification for all HTTPS in the process (dev only; prefer `kweaver auth … --insecure` which saves per platform) |
 | `NODE_TLS_REJECT_UNAUTHORIZED` | Node.js built-in TLS switch: set to `0` to skip certificate verification for HTTPS in this process. The `kweaver` CLI sets this when `KWEAVER_TLS_INSECURE` is set or the saved token has insecure TLS (same scope as above; dev only). |
 
+### Stateless token mode
+
+Pass an access token via `--token` for fully stateless invocations (no read or write of `~/.kweaver/` for that token):
+
+```bash
+kweaver --base-url https://platform.example.com --token "$TOK" bkn list
+```
+
+Resolution order:
+
+| Source | base-url | token |
+|--------|----------|-------|
+| flag   | `--base-url` | `--token` |
+| env    | `KWEAVER_BASE_URL` | `KWEAVER_TOKEN` |
+| disk   | active platform | OAuth session (refreshable) |
+
+When `--token` is used, write-disk commands (`auth login` / `logout` / `use` / `delete` / `switch`, `config set-bd`, the entire `context-loader config` group) error out — drop `--token` or use `kweaver auth login` for a saved session.
+
+`auth whoami` / `auth status` distinguish the two stateless modes: `Source: CLI (flag: --token)` for flag mode, `env (KWEAVER_TOKEN)` for env mode (`whoami --json` uses `"source": "flag"` vs `"source": "env"`).
+
+`kweaver context-loader` runtime subcommands accept `<kn-id>` as the first positional (e.g. `kweaver context-loader tools <kn-id>`) or via the global `--kn-id <id>` / `-k <id>` flag, so they work in stateless mode without any saved config. The `context-loader config set|use|list|remove|show` management group is deprecated, prints a warning on use, and is disabled in its entirety under `--token`.
+
 ### TLS Certificate Troubleshooting
 
 If you encounter errors like `fetch failed`, `self-signed certificate`, or `UNABLE_TO_GET_ISSUER_CERT`, the target server likely uses a self-signed certificate or Kubernetes Ingress default fake certificate. Try the following in order of preference:

package/README.zh.md

@@ -136,15 +136,20 @@ const rows = await client.vega.sqlQuery(
   JSON.stringify({ query: "SELECT * FROM {{res-1}} LIMIT 5", resource_type: "mysql" }),
 );
 
-// Context Loader（通过 MCP 对 BKN 做语义搜索）
+// Context Loader（MCP search_schema + 通用 tools/call）
 const cl      = client.contextLoader(mcpUrl, "bkn-id");
-const results = await cl.search({ query: "高血压 治疗" });
+const schema  = await cl.searchSchema({ query: "高血压 治疗" });
+const rawTool = await cl.callTool("search_schema", { query: "高血压 治疗" });
 
 // Skill（注册表/市场/渐进式读取）
 const skills = await client.skills.market({ name: "kweaver" });
 const skillMd = await client.skills.fetchContent("skill-id");
 ```
 
+`searchSchema()` 是 Context Loader MCP `search_schema` 的类型化封装，默认 `response_format` 为 `json`，支持 `query`、`response_format`、`search_scope`、`max_concepts`、`schema_brief`、`enable_rerank`。解析后的返回结果可能包含 `object_types`、`relation_types`、`action_types`、`metric_types`。
+
+需要直接使用 MCP 原生 `tools/call` 时，使用 `callTool(name, args)`。这适用于服务端新增工具但 SDK 尚未提供类型化封装的场景，参数会原样透传。
+
 ## 命令速查
 
 ```
@@ -171,8 +176,10 @@ kweaver bkn action-log list/get/cancel
 kweaver agent list/get/chat/sessions/history
 kweaver skill list/market/get/register/status/delete/content/read-file/download/install
 kweaver vega health|stats|inspect|sql|catalog|resource|connector-type
-kweaver context-loader config set/use/list/show
-kweaver context-loader kn-search/query-object-instance/...
+kweaver context-loader tools|resources|templates|prompts <kn-id>
+kweaver context-loader search-schema|tool-call|kn-search|kn-schema-search <kn-id> <query|name> [...]
+kweaver context-loader query-object-instance|query-instance-subgraph|get-logic-properties|get-action-info|find-skills <kn-id> ...
+kweaver context-loader config set/use/list/show                       （deprecated；省略 <kn-id> 时回退到已保存配置）
 kweaver call <path> [-X METHOD] [-d BODY] [-H header]
 ```
 
@@ -213,10 +220,33 @@ kweaver vega sql -d '{"resource_type":"mysql","query":"SELECT * FROM {{res-1}} L
 | `KWEAVER_BASE_URL` | KWeaver 实例地址 |
 | `KWEAVER_BUSINESS_DOMAIN` | 业务域标识 |
 | `KWEAVER_TOKEN` | 访问令牌 |
+| `KWEAVER_TOKEN_SOURCE` | CLI 传入 `--token` 时由程序设置的内部标记；请勿手动设置 |
 | `KWEAVER_NO_AUTH` | 设为 `1`/`true`/`yes` 且未设置 `KWEAVER_TOKEN` 时使用 no-auth 占位（需 `KWEAVER_BASE_URL` 或已选平台） |
 | `KWEAVER_TLS_INSECURE` | 设为 `1` 或 `true` 时跳过 TLS 证书校验（仅开发；更推荐 `kweaver auth … --insecure` 以按平台持久化） |
 | `NODE_TLS_REJECT_UNAUTHORIZED` | Node.js 内置 TLS 开关：设为 `0` 时在本进程内跳过 HTTPS 证书校验。`kweaver` 在 `KWEAVER_TLS_INSECURE` 生效或已保存 token 为不安全 TLS 时会设置此项（范围同上；仅开发）。 |
 
+### Stateless token 模式
+
+通过 `--token` 传入访问令牌，该次调用对该 token 路径既不读也不写 `~/.kweaver/`：
+
+```bash
+kweaver --base-url https://platform.example.com --token "$TOK" bkn list
+```
+
+来源优先级：
+
+| 来源 | base-url | token |
+|------|----------|-------|
+| flag | `--base-url` | `--token` |
+| env  | `KWEAVER_BASE_URL` | `KWEAVER_TOKEN` |
+| 磁盘 | active platform | OAuth 会话（可 refresh） |
+
+`--token` 模式下会禁用写盘命令：`auth login` / `logout` / `use` / `delete` / `switch`、`config set-bd`、整个 `context-loader config` 子命令组 ——去掉 `--token` 或改用 `kweaver auth login`。
+
+`auth whoami` / `auth status` 通过文案区分来源：flag 模式为 `CLI (flag: --token)`，env 模式为 `env (KWEAVER_TOKEN)`（`whoami --json` 为 `"source": "flag"` 与 `"source": "env"`）。
+
+`kweaver context-loader` 运行时子命令将 `<kn-id>` 作为第一个位置参数（如 `kweaver context-loader tools <kn-id>`），也支持全局 `--kn-id <id>` / `-k <id>` flag，因此在 stateless 模式下可直接使用，无需任何持久化配置。`context-loader config set|use|list|remove|show` 管理子命令已被标记为 deprecated（每次调用打印警告），且在 `--token` 下整组被禁用。
+
 ### TLS 证书问题排查
 
 如果遇到 `fetch failed`、`self-signed certificate`、`UNABLE_TO_GET_ISSUER_CERT` 等 TLS 相关错误，通常是目标服务器使用了自签名证书或 Kubernetes Ingress 默认假证书。可按优先级尝试以下方案：

package/dist/api/context-loader.d.ts

@@ -4,15 +4,28 @@ export interface ContextLoaderCallOptions {
     knId: string;
     accessToken: string;
 }
-/** Layer 1: kn_search arguments. */
-export interface KnSearchArgs {
-    query: string;
-    only_schema?: boolean;
+export interface SearchSchemaScope {
+    include_object_types?: boolean;
+    include_relation_types?: boolean;
+    include_action_types?: boolean;
+    include_metric_types?: boolean;
 }
-/** Layer 1: kn_schema_search arguments. */
-export interface KnSchemaSearchArgs {
+/** Layer 1: search_schema arguments. */
+export interface SearchSchemaArgs {
     query: string;
+    response_format?: "json" | "toon";
+    search_scope?: SearchSchemaScope;
     max_concepts?: number;
+    schema_brief?: boolean;
+    enable_rerank?: boolean;
+}
+/** Layer 1: search_schema result. */
+export interface SearchSchemaResult {
+    object_types?: unknown[];
+    relation_types?: unknown[];
+    action_types?: unknown[];
+    metric_types?: unknown[];
+    raw?: string;
 }
 /** Condition for query_object_instance and query_instance_subgraph. */
 export interface ConditionSpec {
@@ -60,6 +73,24 @@ export interface GetActionInfoArgs {
     at_id: string;
     _instance_identity: Record<string, string>;
 }
+/** Layer 3: find_skills arguments (object_type_id is required). */
+export interface FindSkillsArgs {
+    object_type_id: string;
+    response_format?: "json" | "toon";
+    instance_identities?: Record<string, unknown>[];
+    skill_query?: string;
+    /** 1..20, default 10 on the server side. */
+    top_k?: number;
+}
+/** Layer 3: find_skills result. */
+export interface FindSkillsResult {
+    entries: Array<{
+        skill_id: string;
+        name: string;
+        description?: string;
+    }>;
+    message?: string;
+}
 /** Error when get_logic_properties_values returns MISSING_INPUT_PARAMS. */
 export interface MissingInputParamsError {
     error_code: "MISSING_INPUT_PARAMS";
@@ -81,10 +112,9 @@ export declare function validateCondition(condition: unknown): void;
 export declare function validateInstanceIdentity(v: unknown, label: string): void;
 /** Guardrail: _instance_identities must be array of plain objects from Layer 2. */
 export declare function validateInstanceIdentities(v: unknown): void;
-/** Layer 1: kn_search. Returns object_types, relation_types, action_types. */
-export declare function knSearch(options: ContextLoaderCallOptions, args: KnSearchArgs): Promise<unknown>;
-/** Layer 1: kn_schema_search. Returns concepts (candidate discovery only). */
-export declare function knSchemaSearch(options: ContextLoaderCallOptions, args: KnSchemaSearchArgs): Promise<unknown>;
+export declare function callTool(options: ContextLoaderCallOptions, toolName: string, args: Record<string, unknown>): Promise<unknown>;
+/** Layer 1: search_schema. Returns object_types, relation_types, action_types, metric_types. */
+export declare function searchSchema(options: ContextLoaderCallOptions, args: SearchSchemaArgs): Promise<SearchSchemaResult>;
 /** Layer 2: query_object_instance. Returns datas with _instance_identity. */
 export declare function queryObjectInstance(options: ContextLoaderCallOptions, args: QueryObjectInstanceArgs): Promise<unknown>;
 /** Layer 2: query_instance_subgraph. Returns entries with nested _instance_identity. */
@@ -93,6 +123,11 @@ export declare function queryInstanceSubgraph(options: ContextLoaderCallOptions,
 export declare function getLogicPropertiesValues(options: ContextLoaderCallOptions, args: GetLogicPropertiesValuesArgs): Promise<unknown>;
 /** Layer 3: get_action_info. Returns _dynamic_tools. */
 export declare function getActionInfo(options: ContextLoaderCallOptions, args: GetActionInfoArgs): Promise<unknown>;
+/**
+ * Layer 3: find_skills. Recall skills attached to an object type or
+ * (optionally) narrowed to specific instances.
+ */
+export declare function findSkills(options: ContextLoaderCallOptions, args: FindSkillsArgs): Promise<FindSkillsResult>;
 /** MCP tools/list. Returns list of available tools. */
 export declare function listTools(options: ContextLoaderCallOptions, params?: {
     cursor?: string;

package/dist/api/context-loader.js

@@ -149,7 +149,7 @@ async function callMcpMethod(options, method, params = {}) {
     }
     throw new Error("Context-loader returned no result");
 }
-async function callTool(options, toolName, args) {
+export async function callTool(options, toolName, args) {
     const sessionId = await ensureSession(options);
     const id = (requestId += 1);
     const body = JSON.stringify({
@@ -208,13 +208,21 @@ async function callTool(options, toolName, args) {
     }
     throw new Error("Context-loader returned no result");
 }
-/** Layer 1: kn_search. Returns object_types, relation_types, action_types. */
-export async function knSearch(options, args) {
-    return callTool(options, "kn_search", { ...args });
-}
-/** Layer 1: kn_schema_search. Returns concepts (candidate discovery only). */
-export async function knSchemaSearch(options, args) {
-    return callTool(options, "kn_schema_search", { ...args });
+/** Layer 1: search_schema. Returns object_types, relation_types, action_types, metric_types. */
+export async function searchSchema(options, args) {
+    const toolArgs = {
+        query: args.query,
+        response_format: args.response_format ?? "json",
+    };
+    if (args.search_scope !== undefined)
+        toolArgs.search_scope = args.search_scope;
+    if (args.max_concepts !== undefined)
+        toolArgs.max_concepts = args.max_concepts;
+    if (args.schema_brief !== undefined)
+        toolArgs.schema_brief = args.schema_brief;
+    if (args.enable_rerank !== undefined)
+        toolArgs.enable_rerank = args.enable_rerank;
+    return (await callTool(options, "search_schema", toolArgs));
 }
 /** Layer 2: query_object_instance. Returns datas with _instance_identity. */
 export async function queryObjectInstance(options, args) {
@@ -240,6 +248,33 @@ export async function getActionInfo(options, args) {
     validateInstanceIdentity(args._instance_identity, "_instance_identity");
     return callTool(options, "get_action_info", { ...args });
 }
+/**
+ * Layer 3: find_skills. Recall skills attached to an object type or
+ * (optionally) narrowed to specific instances.
+ */
+export async function findSkills(options, args) {
+    if (!args.object_type_id || typeof args.object_type_id !== "string") {
+        throw new Error("find_skills: object_type_id is required.");
+    }
+    if (args.top_k !== undefined && (args.top_k < 1 || args.top_k > 20)) {
+        throw new Error("find_skills: top_k must be between 1 and 20.");
+    }
+    if (args.instance_identities !== undefined) {
+        validateInstanceIdentities(args.instance_identities);
+    }
+    const toolArgs = {
+        object_type_id: args.object_type_id,
+    };
+    if (args.response_format !== undefined)
+        toolArgs.response_format = args.response_format;
+    if (args.instance_identities !== undefined)
+        toolArgs.instance_identities = args.instance_identities;
+    if (args.skill_query !== undefined)
+        toolArgs.skill_query = args.skill_query;
+    if (args.top_k !== undefined)
+        toolArgs.top_k = args.top_k;
+    return (await callTool(options, "find_skills", toolArgs));
+}
 /** MCP tools/list. Returns list of available tools. */
 export async function listTools(options, params) {
     return callMcpMethod(options, "tools/list", params ? { cursor: params.cursor } : {});

package/dist/api/semantic-search.d.ts

@@ -10,3 +10,12 @@ export interface SemanticSearchOptions {
     returnQueryUnderstanding?: boolean;
 }
 export declare function semanticSearch(options: SemanticSearchOptions): Promise<string>;
+export interface KnSearchHttpOptions {
+    baseUrl: string;
+    accessToken: string;
+    knId: string;
+    query: string;
+    businessDomain?: string;
+    onlySchema?: boolean;
+}
+export declare function knSearchHttp(options: KnSearchHttpOptions): Promise<string>;

package/dist/api/semantic-search.js

@@ -22,3 +22,22 @@ export async function semanticSearch(options) {
     }
     return body;
 }
+export async function knSearchHttp(options) {
+    const { baseUrl, accessToken, knId, query, businessDomain = "bd_public", onlySchema = false, } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}/api/agent-retrieval/v1/kn/kn_search`;
+    const response = await fetch(url, {
+        method: "POST",
+        headers: { ...buildHeaders(accessToken, businessDomain), "content-type": "application/json" },
+        body: JSON.stringify({
+            kn_id: knId,
+            query,
+            only_schema: onlySchema,
+        }),
+    });
+    const body = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, body);
+    }
+    return body;
+}

package/dist/api/skills.js

@@ -103,18 +103,20 @@ export async function updateSkillStatus(options) {
 }
 export async function registerSkillContent(options) {
     const url = buildUrl(options.baseUrl, `${SKILL_API_PREFIX}/skills`);
-    const payload = {
-        file_type: "content",
-        file: options.content,
-    };
+    const form = new FormData();
+    form.set("file_type", "content");
+    // Backend's gin form-binder rejects plain string field for `file`
+    // (typed json.RawMessage); needs an actual multipart file part with
+    // filename. See utils/gin.go GetBindMultipartFormRaw.
+    form.set("file", new Blob([options.content], { type: "text/markdown" }), "SKILL.md");
     if (options.source)
-        payload.source = options.source;
+        form.set("source", options.source);
     if (options.extendInfo)
-        payload.extend_info = options.extendInfo;
+        form.set("extend_info", JSON.stringify(options.extendInfo));
     const { body } = await fetchTextOrThrow(url, {
         method: "POST",
-        headers: { ...baseHeaders(options), "content-type": "application/json" },
-        body: JSON.stringify(payload),
+        headers: baseHeaders(options),
+        body: form,
     });
     return normalizeSkillId(unwrapEnvelope(body));
 }

package/dist/api/toolboxes.d.ts

@@ -44,6 +44,18 @@ export interface ListToolsOptions extends BaseOpts {
     boxId: string;
 }
 export declare function listTools(opts: ListToolsOptions): Promise<string>;
+export type ImpexType = "toolbox" | "mcp" | "operator";
+export interface ExportConfigOptions extends BaseOpts {
+    id: string;
+    type?: ImpexType;
+}
+export declare function exportConfig(opts: ExportConfigOptions): Promise<Uint8Array>;
+export interface ImportConfigOptions extends BaseOpts {
+    /** Path to a previously exported `.adp` JSON file. */
+    filePath: string;
+    type?: ImpexType;
+}
+export declare function importConfig(opts: ImportConfigOptions): Promise<string>;
 export interface InvokeToolOptions extends BaseOpts {
     boxId: string;
     toolId: string;

package/dist/api/toolboxes.js

@@ -1,6 +1,6 @@
 import { readFile } from "node:fs/promises";
 import { basename } from "node:path";
-import { fetchTextOrThrow } from "../utils/http.js";
+import { HttpError, fetchTextOrThrow, fetchWithRetry } from "../utils/http.js";
 import { buildHeaders } from "./headers.js";
 // Backend endpoints under /api/agent-operator-integration/v1/tool-box.
 //
@@ -97,6 +97,48 @@ export async function listTools(opts) {
     });
     return body;
 }
+// ── impex (export / import) ──────────────────────────────────────────────────
+//
+// Backend mounts the impex endpoints on the same service but under a different
+// path:
+//
+//   GET  /api/agent-operator-integration/v1/impex/export/{type}/{id}
+//   POST /api/agent-operator-integration/v1/impex/import/{type}   (multipart, field "data")
+//
+// Supported {type} values today: "toolbox" | "mcp" | "operator".
+//
+// Export response is the raw JSON config (Content-Type: application/json) plus
+// a `Content-Disposition: attachment; filename=<type>_export_<ts>.adp` header.
+const IMPEX_PATH = "/api/agent-operator-integration/v1/impex";
+export async function exportConfig(opts) {
+    const t = opts.type ?? "toolbox";
+    const target = `${opts.baseUrl.replace(/\/+$/, "")}${IMPEX_PATH}/export/${encodeURIComponent(t)}/${encodeURIComponent(opts.id)}`;
+    // Use raw bytes (not text) so we never lose precision on non-ASCII payloads
+    // and stay symmetric with the Python SDK's `export_config -> bytes`.
+    const response = await fetchWithRetry(target, {
+        method: "GET",
+        headers: buildHeaders(opts.accessToken, opts.businessDomain ?? "bd_public"),
+    });
+    const buf = new Uint8Array(await response.arrayBuffer());
+    if (!response.ok) {
+        const text = new TextDecoder("utf-8").decode(buf);
+        throw new HttpError(response.status, response.statusText, text);
+    }
+    return buf;
+}
+export async function importConfig(opts) {
+    const buf = await readFile(opts.filePath);
+    const t = opts.type ?? "toolbox";
+    const form = new FormData();
+    form.append("data", new Blob([buf]), basename(opts.filePath));
+    const target = `${opts.baseUrl.replace(/\/+$/, "")}${IMPEX_PATH}/import/${encodeURIComponent(t)}`;
+    const { body } = await fetchTextOrThrow(target, {
+        method: "POST",
+        headers: buildHeaders(opts.accessToken, opts.businessDomain ?? "bd_public"),
+        body: form,
+    });
+    return body;
+}
 function buildEnvelope(opts) {
     const envelope = {};
     if (opts.timeout !== undefined)

package/dist/cli.js

@@ -19,7 +19,7 @@ function printHelp() {
     console.log(`kweaver
 
 Usage:
-  kweaver [--user <userId|username>] <command> [options]
+  kweaver [--base-url <url>] [--token <access-token>] [--user <userId|username>] <command> [options]
   kweaver --version | -V
   kweaver --help | -h
 
@@ -39,42 +39,43 @@ Usage:
   kweaver token
 
   kweaver call <url> [-X METHOD] [-H "Name: value"] [-d BODY] [--data-raw BODY]
-             [--url URL] [--pretty] [--verbose] [-bd value]
+             [--url URL] [--verbose] [-bd value]
   (alias: kweaver curl ...)
 
   kweaver agent chat <agent_id> [-m "message"] [--version value] [--conversation-id id]
                 [--stream] [--no-stream] [--verbose] [-bd value]
-  kweaver agent list [--name X] [--limit N] [--offset N] [-bd value] [--pretty]
-  kweaver agent get <agent_id> [-bd value] [--pretty]
-  kweaver agent get-by-key <key> [-bd value] [--pretty]
-  kweaver agent sessions <agent_id> [-bd value] [--limit N] [--pretty]
-  kweaver agent history <conversation_id> [-bd value] [--limit N] [--pretty]
+  kweaver agent list [--name X] [--limit N] [--offset N] [-bd value]
+  kweaver agent get <agent_id> [-bd value]
+  kweaver agent get-by-key <key> [-bd value]
+  kweaver agent sessions <agent_id> [-bd value] [--limit N]
+  kweaver agent history <conversation_id> [-bd value] [--limit N]
   kweaver agent create [options]
   kweaver agent update <agent_id> [options]
   kweaver agent delete <agent_id> [-bd value]
   kweaver agent publish <agent_id> [-bd value]
   kweaver agent unpublish <agent_id> [-bd value]
 
-  kweaver ds list [--keyword X] [--type T] [-bd value] [--pretty]
+  kweaver ds list [--keyword X] [--type T] [-bd value]
   kweaver ds get <id>
   kweaver ds delete <id> [-y]
-  kweaver ds tables <id> [--keyword X] [--pretty]
+  kweaver ds tables <id> [--keyword X]
   kweaver ds connect <db_type> <host> <port> <database> --account X --password Y [--schema S] [--name N]
+                     [--reuse-existing|--force-new]
 
   kweaver dataflow list [-bd value]
   kweaver dataflow run <dagId> (--file <path> | --url <remote-url> --name <filename>) [-bd value]
   kweaver dataflow runs <dagId> [--since <date-like>] [-bd value]
   kweaver dataflow logs <dagId> <instanceId> [--detail] [-bd value]
 
-  kweaver dataview list [--datasource-id id] [--type atomic|custom] [--limit n] [-bd value] [--pretty]
-  kweaver dataview find --name <name> [--exact] [--datasource-id id] [--wait] [--timeout ms] [-bd value] [--pretty]
-  kweaver dataview get <id> [-bd value] [--pretty]
-  kweaver dataview query <id> [--sql sql] [--limit n] [--offset n] [--need-total] [--raw-sql] [-bd value] [--pretty]
+  kweaver dataview list [--datasource-id id] [--type atomic|custom] [--limit n] [-bd value]
+  kweaver dataview find --name <name> [--exact] [--datasource-id id] [--wait] [--timeout ms] [-bd value]
+  kweaver dataview get <id> [-bd value]
+  kweaver dataview query <id> [--sql sql] [--limit n] [--offset n] [--need-total] [--raw-sql] [-bd value]
   kweaver dataview delete <id> [-y] [-bd value]
 
   kweaver bkn list [options]
   kweaver bkn get <kn-id> [options]
-  kweaver bkn search <kn-id> <query> [--max-concepts N] [--mode M] [--pretty] [-bd value]
+  kweaver bkn search <kn-id> <query> [--max-concepts N] [--mode M] [-bd value]
   kweaver bkn create [options]
   kweaver bkn create-from-ds [options]
   kweaver bkn update <kn-id> [options]
@@ -107,6 +108,8 @@ Usage:
   kweaver toolbox list [--keyword X] [--limit N] [--offset N] [-bd value]
   kweaver toolbox publish|unpublish <box-id> [-bd value]
   kweaver toolbox delete <box-id> [-y] [-bd value]
+  kweaver toolbox export <box-id> [-o <file>|-] [--type toolbox|mcp|operator]
+  kweaver toolbox import <file> [--type toolbox|mcp|operator]
 
   kweaver tool upload --toolbox <box-id> <openapi-spec-path> [--metadata-type openapi]
   kweaver tool list --toolbox <box-id> [-bd value]
@@ -121,17 +124,25 @@ Usage:
   kweaver vega query execute|sql [options]
   kweaver vega connector-type list|get [options]
 
-  kweaver context-loader config set|use|list|remove|show [options]
-  kweaver context-loader tools|resources|templates|prompts [--cursor]
-  kweaver context-loader resource <uri>
-  kweaver context-loader prompt <name> [--args json]
-  kweaver context-loader kn-search <query> [--only-schema]
-  kweaver context-loader kn-schema-search <query> [--max N]
-  kweaver context-loader query-object-instance|query-instance-subgraph|get-logic-properties|get-action-info ...
+  kweaver context-loader config set|use|list|remove|show [options]                (deprecated; not supported with --token)
+  kweaver context-loader tools|resources|templates|prompts <kn-id> [--cursor]
+  kweaver context-loader resource <kn-id> <uri>
+  kweaver context-loader prompt <kn-id> <name> [--args json]
+  kweaver context-loader search-schema <kn-id> <query> [--scope object,relation,action,metric] [--max N]
+  kweaver context-loader tool-call <kn-id> <name> --args '<json>'
+  kweaver context-loader kn-search <kn-id> <query> [--only-schema]                 (compat HTTP)
+  kweaver context-loader kn-schema-search <kn-id> <query> [--max N]                (compat HTTP)
+  kweaver context-loader query-object-instance|query-instance-subgraph|get-logic-properties|get-action-info|find-skills <kn-id> ...
+                                                          (omit <kn-id> to fall back to deprecated saved config)
   (alias: kweaver context ...)
 
 Global options:
+  --base-url <url>  Override platform base URL for this command (env: KWEAVER_BASE_URL)
+  --token <value>   Override access token for this command (env: KWEAVER_TOKEN; disables write-to-disk commands)
   --user <id|name>  Use a specific user's credentials for this command (env: KWEAVER_USER)
+  --pretty / --compact
+                    Toggle pretty-printed JSON output. Supported by every
+                    command that prints a JSON payload (default: pretty).
 
 Commands:
   auth           Login, list, inspect, and switch saved platform auth profiles
@@ -145,10 +156,10 @@ Commands:
                  object-type, relation-type, subgraph, action-type, action-execution, action-log)
   config         Per-platform configuration (business domain)
   skill          Skill registry and market (register, search, progressive read, download/install)
-  toolbox        Agent toolbox lifecycle (create, list, publish, delete)
+  toolbox        Agent toolbox lifecycle (create, list, publish, delete, export, import)
   tool           Tools inside a toolbox (upload OpenAPI spec, list, enable/disable)
   vega           Vega observability (catalog, resource, query/sql, connector-type, health/stats/inspect)
-  context-loader Context-loader MCP (config, tools, resources, prompts, kn-search, query-*, etc.)
+  context-loader Context-loader MCP/HTTP (config, tools, resources, search-schema, tool-call, query-*, etc.)
   help           Show this message`);
 }
 export async function run(argv) {
@@ -158,12 +169,40 @@ export async function run(argv) {
         !process.env.KWEAVER_TOKEN) {
         process.env.KWEAVER_TOKEN = NO_AUTH_TOKEN;
     }
-    // Global --user flag: override active user for this invocation
-    const userIdx = argv.indexOf("--user");
+    // Global flags consumed before subcommand dispatch.
+    // Pattern follows --user (legacy): each flag, if present, is removed from argv
+    // and projected into a process.env value that downstream resolvers already read.
     let filteredArgv = argv;
-    if (userIdx !== -1 && userIdx + 1 < argv.length) {
-        process.env.KWEAVER_USER = argv[userIdx + 1];
-        filteredArgv = [...argv.slice(0, userIdx), ...argv.slice(userIdx + 2)];
+    function consumeFlag(flag) {
+        const idx = filteredArgv.indexOf(flag);
+        if (idx === -1 || idx + 1 >= filteredArgv.length)
+            return undefined;
+        const value = filteredArgv[idx + 1];
+        filteredArgv = [...filteredArgv.slice(0, idx), ...filteredArgv.slice(idx + 2)];
+        return value;
+    }
+    const userVal = consumeFlag("--user");
+    if (userVal)
+        process.env.KWEAVER_USER = userVal;
+    const tokenVal = consumeFlag("--token");
+    const baseUrlVal = consumeFlag("--base-url");
+    if (tokenVal) {
+        process.env.KWEAVER_TOKEN = tokenVal;
+        process.env.KWEAVER_TOKEN_SOURCE = "flag";
+    }
+    if (baseUrlVal) {
+        process.env.KWEAVER_BASE_URL = baseUrlVal;
+    }
+    // --token requires a base URL from somewhere; fail fast with guidance.
+    if (tokenVal && !process.env.KWEAVER_BASE_URL) {
+        const { getCurrentPlatform } = await import("./config/store.js");
+        if (!getCurrentPlatform()) {
+            console.error("--token requires a base URL. Provide one of:\n" +
+                "  --base-url <url>\n" +
+                "  export KWEAVER_BASE_URL=<url>\n" +
+                "  kweaver auth login <url>   (save once, reuse later)");
+            return 1;
+        }
     }
     const [command, ...rest] = filteredArgv;
     if (command === "--version" || command === "-V" || command === "version") {