--- title: "Connector" description: "rayfin connector manages external Fabric sources, from discovery and registration through inspection and invocation." url: https://rayfin.ai/docs/reference/cli/connector markdown_url: https://rayfin.ai/docs/reference/cli/connector.md section: reference product: Rayfin sdk_version: 1.34.0 cli_version: 1.33.2 last_updated: 2026-08-29T23:37:34-07:00 source: reference/cli/connector.mdx --- # Connector > rayfin connector manages external Fabric sources, from discovery and registration through inspection and invocation. > [!NOTE] > `connector` is registered only when connectors are enabled. Enable it with > `services.connectors.enabled: true` in `rayfin/rayfin.yml`, with any non-empty > top-level `connectors:` block, or for one command with > `RAYFIN_FEATURE_FLAGS=connectors`. Without one of those opt-ins, the CLI reports > `connector` as an unknown command. Use `rayfin connector` to discover existing Microsoft Fabric sources, register them in `rayfin.yml`, inspect their read shape, and invoke configured operations. For the workflow and app-code model, start with [Connectors](/docs/connectors); this page is the command reference. ```bash npx rayfin connector ``` ## Connector types [#connector-types] | Type | Fabric item | Category | Operations | Version | | ---------------------- | -------------- | ---------- | ------------------------------------ | ---------------------------------- | | `fabric-sqlanalytics` | Lakehouse | Category A | `read` | No | | `fabric-warehouse` | Warehouse | Category A | `read`, `create`, `update`, `delete` | No | | `fabric-sqldatabase` | SQL Database | Category A | `read`, `create`, `update`, `delete` | No | | `fabric-semanticmodel` | Semantic model | Category B | `executeQuery` | Pinned to `'1'` by `connector add` | | `kusto` | KQL Database | Category B | `executeQuery`, `executeCommand` | Pinned to `'1'` by `connector add` | Category A connectors generate entity configuration for Data API Builder. Category B connectors expose function-style query operations and are delegated-only. See [Connectors](/docs/connectors), [Fabric SQL sources](/docs/connectors/sql-sources), [Semantic models](/docs/connectors/semantic-models), and [KQL databases](/docs/connectors/kusto). ## Subcommands [#subcommands] The registered subcommands are `search`, `add`, `list`, `remove`, `types`, `inspect`, and `invoke`. ## `connector search` [#connector-search] ```bash npx rayfin connector search [query] --workspace-id --type npx rayfin connector search [query] --all-workspaces --type npx rayfin connector search [query] ``` Searches Fabric items that the signed-in identity can add as connectors. Use one of these scopes: | Scope | Required flags | Behavior | | ---------------- | ----------------------------------------- | ------------------------------------------------------------------------------------- | | Single workspace | `--workspace-id ` and `--type ` | Searches one workspace. | | Tenant-wide | `--all-workspaces` and `--type ` | Searches all accessible workspaces. | | Deployed project | No scope flags | Searches every workspace recorded in the project's deployments; `--type` is optional. | | Flag | Description | | ----------------------------------- | ---------------------------------------------------------------------------------------------- | | `[query]` | Optional case-insensitive item-name filter. | | `--query ` | Same filter as `[query]`; wins when both are provided. | | `--workspace-id ` | Search one Fabric workspace. Requires `--type`. | | `--all-workspaces` | Search every workspace the signed-in identity can access. Requires `--type`. | | `--type ` | Narrow to one or more comma-separated connector types. Required with explicit workspace scope. | | `--limit ` | Limit non-interactive output to the first `n` results. | | `--output interactive\|plain\|json` | Select output mode. | | `--json` | Emit one JSON object and skip the interactive picker. | | `-v, --verbose` | Enable verbose output. Cannot be combined with `--json`. | | `-y, --yes` | Auto-accept prompts in the interactive add handoff. | With `--json`, the command emits `{ status, query, scope, count, sources }`. Each result in `sources` includes a suggested name and a ready-to-run `addCommand`. ## `connector add` [#connector-add] ```bash npx rayfin connector add --type fabric-sqldatabase --workspace-id --item-id --name sales ``` Registers one source in `rayfin/rayfin.yml` and scaffolds `rayfin/connectors//`. | Flag | Description | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `--type ` | Required. One of the five connector type literals. | | `--workspace-id ` | Required Fabric workspace ID. Must be a literal value; `${VAR}` placeholders are rejected. | | `--item-id ` | Required Fabric item ID. Must be a literal value; `${VAR}` placeholders are rejected. | | `--name ` | Connector name. If omitted, the CLI derives one from the Fabric item display name. Must match `/^[a-zA-Z0-9\-_]+$/` and be at most 256 characters. | | `--operations ` | Comma-separated subset of allowed operations. This can narrow the catalog defaults but cannot widen them; there is no `all` meta-operation. | | `-y, --yes` | Auto-accept confirmation prompts, including overwriting an existing connector. | | `-v, --verbose` | Enable verbose output. | | `--json` | Emit machine-readable JSON. | The command verifies the Fabric item, writes the `connectors:` entry, and writes `rayfin/connectors//schema.ts`. For Category A it also runs schema discovery and writes `metadata.json`. For `kusto`, it resolves `queryServiceUri` and `databaseName` and bakes them into `schema.ts`; those values are not written to `rayfin.yml`. For versioned Category B types (`fabric-semanticmodel` and `kusto`), `connector add` writes the catalog `defaultVersion` automatically. Today that value is `'1'`. `connector add` does not install packages. It prints a version-pinned `npm install` command; with `--json`, the same data appears under `install.packages` and `install.command`. ## `connector list` [#connector-list] ```bash npx rayfin connector list ``` Lists connectors declared in `rayfin.yml`. It does not call Fabric or the deployed workload. | Flag | Description | | --------------- | ---------------------------------------------- | | `-v, --verbose` | Include catalog metadata for each connector. | | `--json` | Emit the configured connector entries as JSON. | ## `connector remove` [#connector-remove] ```bash npx rayfin connector remove sales --yes ``` Removes the named connector entry from `rayfin.yml` and deletes `rayfin/connectors//`. | Flag | Description | | --------------- | ----------------------------------------------------------------------------------------------- | | `-y, --yes` | Auto-accept confirmation prompts. Required in non-interactive contexts for existing connectors. | | `-v, --verbose` | Enable verbose output. | | `--json` | Emit machine-readable JSON. | JSON output for a removed connector is `{ status, action: 'connector.remove', name, removed, directoryDeleted }`. ## `connector types` [#connector-types-1] ```bash npx rayfin connector types --verbose ``` Lists the connector catalog. | Flag | Description | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `-v, --verbose` | Add category, default auth, dialect, operations, discoverable item types, required version, and client packages. | | `--output interactive\|plain\|json` | Select output mode. | | `--json` | Emit the catalog as JSON. | `--json` emits the same detailed catalog fields as verbose mode. ## `connector inspect` [#connector-inspect] ```bash npx rayfin connector inspect --name sales npx rayfin connector inspect --name sales --entity dbo.Customers --rows 10 npx rayfin connector inspect --workspace-id --item-id --type fabric-warehouse --query queries\sample.sql ``` Inspects a source in read-only mode. It supports `fabric-sqlanalytics`, `fabric-warehouse`, `fabric-sqldatabase`, and `fabric-semanticmodel`. It does not support `kusto`; that type fails with `Unsupported connector type: kusto`. | Flag | Description | | -------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `--name ` | Select a connector declared in `rayfin.yml`. Mutually exclusive with direct selectors. | | `--workspace-id ` / `--workspace ` | Direct mode workspace selector. Use with `--item-id` or `--item` and `--type`. | | `--item-id ` / `--item ` | Direct mode item selector. Use with a workspace selector and `--type`. | | `--type ` | Connector type for direct mode. | | `--url ` | Semantic-model portal URL; extracts workspace and item IDs. Cannot be combined with other selectors. | | `--entity ` | Structured entity sampling mode. | | `--query ` | Raw query mode. Path must point to a `.sql` or `.dax` file inside the project. | | `--rows ` | Row cap. Default is 100 for entity listing and 10 for entity or query modes; maximum is 100. | | `-v, --verbose` | Enable verbose output. | | `--output interactive\|plain\|json` | Select output mode. | | `--json` | Emit a machine-readable JSON object. | Inspect has three modes: | Mode | How to select it | Query shape | | ----------------- | ----------------------------- | -------------------------------------------------------------------------------------- | | Entity listing | Omit `--entity` and `--query` | SQL uses `INFORMATION_SCHEMA.TABLES`; DAX uses `INFO.TABLES()`. | | Structured entity | Pass `--entity ` | SQL builds `SELECT TOP(n) * FROM `; DAX builds `EVALUATE TOPN(n, '')`. | | Raw query | Pass `--query ` | Runs the `.sql` or `.dax` file verbatim. | SQL inspect accepts only read queries that start with `SELECT` or `WITH`; DML and DDL are rejected. DAX inspect requires the query to start with `EVALUATE`. ## `connector invoke` [#connector-invoke] ```bash npx rayfin connector invoke mymodel executeQuery --input '{"query":"EVALUATE TOPN(10, Sales)"}' npx rayfin connector invoke --name mymodel --operation executeQuery --file payload.json ``` Invokes one configured operation. The positional connector name and operation also have flag forms, `--name` and `--operation`; flag values win over positionals. | Flag | Description | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `` | Connector name declared in `rayfin.yml`. | | `` | Operation to invoke. | | `--name ` | Connector name flag form; wins over the positional. | | `--operation ` | Operation flag form; wins over the positional. | | `--input ''` | Inline JSON payload. Exactly one of `--input` or `--file` is required. | | `--file ` | JSON payload file, resolved against the project root. The resolved path must stay inside it; `..\` escapes are rejected before the file is read. | | `-v, --verbose` | Enable verbose output. Cannot be combined with `--json`. | | `--output interactive\|plain\|json` | Select output mode. | | `--json` | Emit one machine-readable JSON object. | Operation names match case-insensitively against the connector's `operations:` list. If the entry has no operations, the command falls back to the connector type's full catalog allowlist. ### Invoke transports [#invoke-transports] `fabric-semanticmodel` calls Fabric and Power BI directly under the developer's own identity. It works with or without `rayfin up`, and it requires `workspaceId` and `itemId` under the connector's `config:` block. Every other type, including `kusto`, POSTs to the deployed item at `/__private/connectors//invoke` and requires a prior `rayfin up`. ### Invoke token handling [#invoke-token-handling] `rayfin login` consents to the Fabric scope, not the Power BI scope the semantic-model path needs. Interactively, the CLI prompts to complete Power BI consent. With `--json`, token acquisition is silent-only so prompts cannot corrupt the single-JSON-object contract; if consent is still needed, the command fails and tells you to drop `--json` or set `RAYFIN_TOKEN`. When `RAYFIN_TOKEN` is set, it is passed through unchanged and its audience is decoded and checked locally. ### Invoke output [#invoke-output] Success emits `{ status: 'ok', connector, operation, output }`. A resolved call is not automatically a success: a normalizing connector reports failure as `status: 'error'`, and a connector returning a raw envelope reports failure as `status: 'Failed'`. The CLI converts either failure shape into a non-zero exit. > [!NOTE] > Invoking a semantic model operation whose DAX returns Int64 columns, for example > `DISTINCTCOUNT`, can fail while printing with `Do not know how to serialize a BigInt` even > though the query succeeded. Select a non-Int64 column to read the output. ### Invoke errors [#invoke-errors] | Message | Fix | | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | `Missing required connector invoke arguments` | Supply both the connector name and the operation. | | `Choose exactly one payload source` / `Missing payload input` | Pass exactly one of `--input` or `--file`. | | `Input file must be inside the project` | Use a relative path under the project root. | | `Operation "" is not allowed for connector ""` | Check the connector's `operations:` in `rayfin.yml`, or the type's allowlist. | | `missing workspaceId/itemId in rayfin.yml` | Add both under `config:`, or re-run [`connector add`](#connector-add). | | `Access token has the wrong audience for the Power BI query API` | Unset or replace `RAYFIN_TOKEN`, or re-run without `--json` to consent interactively. | | `No remote endpoint configured` | The non-semantic-model transport needs a deployed item; run `npx rayfin up` first. | ```prompt title="Register a Fabric SQL Database connector" Add a Rayfin connector named "sales" for my Fabric SQL Database using `npx rayfin connector add --type fabric-sqldatabase --workspace-id --item-id --name sales`, then show me the resulting rayfin.yml entry and the scaffolded rayfin/connectors/sales/schema.ts. ```