Ir para o console

Referência da Firebase CLI

A Firebase CLI (GitHub) oferece uma série de ferramentas de gerenciamento, visualização e implantação para projetos do Firebase.

Antes de usar a Firebase CLI, configure um projeto do Firebase.

Instalar a Firebase CLI

A Firebase CLI (interface de linha de comando) requer o Node.js e o gerenciador de pacotes de nós (npm) (ambos em inglês).

  1. Instale o Node.js usando uma das seguintes opções. Por meio dessa instalação, o NPM é instalado automaticamente.

    • Para Mac/Linux, use o gerenciador de versões de nós (nvm).
    • Para Windows, use o nvm-windows.
  2. Instale a Firebase CLI por meio do NPM executando o código a seguir:

    npm install -g firebase-tools

    Essa ação instala o comando firebase disponível globalmente. Se você quiser atualizar a Firebase CLI, execute o mesmo comando npm install.

  3. Faça login no Firebase por meio da sua Conta do Google. Para isso, execute o código a seguir:

    firebase login

    Esse comando conecta sua máquina local ao Firebase e concede acesso aos seus projetos.

  4. Para testar se a autenticação funcionou e listar todos os seus projetos do Firebase, execute o seguinte comando:

    firebase list

    A lista exibida precisa conter os mesmos projetos que aparecem no Console do Firebase.

Atualizar para a versão mais recente da CLI

Execute o comando de instalação da Firebase CLI novamente para verificar se você está usando a versão mais recente:

npm install -g firebase-tools

Inicializar um projeto do Firebase

Para realizar várias tarefas comuns com a CLI, como implantação em um projeto do Firebase, é necessário um diretório de projeto. Para estabelecer um, use o comando firebase init. Normalmente, um diretório de projeto é o mesmo da sua raiz de controle e de origem que, depois de executar o comando firebase init, incluirá um arquivo de configuração firebase.json.

Para inicializar um novo projeto do Firebase, execute o seguinte comando no diretório do seu aplicativo:

firebase init

O comando firebase init guia você pelas etapas de configuração do diretório do seu projeto e de alguns produtos do Firebase. Durante a inicialização do projeto, a Firebase CLI requer que você faça o seguinte:

  • Selecione os produtos desejados do Firebase e defina configurações para arquivos específicos deles.

    Se você quiser configurar um produto específico do Firebase no seu projeto, consulte a documentação correspondente para mais informações, por exemplo, o guia de início rápido do Hosting. Lembre-se de que é possível executar o comando firebase init posteriormente para configurar outros produtos do Firebase.

  • Selecione um projeto padrão do Firebase.

    Essa etapa associa o diretório do projeto atual a um projeto do Firebase para que os comandos específicos dele (como firebase deploy) sejam executados no projeto apropriado do Firebase.

    Também é possível associar vários projetos do Firebase (como um de teste e um de produção) ao mesmo diretório de projeto.

No final da inicialização, o Firebase cria e adiciona automaticamente dois arquivos à raiz do diretório local de aplicativos:

Arquivo firebase.json

O comando firebase init cria um arquivo de configuração firebase.json na raiz do diretório do projeto.

O arquivo firebase.json é necessário para implantar recursos com a Firebase CLI, porque ele especifica quais configurações e arquivos do diretório do projeto serão implantados. Como algumas configurações podem ser definidas no diretório de projeto ou no Console do Firebase, resolva quaisquer conflitos de implantação em potencial.

É possível configurar a maioria das opções do Firebase Hosting diretamente no arquivo firebase.json. No entanto, no caso de outros serviços do Firebase que podem ser implantados com a Firebase CLI, o comando firebase init cria arquivos específicos em que é possível definir as configurações correspondentes, como um arquivo index.js para o Cloud Functions. Também é possível configurar hooks de pré ou pós-implantação no arquivo firebase.json.

Veja abaixo um arquivo firebase.json de exemplo com as configurações padrão que serão aplicadas se você selecionar o Firebase Hosting, o Cloud Firestore e o Cloud Functions para Firebase durante a inicialização.

{
  "hosting": {
    "public": "public",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ]
  },
  "firestore": {
    "rules": "firestore.rules",
    "indexes": "firestore.indexes.json"
  },
  "functions": {
    "predeploy": [
      "npm --prefix \"$RESOURCE_DIR\" run lint"
    ]
  }
}

Disponibilizar e testar seu projeto do Firebase localmente

Veja e teste seu projeto do Firebase em URLs hospedados localmente antes de implantá-lo na produção. Se você quiser testar somente determinados recursos, use uma lista separada por vírgulas em uma sinalização no comando firebase serve.

