Referência da CLI Rayfin

Encontre os comandos da CLI do Rayfin para criar projetos, gerir alterações de esquema, implementar para o Fabric e configurar as definições do ambiente. Cada secção lista a sintaxe dos comandos, opções e usos comuns.

Instalação

Uso npm i @microsoft/rayfin-cli para instalar o CLI.

Como Começar

Siga os passos no seu terminal para criar uma aplicação 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

Sugestão

Para projetos existentes ou vazios, use npx rayfin init em vez de npm create adicionar o Rayfin a um projeto que já tenha código-fonte ou um diretório vazio. O comando init guia-o na ativação dos serviços, na escolha de um dialeto da base de dados e na configuração do alojamento estático sem estruturar um novo modelo.

Para o guia completo, consulte Criar e implementar a sua primeira aplicação Fabric com a CLI e Deploye uma aplicação Fabric para Fabric.

Andaime um projeto com npm create

npm create (pseudónimo de npm init) inicia um novo projeto invocando um pacote Create Initializer. Para andar uma aplicação Fabric, use-a com o inicializador @microsoft/rayfin:

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

Referência de comando

Os comandos e flags neste artigo foram verificados a partir da saída de ajuda da CLI instalada localmente.

Comandos de nível superior

Use esta tabela para encontrar rapidamente o comando certo.

Comando	Usa-o para
npx rayfin init [directory]	Crie ou configure um projeto Rayfin.
npx rayfin connector	Encontrar, configurar, inspecionar e invocar conectores de dados Fabric.
npx rayfin functions init	Estrutura um pacote de Funções.
npx rayfin dev	Executa a aplicação e as Funções localmente.
npx rayfin init ai-files	Instale ou verifique os ficheiros de contexto do agente Rayfin.
npx rayfin up	Implementa a aplicação no Fabric e gere implementações remotas.
npx rayfin env	Gerar ficheiros de ambiente específicos do framework a partir de rayfin/.env.
npx rayfin login	Inicie sessão na plataforma Rayfin.
npx rayfin logout	Sai e limpa as credenciais em cache.

Criar ou configurar um projeto

rayfin init [directory]

Use rayfin init para adicionar Rayfin a um projeto novo ou existente.

Argument	Descrição
--project-name <name>	Define o nome do projeto.
-t, --template <uri>	Especifique o URI do modelo a usar.
--template-name <name>	Selecione um modelo pelo nome.
-l, --list-templates	Lista os modelos disponíveis.
--dialect <dialect>	Define o dialeto da base de dados.
--services <list>	Escolha quais os serviços a disponibilizar.
--auth-methods <list>	Escolha métodos de autenticação.
--static-hosting	Ativa a configuração de alojamento estático.
--overwrite	Sobrescrever ficheiros gerados existentes.
--workspace-id <id>	Use um ID específico de espaço de trabalho Fabric.
--workspace-uri <uri>	Usa um URI específico do Fabric workspace.
--base-api-url <url>	Sobrescrever a URL base da API.
--item-id <id>	Foca num ID específico do item Fabric.

Examples

Liste os modelos disponíveis antes de a estrutura:

npx rayfin init --list-templates

Inicialize o Rayfin no diretório atual usando um modelo nomeado e um dialeto específico:

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

Criar um novo projeto de forma não interativa com serviços e autenticação configurados:

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

Comandos de ligação

O connector grupo de comando gere fontes externas de dados Fabric.

rayfin connector types

Lista tipos de conectores que podes adicionar a um projeto.

Option	Descrição
--json	Emita a lista de tipos de conector como JSON.
-v, --verbose	Inclua detalhes das capacidades.

rayfin connector search [query]

Searches Fabric fornece que a identidade iniciada pode ser adicionada como conectores.

Argumento ou opção	Descrição
[query]	Filtro opcional, insensível a maiúsculas minúsculas, com nome de fonte.
--query <text>	Filtro de nome de fonte nomeado que tem precedência sobre [query].
--type <type>	Tipos de conectores separados por vírgulas; exigidos com --workspace-id ou --all-workspaces.
--workspace-id <id>	Procura num espaço de trabalho Fabric.
--all-workspaces	Pesquise em todos os espaços de trabalho a que a identidade possa aceder.
-y, --yes	Aceita automaticamente a transferência interativa de adição.
--limit <n>	Número máximo de resultados exibidos.
--output <interactive\|plain\|json>	Selecione o formato de saída.
--json	Imprime os resultados em JSON e evita o seletor interativo.
-v, --verbose	Ativa a saída verbosa.

Quando nenhuma das opções de espaço de trabalho é fornecida, o comando pesquisa os espaços de trabalho registados para a implementação atual do projeto.

rayfin connector add --type <type>

