fabric-cli-core

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fabric CLI Core

Fabric CLI 核心

This skill defines safe, consistent defaults for an AI agent helping users operate Microsoft Fabric via the Fabric CLI (
fab
).

本技能为帮助用户通过Fabric CLI (
fab
) 操作Microsoft Fabric的AI Agent定义了安全、一致的默认规则。

1 - Fabric CLI mental model (paths and entities)

1 - Fabric CLI 心智模型（路径与实体）

Automation Scripts

自动化脚本

Ready-to-use Python scripts for core CLI tasks. Run any script with

--help

for full options.

Script	Purpose	Usage
`health_check.py`	Verify CLI installation, auth status, and connectivity	`python scripts/health_check.py [--workspace WS]`

Scripts are located in the

scripts/

folder of this skill.

可直接使用的Python脚本，用于执行核心CLI任务。运行任意脚本时添加

--help

参数可查看完整选项。

脚本	用途	用法
`health_check.py`	验证CLI安装、认证状态和连通性	`python scripts/health_check.py [--workspace WS]`

脚本存放在本技能的

scripts/

文件夹下。

Paths and Entities

路径与实体

Treat Fabric as a filesystem-like hierarchy with consistent dot (.) entity suffixes in paths (e.g.,
```
.Workspace
```
,
```
.Folder
```
,
```
.SemanticModel
```
).
The hierarchy structure is:
- Tenant: The top-level container for everything.
- Workspace: Personal or team workspace holding folders, items, and workspace-level elements.
- Folder: Container for organizing items within a workspace (supports ~10 levels of nesting).
- Item: Individual resource within a workspace or folder (e.g., Notebook, SemanticModel, Lakehouse).
- OneLakeItem: OneLake storage item residing within a Lakehouse (tables, files, etc.).

Prefer and generate paths like:

/Workspace1.Workspace/Notebook1.Notebook

/Workspace1.Workspace/FolderA.Folder/SemanticModel1.SemanticModel

/Workspace1.Workspace/FolderA.Folder/lh1.Lakehouse/Tables

(OneLakeItem)

When a user provides an ambiguous identifier, ask for the full path (or infer with stated assumptions).

将Fabric视为类文件系统层级结构，路径中的实体统一使用点(.)后缀标识（例如
```
.Workspace
```
、
```
.Folder
```
、
```
.SemanticModel
```
）。
层级结构如下：
- 租户（Tenant）：所有资源的顶级容器。
- 工作区（Workspace）：个人或团队工作区，存放文件夹、项目和工作区级元素。
- 文件夹（Folder）：用于在工作区内组织项目的容器（支持约10级嵌套）。
- 项目（Item）：工作区或文件夹内的独立资源（例如Notebook、SemanticModel、Lakehouse）。
- OneLake项目（OneLakeItem）：存放在Lakehouse中的OneLake存储资源（表、文件等）。

推荐生成的路径格式示例：

/Workspace1.Workspace/Notebook1.Notebook

/Workspace1.Workspace/FolderA.Folder/SemanticModel1.SemanticModel

/Workspace1.Workspace/FolderA.Folder/lh1.Lakehouse/Tables

（OneLakeItem）

当用户提供的标识符含义模糊时，请求用户提供完整路径（或在明确说明假设的前提下进行推断）。

2 - Modes (interactive vs command line)

2 - 模式（交互模式 vs 命令行模式）

Be explicit about which mode a user is in:
- Interactive mode behaves like a REPL and runs commands without the
```
fab
```
  prefix.
- Command line mode runs one command per invocation and is best for scripts/automation.
The selected mode is preserved between sessions. If a user exits and logs back in, the CLI resumes in the same mode last used.
When you provide instructions, show commands in command line mode unless the user says they're in interactive mode.

明确告知用户当前所处的模式：
- 交互模式：行为类似REPL，运行命令无需添加
```
fab
```
  前缀。