Execute o seguinte comando a partir da raiz do diretório local do seu projeto se quiser:

  • visualizar o conteúdo estático do seu app hospedado no Firebase;
  • usar o Cloud Functions de modo a gerar conteúdo dinâmico para o Firebase Hosting e usar suas funções HTTP de produção (implantadas) para emular o Hosting em um URL local.
firebase serve --only hosting

Execute qualquer um dos seguintes comandos no diretório do seu projeto para fazer a emulação dele por meio das funções HTTP locais:

  • Para emular funções HTTP e hospedagem para testes em URLs locais, use um dos comandos a seguir:

    firebase serve
    firebase serve --only functions,hosting // uses a flag
  • Para emular somente funções HTTP, use o comando a seguir:

    firebase serve --only functions

Por padrão, o firebase serve apenas responde a solicitações de localhost. Isso significa que você poderá acessar seu conteúdo hospedado a partir do navegador da Web do seu computador, mas não de outros dispositivos na sua rede. Se você quiser testar usando outros dispositivos locais, use o sinalizador --host:

firebase serve --host 0.0.0.0  // accepts requests to any host

Implantar em um projeto do Firebase

Com a Firebase CLI, você gerencia a implantação de código e recursos no projeto do Firebase, incluindo:

  • novas versões dos sites do Firebase Hosting;
  • Cloud Functions para Firebase novo, existente ou atualizado;
  • regras do Firebase Realtime Database;
  • regras do Cloud Storage para Firebase;
  • regras do Cloud Firestore;
  • índices do Cloud Firestore.

Para implantar em um projeto do Firebase, execute o seguinte comando no diretório do seu projeto:

firebase deploy

Por padrão, o comando firebase deploy cria uma versão para todos os recursos implantáveis no diretório do projeto. Para implantar serviços ou recursos específicos do Firebase, use a implantação parcial.

Para implantar recursos a partir de um diretório do projeto, ele precisa ter o arquivo firebase.json, que foi criado automaticamente pelo comando firebase init.

Como alternativa, adicione um comentário a cada uma das suas implantações. Esse comentário será exibido com as outras informações de implantação na página do Firebase Hosting do seu projeto. Exemplo:

firebase deploy -m "Deploying the best new feature ever."

Conflitos de implantação nas regras de segurança

Para o Firebase Realtime Database, o Cloud Storage para Firebase e o Cloud Firestore, é possível definir regras de segurança no diretório de projeto local ou no Console do Firebase.

Outra opção para evitar conflitos de implantação é usar a implantação parcial e definir regras apenas no Console do Firebase.

Cotas de implantação

É possível (embora improvável) que você exceda uma cota que limita a taxa ou o volume das suas operações de implantação do Firebase. Por exemplo, ao implantar muitas funções, você pode receber uma mensagem de erro HTTP 429 Quota. Resolva esses problemas usando a implantação parcial ou por meio da solicitação de aumento de cota para serviços específicos do Firebase. Por exemplo, a cota chamada Solicitações de gravação a cada 100 segundos por usuário pode resolver o erro 429 do Cloud Functions citado acima.

Reverter uma implantação

Se quiser reverter uma implantação na página do Firebase Hosting do seu projeto, selecione a ação Reverter para a versão escolhida.

No momento, não é possível reverter versões de regras de segurança para o Firebase Realtime Database, o Cloud Storage para Firebase ou o Cloud Firestore.

Implantar serviços específicos do Firebase

Se você quiser implantar apenas serviços ou recursos específicos do Firebase, use uma lista separada por vírgulas em uma sinalização no comando firebase deploy. Por exemplo, o comando a seguir implanta o conteúdo do Firebase Hosting e as regras de segurança do Cloud Storage.

firebase deploy --only hosting,storage

A tabela a seguir lista os serviços e recursos disponíveis para implantação parcial. Os nomes nas sinalizações correspondem às chaves no arquivo de configuração firebase.json.

Sintaxe de sinalização Serviço ou recurso implantado
--only hosting conteúdo do Firebase Hosting
--only database regras do Firebase Realtime Database
--only storage regras do Cloud Storage para Firebase
--only firestore regras e índices do Cloud Firestore
--only firestore:rules regras do Cloud Firestore
--only firestore:indexes índices Cloud Firestore
--only functions Cloud Functions para Firebase (é possível haver versões mais específicas dessa sinalização)

Implantar funções específicas

Segmente funções específicas ao fazer a implantação. Exemplo:

firebase deploy --only functions:function1
firebase deploy --only functions:function1,functions:function2

Outra opção é juntar funções em grupos de exportação no seu arquivo /functions/index.js. Com isso, você pode implantar várias funções usando um único comando.

Por exemplo, é possível gravar as seguintes funções para definir um groupA e um groupB:

var functions = require('firebase-functions');

