Referencia de CLI de Rayfin

Encuentra los comandos de la CLI de Rayfin para crear proyectos, gestionar cambios de esquema, desplegar en Fabric y configurar la configuración del entorno. Cada sección enumera la sintaxis de los comandos, las opciones y los usos habituales.

Installation

Lo uso npm i @microsoft/rayfin-cli para instalar la CLI.

Cómo empezar

Sigue los pasos de tu terminal para crear una app de 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

Sugerencia

Para proyectos existentes o vacíos, usa npx rayfin init en lugar de npm create añadir Rayfin a un proyecto que ya tenga código fuente o un directorio vacío. El comando init te guía para habilitar servicios, elegir un dialecto de base de datos y configurar alojamiento estático sin andamiar una nueva plantilla.

Para la guía completa, consulta Crea y despliega tu primera app de Fabric con la CLI y Despliega una app Fabric en Fabric.

Andamiaje de un proyecto con npm create

npm create (alias de npm init) Arranca un nuevo proyecto invocando un paquete Create Initializer. Para andamiar una aplicación Fabric, úsala con el inicializador @microsoft/rayfin:

npm create @microsoft/rayfin@latest my-app --workspace <workspace name>

Referencia de comandos

Los comandos y flags de este artículo fueron verificados a partir de la salida de ayuda de la CLI instalada localmente.

Comandos de nivel superior

Usa esta tabla para encontrar el comando correcto rápidamente.

Comando	Úsela para
npx rayfin init [directory]	Crea o configura un proyecto Rayfin.
npx rayfin connector	Encontrar, configurar, inspeccionar e invocar los conectores de datos Fabric.
npx rayfin functions init	Andamiaje de un paquete de Funciones.
npx rayfin dev	Ejecuta la app y Funciones localmente.
npx rayfin init ai-files	Instala o revisa los archivos contextuales del agente Rayfin.
npx rayfin up	Despliega la app en Fabric y gestiona despliegues remotos.
npx rayfin env	Genera archivos de entorno específicos del framework a partir de rayfin/.envarchivos de .
npx rayfin login	Inicia sesión en la plataforma Rayfin.
npx rayfin logout	Cierra sesión y borra las credenciales en caché.

Crea o configura un proyecto

rayfin init [directory]

Úsalo rayfin init para añadir Rayfin a un proyecto nuevo o ya existente.

Argument	Descripción
--project-name <name>	Establece el nombre del proyecto.
-t, --template <uri>	Especifica el URI plantilla que vas a usar.
--template-name <name>	Selecciona una plantilla por nombre.
-l, --list-templates	Lista de plantillas disponibles.
--dialect <dialect>	Establece el dialecto de la base de datos.
--services <list>	Elige qué servicios habilitar.
--auth-methods <list>	Elige métodos de autenticación.
--static-hosting	Activa la configuración de alojamiento estático.
--overwrite	Sobrescribe los archivos generados existentes.
--workspace-id <id>	Usa un ID específico de Fabric workspace.
--workspace-uri <uri>	Usa un URI específico de Fabric workspace.
--base-api-url <url>	Anula la URL base de la API.
--item-id <id>	Apunta a un ID específico de Fabric.

Ejemplos

Enumera las plantillas disponibles antes de montar el andamiaje:

npx rayfin init --list-templates

Inicializa Rayfin en el directorio actual usando una plantilla con nombre y un dialecto específico:

npx rayfin init . --template-name react-vite --dialect mssql

Crear un nuevo proyecto no interactivo con servicios y autenticación configurados:

npx rayfin init my-app --project-name my-app --services db,storage --auth-methods fabric --static-hosting --overwrite

Comandos de conector

El connector grupo de mando gestiona fuentes externas de datos Fabric.

rayfin connector types

Enumera tipos de conectores que puedes añadir a un proyecto.

Option	Descripción
--json	Emite la lista de tipos de conectores como JSON.
-v, --verbose	Incluye detalles de capacidades.

rayfin connector search [query]

