@smartbi/cli

Smartbi OpenAPI 命令行工具。通过自然语言或命令发现、理解和调用 Smartbi 全部 OpenAPI 接口。

安装

npm install -g @smartbi/cli@latest

要求 Node.js >= 18。

快速开始

1. 初始化配置

smartbi init

按提示选择服务器类型（sdk-server / Smartbi）、填写服务器地址、选择 token 保存方式（环境变量 / 系统 keyring / 明文），一步生成可直接使用的 ~/.smartbi/config.yaml。

2. 发现可用接口

# 列出所有可用接口
smartbi list

# 按领域筛选
smartbi list --domain scheduletask

# 面向 AI Agent 的语义化输出
smartbi list --agent

3. 搜索接口

# 关键词搜索
smartbi search 定时

# 指定搜索范围
smartbi search "企微推送" --in description,summary

# 模糊匹配
smartbi search 订单 --fuzzy

4. 查看接口详情

smartbi describe scheduletask.createTask
smartbi describe scheduletask.createTask --agent

5. 调用接口

smartbi call scheduletask.createTask -d @payload.json

核心命令

| 命令 | 用途 | |------|------| | smartbi init | 初始化配置文件（向导一步生成可用配置） | | smartbi profile add <name> | 添加新的服务器环境（profile），支持多套服务器/凭证切换 | | smartbi list | 列出可用 API 接口 | | smartbi search <keyword> | 搜索接口 | | smartbi describe <operationKey> | 查看接口契约详情 | | smartbi call <operationKey> | 调用接口 |

常用选项

| 选项 | 说明 | |------|------| | --json | JSON 格式输出 | | --agent | 面向 AI Agent 的结构化输出（含错误 JSON） | | --verbose | 输出详细信息 | | --domain | 按领域筛选 | | -d @file.json | 从 JSON 文件传入请求体 | | --dry-run | 预览请求，不实际发送 |

配置文件

CLI 默认读取 ~/.smartbi/config.yaml，通过 smartbi init 生成。一个 config 可包含多个 profile（多套服务器环境）：smartbi profile add <name> 添加、smartbi profile set-default <name> 切换默认、smartbi profile show 查看当前配置。

profile: dev
profiles:
  dev:
    serverType: smartbi
    baseUrl: "http://your-server:8080/smartbi"
    tokenEnv: "SMARTBI_TOKEN_DEV"
    timeoutMs: 300000

registry:
  source: remote
  checkIntervalSeconds: 300

支持通过环境变量配置（baseUrlEnv / tokenEnv），适合 CI/CD 场景。token 也可存入系统 keyring（init 向导选「系统 keyring」，配置为 tokenKeyring: true）。

典型场景

定时计划任务：smartbi list --domain scheduletask → smartbi describe scheduletask.createTask → smartbi call scheduletask.createTask -d @task.json

数据查询：smartbi search "执行 MQL 查询" → smartbi describe datamodel.queryDataByMql → smartbi call datamodel.queryDataByMql -d @query.json

文档

详细使用指南：smartbi --help