exports.groupA = {
  function1: functions.https.onRequest(...);
  function2: functions.database.ref('\path').onWrite(...);
}
exports.groupB = require('./groupB');

Neste exemplo, um arquivo functions/groupB.js separado contém outras funções que definem especificamente as funções em groupB:

var functions = require('firebase-functions');

exports.function3 = functions.storage.object().onChange(...);
exports.function4 = functions.analytics.event('in_app_purchase').onLog(...);

Neste exemplo, é possível implantar todas as funções groupA ao executar o seguinte comando no diretório do projeto:

firebase deploy --only functions:groupA

Outra opção seria direcionar uma função específica dentro de um grupo. Para isso, execute o seguinte comando:

firebase deploy --only functions:groupA.function1,groupB.function4

Excluir funções

A Firebase CLI é compatível com os seguintes comandos e opções para excluir funções implantadas anteriormente:

  • Para excluir todas as funções que correspondem ao nome especificado em todas as regiões:

    firebase functions:delete function1-name

  • Para excluir uma função especificada executada em uma região que não seja padrão:

    firebase functions:delete function1-name --region region-name

  • Para excluir mais de uma função:

    firebase functions:delete function1-name function2-name

  • Para excluir um grupo de funções especificado:

    firebase functions:delete group-name

  • Para ignorar o prompt de confirmação:

    firebase functions:delete function1-name --force

Configurar tarefas de pré e pós-implantação com script

Conecte scripts de shell ao comando firebase deploy para realizar tarefas de pré ou pós-implantação. Por exemplo, um script de pré-implantação poderia transcompilar o código TypeScript em JavaScript, e um hook de pós-implantação poderia notificar os administradores sobre o novo conteúdo do site implantado no Firebase Hosting.

Para configurar os hooks de pré ou pós-implantação, adicione scripts bash ao arquivo de configuração firebase.json. Defina scripts breves diretamente no arquivo firebase.json ou fazer referência a outros arquivos que estão no diretório de projeto.

Por exemplo, o script a seguir é a expressão firebase.json para uma tarefa de pós-implantação que envia uma mensagem Slack após uma implantação bem-sucedida no Firebase Hosting:

"hosting": {
  // ...

  "postdeploy": "./messageSlack.sh 'Just deployed to Firebase Hosting'",
  "public": "public"
}

O arquivo de script messageSlack.sh fica no diretório do projeto e tem esta aparência:

curl -X POST -H 'Content-type: application/json' --data '{"text":"$1"}'
     \https://Slack-Webhook-URL

É possível configurar hooks de predeploy e postdeploy para qualquer um dos recursos que podem ser implantados. Ao executar firebase deploy, todas as tarefas de pré e pós-implantação definidas no arquivo firebase.json são acionadas. Para executar apenas as tarefas associadas a um serviço específico do Firebase, use comandos parciais de implantação.

Os hooks de predeploy e postdeploy imprimem o resultado padrão e os fluxos de erros dos scripts no terminal. Em casos de falha, observe que:

  • se um hook de pré-implantação não for concluído conforme o esperado, a implantação será cancelada;
  • se ocorrer falhas na implantação por qualquer motivo, os hooks de pós-implantação não serão acionados.

Variáveis de ambiente

As variáveis de ambiente a seguir estão disponíveis nos scripts em execução nos hooks de pré e pós-implantação:

  • $GCLOUD_PROJECT: o código do projeto ativo
  • $PROJECT_DIR: o diretório raiz que contém firebase.json
  • $RESOURCE_DIR: (somente para scripts de hosting e functions) o local do diretório que contém os recursos do Hosting ou do Cloud Functions a serem implantados

Gerenciar aliases de projeto

Associe diversos projetos do Firebase ao mesmo diretório do projeto. Por exemplo, você pode usar um projeto para teste e outro para produção. Ao usar diferentes ambientes de projeto, confirme as alterações antes de implantá-las na produção. Com o comando firebase use, alterne entre os aliases e criar novos.

Adicionar um alias de projeto

Quando você seleciona um projeto do Firebase durante a inicialização, o alias dele é denominado automaticamente como default. No entanto, para permitir que comandos específicos do projeto sejam executados em outro projeto do Firebase, mas use o mesmo diretório, execute este comando:

firebase use --add

Ele solicita que você selecione outro projeto do Firebase e atribua a ele um alias definido. As definições do alias são gravadas em um arquivo .firebaserc no seu diretório de projetos.

Usar aliases de projeto

Para usar os aliases de projeto definidos do Firebase, execute qualquer um dos seguintes comandos no diretório do projeto.