Searches Fabric aporta que la identidad iniciada puede añadirse como conectores.

Argumento u opción	Descripción
[query]	Filtro opcional, insensible a mayúsculas y mayúsculas.
--query <text>	Filtro de nombre fuente nombrado que tiene precedencia sobre [query].
--type <type>	Tipos de conectores separados por comas; requeridos con --workspace-id o --all-workspaces.
--workspace-id <id>	Busca en un espacio de trabajo de Fabric.
--all-workspaces	Busca en todos los espacios de trabajo al que pueda acceder la identidad.
-y, --yes	Acepta automáticamente la transferencia interactiva de añadidos.
--limit <n>	Número máximo de resultados mostrados.
--output <interactive\|plain\|json>	Selecciona el formato de salida.
--json	Imprime los resultados en JSON y salta el selector interactivo.
-v, --verbose	Habilite la salida detallada.

Cuando ninguna de las opciones de espacio de trabajo está disponible, el comando busca en los espacios de trabajo registrados para el despliegue actual del proyecto.

rayfin connector add --type <type>

Añade una declaración de conector y estructura sus archivos de proyecto.

Option	Descripción
--type <type>	Required. Tipo de conector; usar rayfin connector types para listar tipos.
--name <name>	Nombre del conector; derivado del elemento cuando se omite.
--workspace-id <id>	ID de espacio de trabajo Fabric.
--item-id <id>	ID del Fabric Article.
--operations <ops>	Subconjunto separado por comas de operaciones permitidas.
-v, --verbose	Habilite la salida detallada.
-y, --yes	Acepta automáticamente las confirmaciones.
--json	Emite salida JSON.

rayfin connector list

Lista los conectores declarados en rayfin.yml.

Option	Descripción
-v, --verbose	Incluye metadatos y capacidades del conector.
--json	Emite salida JSON.

rayfin connector inspect

Inspecciona un conector configurado o una fuente Fabric directamente dirigida sin realizar cambios.

Option	Descripción
--name <name>	Nombre del conector configurado.
-w, --workspace <name>	Nombre del espacio de trabajo para inspección directa.
--workspace-id <id>	ID del espacio de trabajo para inspección directa.
--item <name>	Nombre del artículo para inspección directa.
--item-id <id>	Identificación del artículo para inspección directa.
--type <type>	Tipo de conector para inspección directa.
--url <url>	URL del portal de modelos semánticos; deriva los IDs de espacio de trabajo y de elementos.
--entity <name>	Entidad o tabla para muestrear; omitir con --query para listar entidades.
--query <path>	.sql o .dax archivo para ejecutarse en modo de solo lectura.
--rows <n>	Límite de fila; por defecto es 10 para muestras y está limitado a 100.
-v, --verbose	Habilite la salida detallada.
--output <interactive\|plain\|json>	Selecciona el formato de salida.
--json	Emite salida JSON.

Úsase --name para un conector configurado, un selector completo de fuente directa o --url para un modelo semántico.

rayfin connector invoke [connector-name] [operation]

Invoca una operación en un conector configurado.

Argumento u opción	Descripción
[connector-name]	Nombre del conector configurado.
[operation]	Operación de conectores, como executeQuery.
--name <name>	Alternativa llamada a [connector-name].
--operation <operation>	Alternativa llamada a [operation].
--input <json>	Entrada de operación JSON.
--file <path>	Archivo JSON que contiene la entrada de operaciones.
--transport <auto\|deployed>	Ruta de invocación; por defecto es auto.
-v, --verbose	Habilite la salida detallada.
--output <interactive\|plain\|json>	Selecciona el formato de salida.
--output-file <path>	Escribe el resultado completo en un archivo.
--max-inline-bytes <bytes>	Umbral de tamaño de resultado para escribir un archivo; por defecto es 1 MiB.
--json	Emite salida JSON.

rayfin connector remove <name>

Elimina una declaración de conector y sus archivos de conector generados.

