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.

Update to the latest CLI version

Make sure that you're using the most up-to-date Firebase CLI version by re-running the CLI installation command:

npm install -g firebase-tools

Initialize a Firebase project

Many common tasks performed using the CLI, such as deploying to a Firebase project, require a project directory. You establish a project directory using the firebase init command. A project directory is generally the same directory as your source control root, and after running firebase init, the directory will contain a firebase.json configuration file.

To initialize a new Firebase project, run the following command from within your app's directory:

firebase init

The firebase init command steps you through setting up your project directory, including asking you to select desired Firebase services then configuring specific files for the selected services. If you want to add other Firebase services later, just run firebase init again.

The initialization process also asks you to choose a default Firebase project. This step associates the current project directory with a Firebase project so that project-specific commands (like firebase deploy) run against the appropriate Firebase project. It's also possible to associate multiple Firebase projects (such as a staging project and a production project) with the same project directory.

The firebase.json file

The firebase init command creates a firebase.json configuration file in the root of your project directory.

The firebase.json file is required to deploy assets with the Firebase CLI because it specifies which files and settings from your project directory are deployed to your Firebase project. Since some settings can be defined in either your project directory or the Firebase console, make sure that you resolve any potential deployment conflicts.

You can configure most Firebase Hosting options directly in the firebase.json file. However, for other Firebase services that can be deployed with the Firebase CLI, the firebase init command creates specific files where you can define settings for those services, such as an index.js file for Cloud Functions. You can also set up predeploy or postdeploy hooks in the firebase.json file.

The following is an example firebase.json file with default settings if you select Firebase Hosting, Cloud Firestore, and Cloud Functions for Firebase during initialization.

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

Serve and test your Firebase project locally

You can view and test your Firebase project on locally hosted URLs before deploying to production. If you only want to test select features, you can use a comma-separated list in a flag on the firebase serve command.

Run any of the following commands from your project directory to emulate your project using local HTTP functions.

  • To emulate HTTP functions and hosting for testing on local URLs, use either of the following commands:

    firebase serve
    firebase serve --only functions,hosting // uses a flag
  • To emulate HTTP functions only, use the following command:

    firebase serve --only functions

Run the following command from your project directory if you want to either:

firebase serve --only hosting

Deploy to a Firebase project

The Firebase CLI manages deployment of code and assets to your Firebase project, including:

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

To deploy to a Firebase project, run the following command from your project directory:

firebase deploy

By default, firebase deploy creates a release for all deployable resources in your project directory. To deploy specific Firebase services or features, use partial deployment.

Note that to deploy resources from a project directory, the project directory must have a firebase.json file. This file was automatically created for you by the firebase init command.

You can optionally add a comment to each of your deployments. This comment will display with the other deployment information on your project's Firebase Hosting page. For example:

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

Deployment conflicts for security rules

For Firebase Realtime Database, Cloud Storage for Firebase, and Cloud Firestore, you can define security rules either in your local project directory or in the Firebase console.

Another option to avoid deployment conflicts is to use partial deployment and only define rules in the Firebase console.

Deployment quotas

It's possible (though unlikely) that you might exceed a quota that limits 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 using partial deployment or requesting quota increases for specific Firebase services. For example, the quota called Write requests per 100 seconds per user might help to resolve the Cloud Functions 429 error cited above.

Roll back a deployment

You can roll back a Firebase Hosting deployment from your project's Firebase Hosting page by selecting the Rollback action for the desired release. It's not currently possible to roll back releases of security rules for Firebase Realtime Database, Cloud Storage for Firebase, or Cloud Firestore.

Deploy specific Firebase services

If you only want to deploy specific Firebase services or features, you can use a comma-separated list in a flag on the firebase deploy command. For example, the following command deploys Firebase Hosting content and Cloud Storage security rules.

firebase deploy --only hosting,storage

The following table lists the services and features available for partial deployment. The names in the flags correspond to the keys in your firebase.json configuration file.