- 命令行模式：每次调用运行一条命令，最适合脚本/自动化场景。
所选模式会在会话间保留。如果用户退出后重新登录，CLI会恢复到上次使用的模式。
提供操作说明时，默认展示命令行模式下的命令，除非用户明确说明处于交互模式。

3 - Authentication (public-safe guidance)

3 - 身份认证（公共安全指南）

Prefer these auth patterns and do not invent new flows:
1. Interactive user:
```
fab auth login
```
  (browser/WAM where supported).
2. Service principal (secret/cert): use environment variables / secure mechanisms; avoid embedding secrets in files.
3. Service principal (federated credential): use the federated token environment variable (
```
FAB_SPN_FEDERATED_TOKEN
```
  ) and do not persist the raw token.
4. Managed identity: supported for Azure-hosted workloads; no credentials required.
Never ask users to paste secrets into chat or print them back.

优先使用以下认证模式，请勿自创流程：
1. 交互式用户：
```
fab auth login
```
  （支持的环境下使用浏览器/WAM认证）。
2. 服务主体（密钥/证书）：使用环境变量/安全机制，避免将密钥嵌入文件。
3. 服务主体（联合凭证）：使用联合令牌环境变量(
```
FAB_SPN_FEDERATED_TOKEN
```
  )，请勿持久化原始令牌。
4. 托管身份：支持Azure托管的工作负载，无需提供凭证。
切勿要求用户在聊天中粘贴密钥，也不要将密钥回显给用户。

4 - Sensitive data handling (strict)

4 - 敏感数据处理（严格规范）

Never log or output tokens, passwords, client secrets, or raw federated tokens.
Validate all user inputs that could affect security:
- Paths: Sanitize file paths and API parameters.
- GUIDs: Validate resource identifiers before use.
- JSON: Validate JSON inputs for proper format.
If a user shares sensitive strings, advise rotating/regenerating them and moving to secure storage.

切勿记录或输出令牌、密码、客户端密钥、原始联合令牌。
校验所有可能影响安全的用户输入：
- 路径：清理文件路径和API参数。
- GUID：使用前验证资源标识符。
- JSON：验证JSON输入格式是否正确。
如果用户分享了敏感字符串，建议用户轮换/重新生成这些密钥，并迁移到安全存储中。

5 - Hidden entities and discovery

5 - 隐藏实体与发现

Hidden entities are special resources not normally visible, following a dot-prefixed naming convention (similar to UNIX hidden files).

Tenant-level hidden entities (accessed from root):

.capacities

—

fab ls .capacities

fab get .capacities/<name>.Capacity

.gateways

—

fab ls .gateways

fab get .gateways/<name>.Gateway

.connections

—

fab ls .connections

fab get .connections/<name>.Connection

.domains

—

fab ls .domains

fab get .domains/<name>.Domain

Workspace-level hidden entities (accessed within a workspace):

.managedidentities

—

fab ls ws1.Workspace/.managedidentities

.managedprivateendpoints

—

fab ls ws1.Workspace/.managedprivateendpoints

.externaldatashares

—

fab ls ws1.Workspace/.externaldatashares

.sparkpools

—

fab ls ws1.Workspace/.sparkpools

To show hidden resources, recommend
```
ls -a
```
/
```
ls --all
```
.

隐藏实体是通常不可见的特殊资源，遵循点前缀命名约定（类似UNIX隐藏文件）。

租户级隐藏实体（从根路径访问）：

.capacities

—

fab ls .capacities

fab get .capacities/<name>.Capacity

.gateways

—

fab ls .gateways

fab get .gateways/<name>.Gateway

.connections

—

fab ls .connections

fab get .connections/<name>.Connection

.domains

—

fab ls .domains

fab get .domains/<name>.Domain

工作区级隐藏实体（在工作区内访问）：

.managedidentities

—

fab ls ws1.Workspace/.managedidentities

.managedprivateendpoints

—

fab ls ws1.Workspace/.managedprivateendpoints

.externaldatashares

—

fab ls ws1.Workspace/.externaldatashares

