找到 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透過呼叫 create initializer 套件來啟動新專案。 要搭建一個 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 |
Structure a Functions 套件。 |
npx rayfin dev |
在本地執行應用程式和功能。 |
npx rayfin init ai-files |
安裝或檢查 Rayfin agent 的上下文檔案。 |
npx rayfin up |
將應用程式部署到 Fabric 並管理遠端部署。 |
npx rayfin env |
從 rayfin/.env中產生框架專用環境檔案。 |
npx rayfin login |
登入 Rayfin 平台。 |
npx rayfin logout |
登出並清除快取的憑證。 |
建立或配置專案
rayfin init [directory]
用 rayfin init 來新增或現有專案加入 Rayfin。
| Argument | Description |
|---|---|
--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。 |
Examples
在支架前列出可用範本：
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
列出你可以加入專案的連接器類型。
| Option | Description |
|---|---|
--json |
將連接器類型清單以 JSON 形式發佈。 |
-v, --verbose |
包含能力細節。 |
rayfin connector search [query]
搜尋 Fabric 來源，確認登入身份可新增為連接器。
| 論證或選項 | Description |
|---|---|
[query] |
可選的大小寫不區分來源名稱過濾器。 |
--query <text> |
命名的來源名稱過濾器，優先於 [query]。 |
--type <type> |
逗號分隔的連接器類型;必須與或 --all-workspaces一起。--workspace-id |
--workspace-id <id> |
搜尋一個 Fabric 工作區。 |
--all-workspaces |
搜尋該身份能存取的每一個工作區。 |
-y, --yes |
自動接受互動式新增切換。 |
--limit <n> |
顯示結果的最大數量。 |
--output <interactive\|plain\|json> |
選擇輸出格式。 |
--json |
列印結果為 JSON 並跳過互動式選擇器。 |
-v, --verbose |
啟用冗長輸出。 |
當兩個工作區選項都未提供時，指令會搜尋目前專案部署所記錄的工作區。
rayfin connector add --type <type>
新增一個連接器聲明並搭建專案檔案。
| Option | Description |
|---|---|
--type <type> |
Required. 連接器類型;用於 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宣告的連接器。
| Option | Description |
|---|---|
-v, --verbose |
請包含連接器的元資料與功能。 |
--json |
輸出 JSON 。 |
rayfin connector inspect
檢查已設定的連接器或直接位址的 Fabric 來源，且不做任何更改。
| Option | Description |
|---|---|
--name <name> |
已設定連接器名稱。 |
-w, --workspace <name> |
工作區名稱以便直接檢查。 |
--workspace-id <id> |
工作區 ID 用於直接檢查。 |
--item <name> |
直接檢查時會用物品名稱。 |
--item-id <id> |
物品識別碼以便直接檢查。 |
--type <type> |
直接檢查用的連接器類型。 |
--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]
呼叫已配置連接器的操作。
| 論證或選項 | Description |
|---|---|
[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>
移除一個連接器宣告及其產生的連接器檔案。
| 論證或選項 | Description |
|---|---|
<name> |
Required. 連接器名稱需移除。 |
-v, --verbose |
啟用冗長輸出。 |
-y, --yes |
自動接受移除確認。 |
--json |
輸出 JSON 。 |
函數指令
rayfin functions init [directory]
架構並配置一個函式套件。
| 論證或選項 | Description |
|---|---|
[directory] |
Project root;預設為目前的目錄。 |
--force |
覆寫現有的功能支架。 |
--path <relative-path> |
函式套件相對於專案根的位置。 |
套件位置預設為偵測到的工作區位置或 rayfin/functions。
開發指令
rayfin dev [project-path]
開始對 Rayfin 後端進行本地開發。
| 論證或選項 | Description |
|---|---|
[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 租用戶識別碼。 |
--encryption-fallback-enabled |
當作業系統無法使用鑰匙圈時，允許純文字令牌儲存。 |
--no-emit-env |
不要重新產生框架 .env.local 檔案。 |
-v, --verbose |
啟用詳細資訊記錄。 |
rayfin dev functions apply
啟動本地函式主機，對主動部署進行。
| Option | Description |
|---|---|
--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 agent 上下文檔案：AGENTS.md、、 .mcp.json.agents/skills/rayfin/SKILL.md和 。 CLI 會在你搭建專案時自動安裝這些檔案。 執行以下指令，安裝或刷新現有專案，或檢查狀態。
rayfin init ai-files install
安裝或刷新 Rayfin 代理檔。 此指令為冪元指令，並保留現有使用者設定。
| Option | Description |
|---|---|
--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、 not-installed、 disabledorphanedunreadable和 。 執行 rayfin init ai-files install 以刷新檔案或 rayfin init ai-files install --force <id> 覆寫特定受管理項目。
部署到 Fabric
rayfin up
使用 rayfin up 將應用程式部署到 Fabric，作為 Rayfin 項目。
| Argument | Description |
|---|---|
-t, --tenant <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。 |
Examples
部署到目前選擇的 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結合使用。
| Subcommand | Description |
|---|---|
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 項目工作負載端點。
| Argument | Description |
|---|---|
--verbose |
顯示詳細輸出。 |
--force |
強制再生並套用設定。 |
--json |
以 JSON 格式回傳輸出。 |
Examples
對遠端 Rayfin 項目套用資料庫設定變更：
npx rayfin up db apply
強制再生並捕捉機器可讀的輸出：
npx rayfin up db apply --force --json
rayfin up functions deploy
建置、封裝並部署函式到活躍的遠端項目。
| Option | Description |
|---|---|
--verbose |
顯示詳細輸出。 |
--skip-build |
部署現有函式輸出，無需建構。 |
--json |
輸出 JSON 。 |
rayfin up connector apply
為宣告的 GraphQL 連接器套用資料庫配置。
| Option | Description |
|---|---|
--name <name> |
只套用指定的連接器。 |
--verbose |
啟用冗長輸出。 |
--json |
輸出 JSON 。 |
rayfin up staticapp deploy
建置、封裝並部署靜態內容到遠端 Rayfin 項目。
| Argument | Description |
|---|---|
--verbose |
顯示詳細輸出。 |
--skip-build |
部署時不執行建置步驟。 |
--json |
以 JSON 格式回傳輸出。 |
Examples
建置並部署靜態內容：
npx rayfin up staticapp deploy
部署一個預先建置 dist 的資料夾，無需重跑建置：
npx rayfin up staticapp deploy --skip-build
rayfin up status
顯示雲端部署狀態。
| Argument | Description |
|---|---|
--json |
以 JSON 格式回傳狀態。 |
--verbose |
顯示詳細輸出。 |
Examples
請查看目前的部署狀態：
npx rayfin up status
回傳狀態為 JSON 用於腳本：
npx rayfin up status --json
rayfin up list
列出本專案所有錄製的 Fabric 部署。
| Argument | Description |
|---|---|
--json |
請以 JSON 格式回傳部署清單。 |
Examples
列出本專案所有已錄製的 Fabric 部署：
npx rayfin up list
rayfin up switch [workspace]
切換主動Fabric部署並相應重寫 rayfin/.env。
| Argument | Description |
|---|---|
-l, --list |
列出可部署的方案，無需切換。 |
--no-emit-env |
跳過寫入已發佈的環境檔案。 |
Examples
列出可切換的部署：
npx rayfin up switch --list
將主動部署切換到特定工作區：
npx rayfin up switch my-workspace
產生環境檔案
rayfin env
使用 rayfin env 以輸出框架特定的.env.local值。rayfin/.env
| Argument | Description |
|---|---|
--framework <vite|nextjs|plain> |
選擇目標框架格式。 |
--output <dir> |
將產生的檔案寫入特定目錄。 |
--show |
列印輸出值時不寫入檔案。 |
Examples
產生相容 .env.local的 Vite：
npx rayfin env --framework vite
預覽已發出的環境值，無需寫入檔案：
npx rayfin env --framework nextjs --show
登入和登出
rayfin login
請使用 rayfin login 登入 Rayfin 平台。
| Argument | Description |
|---|---|
--tenant <id> |
使用特定的租戶識別碼。 |
--service-principal |
嘗試服務負責人簽到。 這個選項在說明中有列出，但目前不支援。 |
-u, --client-id <id> |
請提供服務主體登入時的客戶 ID。 這個選項在說明中有列出，但目前不支援。 |
-p, --client-secret <secret> |
提供客戶端的秘密資料以便服務主體登入。 這個選項在說明中有列出，但目前不支援。 |
--select |
從可用的登入帳號或情境中選擇。 |
--encryption-fallback-enabled |
啟用加密備援行為。 |
Examples
互動式登入：
npx rayfin login
登入特定租戶：
npx rayfin login --tenant 00000000-0000-0000-0000-000000000000
切換登入帳號：
npx rayfin login --select
| Subcommand | Description |
|---|---|
npx rayfin login status |
顯示目前的認證狀態。 |
rayfin login status
顯示目前的認證狀態。
| Argument | Description |
|---|---|
| 沒有 | 這個子指令在 CLI 說明的輸出中沒有列出任何選項。 |
Example
請確認您是否已登入：
npx rayfin login status
rayfin logout
登出並清除快取的憑證。
| Argument | Description |
|---|---|
| 沒有 | 這個指令在 CLI 說明的輸出中沒有列出任何選項。 |
Example
登出並清除快取憑證：
npx rayfin logout