Adiciona uma declaração de conector e estrutura os seus ficheiros de projeto.

Option	Descrição
--type <type>	Required. Tipo de conector; usar rayfin connector types para listar tipos.
--name <name>	Nome do conector; derivado do item quando omitido.
--workspace-id <id>	ID do espaço de trabalho Fabric.
--item-id <id>	ID do artigo Fabric.
--operations <ops>	Subconjunto separado por vírgulas das operações permitidas.
-v, --verbose	Ativa a saída verbosa.
-y, --yes	Aceita automaticamente confirmações.
--json	Emitir saída JSON.

rayfin connector list

Lista os conectores declarados em rayfin.yml.

Option	Descrição
-v, --verbose	Incluir metadados e capacidades do conector.
--json	Emitir saída JSON.

rayfin connector inspect

Inspeciona um conector configurado ou uma fonte Fabric diretamente endereçada sem fazer alterações.

Option	Descrição
--name <name>	Nome do conector configurado.
-w, --workspace <name>	Nome do espaço de trabalho para inspeção direta.
--workspace-id <id>	ID do espaço de trabalho para inspeção direta.
--item <name>	Nome do item para inspeção direta.
--item-id <id>	ID do item para inspeção direta.
--type <type>	Tipo de conector para inspeção direta.
--url <url>	URL do portal de modelos semânticos; deriva os IDs do espaço de trabalho e dos itens.
--entity <name>	Entidade ou tabela para amostrar; omitir com --query para listar as entidades.
--query <path>	.sql ou .dax para executar em modo apenas leitura.
--rows <n>	Limite de linhas; por defeito é 10 para amostras e é limitado a 100.
-v, --verbose	Ativa a saída verbosa.
--output <interactive\|plain\|json>	Selecione o formato de saída.
--json	Emitir saída JSON.

Use --name para um conector configurado, um seletor completo de fonte direta ou --url para um modelo semântico.

rayfin connector invoke [connector-name] [operation]

Invoca uma operação num conector configurado.

Argumento ou opção	Descrição
[connector-name]	Nome do conector configurado.
[operation]	Operação de conectores, como executeQuery.
--name <name>	Alternativa nomeada a [connector-name].
--operation <operation>	Alternativa nomeada a [operation].
--input <json>	Input de operação JSON.
--file <path>	ficheiro JSON contendo a entrada da operação.
--transport <auto\|deployed>	Caminho de invocação; por defeito para auto.
-v, --verbose	Ativa a saída verbosa.
--output <interactive\|plain\|json>	Selecione o formato de saída.
--output-file <path>	Escreve o resultado completo num ficheiro.
--max-inline-bytes <bytes>	Limiar de tamanho do resultado para escrever um ficheiro; por defeito é 1 MiB.
--json	Emitir saída JSON.

rayfin connector remove <name>

Remove uma declaração de conector e os seus ficheiros de conector gerados.

Argumento ou opção	Descrição
<name>	Required. Nome do conector para remover.
-v, --verbose	Ativa a saída verbosa.
-y, --yes	Aceita automaticamente a confirmação da remoção.
--json	Emitir saída JSON.

Comandos de funções

rayfin functions init [directory]

Estrutura e configura um pacote de Funções.

Argumento ou opção	Descrição
[directory]	Project root; por defeito para o diretório atual.
--force	Sobrescreva uma estrutura de Funções existente.
--path <relative-path>	A localização do pacote de funções relativa à raiz do projeto.

A localização do pacote corresponde por defeito a uma localização de espaço de trabalho detetada ou rayfin/functions.

Comandos de desenvolvimento

rayfin dev [project-path]

Inicia uma sessão de desenvolvimento local contra um backend Rayfin.

Argumento ou opção	Descrição
[project-path]	Project root; por defeito para o diretório atual.
--skip-db-apply	Evite a configuração automática da base de dados.
--env-file <path>	.env ficheiro usado para rayfin.yml interpolação.
--provider <fabric>	Fornecedor backend; por defeito para fabric.
-w, --workspace <name>	Nome de espaço de trabalho Fabric para um backend de primeira execução.
--workspace-id <id>	ID de espaço de trabalho Fabric para um backend de primeira execução.
--capacity-id <id>	ID de capacidade Fabric para um espaço de trabalho sem capacidade utilizável.
-t, --tenant <id>	ID do inquilino do Microsoft Entra.
--encryption-fallback-enabled	Permitir o armazenamento de tokens em texto simples quando não houver um chaveiro do sistema operativo disponível.
--no-emit-env	Não regeneres o ficheiro do framework .env.local .
-v, --verbose	Ativar o registo de verboses.

rayfin dev functions apply

Inicia o host local de Funções contra a implementação ativa.