Argumento u opción	Descripción
<name>	Required. Nombre del conector para eliminar.
-v, --verbose	Habilite la salida detallada.
-y, --yes	Acepta automáticamente la confirmación de retirada.
--json	Emite salida JSON.

Comandos de funciones

rayfin functions init [directory]

Estructura y configura un paquete de Funciones.

Argumento u opción	Descripción
[directory]	Project root; por defecto se recuesta en el directorio actual.
--force	Sobrscribe un andamiaje de Funciones existente.
--path <relative-path>	Ubicación del paquete de funciones en relación con la raíz del proyecto.

La ubicación del paquete por defecto es una ubicación de espacio de trabajo detectada o rayfin/functions.

Comandos de desarrollo

rayfin dev [project-path]

Inicia una sesión de desarrollo local contra un backend de Rayfin.

Argumento u opción	Descripción
[project-path]	Project root; por defecto se recuesta en el directorio actual.
--skip-db-apply	Salta la aplicación de configuración automática de la base de datos.
--env-file <path>	.env Archivo usado para rayfin.yml interpolación.
--provider <fabric>	Proveedor backend; por defecto a fabric.
-w, --workspace <name>	Nombre de espacio de trabajo Fabric para un backend de primera ejecución.
--workspace-id <id>	ID de espacio de trabajo Fabric para un backend de primera ejecución.
--capacity-id <id>	ID de capacidad Fabric para un espacio de trabajo sin capacidad utilizable.
-t, --tenant <id>	Identificador de inquilino de Microsoft Entra.
--encryption-fallback-enabled	Permitir el almacenamiento de tokens en texto plano cuando no haya un llavero del sistema operativo disponible.
--no-emit-env	No regeneres el archivo del framework .env.local .
-v, --verbose	Habilita el registro detallado.

rayfin dev functions apply

Inicia el host local de Funciones contra el despliegue activo.

Option	Descripción
--port <port>	Funciones Locales en el puerto host; por defecto es 7071.
--inspect-port <port>	Node.js puerto inspector; por defecto se ajusta a 9229.
--no-debug	Desactiva el inspector de Node.js.
--no-emit-env	No regeneres el archivo del framework .env.local .
--verbose	Mostrar la salida de diagnóstico.
--json	Emite salida JSON.
-y, --yes	Corre sin indicaciones interactivas.

Gestionar archivos de agentes

El rayfin init ai-files comando gestiona los archivos contextuales del agente Rayfin en tu proyecto: AGENTS.md, .mcp.json, y .agents/skills/rayfin/SKILL.md. La CLI instala estos archivos automáticamente cuando andamias un proyecto. Ejecuta los comandos a continuación para instalarlos o actualizarlos en un proyecto existente, o comprueba su estado.

rayfin init ai-files install

Instala o actualiza los archivos agentes de Rayfin. El comando es idempotente y preserva la configuración existente del usuario.

Option	Descripción
--enable <id>	Instala o mantén un elemento específico con su ID con espacio de nombre, como skill:rayfin. Repetible.
--disable <id>	Deja de gestionar un elemento específico sin borrar su archivo. Repetible.
--remove-files	Elimina el archivo en disco al desactivar un elemento. Se requiere --disable.
--force [ids...]	Sobrscribe elementos modificados, restaura los objetos faltantes o reconstruye los malformados .mcp.json. Acepta IDs opcionales con espacio de nombres para asignar el alcance de la operación. Nunca sobrescribe AGENTS.md.
-n, --dry-run	Informa de los cambios sin escribir archivos.
--json	Emite salida estructurada como JSON; implica modo no interactivo.
-y, --yes, --non-interactive	Salta el prompt interactivo y acepta los valores predeterminados.

Por ejemplo, instalar los valores predeterminados sin que se lo pidan:

npx rayfin init ai-files install --yes

rayfin init ai-files status

Imprime el estado de cada archivo de agente gestionado. Úsalo --json para salida estructurada.

