YouData CLI 让你在终端或支持执行命令的 AI 工具中查找数据模型、生成 SQL、查询数据。安装包自带运行环境，无需额外安装 Node.js 或 Bun。

适用版本：0.1.0。业务命令以所连接有数平台的帮助为准。

私域部署若采用 http 协议，下面 https 请替换成http://域名/路由

一、快速开始

1. 安装 YouData CLI

支持 macOS（Apple M / Intel）、Linux（ARM64 / x64，glibc）和 Windows x64；暂不支持 Windows ARM64、Linux musl。macOS Intel 的系统兼容性请以对应安装包的验证记录为准。

方式一：手动安装

1. 打开 https://域名/dash/cli，进入 CLI 下载页。下方示例中的“域名”请替换为实际有数域名；有端口或部署子路径时，下载地址与 Host 都要保留，协议也须与实际部署一致。

2. 复制落地页对应系统的安装命令，或替换下方域名后执行：

   macOS / Linux（Shell）：

   (youdata_installer=$(curl -fsSL "https://域名/api/dash/util/download?key=public-youdata-cli%2Finstall.sh") && printf '%s\n' "$youdata_installer" | sh -s -- --host "https://域名")

   Windows PowerShell：

   $installer = (Invoke-WebRequest -UseBasicParsing "https://域名/api/dash/util/download?key=public-youdata-cli%2Finstall.ps1").Content
   if ($installer -is [byte[]]) { $installer = [Text.Encoding]::UTF8.GetString($installer) }
   & ([scriptblock]::Create($installer)) -BaseUrl "https://域名"

3. 按提示完成浏览器登录授权。已有有效登录时，脚本会自动跳过授权。也可以下载对应平台的压缩包，解压后运行程序：

   macOS / Linux：

   ./youdata --version

   Windows PowerShell：

   .\youdata.exe --version

   后续示例统一使用 youdata。未加入 PATH 时，请在解压目录中分别改用 ./youdata 或.\youdata.exe。

方式二：让 AI 工具辅助安装

• 把上方对应系统的完整安装命令替换好域名，复制给支持终端执行的 AI 工具，并输入：

帮我安装 YouData CLI。先检查当前系统与处理器，再执行下面的官方安装命令；需要浏览器授权时提示我操作，完成后检查版本和登录状态。

安装命令：粘贴上方对应系统且已替换域名的完整命令

2. 登录并检查

安装脚本已完成登录时，直接检查状态；手动解压安装或登录未完成时，先执行：

youdata auth login --host "https://域名"

--host 填有数服务基础地址，保留协议、端口及部署子路径，不带 /dash/... 页面路径或安装包下载路径。安装脚本会保存该地址，后续可直接运行 youdata auth login。

在浏览器中登录，选择默认项目和可选助手，确认授权。等终端提示登录成功后，再执行后续命令。

youdata --version
youdata auth status
youdata doctor

auth status 返回 authenticated 表示身份验证通过；doctor 返回 data.status: "ok"表示连接与命令契约检查通过。查询数据还需具备知数使用权限及对应项目、数据模型的访问权限。

3. 开启第一个任务

在终端查数

youdata model list --limit 10
youdata model nlsearch --question "各区域销售额"
youdata model meta --data-model-id "<数据模型ID>"
youdata model query --data-model-id "<数据模型ID>" --question "2024年各区域销售额是多少？" --limit 10

把 <数据模型ID> 替换为检索结果中的真实 ID；先确认字段和业务口径，再按实际需求修改问题。

在 AI 工具中提需求

请使用 YouData CLI 查询 2024 年各区域销售额。先查看命令帮助，查找合适的数据模型并确认字段，再查询数据，用表格展示结果并概括主要差异。

4. 更新 YouData CLI

重新执行上方对应系统的安装命令（域名与当前服务保持一致），或从 CLI 下载页复制安装命令再运行 youdata --version 核对版本。同一服务地址下会保留已有配置；更换服务地址会清除本地旧凭据及默认项目、助手配置。

二、能力地图

不确定参数时，逐层查看帮助：

youdata -h
youdata model -h
youdata model query -h

帮助命令不会查询业务数据。query 的 --question 与 --sql 必须二选一。

三、常用认证与配置

修改默认项目或助手：

youdata profile set --project-id "<项目ID>" --assistant-id "<助手ID>"

两项可以单独设置；只改项目不会清除原助手。助手 ID 使用真实正整数。项目和助手只是默认配置，不会增加权限；model list、model meta 不使用助手。

临时切换项目可给 model list、model nlsearch 加 --project-id。查询指定数据模型时使用 --data-model-id，无需传项目 ID。

四、常见问题

1.找不到 youdata，或程序无法运行？

先检查安装目录是否加入 PATH，或使用程序完整路径运行。确认安装包与系统、处理器匹配；macOS / Linux 缺少执行权限时，在程序目录执行 chmod +x ./youdata。macOS 安全拦截请在确认来源后按系统“隐私与安全性”提示处理。

2.没有浏览器，怎样登录？

在可打开网页的设备上进入有数站点的 /dash/profile/tokenKey 页面，获取自己的 Token key，再在运行 CLI 的机器上配置：

youdata profile set --host "https://域名" --project-id "<项目ID>" --token-key "<平台下发的Token key>"
youdata auth status

填写平台下发的 Token key，访问 Token 由 CLI 自动兑换。命令参数可能留在终端历史中；服务器或流水线可通过密钥管理注入 YOUDATA_BASE_URL、YOUDATA_TOKEN 和 YOUDATA_PROJECT_ID，其中 YOUDATA_TOKEN 的值仍是 Token key。不要把真实 Key 发到聊天或日志。

3.登录成功，但找不到数据模型或提示无权限？

先用 auth status 核对身份，再检查默认项目、数据模型是否已上线并开启问答，以及本人访问权限。使用助手时，还需确认助手可用且包含目标数据模型。环境变量会覆盖 Profile；YOUDATA_TOKEN 可能使实际身份与浏览器登录账号不同。

4.缺少命令、连接失败或参数报错？

依次运行 youdata profile get、youdata doctor 和对应命令的 -h。检查服务地址、网络或 VPN，并按 doctor 的处理提示操作。参数以当前帮助为准；版本不兼容时按提示升级或联系管理员。

5.怎样先看 SQL，或继续翻页？

先用 model nl2sql 生成 SQL，确认后再用 model query --sql 查询。按问题查询后，也可复用结果中的 data.logicSql 继续翻页：

youdata model query --data-model-id "<数据模型ID>" --sql "<上一页返回的logicSql>" --limit 20 --offset 20

示例适用于第一页已返回 20 行的情况。每页默认 20 行，最多 100 行；offset 是记录偏移量。翻页时保持数据模型、SQL、排序和每页条数不变，SQL 应包含稳定排序；entire=true 时结束。按问题查询不支持用 offset 继续翻页。 仍无法解决时，向管理员提供 CLI 版本、系统与处理器类型、脱敏后的命令、错误码及提示。

五、管理员发布安装包

1. 技术支持从官方安装目录 获取 youdata-cli-<version>.zip 整包。
2. 使用超管账号进入目标有数站点的 /dash/cli/manage，上传完整 ZIP。
3. 上传成功后，用户即可从 /dash/cli 获取当前平台的安装包或安装命令。

目标部署须已购买知数能力，并提供 CLI 管理功能；默认 Platform 镜像不含安装包。部署内仅保留当前版本，发布后请核对下载程序的版本。