@kweaver-ai/kweaver-sdk 0.7.1 → 0.7.3

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.
 
@@ -188,10 +188,12 @@ 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 search-schema/tool-call/kn-search/query-object-instance/find-skills/...
+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 tool upload/list/enable/disable/execute/debug (execute and debug accept --path for OpenAPI path params)
 kweaver call <path> [-X METHOD] [-d BODY] [-H header] [-F key=value]
 ```
 
@@ -240,6 +242,11 @@ kweaver tool upload --toolbox <BOX_ID> ./openapi.json
 # 3. Publish the toolbox and enable the tool
 kweaver toolbox publish <BOX_ID>
 kweaver tool enable --toolbox <BOX_ID> <TOOL_ID>
+
+# Invoke / debug: envelope supports `--header`, `--query`, `--body`, and **`--path`**
+# for OpenAPI `{param}` placeholders (required for paths like `/data-views/{id}`).
+kweaver tool debug --toolbox <BOX_ID> <TOOL_ID> \
+  --path '{"id":"<DATA_VIEW_UUID>"}' [--body '<json>']
 ```
 
 **No-auth platforms:** If OAuth is not enabled, use `kweaver auth <url> --no-auth` (or run a normal `auth login`; a **404** on `POST /oauth2/clients` switches to no-auth automatically). Credentials are still saved under `~/.kweaver/` and work with `auth use` / `auth list`. Optional: `KWEAVER_NO_AUTH=1` with `KWEAVER_BASE_URL` when no token env is set. SDK: `new KWeaverClient({ baseUrl, auth: false })` or `kweaver.configure({ baseUrl, auth: false })`.
@@ -251,10 +258,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

