Deploying with rayfin up

Use rayfin up to publish a Rayfin project to Microsoft Fabric. It is the full production deploy command: it syncs backend settings, applies schema changes, builds static content, and deploys enabled Functions. Use rayfin dev for local iteration.

Prerequisites

• A Rayfin project with rayfin/rayfin.yml.
• A Microsoft account or service principal with access to a Fabric workspace.
• Fabric apps enabled for the tenant.
• Usable Fabric capacity on the target workspace, or permission for Rayfin to prepare one.

Sign in interactively

npx rayfin login

The CLI opens a browser for Microsoft Entra ID sign-in and stores tokens with the operating system keychain. Check the current session at any time:

npx rayfin login status

If the keychain is unavailable in a development container or similar environment, opt in explicitly:

npx rayfin login --encryption-fallback-enabled

Sign in for CI

Use service principal credentials when a browser prompt is not available:

npx rayfin login --service-principal \
  --client-id <app-registration-client-id> \
  --client-secret <secret> \
  --tenant <tenant-id>

Credentials persist for later commands in the same job.

You can also set RAYFIN_TOKEN to a pre-acquired bearer token for headless automation. Use this only when an external system already owns token acquisition; otherwise prefer rayfin login --service-principal so the CLI can manage tenant and audience details.

Run a full deploy

npx rayfin up

If you are not signed in, the command starts the interactive login flow.

What rayfin up does

1. Reads rayfin/rayfin.yml, interpolates env values, and validates local service inputs.
2. Resolves the target Fabric workspace from flags, RAYFIN_WORKSPACE_ID, recorded deployments, or interactive selection.
3. Checks Fabric capacity readiness and prepares a workspace when needed.
4. Chooses the Fabric item display name from --item-name or id in rayfin.yml.
5. Creates the App (preview) item on first deploy, or reuses the recorded item.
6. Retrieves the publishable key.
7. Resolves package versions (packageVersions) for the deploy client and installed auth SDK. New in 1.35.1
8. Syncs runtime settings from rayfin.yml, including auth, static hosting access, Functions, storage flags, and connectors.
9. Generates connector configuration and function metadata required by enabled services.
10. Applies the data schema generated from decorated entities.
11. Builds and packages static content when services.staticHosting.enabled is true and not excluded.
12. Uploads the static archive and records the hosting URL.
13. Deploys Functions when services.functions.enabled is true and not excluded.
14. Writes rayfin/.deployments.json, merges RAYFIN_PUBLIC_* values into rayfin/.env, and regenerates the frontend .env.local when possible.

When it finishes, the CLI prints the hosting URL when static content is deployed, a Fabric portal link, and deployment identifiers.

Target a workspace or item

Pass at most one workspace selector. --item-name changes the Fabric item display name for the deployment; runtime settings still come from rayfin.yml. After the item is recorded, later deploys reuse that item.

Prepare workspace capacity

Rayfin 1.36 can prepare a workspace and assign capacity during first deploys. New in 1.36

Readiness flow

1. If the selected workspace already has usable capacity, Rayfin uses it and does not change the assignment.
2. If no target is recorded or passed and the terminal is interactive, Rayfin asks: Choose a Fabric workspace for this deployment: with Use new workspace [Recommended] and Select existing workspace.
3. If a new workspace is selected, Rayfin creates a uniquely named workspace for the project and assigns capacity.
4. If an existing workspace is selected, Rayfin uses the accessible-workspace picker.
5. If a trial capacity is required, Rayfin may start or reuse an eligible Fabric trial capacity.
6. If assigning a selected or trial capacity requires consent, Rayfin prompts with Assign capacity <name> (<id>) to workspace <workspace>?.
7. With --yes, deterministic assignment prompts are approved automatically.
8. With --json or another non-interactive mode, Rayfin cannot ask questions. Provide explicit workspace targeting, or pass --capacity-id when capacity selection is required.

Capacity outcomes and exact messages

Do not combine --capacity-id with --workspace, --workspace-id, --workspace-uri, or RAYFIN_WORKSPACE_ID; the CLI validates this in the shared capacity option checker before deployment.

Preview without deploying

npx rayfin up --dry-run --workspace-id <workspace-guid>

Dry run validates local inputs and resolves the workspace without deploying or modifying resources. Changed in 1.36

Dry run does:

• Validate static-hosting paths and access posture; reports that a non-interactive deploy would default missing static-hosting posture to assetAccess: protected and write it to rayfin.yml. New in 1.35.1
• Resolve package versions that a deploy would declare.
• Authenticate and make read-only Fabric requests needed to resolve the workspace.
• Print the planned operations and target workspace.

Dry run does not:

• Run build commands.
• Create Fabric items.
• Apply runtime settings or schemas.
• Upload static content.
• Deploy Functions.
• Write rayfin/.deployments.json, rayfin/.env, or .env.local.

Skip specific deployment phases

Use --exclude-services <names> for scripts that intentionally run the deploy workflow while skipping selected build/package/deploy phases.

npx rayfin up --exclude-services staticHosting
npx rayfin up --exclude-services functions

This is not the normal local development loop. Use npm run dev for that.

Deploy schema, static content, or Functions only

Enabled Functions require application authentication in rayfin.yml before deploy:

services:
  functions:
    enabled: true
    auth:
      type: application

See Functions for authoring and authentication details.

Deployment metadata

rayfin/.deployments.json records deployments by workspace and is not committed to source control:

{
  "active": "team-apps",
  "deployments": {
    "team-apps": {
      "fabricItemId": "7db00cb9-f630-4ecf-8fc9-942e60af5d78",
      "itemName": "my-team-app",
      "fabricWorkspaceId": "8b17cf64-3c12-46ac-a572-192732c32641",
      "fabricTenantId": "00000000-0000-0000-0000-000000000000",
      "publishableKey": "pk-nua-EHihY2jz71V65YB4",
      "fabricPortalUrl": "https://app.fabric.microsoft.com/",
      "hostingUrl": "https://silky-sand-4924b3ad1f-centraluseuap.webapp.rayfingwdev.com",
      "deployedAt": "2026-04-28T01:15:50.514Z"
    }
  }
}

The matching RAYFIN_PUBLIC_* values are merged into rayfin/.env, and rayfin env maps them into framework-specific names such as VITE_RAYFIN_API_URL.

Manage multiple deployments

Use separate workspaces for dev, test, and production. A single checkout can record multiple deployments:

npx rayfin up list
npx rayfin up switch team-apps
npx rayfin up switch --workspace-id <workspace-guid>

up switch rewrites rayfin/.env for the selected deployment and regenerates the frontend .env.local unless --no-emit-env is set. If the active sign-in tenant differs from the deployment tenant, the command warns so you can run npx rayfin login with the right account.

Check deployment status

npx rayfin up status
npx rayfin up status --json

The status check verifies authenticated management access to the Fabric item. It does not validate every application route or function.

When static content is deployed, human-readable output includes:

Static app:      https://silky-sand-4924b3ad1f-centraluseuap.webapp.rayfingwdev.com

JSON output exposes the same value as deployment.hostingUrl:

{
  "deployment": {
    "hostingUrl": "https://silky-sand-4924b3ad1f-centraluseuap.webapp.rayfingwdev.com"
  }
}

When no static app URL is recorded, the line is omitted and deployment.hostingUrl is null.

Sign out

npx rayfin logout

Common flags

This table covers the flags used most often in guides and automation. See rayfin up for the exhaustive list.

Troubleshooting

See Deployment troubleshooting for exact CLI error text.