Los estados posibles incluyen up-to-date, update-available, user-modified, missing, not-installed, disabled, orphaned, y unreadable. Corre rayfin init ai-files install para actualizar archivos o rayfin init ai-files install --force <id> sobrescribir un elemento gestionado específico.

Implementación en Fabric

rayfin up

Usa rayfin up para desplegar la aplicación en Fabric como un elemento de Rayfin.

Argument	Descripción
-t, --tenant <id>	Usa un ID de inquilino específico.
-w, --workspace <name>	Despliega en un espacio de trabajo de Fabric por nombre; por defecto es My Workspace.
--workspace-id <id>	Despliega en un ID específico de espacio de trabajo de Fabric.
--workspace-uri <uri>	Despliega en un URI específico de espacio de trabajo de Fabric.
--item-name <name>	Nombre de visualización del elemento Fabric; por defecto se asigna al ID del proyecto.
--capacity-id <id>	ID de capacidad Fabric cuando el espacio de trabajo objetivo necesita capacidad.
--force	Permitir cambios destructivos en el esquema de datos.
-n, --dry-run	Valida las entradas y resuelve el espacio de trabajo sin desplegar.
--env-file <path>	.env file para propiedades de despliegue; por defecto en rayfin/.env.
-v, --verbose	Habilite la salida detallada.
--json	Devuelve la salida de despliegue en formato JSON.
-y, --yes	Acepta automáticamente las confirmaciones.
--encryption-fallback-enabled	Permitir el almacenamiento de tokens en texto plano cuando no haya un llavero del sistema operativo disponible.
--exclude-services <names>	Servicios separados por comas para saltar durante la compilación y despliegue: staticHosting o functions.
--provider <fabric>	Proveedor de despliegue; por defecto es fabric.

Ejemplos

Despliega en el espacio de trabajo de Fabric seleccionado actualmente:

npx rayfin up

Previsualizar las acciones de despliegue sin aplicarlas:

npx rayfin up --dry-run --verbose

Despliega en un espacio de trabajo específico de forma no interactiva:

npx rayfin up --workspace-id <workspace-id> --yes

Desplegar sin construir ni desplegar Funciones:

npx rayfin up --exclude-services functions

--capacity-id No se puede combinar con --workspace, --workspace-ido --workspace-uri.

Subcommand	Descripción
npx rayfin up db apply	Genera y aplica la configuración DAB al endpoint remoto de la carga de trabajo de ítems de Rayfin.
npx rayfin up functions deploy	Compila, empaqueta y despliega Funciones en el elemento activo remoto.
npx rayfin up staticapp deploy	Compila, empaqueta y despliega contenido estático en el elemento remoto de Rayfin.
npx rayfin up connector apply	Aplicar la configuración de la base de datos para los conectores GraphQL declarados.
npx rayfin up status	Muestra el estado actual del despliegue.
npx rayfin up list	Enumera todos los despliegues de Fabric grabados para el proyecto.
npx rayfin up switch [workspace]	Cambia el despliegue activo Fabric y reescribe rayfin/.env.

rayfin up db apply

Genera y aplica la configuración DAB al extremo remoto de la carga de trabajo de ítems de Rayfin.

Argument	Descripción
--verbose	Mostrar resultado detallado.
--force	Forzar la regeneración y aplicar configuración.
--json	Devuelve la salida en formato JSON.

Ejemplos

Aplicar cambios en la configuración de la base de datos al elemento remoto de Rayfin:

npx rayfin up db apply

Regeneración forzada y captura de salida legible por máquina:

npx rayfin up db apply --force --json

rayfin up functions deploy

Compila, empaqueta y despliega Funciones en el elemento remoto activo.

Option	Descripción
--verbose	Mostrar resultado detallado.
--skip-build	Despliega la salida de las funciones existentes sin construir.
--json	Emite salida JSON.

rayfin up connector apply

Aplica la configuración de la base de datos para los conectores GraphQL declarados.

Option	Descripción
--name <name>	Aplica solo el conector nombrado.
--verbose	Habilite la salida detallada.
--json	Emite salida JSON.