@@ -176,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 search-schema/tool-call/kn-search/query-object-instance/find-skills/...
+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]
 ```
 
@@ -218,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/datasources.d.ts

@@ -71,3 +71,10 @@ export interface ScanMetadataOptions {
     businessDomain?: string;
 }
 export declare function scanMetadata(options: ScanMetadataOptions): Promise<string>;
+export interface ScanDatasourceMetadataOptions {
+    baseUrl: string;
+    accessToken: string;
+    id: string;
+    businessDomain?: string;
+}
+export declare function scanDatasourceMetadata(options: ScanDatasourceMetadataOptions): Promise<string>;

package/dist/api/datasources.js

@@ -208,3 +208,11 @@ export async function scanMetadata(options) {
     }
     return taskId;
 }
+// Looks up a datasource's type then triggers a metadata scan, so callers
+// don't have to repeat the GET-then-scan dance whenever a flow needs the
+// platform catalog refreshed (after import-csv, before discovering tables).
+export async function scanDatasourceMetadata(options) {
+    const dsBody = await getDatasource(options);
+    const dsType = JSON.parse(dsBody).type ?? "mysql";
+    return scanMetadata({ ...options, dsType });
+}

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

@@ -63,6 +63,8 @@ export interface InvokeToolOptions extends BaseOpts {
     header?: Record<string, unknown>;
     /** Optional query params to forward. */
     query?: Record<string, unknown>;
+    /** Path parameter map for OpenAPI `{param}` placeholders (e.g. `{ id: "<uuid>" }`). */
+    path?: Record<string, unknown>;
     /** JSON body forwarded to the downstream tool. */
     body?: unknown;
     /** Per-call timeout in seconds; backend default applies when omitted. */

package/dist/api/toolboxes.js

@@ -20,7 +20,7 @@ import { buildHeaders } from "./headers.js";
 //   POST   /tool-box/{box}/tool/{tool}/debug       debug tool (envelope JSON)
 //
 // Envelope shape required by /proxy and /debug:
-//   { "timeout": <s>, "header": {...}, "query": {...}, "body": {...} }
+//   { "timeout": <s>, "header": {...}, "query": {...}, "body": {...}, "path": {...} }
 // Flat-shape requests cause the forwarder to drop downstream Authorization
 // headers, which manifests as 401 "token expired" from the underlying tool.
 const PATH = "/api/agent-operator-integration/v1/tool-box";
@@ -145,6 +145,7 @@ function buildEnvelope(opts) {
         envelope.timeout = opts.timeout;
     envelope.header = opts.header ?? {};
     envelope.query = opts.query ?? {};
+    envelope.path = opts.path ?? {};
     envelope.body = opts.body ?? {};
     return JSON.stringify(envelope);
 }

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
 
@@ -60,7 +60,12 @@ Usage:
   kweaver ds delete <id> [-y]
   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 templates [--json]
+  kweaver dataflow create-dataset --template <name> --set "key=value" [--json] [-bd value]
+  kweaver dataflow create-bkn --template <name> --set "key=value" [--json] [-bd value]
+  kweaver dataflow create (--template <name> --set "key=value" | <json>) [-bd value]
   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]
@@ -115,7 +120,7 @@ Usage:
   kweaver tool enable|disable --toolbox <box-id> <tool-id>... [-bd value]
   kweaver tool execute|debug --toolbox <box-id> <tool-id>
                              [--body '<json>'|--body-file <path>]
-                             [--header '<json>'] [--query '<json>'] [--timeout <s>]
+                             [--header '<json>'] [--query '<json>'] [--path '<json>'] [--timeout <s>]
 
   kweaver vega health|stats|inspect
   kweaver vega catalog list|get|health|test-connection|discover|resources [options]
@@ -123,19 +128,34 @@ 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 search-schema <query> [--scope object,relation,action,metric] [--max N]
-  kweaver context-loader tool-call <name> --args '<json>'
-  kweaver context-loader kn-search <query> [--only-schema]      (compat HTTP)
-  kweaver context-loader kn-schema-search <query> [--max N]     (compat HTTP)
-  kweaver context-loader query-object-instance|query-instance-subgraph|get-logic-properties|get-action-info|find-skills ...
+  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:
-  --user <id|name>  Use a specific user's credentials for this command (env: KWEAVER_USER)
+  --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, transient (env: KWEAVER_USER)
+
+Multi-shell account isolation:
+  KWEAVER_PROFILE=<name>     Scope state.json (active platform / active user) to a named
+                             profile. Tokens under platforms/ are still shared, so each
+                             profile reuses logins. Required for \`auth switch\` and
+                             \`auth use\` (use --global to override). Name must match
+                             [A-Za-z0-9_-]{1,64}.
+  KWEAVERC_CONFIG_DIR=<dir>  Override the entire config root (~/.kweaver by default).
+                             Use this for hard isolation (separate token store per shell).
+
+For agents / multi-terminal scripts: prefer \`--user <id>\` (transient, no persistence)
+over \`auth switch\` (persistent, requires KWEAVER_PROFILE).
   --pretty / --compact
                     Toggle pretty-printed JSON output. Supported by every
                     command that prints a JSON payload (default: pretty).
@@ -165,12 +185,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") {

package/dist/commands/auth.js

@@ -1,8 +1,31 @@
 import { isNoAuth } from "../config/no-auth.js";
-import { autoSelectBusinessDomain, clearPlatformSession, deletePlatform, deleteUser, getActiveUser, getConfigDir, getCurrentPlatform, getPlatformAlias, hasPlatform, listPlatforms, listUserProfiles, loadClientConfig, loadTokenConfig, loadUserTokenConfig, resolveBusinessDomain, resolvePlatformIdentifier, resolveUserId, saveNoAuthPlatform, setActiveUser, setCurrentPlatform, setPlatformAlias, } from "../config/store.js";
+import { assertNotStatelessForWrite } from "../config/stateless.js";
+import { autoSelectBusinessDomain, clearPlatformSession, deletePlatform, deleteUser, getActiveUser, getConfigDir, getCurrentPlatform, getPlatformAlias, getProfileName, hasPlatform, listPlatforms, listUserProfiles, loadClientConfig, loadTokenConfig, loadUserTokenConfig, resolveBusinessDomain, resolvePlatformIdentifier, resolveUserId, saveNoAuthPlatform, setActiveUser, setCurrentPlatform, setPlatformAlias, } from "../config/store.js";
 import { decodeJwtPayload } from "../config/jwt.js";
 import { eacpModifyPassword } from "../auth/eacp-modify-password.js";
 import { buildCopyCommand, fetchEacpUserInfo, formatHttpError, InitialPasswordChangeRequiredError, normalizeBaseUrl, oauth2Login, oauth2PasswordSigninLogin, promptForUsername, promptForPassword, refreshTokenLogin, resolveActivePlatform, } from "../auth/oauth.js";
+function consumeGlobalFlag(args) {
+    const idx = args.indexOf("--global");
+    if (idx === -1)
+        return { args, isGlobal: false };
+    return { args: [...args.slice(0, idx), ...args.slice(idx + 1)], isGlobal: true };
+}
+function requireProfileOrGlobal(command, isGlobal) {
+    if (isGlobal)
+        return null;
+    try {
+        if (getProfileName())
+            return null;
+    }
+    catch (err) {
+        return err instanceof Error ? err.message : String(err);
+    }
+    return (`kweaver auth ${command} mutates the active account globally and would affect every shell using ~/.kweaver.\n` +
+        `Pick one:\n` +
+        `  - Transient: prepend \`--user <id|name>\` (or \`KWEAVER_USER=<id>\`) to the command you actually want to run; no persistent switch.\n` +
+        `  - Persistent (this shell only): \`export KWEAVER_PROFILE=<name>\`, then re-run.\n` +
+        `  - Intentionally global (CI / single-user setup): re-run with \`--global\`.`);
+}
 export async function runAuthCommand(args) {
     const target = args[0];
     const rest = args.slice(1);
@@ -71,6 +94,13 @@ Login options:
     const LOGIN_SUBCOMMANDS = new Set(["status", "list", "use", "delete", "logout", "export", "whoami", "users", "switch"]);
     if (target && !LOGIN_SUBCOMMANDS.has(target)) {
         try {
+            try {
+                assertNotStatelessForWrite("auth login");
+            }
+            catch (err) {
+                console.error(err instanceof Error ? err.message : String(err));
+                return 1;
+            }
             const normalizedTarget = normalizeBaseUrl(target);
             const alias = readOption(args, "--alias");
             let username = readOption(args, "--username") ?? readOption(args, "-u");
@@ -268,7 +298,8 @@ Login options:
             }
             console.log(`Config directory: ${getConfigDir()}`);
             console.log(`Platform:         ${active.url} (KWEAVER_BASE_URL)`);
-            console.log(`Token present:    yes (KWEAVER_TOKEN)`);
+            const tokenProvenance = process.env.KWEAVER_TOKEN_SOURCE === "flag" ? "CLI (flag: --token)" : "KWEAVER_TOKEN";
+            console.log(`Token present:    yes (${tokenProvenance})`);
             console.log(`Refresh token:    n/a (env)`);
             return 0;
         }
@@ -348,16 +379,29 @@ Login options:
         return 0;
     }
     if (target === "use") {
-        const resolvedTarget = args[1] ? resolvePlatformIdentifier(args[1]) : "";
+        const { args: useArgs, isGlobal } = consumeGlobalFlag(args);
+        const refusal = requireProfileOrGlobal("use", isGlobal);
+        if (refusal !== null) {
+            console.error(refusal);
+            return 1;
+        }
+        const resolvedTarget = useArgs[1] ? resolvePlatformIdentifier(useArgs[1]) : "";
         const useTarget = resolvedTarget && /^https?:\/\//.test(resolvedTarget) ? normalizeBaseUrl(resolvedTarget) : resolvedTarget;
         if (!useTarget) {
-            console.error("Usage: kweaver auth use <platform-url|alias>");
+            console.error("Usage: kweaver auth use [--global] <platform-url|alias>");
             return 1;
         }
         if (!hasPlatform(useTarget)) {
             console.error(`No saved token for ${useTarget}. Run \`kweaver auth login ${useTarget}\` first.`);
             return 1;
         }
+        try {
+            assertNotStatelessForWrite("auth use");
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            return 1;
+        }
         setCurrentPlatform(useTarget);
         console.log(`Current platform: ${useTarget}`);
         return 0;
@@ -375,6 +419,13 @@ Login options:
             console.error(`No saved token for ${deleteTarget}.`);
             return 1;
         }