Comando Descrição
firebase use Exibe uma lista de aliases atualmente definidos para o diretório do seu projeto.
firebase use alias_or_projectID Alterna entre os aliases do diretório do seu projeto.
firebase use --clear Limpa o alias "usado" atualmente e direciona todos os comandos para o alias default.
firebase use --unalias alias Remove um alias do diretório do seu projeto.

Durante o uso de um alias, todos os comandos específicos do projeto, como firebase deploy ou firebase data:get, serão executados no projeto atual. Se apenas um alias tiver sido definido no diretório de projeto, todos os comandos específicos serão executados automaticamente nesse alias.

Aliases de controle de origem e de projeto do Firebase

Normalmente, é necessário incluir o arquivo .firebaserc no controle de origem para que sua equipe compartilhe aliases de projetos comuns. No entanto, para projetos de código aberto ou modelos iniciais, geralmente não é necessário incluí-los no arquivo .firebaserc.

Caso você tenha um projeto de desenvolvimento somente para uso pessoal, envie a sinalização --project a cada comando ou execute firebase use projectID sem definir um alias para o projeto do Firebase.

Gerenciar várias instâncias do Firebase Realtime Database

Se um único projeto tiver várias instâncias do Realtime Database, use a opção --instance instance-name para interagir com a instância de banco de dados não padrão instance-name.firebaseio.com.

Os seguintes comandos aceitam a opção --instance:

Comando
database:profile
database:remove
database:push
database:set
database:update
database:get

Referência de comandos

Comandos administrativos

Comando Descrição
login Autentica a conta do Firebase. Exige acesso a um navegador da Web.
logout Sai da Firebase CLI.
login:ci Gera um token de autenticação para uso em ambientes não interativos.
list Imprime uma lista de todos os seus projetos do Firebase.
use Define o projeto do Firebase ativo e gerencia aliases do projeto.
open Abre rapidamente um navegador para recursos relevantes do projeto.
init Configura um novo projeto do Firebase no diretório atual. Esse comando criará um arquivo de configuração firebase.json no diretório atual.
help Exibe informações de ajuda sobre a CLI ou comandos específicos.

Implantação e desenvolvimento local

Com estes comandos, você faz a implantação e interage com o site do Firebase Hosting.

Comando Descrição
deploy Implanta o código e os recursos do diretório no seu projeto do Firebase. No caso do Firebase Hosting, é necessário um arquivo de configuração firebase.json.
serve Inicia um servidor da Web local com a configuração do Firebase Hosting. No caso do Firebase Hosting, é necessário um arquivo de configuração firebase.json.

Comandos do Realtime Database

Comando Descrição
database:get Carrega dados no banco de dados do projeto atual e exibe-os como JSON. É compatível com consultas em dados indexados.
database:set Substitui todos os dados em um local específico no banco de dados do projeto atual. Usa como entrada o arquivo STDIN ou o argumento de linha de comando.
database:update Executa uma atualização parcial em um local específico no banco de dados do projeto atual. Usa como entrada o arquivo STDIN ou o argumento de linha de comando.
database:push Envia novos dados para uma lista em um local específico no banco de dados do projeto atual. Usa como entrada o arquivo STDIN ou o argumento de linha de comando.
database:remove Exclui todos os dados de um local específico no banco de dados do projeto atual.
database:profile Cria um perfil de operações no banco de dados do seu projeto. Consulte Perfil do Realtime Database para ver informações mais detalhadas sobre as operações.

Comandos do Hosting

Comando Descrição
hosting:disable Interrompe o atendimento ao tráfego do Firebase Hosting para o projeto ativo. Após a execução desse comando, a mensagem "Site não encontrado" aparece no URL do Hosting de seus projetos.

Comandos do Cloud Firestore

Comando Descrição
firestore:delete Exclui documentos no Cloud Firestore. Com a Firebase CLI, você pode usar exclusões recursivas para excluir todos os documentos em uma coleção.

Comandos do Cloud Functions

Comando Descrição
functions:log Lê os registros das funções implantadas no Cloud Functions.
functions:config:set Armazena os valores de configuração do tempo de execução para as funções do Cloud Functions do projeto atual.
functions:config:get Recupera os valores de configuração para as funções do Cloud Functions do projeto atual.
functions:config:unset Remove os valores de configuração do tempo de execução do projeto atual.
functions:config:clone Copia a configuração do tempo de execução de um ambiente de projeto para outro.

Para mais informações, consulte Configuração do ambiente.

Comandos de gerenciamento de usuários

Comando Descrição
auth:import Importa contas de usuário de um arquivo para o projeto ativo. Consulte a página auth:import e auth:export para ver mais detalhes.
auth:export Exporta as contas de usuário do projeto ativo para um arquivo JSON ou CSV. Consulte a página auth:import e auth:export para ver mais detalhes.