Option	Descrição
--port <port>	Funções Locais porta host; por defeito para 7071.
--inspect-port <port>	Node.js porta inspetor; por defeito para 9229.
--no-debug	Desativa o inspetor de Node.js.
--no-emit-env	Não regeneres o ficheiro do framework .env.local .
--verbose	Mostrar a saída de diagnóstico.
--json	Emitir saída JSON.
-y, --yes	Corra sem comandos interativos.

Gerir ficheiros de agente

O rayfin init ai-files comando gere os ficheiros de contexto do agente Rayfin no seu projeto: AGENTS.md, .mcp.json, e .agents/skills/rayfin/SKILL.md. A CLI instala estes ficheiros automaticamente quando anda um projeto. Execute os comandos abaixo para os instalar ou atualizar num projeto existente, ou verificar o seu estado.

rayfin init ai-files install

Instala ou atualiza os ficheiros do agente Rayfin. O comando é idempotente e preserva a configuração existente do utilizador.

Option	Descrição
--enable <id>	Instale ou mantenha um item específico pelo seu ID com espaço de nomes, como skill:rayfin. Repetível.
--disable <id>	Pare de gerir um item específico sem apagar o seu ficheiro. Repetível.
--remove-files	Remova o ficheiro no disco ao desativar um item. Requer --disable.
--force [ids...]	Sobrescrever itens modificados, restaurar itens em falta ou reconstruir os malformados .mcp.json. Aceita IDs opcionais com namespaces para definir o âmbito da operação. Nunca sobrescreve AGENTS.md.
-n, --dry-run	Reporte as alterações sem escrever ficheiros.
--json	Emitir saída estruturada como JSON; implica modo não interativo.
-y, --yes, --non-interactive	Ignora o prompt interativo e aceita os predefinidos.

Por exemplo, instalar os valores predefinidos sem que seja solicitado:

npx rayfin init ai-files install --yes

rayfin init ai-files status

Imprime o estado de cada ficheiro de agente gerido. Use --json para saída estruturada.

Os estados possíveis incluem up-to-date, update-available, user-modified, missing, not-installed, disabled, orphaned, e unreadable. Execute rayfin init ai-files install para atualizar ficheiros ou rayfin init ai-files install --force <id> para sobrescrever um item gerido específico.

Implementar no Fabric

rayfin up

Use rayfin up para implementar a aplicação para Fabric como um item Rayfin.

Argument	Descrição
-t, --tenant <id>	Use um ID de inquilino específico.
-w, --workspace <name>	Implementar num espaço de trabalho Fabric pelo nome; por defeito para My Workspace.
--workspace-id <id>	Implemente para um ID específico de espaço de trabalho Fabric.
--workspace-uri <uri>	Implemente para um URI específico do espaço de trabalho Fabric.
--item-name <name>	Nome de exibição do item Fabric; por defeito corresponde ao ID do projeto.
--capacity-id <id>	ID de capacidade Fabric quando o espaço de trabalho alvo precisa de capacidade.
--force	Permitir alterações destrutivas no esquema de dados.
-n, --dry-run	Valide entradas e resolva o espaço de trabalho sem fazer deploy.
--env-file <path>	.env file para propriedades de implementação; por defeito para rayfin/.env.
-v, --verbose	Ativa a saída verbosa.
--json	Devolva a saída de implementação em formato JSON.
-y, --yes	Aceita automaticamente confirmações.
--encryption-fallback-enabled	Permitir o armazenamento de tokens em texto simples quando não houver um chaveiro do sistema operativo disponível.
--exclude-services <names>	Serviços separados por vírgulas para saltar durante a construção e implementação: staticHosting ou functions.
--provider <fabric>	Fornecedor de implantação; por defeito para fabric.

Examples

Implementar no espaço de trabalho Fabric atualmente selecionado:

npx rayfin up

Pré-visualize as ações de implementação sem as aplicar:

npx rayfin up --dry-run --verbose

Implemente para um espaço de trabalho específico de forma não interativa:

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

Implementar sem construir ou implementar Funções:

npx rayfin up --exclude-services functions

--capacity-id não pode ser combinado com --workspace, --workspace-id, ou --workspace-uri.

Subcomando	Descrição
npx rayfin up db apply	Gerar e aplicar configuração DAB ao endpoint remoto da carga de trabalho do item Rayfin.
npx rayfin up functions deploy	Construa, empacote e implemente Funções no item remoto ativo.
npx rayfin up staticapp deploy	Construa, empacota e implemente conteúdo estático para o item remoto do Rayfin.
npx rayfin up connector apply	Aplique a configuração da base de dados para conectores GraphQL declarados.
npx rayfin up status	Mostrar o estado atual da implantação.
npx rayfin up list	Liste todas as implementações de Fabric registadas para o projeto.
npx rayfin up switch [workspace]	Muda a ativa Fabric deployment e reescreve rayfin/.env.

