查找 Rayfin CLI 命令，用于创建项目、管理模式变更、部署到 Fabric 以及配置环境设置。 每个章节列出命令语法、选项和常见用途。
安装
用于 npm i @microsoft/rayfin-cli 安装CLI。
入门
按照终端中的步骤创建 Fabric 应用。
npm create @microsoft/rayfin@latest my-app # 1. Create a project from a template
cd my-app
npx rayfin dev # 2. Run the frontend dev server
npx rayfin up # 3. Deploy to Microsoft Fabric
小窍门
对于已有或空项目，建议用 npx rayfin init 代替 npm create Rayfin 添加到已有源代码或空目录的项目中。 init 命令会引导你如何启用服务、选择数据库方言，以及配置静态托管，无需搭建新模板。
完整攻略请参见 使用 CLI创建并部署你的第一个 Fabric 应用，以及 将Fabric应用部署到 Fabric。
支架项目 npm create
npm create （别 npm init名）通过调用创建初始化器包来启动新项目。 要搭建一个Fabric应用，请配合 @microsoft/rayfin 初始化器使用：
npm create @microsoft/rayfin@latest my-app --workspace <workspace name>
命令参考
本文中的命令和标志是从本地安装的CLI帮助输出中验证的。
顶级命令
使用此表快速找到合适的命令。
| 命令 | 使用它 |
|---|---|
npx rayfin init [directory] |
创建或配置一个Rayfin项目。 |
npx rayfin connector |
查找、配置、检查并调用 Fabric 数据连接器。 |
npx rayfin functions init |
支架一个函数包。 |
npx rayfin dev |
在本地运行应用和功能。 |
npx rayfin init ai-files |
安装或检查 Rayfin 代理上下文文件。 |
npx rayfin up |
将应用部署到 Fabric 并管理远程部署。 |
npx rayfin env |
从中 rayfin/.env生成框架特定的环境文件。 |
npx rayfin login |
登录Rayfin平台。 |
npx rayfin logout |
登出并清除缓存凭证。 |
创建或配置项目
rayfin init [directory]
用于 rayfin init 将Rayfin添加到新建或已有项目中。
| 论点 | 说明 |
|---|---|
--project-name <name> |
设置项目名称。 |
-t, --template <uri> |
指定要使用的模板URI。 |
--template-name <name> |
按名称选择模板。 |
-l, --list-templates |
列出可用的模板。 |
--dialect <dialect> |
设置数据库方言。 |
--services <list> |
选择启用哪些服务。 |
--auth-methods <list> |
选择认证方式。 |
--static-hosting |
启用静态托管设置。 |
--overwrite |
覆盖现有生成的文件。 |
--workspace-id <id> |
使用特定的 Fabric 工作区 ID。 |
--workspace-uri <uri> |
使用特定的 Fabric 工作区 URI。 |
--base-api-url <url> |
覆盖基础 API URL。 |
--item-id <id> |
针对特定的Fabric物品ID。 |
示例
在搭建脚手架前列出可用模板：
npx rayfin init --list-templates
在当前目录中，使用命名模板和特定方言初始化 Rayfin：
npx rayfin init . --template-name react-vite --dialect mssql
创建一个非交互式的新项目，服务和认证已配置：
npx rayfin init my-app --project-name my-app --services db,storage --auth-methods fabric --static-hosting --overwrite
连接器命令
connector命令组管理外部 Fabric 数据源。
rayfin connector types
列出你可以添加到项目中的连接器类型。
| 选项 | 说明 |
|---|---|
--json |
将连接器类型列表以 JSON 形式发布。 |
-v, --verbose |
包含能力细节。 |
rayfin connector search [query]
搜索 Fabric 来源，查找登录身份可以添加为连接器的来源。
| 论证或选项 | 说明 |
|---|---|
[query] |
可选的、不区分大小写的源名称过滤器。 |
--query <text> |
优先于的命名源名滤波器 [query]。 |
--type <type> |
逗号分隔的连接器类型;要求与或 --workspace-id--all-workspaces。 |
--workspace-id <id> |
搜索一个 Fabric 工作区。 |
--all-workspaces |
搜索该身份能访问的所有工作区。 |
-y, --yes |
自动接受交互式添加切换。 |
--limit <n> |
显示结果的最大数量。 |
--output <interactive\|plain\|json> |
选择输出格式。 |
--json |
打印结果为JSON，跳过交互式选择器。 |
-v, --verbose |
启用详细输出。 |
当这两个工作区选项都未提供时，命令会搜索当前项目部署记录的工作区。
rayfin connector add --type <type>
添加连接器声明并搭建项目文件。
| 选项 | 说明 |
|---|---|
--type <type> |
必填。 连接器类型;用于 rayfin connector types 列出类型。 |
--name <name> |
连接器名称;由省略时的项目名称衍生。 |
--workspace-id <id> |
Fabric工作区ID。 |
--item-id <id> |
Fabric 物品编号。 |
--operations <ops> |
允许操作的逗号分隔子集。 |
-v, --verbose |
启用详细输出。 |
-y, --yes |
自动接受确认。 |
--json |
输出JSON。 |
rayfin connector list
列出了在中 rayfin.yml声明的连接器。
| 选项 | 说明 |
|---|---|
-v, --verbose |
包含连接器元数据和功能。 |
--json |
输出JSON。 |
rayfin connector inspect
检查配置好的连接器或直接指向的 Fabric 源，无需做更改。
| 选项 | 说明 |
|---|---|
--name <name> |
已配置连接器名称。 |
-w, --workspace <name> |
工作区名称以便直接检查。 |
--workspace-id <id> |
工作区标识用于直接检查。 |
--item <name> |
物品名称以便直接检查。 |
--item-id <id> |
物品编号以便直接检查。 |
--type <type> |
用于直接检查的连接器类型。 |
--url <url> |
语义模型门户 URL;派生工作区和项目 ID。 |
--entity <name> |
用实体或表进行采样;省略 和 --query 以列出实体。 |
--query <path> |
.sql 或 .dax 文件以只读模式执行。 |
--rows <n> |
行数限制;样本默认为10行，最高限制为100行。 |
-v, --verbose |
启用详细输出。 |
--output <interactive\|plain\|json> |
选择输出格式。 |
--json |
输出JSON。 |
用于 --name 配置连接器、完整的直接源选择器或 --url 语义模型。
rayfin connector invoke [connector-name] [operation]
调用配置好的连接器上的操作。
| 论证或选项 | 说明 |
|---|---|
[connector-name] |
已配置连接器名称。 |
[operation] |
连接器操作，如 executeQuery。 |
--name <name> |
命名的替代方案。[connector-name] |
--operation <operation> |
命名的替代方案。[operation] |
--input <json> |
JSON 操作输入。 |
--file <path> |
包含操作输入的JSON文件。 |
--transport <auto\|deployed> |
调用路径;默认为 auto。 |
-v, --verbose |
启用详细输出。 |
--output <interactive\|plain\|json> |
选择输出格式。 |
--output-file <path> |
把完整结果写入文件。 |
--max-inline-bytes <bytes> |
写入文件的结果大小阈值;默认为1 MiB。 |
--json |
输出JSON。 |
rayfin connector remove <name>
移除连接器声明及其生成的连接器文件。
| 论证或选项 | 说明 |
|---|---|
<name> |
必填。 连接器名称需移除。 |
-v, --verbose |
启用详细输出。 |
-y, --yes |
自动接受移除确认。 |
--json |
输出JSON。 |
函数命令
rayfin functions init [directory]
支架并配置一个函数包。
| 论证或选项 | 说明 |
|---|---|
[directory] |
Project root;默认使用当前目录。 |
--force |
覆盖现有的功能支架。 |
--path <relative-path> |
函数包的位置相对于项目根节点。 |
包的位置默认为检测到的工作区位置或 rayfin/functions。
开发命令
rayfin dev [project-path]
启动一个针对Rayfin后端的本地开发会话。
| 论证或选项 | 说明 |
|---|---|
[project-path] |
Project root;默认使用当前目录。 |
--skip-db-apply |
跳过自动数据库配置应用。 |
--env-file <path> |
.env 用于 rayfin.yml 插值的文件。 |
--provider <fabric> |
后端提供者;默认为 fabric。 |
-w, --workspace <name> |
Fabric 工作区名称，指的是首发后端。 |
--workspace-id <id> |
用于首次运行后端的 Fabric 工作区 ID。 |
--capacity-id <id> |
对于没有可用容量的工作空间，使用 Fabric 容量 ID。 |
-t, --tenant <id> |
Microsoft Entra 租户 ID。 |
--encryption-fallback-enabled |
当操作系统密钥链不可用时，允许纯文本令牌存储。 |
--no-emit-env |
不要重新生成框架 .env.local 文件。 |
-v, --verbose |
启用详细日志记录。 |
rayfin dev functions apply
启动本地功能主机，针对当前部署。
| 选项 | 说明 |
|---|---|
--port <port> |
本地功能主机端口;默认为 7071。 |
--inspect-port <port> |
Node.js 检查端口;默认为 9229。 |
--no-debug |
禁用 Node.js 检测器。 |
--no-emit-env |
不要重新生成框架 .env.local 文件。 |
--verbose |
显示诊断输出。 |
--json |
输出JSON。 |
-y, --yes |
不要有互动提示即可运行。 |
管理代理文件
该rayfin init ai-files命令管理你项目中的 Rayfin 代理上下文文件：AGENTS.md、、 .mcp.json.agents/skills/rayfin/SKILL.md和 。 当你构建项目时，CLI会自动安装这些文件。 请执行以下命令，在现有项目中安装或刷新这些文件，或检查其状态。
rayfin init ai-files install
安装或刷新Rayfin代理文件。 该命令是幂等的，保留已有的用户配置。
| 选项 | 说明 |
|---|---|
--enable <id> |
通过命名空格的 ID 安装或保留特定项目，例如 skill:rayfin。 重复。 |
--disable <id> |
停止管理某个特定项目而不删除其文件。 重复。 |
--remove-files |
禁用项目时删除磁盘文件。 需要 --disable。 |
--force [ids...] |
覆盖修改过的物品，恢复缺失的物品，或重建畸形 .mcp.json的物品。 接受可选的命名空格ID以作用范围操作。 永远不会覆盖 AGENTS.md。 |
-n, --dry-run |
报告变更时无需写文件。 |
--json |
以 JSON 形式输出结构化;意味着非交互模式。 |
-y, --yes、--non-interactive |
跳过交互提示，接受默认值。 |
例如，安装默认设置无需提示：
npx rayfin init ai-files install --yes
rayfin init ai-files status
打印每个托管代理文件的状态。 用于 --json 结构化输出。
可能的状态包括 up-to-date、 update-available、 user-modifiedmissing、 orphanednot-installeddisabledunreadable和 。 运行 rayfin init ai-files install 以刷新文件或 rayfin init ai-files install --force <id> 覆盖特定受管理项目。
部署到Fabric
rayfin up
使用 rayfin up 将应用部署到 Fabric 作为 Rayfin 项。
| 论点 | 说明 |
|---|---|
-t, --tenant <id> |
使用特定的租户ID。 |
-w, --workspace <name> |
按名称部署到 Fabric 工作区;默认为 My Workspace。 |
--workspace-id <id> |
部署到特定的 Fabric 工作区 ID。 |
--workspace-uri <uri> |
部署到特定的 Fabric 工作区 URI。 |
--item-name <name> |
Fabric 项目显示名称;默认为项目 ID。 |
--capacity-id <id> |
当目标工作空间需要容量时，使用Fabric容量ID。 |
--force |
允许破坏性的数据模式变更。 |
-n, --dry-run |
验证输入并解析工作空间，无需部署。 |
--env-file <path> |
.env 用于部署属性的文件;默认为 rayfin/.env。 |
-v, --verbose |
启用详细输出。 |
--json |
返回部署输出为JSON格式。 |
-y, --yes |
自动接受确认。 |
--encryption-fallback-enabled |
当操作系统密钥链不可用时，允许纯文本令牌存储。 |
--exclude-services <names> |
在构建和部署过程中跳过逗号分隔的服务： staticHosting 或 functions。 |
--provider <fabric> |
部署提供者;默认为 fabric。 |
示例
部署到当前选定的 Fabric 工作区：
npx rayfin up
预览部署操作而不应用：
npx rayfin up --dry-run --verbose
非交互式地部署到特定工作区：
npx rayfin up --workspace-id <workspace-id> --yes
部署时无需构建或部署功能：
npx rayfin up --exclude-services functions
--capacity-id 不能与 --workspace、 --workspace-id或 --workspace-uri组合使用。
| 子命令 | 说明 |
|---|---|
npx rayfin up db apply |
生成并应用DAB配置到远程Rayfin项目工作负载终端。 |
npx rayfin up functions deploy |
构建、打包并部署函数到活动的远程项目。 |
npx rayfin up staticapp deploy |
构建、打包并部署静态内容到远程的 Rayfin 项目。 |
npx rayfin up connector apply |
为已声明的GraphQL连接器应用数据库配置。 |
npx rayfin up status |
显示当前部署状态。 |
npx rayfin up list |
列出该项目录制的所有 Fabric 部署。 |
npx rayfin up switch [workspace] |
切换主动Fabric部署，重写 rayfin/.env。 |
rayfin up db apply
生成并应用DAB配置到远程Rayfin项目工作负载终端。
| 论点 | 说明 |
|---|---|
--verbose |
显示详细输出。 |
--force |
强制再生并应用配置。 |
--json |
返回 JSON 格式的输出。 |
示例
对远程Rayfin项应用数据库配置更改：
npx rayfin up db apply
强制再生并捕捉机器可读输出：
npx rayfin up db apply --force --json
rayfin up functions deploy
构建、打包并部署函数到活动的远程项目。
| 选项 | 说明 |
|---|---|
--verbose |
显示详细输出。 |
--skip-build |
部署现有的功能输出，无需构建。 |
--json |
输出JSON。 |
rayfin up connector apply
为声明的 GraphQL 连接器应用数据库配置。
| 选项 | 说明 |
|---|---|
--name <name> |
只使用指定的连接器。 |
--verbose |
启用详细输出。 |
--json |
输出JSON。 |
rayfin up staticapp deploy
构建、打包并部署静态内容到远程 Rayfin 项目。
| 论点 | 说明 |
|---|---|
--verbose |
显示详细输出。 |
--skip-build |
部署时不运行构建步骤。 |
--json |
返回 JSON 格式的输出。 |
示例
构建和部署静态内容：
npx rayfin up staticapp deploy
部署一个预构建 dist 的文件夹，无需重开构建：
npx rayfin up staticapp deploy --skip-build
rayfin up status
显示云部署状态。
| 论点 | 说明 |
|---|---|
--json |
返回状态格式为JSON。 |
--verbose |
显示详细输出。 |
示例
请查看当前部署状态：
npx rayfin up status
返回状态为脚本中使用的 JSON：
npx rayfin up status --json
rayfin up list
列出本项目中所有录制的 Fabric 部署。
| 论点 | 说明 |
|---|---|
--json |
返回部署列表，格式为JSON。 |
示例
列出该项目所有录制的 Fabric 部署：
npx rayfin up list
rayfin up switch [workspace]
切换激活Fabric部署，并相应重写rayfin/.env。
| 论点 | 说明 |
|---|---|
-l, --list |
列出无需切换即可部署的方案。 |
--no-emit-env |
跳过写出环境文件。 |
示例
列出可切换的部署：
npx rayfin up switch --list
将主动部署切换到特定工作区：
npx rayfin up switch my-workspace
生成环境文件
rayfin env
用于rayfin env输出框架特定的.env.local值。rayfin/.env
| 论点 | 说明 |
|---|---|
--framework <vite|nextjs|plain> |
选择目标框架格式。 |
--output <dir> |
把生成的文件写到特定的目录。 |
--show |
打印输出值而不写文件。 |
示例
生成与Vite兼容 .env.local的：
npx rayfin env --framework vite
无需写入文件即可预览发出的环境值：
npx rayfin env --framework nextjs --show
登录和登出
rayfin login
登录 rayfin login Rayfin平台。
| 论点 | 说明 |
|---|---|
--tenant <id> |
使用特定的租户ID。 |
--service-principal |
尝试服务负责人签到。 这个选项在帮助中列出，但目前不支持。 |
-u, --client-id <id> |
请提供客户ID，以便服务负责人登录。 这个选项在帮助中列出，但目前不支持。 |
-p, --client-secret <secret> |
提供客户密钥以便服务主体登录。 这个选项在帮助中列出，但目前不支持。 |
--select |
从可用的登录账户或上下文中选择。 |
--encryption-fallback-enabled |
启用加密备份行为。 |
示例
交互式登录：
npx rayfin login
登录特定租户：
npx rayfin login --tenant 00000000-0000-0000-0000-000000000000
切换登录账户：
npx rayfin login --select
| 子命令 | 说明 |
|---|---|
npx rayfin login status |
显示当前的认证状态。 |
rayfin login status
显示当前认证状态。
| 论点 | 说明 |
|---|---|
| 没有 | 这个子命令在CLI帮助输出中没有列出任何选项。 |
例子
检查您是否已登录：
npx rayfin login status
rayfin logout
登出并清除缓存的凭据。
| 论点 | 说明 |
|---|---|
| 没有 | 这个命令在CLI帮助输出中没有列出任何选项。 |
例子
登出并清除缓存凭证：
npx rayfin logout