.sparkpools

—

fab ls ws1.Workspace/.sparkpools

如需展示隐藏资源，推荐使用
```
ls -a
```
/
```
ls --all
```
命令。

6 - Errors and troubleshooting guidance

6 - 错误与故障排除指南

When describing failures, include:
- What the command was trying to do
- The likely cause
- The next actionable step
If the CLI surfaces an error code/message, keep it intact and do not paraphrase away the key identifiers. (Fabric CLI emphasizes stable error codes/messages.)
Include request IDs for API errors to aid debugging when available.

描述故障时，需包含以下内容：
- 该命令原本要执行的操作
- 可能的原因
- 下一步可执行的操作
如果CLI返回了错误代码/消息，请完整保留，不要改写关键标识。（Fabric CLI强调稳定的错误代码/消息。）
API错误如果有请求ID，需包含请求ID以便调试。

7 - Output conventions for the agent

7 - Agent 输出规范

Default to concise, runnable steps.
When recommending commands, include:
- Preconditions (auth, correct workspace/path)
- Expected result
- How to verify (e.g., follow-up
```
fab ls
```
  /
```
fab get
```
  )

默认提供简洁、可直接运行的步骤。
推荐命令时，需包含：
- 前置条件（认证、正确的工作区/路径）
- 预期结果
- 验证方法（例如后续执行
```
fab ls
```
  /
```
fab get
```
  ）

8 - Safety defaults

8 - 安全默认规则

Ask before suggesting commands that delete, overwrite, or change access/permissions.
If the user explicitly confirms, proceed with a clear rollback note when possible.

建议执行删除、覆盖或修改访问/权限的命令前，先询问用户确认。
如果用户明确确认，可继续执行，尽可能提供清晰的回滚说明。

9 - Platform and troubleshooting reference

9 - 平台与故障排除参考

Supported platforms: Windows, Linux, macOS.
Supported shells: zsh, bash, PowerShell, cmd (Windows command prompt).
Python versions: 3.10, 3.11, 3.12, 3.13.
CLI file storage (useful for troubleshooting):
- Config files are stored in
```
~/.config/fab/
```
  :
  - ```
  cache.bin
```
  — encrypted auth token cache
- ```
config.json
```
    — non-sensitive CLI settings
  - ```
  auth.json
```
  — non-sensitive auth info
- ```
context-<session_id>
```
    — path context for command-line mode sessions
- Debug logs are written to:
  - Windows:
```
%AppData%/fabcli_debug.log
```
  - macOS:
```
~/Library/Logs/fabcli_debug.log
```
  - Linux:
```
~/.local/state/fabcli_debug.log
```

支持的平台：Windows、Linux、macOS。
支持的Shell：zsh、bash、PowerShell、cmd（Windows命令提示符）。
支持的Python版本：3.10、3.11、3.12、3.13。
CLI文件存储路径（可用于故障排除）：
- 配置文件存储在
```
~/.config/fab/
```
  ：
  - ```
  cache.bin
```
  — 加密的认证令牌缓存
- ```
config.json
```
    — 非敏感CLI设置
  - ```
  auth.json
```
  — 非敏感认证信息
- ```
context-<session_id>
```
    — 命令行模式会话的路径上下文
- 调试日志写入路径：
  - Windows：
```
%AppData%/fabcli_debug.log
```
  - macOS：
```
~/Library/Logs/fabcli_debug.log
```
  - Linux：
```
~/.local/state/fabcli_debug.log
```

10 - Critical operational rules

10 - 关键操作规则

First run: Always run
```
fab auth status
```
to verify authentication before executing commands. If not authenticated, ask the user to run
```
fab auth login
```
.
Learn before executing: Always use
```
fab --help
```
and
```
fab <command> --help
```
the first time you use a command to understand its syntax.
Start simple: Try the basic
```
fab
```
command alone first before piping or chaining.
Non-interactive mode: Use
```
fab
```
in command-line mode when working with coding agents. Interactive mode doesn't work with automation.
Force flag: Use
```
-f
```
when executing commands if the flag is available to run non-interactively (skips confirmation prompts).
Verify before acting: If workspace or item name is unclear, ask the user first, then verify with
```
fab ls
```
or
```
fab exists
```
before proceeding.
Permission errors: If a command is blocked by permissions, stop and ask the user for clarification; never try to circumvent it.

