Firebase CLI Reference

The Firebase CLI (GitHub) provides a variety of tools for managing, viewing, and deploying to Firebase projects.

Setup

Before you can install the Firebase CLI, you will need to install Node.js on your machine. Once you've installed Node.js, you can install the Firebase CLI using npm (the Node Package Manager) by running the following command:

npm install -g firebase-tools

You should now have a globally available firebase command available from any terminal window on your machine. Once you've installed the Firebase CLI, sign in using your Google account:

firebase login

This command connects your local machine to your Firebase account and grants access to your projects. To test that authentication worked, you can run firebase list to see a list of all of your Firebase projects. The list should be the same as the projects listed at Firebase console.

Getting the latest version

You can make sure your Firebase CLI is up to date by re-running the installation command:

npm install -g firebase-tools

Project directories

Many common tasks performed by the CLI, such as deployment, require a Project Directory. A project directory is a any directory that has a firebase.json configuration file. The project directory should generally be the same as your source control root, and firebase.json generally lives alongside README and other top-level files.

Initializing a project directory

To initialize a new project directory, change directories in the terminal to your desired project directory and run:

firebase init

The init command steps you through setting up your project directory, including asking which Firebase features you want to use. Don't worry, you can always run init again later to add a new feature.

The last step of the init command asks you to choose a default Firebase project. This associates the directory with a project so that when you run project-specific commands such as firebase deploy from within your project directory, the correct project is used. It is also possible to associate multiple projects (such as a staging and production project) with the same directory.

Deployment

The Firebase CLI manages deployment of code and assets to your Firebase project. The firebase deploy command is capable of deploying:

  • New releases of your Firebase Hosting sites
  • New or existing Cloud Functions
  • Rules for Firebase Realtime Database
  • Rules for Cloud Storage
  • Rules for Cloud Firestore
  • Indexes for Cloud Firestore

By default, deploys create new releases for all deployable resources in your project directory. A project directory must have a firebase.json to be able to deploy.

Deployment conflicts

When you deploy security rules for Firebase Database or Storage, any existing security rules are overwritten. This means that any edits that were made in the Firebase Console may be lost if you run firebase deploy from the command line. If you specify rules in your Firebase project directory, it's imperative that you do not edit rules in the Firebase Console, or immediately update your local rules copy after publishing them.

Deployment quotas

It is possible (though unlikely) that you might exceeed a quota limiting the rate or volume of your Firebase deployment operations. For example, when deploying very large numbers of functions you might receive an HTTP 429 Quota error message. To solve such issues, try partial deploys or request a quota increase. You can request specific quota increases for Firebase services, including the Write requests per 100 seconds per user quota related to the Cloud Functions error cited above.

Rolling back

You can roll back Firebase Hosting deploys by visiting the Hosting panel for your project in the Firebase Console and choosing the Rollback action for the desired release. It is not currently possible to roll back releases of Firebase Database or Storage rules.

Partial deploys

If you only wish to deploy select features, you can use a comma-separated list in a flag on the deploy command. For example:

firebase deploy --only hosting

Valid features for the --only flag are hosting, functions, database, storage, and firestore. These names correspond to the keys in your firebase.json configuration file.

When deploying functions, you can target specific ones:

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

You can also group functions together into export groups in order to deploy multiple functions in a single command. For example, you can define groups within functions/index.js like this:

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

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

In this case, functions/groupB.js contains additional functions:

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

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

You can deploy all the functions in a group by running:

firebase deploy --only functions:groupA

You can target a specific function within a group by running:

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

Predeploy and postdeploy hooks

You can connect shell scripts to the deployment command in order to perfom predeploy or postdeploy tasks. For example, a predeploy script could transpile TypeScript code into JavaScript, and a postdeploy hook could notify administrators of deployment of new site content to Firebase hosting.

To set up deployment hooks, add bash scripts to the firebase.json configuration file for the project. Brief scripts can be defined directly in the file, or you can reference files in your project directory. For example, here is the firebase.json expression for a postdeploy script that sends a Slack message on successful completion of a deployment to Firebase hosting:

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

The messageSlack.sh script residing in the project directory would look like:

 curl -X POST -H 'Content-type: application/json' --data '{"text":"$1"}'
 \https://<Slack_Webhook_URL>