Flag syntax Service or feature deployed
--only hosting Firebase Hosting content
--only database Firebase Realtime Database rules
--only storage Cloud Storage for Firebase rules
--only firestore Cloud Firestore rules and indexes
--only firestore:rules Cloud Firestore rules
--only firestore:indexes Cloud Firestore indexes
--only functions Cloud Functions for Firebase (more specific versions of this flag are possible)

Deploy specific functions

When deploying functions, you can target specific functions. For example:

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

Another option is to group functions into export groups in your /functions/index.js file. Grouping functions allows you to deploy multiple functions using a single command.

For example, you can write the following functions to define a groupA and a groupB:

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

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

In this example, a separate functions/groupB.js file contains additional functions that specifically define the functions in groupB:

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

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

In this example, you can deploy all the groupA functions by running the following command from your project directory:

firebase deploy --only functions:groupA

Or you can target a specific function within a group by running the following command:

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

Delete functions

The Firebase CLI supports the following commands and options for deleting previously deployed functions:

  • Delete all functions that match the specified name in all regions:

    firebase functions:delete function1-name

  • Delete a specified function running in a non-default region:

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

  • Delete more than one function:

    firebase functions:delete function1-name function2-name

  • Delete a specified functions group:

    firebase functions:delete group-name

  • Bypass the confirmation prompt:

    firebase functions:delete function1-name --force

Set up predeploy and postdeploy hooks

You can connect shell scripts to the firebase deploy command to perform 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 predeploy or postdeploy hooks, add bash scripts to your firebase.json configuration file. You can define brief scripts directly in the firebase.json file, or you can reference other files that are in your project directory.

For example, the following script is the firebase.json expression for a postdeploy task that sends a Slack message upon successful deployment to Firebase Hosting:

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

The messageSlack.sh script file resides in the project directory and looks like this:

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

You can set up predeploy and postdeploy hooks for any of the assets that you can deploy. Note that running firebase deploy triggers all the predeploy and postdeploy tasks defined in your firebase.json file. To run only those tasks associated with a specific Firebase service, use partial deployment commands.

Both predeploy and postdeploy hooks print the standard output and error streams of the scripts to the terminal. For failure cases, note that:

  • If a predeploy hook fails to complete as expected, deployment is canceled.
  • If deployment fails for any reason, postdeploy hooks are not triggered.

Environment variables

Within scripts running in the predeploy and postdeploy hooks, the following environment 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 that contains the Hosting or Cloud Functions resources to be deployed

Manage project aliases

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

Add a project alias

When you select a Firebase project during project initialization, the project's alias is automatically called default. However, to allow project-specific commands to run against a different Firebase project but use the same project directory, run the following command from within your project directory.

firebase use --add

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

Use project aliases

To use defined Firebase project aliases, run any of the following commands from within your project directory.

Command Description
firebase use View a list of currently defined aliases for your project directory
firebase use alias_or_project-id Switch between aliases for your project directory
firebase use --clear Clears the currently "used" alias and directs all commands to the default alias
firebase use --unalias alias Remove an alias from your project directory

While using an alias, all project-specific commands (such as firebase deploy or firebase data:get) run against the currently "used" Firebase project. If only one alias has been defined in your project directory, then any project-specific commands will automatically run against that alias.

Source control and Firebase project aliases

In general, you should check your .firebaserc file into source control. This allows your team to share common project aliases. However, for open source projects or starter templates, you should generally not check in the .firebaserc file.

If you have a development project that's for your use only, you can either pass the --project flag with each command or run firebase use project-id without defining the Firebase project an alias.

Managing multiple Firebase Realtime Database instances

If a single project has multiple Realtime Database instances, use the --instance instance-name option to interact with the non-default database instance, instance-name.firebaseio.com.

The following commands support the --instance option:

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

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 Set up a new Firebase project in the current directory. This command will create a firebase.json configuration file in the 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 code and assets from your project directory to your Firebase project. For Firebase Hosting, a firebase.json configuration file is required.
serve Starts a local web server with your Firebase Hosting configuration. For Firebase Hosting, a firebase.json configuration file is required.

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.