首次运行：执行任何命令前，始终先运行
```
fab auth status
```
验证认证状态。如果未认证，要求用户运行
```
fab auth login
```
。
执行前学习：首次使用某条命令时，始终先使用
```
fab --help
```
和
```
fab <command> --help
```
了解其语法。
从简起步：在使用管道或链式调用前，先尝试单独运行基础
```
fab
```
命令。
非交互模式：与编码Agent配合使用时，采用命令行模式运行
```
fab
```
。交互模式不支持自动化场景。
强制标志：执行命令时如果支持
```
-f
```
标志，可使用该标志非交互运行（跳过确认提示）。
操作前验证：如果工作区或项目名称不明确，先询问用户，然后使用
```
fab ls
```
或
```
fab exists
```
验证后再继续操作。
权限错误：如果命令因权限被阻止，停止操作并询问用户确认，切勿尝试绕过权限。

11 - Common item types

11 - 常见项目类型

Extension	Description
`.Workspace`	Workspace container
`.Folder`	Folder within workspace
`.SemanticModel`	Power BI dataset/semantic model
`.Report`	Power BI report
`.Dashboard`	Power BI dashboard
`.Notebook`	Fabric notebook
`.Lakehouse`	Lakehouse
`.Warehouse`	Data warehouse
`.DataPipeline`	Data pipeline
`.SparkJobDefinition`	Spark job definition
`.Eventstream`	Real-time event stream
`.KQLDatabase`	KQL database
`.MLModel`	ML model
`.MLExperiment`	ML experiment
`.Capacity`	Fabric capacity (hidden)
`.Gateway`	Data gateway (hidden)
`.Connection`	Connection (hidden)

Use

fab desc .<ItemType>

to explore any item type.

后缀	描述
`.Workspace`	工作区容器
`.Folder`	工作区内的文件夹
`.SemanticModel`	Power BI数据集/语义模型
`.Report`	Power BI报表
`.Dashboard`	Power BI仪表板
`.Notebook`	Fabric笔记本
`.Lakehouse`	Lakehouse
`.Warehouse`	数据仓库
`.DataPipeline`	数据管道
`.SparkJobDefinition`	Spark作业定义
`.Eventstream`	实时事件流
`.KQLDatabase`	KQL数据库
`.MLModel`	ML模型
`.MLExperiment`	ML实验
`.Capacity`	Fabric容量（隐藏）
`.Gateway`	数据网关（隐藏）
`.Connection`	连接（隐藏）

使用

fab desc .<ItemType>

可查看任意项目类型的详情。

12 - Command references

12 - 命令参考

For detailed command syntax and working examples, see:

Quick Start Guide — Copy-paste examples for common tasks
Full Command Reference — All commands with flags and patterns
Semantic Models — TMDL, DAX queries, refresh, storage modes
Notebooks — Job execution, parameters, scheduling
Reports — Export, import, rebind to models
Workspaces — Create, manage, permissions
Querying Data — DAX and lakehouse table queries
API Reference — Direct REST API access patterns
Create Workspaces — Workspace creation workflows

如需了解详细的命令语法和可用示例，请查看：

快速入门指南 — 常见任务的可复制示例
完整命令参考 — 所有命令的参数和使用模式
语义模型 — TMDL、DAX查询、刷新、存储模式
笔记本 — 作业执行、参数、调度
报表 — 导出、导入、重新绑定到模型
工作区 — 创建、管理、权限
数据查询 — DAX和lakehouse表查询
API参考 — 直接REST API访问模式
创建工作区 — 工作区创建流程