For any of the assets you can deploy—hosting, functions, database, storage, and firestore— you can add predeploy and postdeploy hooks in firebase.json, and your scripts will run with the corresponding deployment command. Both predeploy and postdeploy hooks print the standard output and error streams of the scripts to the terminal. For failure cases, note that:

  • Failure to complete a predeploy hook as expected cancels the deployment.
  • Where deployment fails for any reason, postdeploy hooks are not triggered.

Environment Variables

Within scripts running in the predeploy and postdeploy hooks, the following environemnt variables are available:

  • $GCLOUD_PROJECT: The active project ID.
  • $PROJECT_DIR: The root directory containing firebase.json.
  • $RESOURCE_DIR: For hosting and functions scripts only - The location of the directory containing the hosting or functions resources to be deployed.

Managing project aliases

You can associate multiple Firebase projects with the same working directory. For example, you may want to use one Firebase project for staging and another for production. Using different project environments allows you to verify changes before deploying to production. The firebase use command lets you switch between aliases as well as create new ones.

Adding a project alias

When you select a project during firebase init, an alias called default is created for you. To create a new alias, run:

firebase use --add

This command allows you to select a Firebase project and give it a named alias. Alias definitions are written to a .firebaserc file inside your project directory.

Using project aliases

You can view a list of currently defined aliases for your project directory by running firebase use. To switch between aliases, run:

firebase use <alias_or_project_id>

While using an alias, all project-specific commands (like firebase deploy or firebase data:get) will run against the currently used project. If only one alias is defined in your project directory it will be used automatically.

You can clear your current alias by running firebase use --clear, and remove an alias by running firebase use --unalias <alias>.

Source control and project aliases

In general, you should check your .firebaserc project into source control. This allows your team to share common project aliases. If you have a development project only for your use, you can either pass the --project flag with each command or run firebase use <project_id> without defining it as an alias.

Open source projects or starter templates should generally not check in the .firebaserc file.

Command reference

Administrative commands

Command Description
login Authenticate to your Firebase account. Requires access to a web browser.
logout Sign out of the Firebase CLI.
login:ci Generate an authentication token for use in non-interactive environments.
list Print a list of all of your Firebase projects.
use Set active Firebase project, manage project aliases.
open Quickly open a browser to relevant project resources.
init Setup a new Firebase project in the current directory. This command will create a firebase.json configuration file in your current directory.
help Display help information about the CLI or specific commands.

Deployment and local development

These commands let you deploy and interact with your Firebase Hosting site.

Command Description
deploy Deploys your Firebase project. Relies on firebase.json configuration and your local project folder.
serve Start a local web server with your Firebase Hosting configuration. Relies on firebase.json.

Database commands

Command Description
database:get Fetch data from the current project's database and display it as JSON. Supports querying on indexed data.
database:set Replace all data at a specified location in the current project's database. Takes input from file, STDIN, or command-line argument.
database:update Perform a partial update at a specified location in the current project's database. Takes input from file, STDIN, or command-line argument.
database:push Push new data to a list at a specified location in the current project's database. Takes input from file, STDIN, or command-line argument.
database:remove Delete all data at a specified location in the current project's database.
database:profile Build a profile of operations on your project's database. See Realtime Database Profile for more detailed information about the operations.

Hosting commands

Command Description
hosting:disable Stop serving Firebase Hosting traffic for the active project. A "Site Not Found" message will be displayed at your project's Hosting URL after running this command.

Cloud Firestore commands

Command Description
firestore:delete Delete documents in Cloud Firestore. With the Firebase CLI, you can use recursive deletes to delete all the documents in a collection.

Cloud Functions commands

Command Description
functions:log Read logs from deployed Cloud Functions.
functions:config:set Store runtime configuration values for the current project's Cloud Functions.
functions:config:get Retrieve existing configuration values for the current project's Cloud Functions.
functions:config:unset Remove values from the current project's runtime configuration.
functions:config:clone Copy runtime configuration from one project environment to another.

For more information, see Environment Configuration.

User management commands

Command Description
auth:import Import user accounts from a file into the active project. See the auth:import and auth:export page for details.
auth:export Export the active project's user accounts to a JSON or CSV file. See the auth:import and auth:export page for details.

Send feedback about...

Need help? Visit our support page.