+        try {
+            assertNotStatelessForWrite("auth delete");
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            return 1;
+        }
         if (deleteUserArg) {
             const deleteUserId = resolveUserId(deleteTarget, deleteUserArg) ?? deleteUserArg;
             deleteUser(deleteTarget, deleteUserId);
@@ -404,6 +455,13 @@ Login options:
             console.error(`No saved token for ${logoutTarget}.`);
             return 1;
         }
+        try {
+            assertNotStatelessForWrite("auth logout");
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            return 1;
+        }
         const logoutUserId = logoutUserArg ? resolveUserId(logoutTarget, logoutUserArg) ?? logoutUserArg : undefined;
         clearPlatformSession(logoutTarget, logoutUserId);
         const userHint = logoutUserId ? ` (user: ${logoutUserId})` : "";
@@ -460,18 +518,25 @@ You can use either userId or username with --user in switch/logout/delete.`);
 }
 function runAuthSwitchCommand(args) {
     if (args[0] === "--help" || args[0] === "-h") {
-        console.log(`kweaver auth switch [platform-url|alias] --user <userId|username>
+        console.log(`kweaver auth switch [--global] [platform-url|alias] --user <userId|username>
 
 Switch the active user for a platform.
 You can specify either the userId (sub claim) or the username (preferred_username from id_token).`);
         return 0;
     }