rayfin up staticapp deploy

Construye, empaqueta y despliega contenido estático en el objeto remoto de Rayfin.

Argument	Descripción
--verbose	Mostrar resultado detallado.
--skip-build	Desplega sin ejecutar el paso de compilación.
--json	Devuelve la salida en formato JSON.

Ejemplos

Crear y desplegar contenido estático:

npx rayfin up staticapp deploy

Despliega una carpeta preconstruida dist sin volver a ejecutar la compilación:

npx rayfin up staticapp deploy --skip-build

rayfin up status

Muestra el estado del despliegue en la nube.

Argument	Descripción
--json	Estado de retorno en formato JSON.
--verbose	Mostrar resultado detallado.

Ejemplos

Consulta el estado actual del despliegue:

npx rayfin up status

Estado de retorno como JSON para uso en scripts:

npx rayfin up status --json

rayfin up list

Lista todos los despliegues de Fabric registrados para este proyecto.

Argument	Descripción
--json	Devuelva la lista de despliegue en formato JSON.

Ejemplos

Lista todos los despliegues Fabric registrados para el proyecto:

npx rayfin up list

rayfin up switch [workspace]

Cambia el despliegue activo Fabric y reescribe rayfin/.env en consecuencia.

Argument	Descripción
-l, --list	Lista los despliegues disponibles sin cambiar.
--no-emit-env	Salta escribir archivos de entorno emitidos.

Ejemplos

Lista de despliegues disponibles a los que cambiar:

npx rayfin up switch --list

Cambia el despliegue activo a un espacio de trabajo específico:

npx rayfin up switch my-workspace

Generar archivos de entorno

rayfin env

Usar rayfin env para emitir valores específicos .env.local del marco de rayfin/.env.

Argument	Descripción
--framework <vite|nextjs|plain>	Elige el formato del framework objetivo.
--output <dir>	Escribe archivos generados en un directorio específico.
--show	Imprime los valores emitidos sin escribir archivos.

Ejemplos

Genera un Vite-compatible .env.local:

npx rayfin env --framework vite

Vista previa emitió valores de entorno sin escribir archivos:

npx rayfin env --framework nextjs --show

Inicio y cierre de sesión

rayfin login

Úsalo rayfin login para iniciar sesión en la plataforma Rayfin.

Argument	Descripción
--tenant <id>	Usa un ID de inquilino específico.
--service-principal	Intenta iniciar sesión con el principal del servicio. Esta opción aparece en la sección de ayuda pero actualmente no está soportada.
-u, --client-id <id>	Proporciona el ID del cliente para iniciar sesión con el principal de servicio. Esta opción aparece en la sección de ayuda pero actualmente no está soportada.
-p, --client-secret <secret>	Proporciona al cliente el secreto de inicio de sesión del principal de servicio. Esta opción aparece en la sección de ayuda pero actualmente no está soportada.
--select	Selecciona entre cuentas o contextos disponibles con inicio de sesión.
--encryption-fallback-enabled	Activa el comportamiento de respaldo del cifrado.

Ejemplos

Inicia sesión de forma interactiva:

npx rayfin login

Inicia sesión con un inquilino específico:

npx rayfin login --tenant 00000000-0000-0000-0000-000000000000

Cambiar entre cuentas iniciadas en sesión:

npx rayfin login --select

Subcommand	Descripción
npx rayfin login status	Mostrar el estado actual de autenticación.

rayfin login status

Muestra el estado actual de autenticación.

Argument	Descripción
Ninguno	Este subcomando no muestra ninguna opción en la salida de ayuda de la CLI.

Ejemplo

Comprueba si has iniciado sesión:

npx rayfin login status

rayfin logout

Cierra sesión y borra las credenciales en caché.

Argument	Descripción
Ninguno	Este comando no muestra ninguna opción en la salida de ayuda de la CLI.

Ejemplo

Cerrar sesión y borrar las credenciales en caché:

npx rayfin logout