rayfin up db apply

Gera e aplica configuração DAB ao endpoint remoto da carga de trabalho do item Rayfin.

Argument	Descrição
--verbose	Mostrar saída detalhada.
--force	Forçar a regeneração e aplicar a configuração.
--json	Devolver a saída em formato JSON.

Examples

Aplicar alterações na configuração da base de dados ao item remoto do Rayfin:

npx rayfin up db apply

Regeneração forçada e captura de saída legível por máquina:

npx rayfin up db apply --force --json

rayfin up functions deploy

Constrói, empacota e implementa Funções no item remoto ativo.

Option	Descrição
--verbose	Mostrar saída detalhada.
--skip-build	Implemente a saída existente das Funções sem construir.
--json	Emitir saída JSON.

rayfin up connector apply

Aplica a configuração da base de dados para conectores GraphQL declarados.

Option	Descrição
--name <name>	Aplique apenas o conector nomeado.
--verbose	Ativa a saída verbosa.
--json	Emitir saída JSON.

rayfin up staticapp deploy

Constrói, empacota e implementa conteúdo estático no item remoto do Rayfin.

Argument	Descrição
--verbose	Mostrar saída detalhada.
--skip-build	Implemente sem executar a etapa de construção.
--json	Devolver a saída em formato JSON.

Examples

Construir e implementar conteúdo estático:

npx rayfin up staticapp deploy

Implemente uma pasta pré-construída dist sem repetir a compilação:

npx rayfin up staticapp deploy --skip-build

rayfin up status

Mostra o estado da implementação na cloud.

Argument	Descrição
--json	Estado do retorno em formato JSON.
--verbose	Mostrar saída detalhada.

Examples

Verifique o estado atual da implementação:

npx rayfin up status

Estado de retorno como JSON para uso em scripts:

npx rayfin up status --json

rayfin up list

Lista todas as implementações Fabric registadas para este projeto.

Argument	Descrição
--json	Devolva a lista de implementação em formato JSON.

Examples

Liste todas as implementações Fabric registadas para o projeto:

npx rayfin up list

rayfin up switch [workspace]

Muda o ativo Fabric implementação e reescreve rayfin/.env em conformidade.

Argument	Descrição
-l, --list	Liste as implementações disponíveis sem necessidade de mudar.
--no-emit-env	Ignora a escrita de ficheiros de ambiente emitidos.

Examples

Lista de implementações disponíveis para mudar:

npx rayfin up switch --list

Mude a implementação ativa para um espaço de trabalho específico:

npx rayfin up switch my-workspace

Gerar ficheiros de ambiente

rayfin env

Use rayfin env para emitir valores específicos .env.local do framework a partir de rayfin/.env.

Argument	Descrição
--framework <vite|nextjs|plain>	Escolha o formato do framework de destino.
--output <dir>	Escreve ficheiros gerados num diretório específico.
--show	Imprimir valores emitidos sem escrever ficheiros.

Examples

Gerar um Vite-compatível .env.local:

npx rayfin env --framework vite

Pré-visualização emitiu valores de ambiente sem escrever ficheiros:

npx rayfin env --framework nextjs --show

Entrar e sair da sessão

rayfin login

Use rayfin login para iniciar sessão na plataforma Rayfin.

Argument	Descrição
--tenant <id>	Use um ID de inquilino específico.
--service-principal	Tente iniciar sessão com o principal do serviço. Esta opção está listada na ajuda, mas atualmente não é suportada.
-u, --client-id <id>	Forneça o ID do cliente para o início de sessão do principal de serviço. Esta opção está listada na ajuda, mas atualmente não é suportada.
-p, --client-secret <secret>	Forneça ao cliente o principal secreto para o serviço. Esta opção está listada na ajuda, mas atualmente não é suportada.
--select	Selecione entre contas ou contextos ligados disponíveis.
--encryption-fallback-enabled	Ativar o comportamento de encriptação.

Examples

Iniciar sessão interativamente:

npx rayfin login

Inicie sessão num inquilino específico:

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

Alterne entre contas iniciadas:

npx rayfin login --select

Subcomando	Descrição
npx rayfin login status	Mostrar o estado atual da autenticação.

rayfin login status

Mostra o estado atual de autenticação.

Argument	Descrição
None	Este subcomando não lista quaisquer opções na saída de ajuda da CLI.

Example

Verifica se estás com sessão iniciada:

npx rayfin login status

rayfin logout

Desliga-se e limpa as credenciais em cache.

Argument	Descrição
None	Este comando não lista nenhuma opção na saída de ajuda da CLI.

Example

Sair e limpar as credenciais em cache:

npx rayfin logout