-    const userArg = readOption(args, "--user");
+    const { args: switchArgs, isGlobal } = consumeGlobalFlag(args);
+    const refusal = requireProfileOrGlobal("switch", isGlobal);
+    if (refusal !== null) {
+        console.error(refusal);
+        return 1;
+    }
+    const cleanedArgs = switchArgs;
+    const userArg = readOption(cleanedArgs, "--user") ?? process.env.KWEAVER_USER;
     if (!userArg) {
-        console.error("Usage: kweaver auth switch [platform-url|alias] --user <userId|username>");
+        console.error("Usage: kweaver auth switch [--global] [platform-url|alias] --user <userId|username>");
         return 1;
     }
-    const filteredArgs = args.filter((a) => a !== "--user" && a !== userArg);
+    const filteredArgs = cleanedArgs.filter((a) => a !== "--user" && a !== userArg);
     const platform = resolvePlatformArg(filteredArgs);
     if (!platform) {
         console.error("No active platform. Run `kweaver auth login <platform-url>` first.");
@@ -487,6 +552,13 @@ You can specify either the userId (sub claim) or the username (preferred_usernam
         }
         return 1;
     }
+    try {
+        assertNotStatelessForWrite("auth switch");
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
     setActiveUser(platform, resolvedId);
     const profiles = listUserProfiles(platform);
     const profile = profiles.find((p) => p.userId === resolvedId);
@@ -535,7 +607,10 @@ Options:
         // complete picture without forcing them to pick a mode.
         const jwtPayload = decodeJwtPayload(accessToken);
         if (jsonOutput) {
-            const out = { platform: envUrl, source: "env" };
+            const out = {
+                platform: envUrl,
+                source: process.env.KWEAVER_TOKEN_SOURCE === "flag" ? "flag" : "env",
+            };
             if (userInfo)
                 out.userInfo = userInfo;
             if (jwtPayload)
@@ -544,7 +619,7 @@ Options:
             return 0;
         }
         console.log(`Platform: ${envUrl}`);
-        console.log(`Source:   env (KWEAVER_TOKEN)`);
+        console.log(`Source:   ${process.env.KWEAVER_TOKEN_SOURCE === "flag" ? "CLI (flag: --token)" : "env (KWEAVER_TOKEN)"}`);
         if (userInfo) {
             console.log(`Type:     ${userInfo.type}`);
             console.log(`User ID:  ${userInfo.id}`);

package/dist/commands/bkn-ops.d.ts

@@ -1,4 +1,6 @@
 import { type BknEncodingImportOptions } from "../utils/bkn-encoding.js";
+export declare const BKN_OBJECT_NAME_MAX_LENGTH = 40;
+export declare function assertValidBknObjectNames(names: string[], context: string): void;
 export declare function parseKnBuildArgs(args: string[]): {
     knId: string;
     wait: boolean;
@@ -30,10 +32,12 @@ export declare function parseKnCreateFromDsArgs(args: string[]): {
     dsId: string;
     name: string;
     tables: string[];
+    pkMap: Record<string, string>;
     build: boolean;
     timeout: number;
     businessDomain: string;
     pretty: boolean;
+    noRollback: boolean;
 };
 /** Generate a BKN ObjectType YAML markdown file for a table. */
 export declare function generateObjectTypeBkn(tableName: string, dvId: string, pk: string, dk: string, columns: Array<{
@@ -48,10 +52,11 @@ export declare function parseKnCreateFromCsvArgs(args: string[]): {
     tablePrefix: string;
     batchSize: number;
     tables: string[];
+    pkMap: Record<string, string>;
     build: boolean;
-    recreate: boolean;
     timeout: number;
     businessDomain: string;
+    noRollback: boolean;
 };
 export declare function runKnCreateFromCsvCommand(args: string[]): Promise<number>;
 export interface ActionScheduleParsed {