firebase-basics

# Firebase Android Setup Guide

______________________________________________________________________

## Prerequisites

1. **Firebase CLI**: Make sure the Firebase CLI is available and authenticated.

   For detailed instructions about the Firebase CLI, see
   `firebase_basics/references/local-env-setup`. Here are high-level
   instructions for setting up the Firebase CLI.

   1. Ensure the Firebase CLI is available:

      ```bash
      npx -y firebase-tools@latest --version
      ```

   1. Login to the CLI:

      - local:

        ```bash
        npx -y firebase-tools@latest login
        ```

      - remote servers:

        ```bash
        npx -y firebase-tools@latest login --no-localhost
        ```

1. **Android project**: Create or use an existing Android project in an
   Android-development IDE.

______________________________________________________________________

## 1. Check if the Android project is connected to a Firebase Project

Check if the Android project already has a `google-services.json` file in its
**module (app-level)** root directory.

### `google-services.json` file is present

If the Android project already has a `google-services.json` file, do NOT create
a new Firebase project or re-register the app — skip steps 2 through 4 below.
Instead, verify the existing Firebase setup within the codebase and fix anything
that is missing:

- The `google-services.json` file is in the **module (app-level)** root
  directory: `app/google-services.json`

- The Google services Gradle plugin (`google-services`) is added to *both* the
  project-level and module (app-level) Gradle build files. If it is missing from
  either file, add it by following step 5 below.

### `google-services.json` file is NOT present

If the Android project does NOT already have a `google-services.json` file, then
proceed with the remaining steps in this guide.

______________________________________________________________________

## 2. Create a new Firebase project or use an existing one

Check if there's an existing Firebase Project available for use with the Android
project:

```bash
npx -y firebase-tools@latest projects:list
```

- **If existing Firebase Project:** Ask the human user if they want to use the
  existing project.

- **If no existing Firebase Project or human user does not want to use an
  existing project:** Create a new Firebase Project.

  Provide a required unique PROJECT_ID and an optional PROJECT_DISPLAY_NAME:

  ```bash
  npx -y firebase-tools@latest projects:create <UNIQUE_PROJECT_ID> --display-name <PROJECT_DISPLAY_NAME>
  ```

  *Example:*

  ```bash
  npx -y firebase-tools@latest projects:create my-cool-app-20260330 --display-name MyCoolApp
  ```

______________________________________________________________________

## 3. Register the Android project

Register the app module (package name) of the Android project with the Firebase
project. Provide an optional APP_DISPLAY_NAME and required PACKAGE_NAME:

```bash
npx -y firebase-tools@latest apps:create ANDROID <APP_DISPLAY_NAME> --package-name <PACKAGE_NAME> --project <PROJECT_ID>
```

*Example:*

```bash
npx -y firebase-tools@latest apps:create ANDROID MyApplication --package-name com.example.myapplication --project my-cool-app-20260330
```

NOTE: A package name is often referred to as an *application ID* within an
Android project. Find an app's package name in the module (app-level) Gradle
file, usually `app/build.gradle.kts`.

______________________________________________________________________

## 4. Obtain and save `google-services.json`

1. Fetch the Firebase configuration file (`google-services.json`) using the
   Firebase Android APP_ID (which is printed in the output of the previous
   `apps:create` command):

   ```bash
   npx -y firebase-tools@latest apps:sdkconfig ANDROID <APP_ID> --project <PROJECT_ID>
   ```

1. Save the configuration file within the **module (app-level)** root directory
   of the Android project: `app/google-services.json`

______________________________________________________________________

## 5. Add the `google-services` plugin

> [!IMPORTANT] **[AGENT] RESOLVING THE PLUGIN VERSION DETERMINISTICALLY** Never
> guess or hardcode a memorized out-of-date plugin version. Before adding
> dependencies, you MUST query the latest available versions directly from the
> Google Maven Repository:
>
> ```bash
> # Find the latest Google services Gradle plugin version
> curl -s https://dl.google.com/dl/android/maven2/com/google/gms/google-services/maven-metadata.xml | grep -oE '<latest>[^<]+' | cut -d'>' -f2
> ```

These changes are made to the Android project's Gradle files.

### Project-level `build.gradle.kts` (`<project>/build.gradle.kts`)

Add the latest version of the Google services Gradle plugin to the `plugins`
block:

```kotlin
plugins {
    // ... other plugins

    // [AGENT] Fetch the latest resolved version using the Gradle command above
    id("com.google.gms.google-services") version "<latest_plugin_version>" apply false
}
```

### Module (app-level) `build.gradle.kts` (`<project>/<app-module>/build.gradle.kts`)

Add the Google services Gradle plugin to the `plugins` block:

```kotlin
plugins {
    // ... other plugins
    id("com.google.gms.google-services")
}
```

______________________________________________________________________

## 6. App Check (Debug Token Persistence)

When using App Check on Android emulators or local development,
`DebugAppCheckProviderFactory.getInstance()` generates a UUID token and stores
it in `SharedPreferences`. Wiping emulator data, clearing app storage, or fresh
installs generate a new UUID in Logcat, causing debug token churn in the
Firebase Console.

> [!WARNING] **CRITICAL: Never Hardcode or Commit Debug Tokens** App Check debug
> tokens allow clients to bypass attestation and access backend resources
> without a genuine device. **Never hardcode debug token strings in
> build.gradle.kts, Java, or Kotlin files, and never commit tokens to version
> control.** If a token is compromised, revoke it immediately in the Firebase
> Console.

To persist a stable debug token across emulator resets and testing without
committing secrets:

1. Obtain or generate a stable UUID debug token and register it in the Firebase
   Console under **Security > App Check > Apps > Manage debug tokens**.

1. Store the token in your project's gitignored `local.properties`:

   ```properties
   # In local.properties (ensure this file is in your .gitignore!)
   APP_CHECK_DEBUG_TOKEN=<YOUR_DEBUG_TOKEN>
   ```

1. Inject the secret in `app/build.gradle.kts` for instrumentation/testing:

   ```kotlin
   val localProperties = java.util.Properties().apply {
       val localPropertiesFile = rootProject.file("local.properties")
       if (localPropertiesFile.exists()) {
           load(localPropertiesFile.inputStream())
       }
   }
   val appCheckDebugToken = localProperties.getProperty("APP_CHECK_DEBUG_TOKEN")
       ?: System.getenv("APP_CHECK_DEBUG_TOKEN") ?: ""

   android {
       defaultConfig {
           // For normal emulator runs (injects into AndroidManifest)
           manifestPlaceholders["firebaseAppCheckDebugSecret"] = appCheckDebugToken

           // For instrumentation tests
           if (appCheckDebugToken.isNotEmpty()) {
               testInstrumentationRunnerArguments["firebaseAppCheckDebugSecret"] = appCheckDebugToken
           }
       }
   }
   ```

1. In your application or activity, install the debug provider for debug builds:

   ```kotlin
   if (BuildConfig.DEBUG) {
       Firebase.appCheck.installAppCheckProviderFactory(
           DebugAppCheckProviderFactory.getInstance()
       )
   }
   ```

______________________________________________________________________

## Verification plan

### Manual verification

Validate that the Firebase Project was created and the Firebase Android App was
registered successfully:

```bash
npx -y firebase-tools@latest projects:list
npx -y firebase-tools@latest apps:list --project <PROJECT_ID>
```

______________________________________________________________________

# Exploring Commands

The Firebase CLI documents itself. Use help commands to discover functionality.

- **Global Help**: List all available commands and categories.

  ```bash
  npx -y firebase-tools@latest --help
  ```

- **Command Help**: Get detailed usage for a specific command.

  ```bash
  npx -y firebase-tools@latest [command] --help
  # Example:
  npx -y firebase-tools@latest deploy --help
  npx -y firebase-tools@latest firestore:indexes --help
  ```

# Initialization

Before initializing, check if you are already in a Firebase project directory by
looking for `firebase.json`.

1. **Project Directory:** Navigate to the root directory of the codebase. *(Only
   if starting a completely new project from scratch without an existing
   codebase, create a directory first: `mkdir my-project && cd my-project`)*

1. **Initialize Services:** Run the initialization command:

   ```bash
   npx -y firebase-tools@latest init
   ```

The CLI will guide you through:

- Selecting features (Firestore, Functions, Hosting, etc.).
- Associating with an existing project or creating a new one.
- Configuring files (e.g. `firebase.json`, `.firebaserc`).

# Flutter & Firebase Setup Guide

This guide covers the initial setup of Flutter and its integration with Firebase
using the FlutterFire CLI.

## Prerequisites

1. **Flutter SDK**: Ensure Flutter is installed and available in the PATH.

   **Standard Setup (Manual):**

   1. **Determine Architecture**: Check if you are on Intel (`x64`) or Apple
      Silicon (`arm64`) using `uname -m`.
   1. **Download SDK**: Fetch the latest stable SDK from the
      [Flutter Archive](https://docs.flutter.dev/install/archive?tab=macos).
   1. **Extract**: Unzip the SDK to a permanent directory (e.g.,
      `~/development/flutter`).
   1. **Update PATH**: Add the `bin` folder to your shell configuration (e.g.,
      `~/.zshrc`).
      ```bash
      echo 'export PATH="$PATH:$HOME/development/flutter/bin"' >> ~/.zshrc
      source ~/.zshrc
      ```
   1. **Verify**: Run `flutter doctor` to ensure the SDK is correctly linked and
      initialized.

1. **Firebase CLI**: Ensure the Firebase CLI is available.

   - Run `npx -y firebase-tools@latest --version`.
   - Login with `npx -y firebase-tools@latest login`.

1. **FlutterFire CLI**: Install the official FlutterFire CLI globally.

   - Run `dart pub global activate flutterfire_cli`.
   - **Note**: Ensure `~/.pub-cache/bin` is also in your PATH if `flutterfire`
     is not found.

## Step 1: Create a Flutter Project

If you don't have a project yet, create one:

```bash
flutter create my_awesome_app
cd my_awesome_app
```

## Step 2: Configure Firebase

> [!IMPORTANT] **For Agents:** Before running the configuration command, you
> MUST pause and ask the developer if they prefer to:
>
> 1. Create a new Firebase project, or
> 1. Provide an existing Firebase Project ID.

- If the developer provides an existing Project ID, run:
  ```bash
  flutterfire configure --project=<project_id>
  ```
- If the developer prefers to create a new project interactively, run:
  ```bash
  flutterfire configure
  ```

This tool automates:

- Registering your apps (iOS, Android, Web, etc.) with a Firebase project.
- Generating the `lib/firebase_options.dart` file.

## Step 3: Initialize Firebase in Code

Add the `firebase_core` package and initialize it in your `main.dart`.

1. Add the dependency:

```bash
flutter pub add firebase_core
```

2. Update `lib/main.dart`:

```dart
import 'package:flutter/material.dart';
import 'package:firebase_core/firebase_core.dart';
import 'firebase_options.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp(
    options: DefaultFirebaseOptions.currentPlatform,
  );
  runApp(const MyApp());
}
```

## Step 4: Add Firebase Services

To add specific services (Firestore, Auth, etc.), follow the "Pub Add &
Configure" pattern:

1. Add the service: `flutter pub add cloud_firestore`
1. **Crucial**: Re-run `flutterfire configure` to sync platform configurations.
1. Import and use the package in your code.

## Step 5: Important Gotchas & Platform Specifics

### 1. Re-running `flutterfire configure` Upon Renaming

When creating a new project, developers often change the bundle identifier (iOS)
or `applicationId` (Android) after the fact. If the package names change,
`flutterfire configure` **must** be re-run to update the respective Google
service files and `firebase_options.dart`.

### 2. Platform-Specific Build Requirements

- **Android**: Adding Firebase often requires a higher `minSdkVersion` (commonly
  `21` or `23`) than the platform default. Be prepared to update
  `android/app/build.gradle` automatically when installing certain plugins.
- **iOS**: Always check if there is a `Podfile` in the `/ios` directory whenever
  native services (like `cloud_firestore`) are added. If there is, run
  `pod install`. Failing to do this will cause Xcode build errors. Note that
  Flutter is moving towards Swift Package Manager (SPM), and FlutterFire
  supports SPM, so a `Podfile` may not exist if the project only uses SPM
  dependencies.

### 3. Web CORS Best Practices

When testing Firebase features locally on Chrome, requests to Google servers can
sometimes get blocked by CORS policies. Avoid relying on
`--disable-web-security` flags as it promotes bad security practices. Instead,
run the app on localhost with a specific port, and ensure `localhost` is added
to your Firebase Auth "Authorized Domains".

```bash
flutter run -d chrome --web-hostname=localhost --web-port=5000
```

### 4. Elaborating on `WidgetsFlutterBinding.ensureInitialized()`

In your `main.dart`, this call is mandatory before `Firebase.initializeApp()`.
*Why?* Because Firebase initialization requires communication across Flutter's
native iOS/Android method channels. `ensureInitialized()` guarantees the Fluter
engine is fully booted up and ready to handle these native platform calls before
`runApp()` executes.

# Firebase iOS Setup Guide

# ⛔️ CRITICAL RULE: STATE MANAGEMENT (OBSERVATION VS COMBINE) ⛔️

When writing or updating SwiftUI code, you **MUST** prioritize the modern Swift
**Observation framework (`@Observable` macro and `@State`)** as your default
approach.

However, it is acceptable to use **Combine** (`ObservableObject`, `@Published`,
`@StateObject`, `@EnvironmentObject`) under the following conditions:

- The user explicitly asks you to use Combine.
- There are strong signals in the existing codebase that the project is heavily
  relying on Combine.

If neither of those conditions are true, default to the Swift 5.9+ Observation
framework.

# ⛔️ CRITICAL RULE: INITIALIZATION ORDER ⛔️

When using SwiftUI, you **MUST** ensure `FirebaseApp.configure()` is called
**BEFORE** any Firebase-dependent state objects are initialized.

- **UNSAFE (CRASH):** Declaring a `@State` (for `@Observable`) or `@StateObject`
  (for Combine) property in the root `App` struct if its initializer touches
  Firebase. Property initializers run *before* the `App.init()` body, meaning
  the object's `init()` will fire before Firebase is configured.
- **SAFE:** Initialize Firebase in `App.init()` and pass your state objects into
  the sub-views (like `ContentView`), or use `onAppear` for delayed setup.

Failing to follow this will result in a fatal crash:
`Default FirebaseApp is not configured`.

## 1. Create a Firebase Project and App (Automated)

Do not use the Firebase Console. Use the CLI to automate setup:

1. Create the project: `npx -y firebase-tools@latest projects:create`
1. Action: Read the Xcode project (`.pbxproj` or `Info.plist`) to determine the
   iOS bundle ID.
1. Register the iOS app:
   `npx -y firebase-tools@latest apps:create IOS <bundle-id>`
1. Fetch the config: `npx -y firebase-tools@latest apps:sdkconfig IOS <App-ID>`
1. Save the output as `GoogleService-Info.plist` in your Xcode project folder.
   Ensure you remove any non-XML CLI output headers, and ensure the file is
   linked to the main application target.

## 2. Installation (Automated via Swift Package Manager CLI)

Do not use raw text parsing, sed, or Ruby scripts (like `xcodeproj` gem) to
modify `.pbxproj` files directly.

Instead, use the **`xcode-project-setup`** skill. Load that skill using your
tools to securely execute its native Swift package setup script. That skill
handles installing the required SPM packages and safely linking the
`GoogleService-Info.plist` file.

> **💡 TIP: ALWAYS USE THE LATEST SDK VERSION** To ensure access to the latest
> features and security fixes, always check for the most recent version of the
> Firebase iOS SDK at
> [https://github.com/firebase/firebase-ios-sdk/releases](https://github.com/firebase/firebase-ios-sdk/releases)
> and use that version when adding the SPM dependency.

## 3. Initialization

Configure the shared `FirebaseApp` instance. You can do this either in a modern
SwiftUI `App` structure or a traditional `AppDelegate`.

### SwiftUI (Modern - SAFE PATTERN)

```swift
import SwiftUI
import FirebaseCore

@main
struct YourApp: App {
  // ⛔️ FATAL CRASH: @State private var auth = AuthManager()
  // property initializers run before init(), causing FirebaseApp not configured error
  @State private var authManager: AuthManager

  init() {
    // ✅ SAFE: This runs FIRST
    FirebaseApp.configure()
    
    // ✅ SAFE: Initialize state ONLY AFTER Firebase is configured
    _authManager = State(initialValue: AuthManager())
  }

  var body: some Scene {
    WindowGroup {
      ContentView()
        .environment(authManager)
    }
  }
}
```

### AppDelegate (Traditional / UIKit)

```swift
import UIKit
import FirebaseCore

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
  func application(_ application: UIApplication,
                   didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
    // ✅ SAFE: Always the first line in didFinishLaunching
    FirebaseApp.configure()
    return true
  }
}
```

## 4. App Check (Debug Token Persistence)

When using App Check in local development or the iOS Simulator, the Firebase iOS
SDK generates a new UUID debug token whenever `NSUserDefaults` is erased (such
as during a simulator reset or fresh install). This causes debug token churn and
invalidates tokens previously registered in the Firebase console.

> [!WARNING] **CRITICAL: Never Hardcode or Commit Debug Tokens** App Check debug
> tokens allow clients to bypass attestation and access backend resources
> without a genuine device. Treat them as sensitive secrets. **Never commit
> debug tokens into version control or hardcode them directly into source
> code.** If a token is compromised, revoke it immediately in the Firebase
> Console.

To persist a stable debug token across simulator resets without committing
secrets:

1. Obtain or generate a stable UUID debug token and register it in the Firebase
   Console under **Security > App Check > Apps > Manage debug tokens**.

1. Supply `AppCheckDebugToken` via your local environment instead of hardcoding
   it in code:

   - **Xcode Scheme Environment Variables (Recommended):**

     - Select **Product > Scheme > Edit Scheme...** (or `Cmd + <`).
     - Navigate to **Run > Arguments > Environment Variables**.
     - Add `AppCheckDebugToken = <YOUR_DEBUG_TOKEN>`.
     - *Tip:* Keep your personal scheme unshared or ensure user scheme data
       (`xcuserdata/`) is included in `.gitignore` so your personal debug token
       is not committed.

   - **In Code (Only with Secure / Gitignored Loading):** If setting the
     environment variable in code before initializing
     `AppCheckDebugProviderFactory`, load the token dynamically from a
     gitignored local file or build configuration—never hardcode the raw token
     string:

     ```swift
     #if DEBUG
     // ⛔️ DO NOT hardcode literal tokens: setenv("AppCheckDebugToken", "secret-uuid", 0)
     // ✅ SAFE: Load dynamically from a gitignored local file, xcconfig, or process environment
     // Note: loadGitIgnoredDebugToken() is a placeholder for your custom helper (e.g., reading from a gitignored plist)
     if let debugToken = loadGitIgnoredDebugToken() {
       setenv("AppCheckDebugToken", debugToken, 0)
     }
     let providerFactory = AppCheckDebugProviderFactory()
     AppCheck.setAppCheckProviderFactory(providerFactory)
     #endif

     FirebaseApp.configure() // Must be called AFTER setting the App Check provider factory
     ```

Setting this environment variable avoids invalidating tokens registered in the
Firebase console by ensuring a consistent debug token is reused across simulator
resets and fresh app installs.

# Firebase Local Environment Setup

This skill documents the bare minimum setup required for a full Firebase
experience for the agent. Before starting to use any Firebase features, you MUST
verify that each of the following steps has been completed.

## 1. Verify Node.js

- **Action**: Run `node --version`.

- **Handling**: Ensure Node.js is installed and the version is `>= 20`. If
  Node.js is missing or `< v20`, install it based on the operating system:

  **Recommended: Use a Node Version Manager** This avoids permission issues when
  installing global packages.

  **For macOS or Linux:**

  1. Guide the user to the
     [official nvm repository](https://github.com/nvm-sh/nvm#installing-and-updating).
  1. Request the user to manually install `nvm` and reply when finished. **Stop
     and wait** for the user's confirmation.
  1. Make `nvm` available in the current terminal session by sourcing the
     appropriate profile:
     ```bash
     # For Bash
     source ~/.bash_profile
     source ~/.bashrc

     # For Zsh
     source ~/.zprofile
     source ~/.zshrc
     ```
  1. Install Node.js:
     ```bash
     nvm install 24
     nvm use 24
     ```

  **For Windows:**

  1. Guide the user to download and install
     [nvm-windows](https://github.com/coreybutler/nvm-windows/releases).
  1. Request the user to manually install `nvm-windows` and Node.js, and reply
     when finished. **Stop and wait** for the user's confirmation.
  1. After the user confirms, verify Node.js is available:
     ```bash
     node --version
     ```

  **Alternative: Official Installer**

  1. Guide the user to download and install the LTS version from
     [nodejs.org](https://nodejs.org/en/download).
  1. Request the user to manually install Node.js and reply when finished.
     **Stop and wait** for the user's confirmation.

## 2. Verify Firebase CLI

- **Command**: `npx -y firebase-tools@latest --version`
- **Expected**: Successfully outputs a version string.

## 3. Verify Firebase Authentication

You must be authenticated to manage Firebase projects.

- **Action**: Run `npx -y firebase-tools@latest login`.
- **Handling**: If the environment is remote or restricted (no browser access),
  run `npx -y firebase-tools@latest login --no-localhost` instead.

## 4. Install Agent Skills and MCP Server

To fully manage Firebase, the agent needs specific skills and the Firebase MCP
server installed. Refer to the main `SKILL.md` for direct links to the
installation instructions specific to your agent environment.

______________________________________________________________________

**CRITICAL AGENT RULE:** Do NOT proceed with any other Firebase tasks until
EVERY step above has been successfully verified and completed.

# Refresh Android Studio Local Environment

Follow these steps to refresh Gemini in Android Studio's local environment,
ensuring that agent skills are fully up-to-date.

Gemini in Android Studio expects skills to be located at `~/.agents/skills`.

1. **List Available Skills:** Identify all Firebase skills available in the
   repository:

   ```bash
   npx -y skills add firebase/agent-skills --list
   ```

1. **Check Currently Installed Skills:** Check the contents of the skills
   directory to see what is currently installed:

   ```bash
   ls -la ~/.agents/skills
   ```

1. **Add Missing Skills:** Use the `skills` CLI to add skills. If the CLI
   supports an `android_studio` agent identifier, you can run:

   ```bash
   npx -y skills add firebase/agent-skills --agent android_studio --skill "*" --yes
   ```

   If the `skills` CLI does not support Android Studio directly, you can
   manually copy or symlink the desired skills from your local clone of
   `firebase/agent-skills` to `~/.agents/skills`.

1. **Update Existing Skills:** To update skills, you can try:

   ```bash
   npx -y skills update --agent android_studio --yes
   ```

   If manual installation was used, pull the latest changes from the
   `firebase/agent-skills` repository and copy the updated files to
   `~/.agents/skills`.

# Refresh Antigravity Local Environment

Follow these steps to refresh Antigravity's local environment, ensuring that
their agent skills and plugins are fully up-to-date.

Antigravity relies on `npx skills`. Updates should prioritize the global level;
if skills are installed at the project level, omit the `--global` flag.

1. **List Available Skills:** Identify all Firebase skills available in the
   repository:

   ```bash
   npx -y skills add firebase/agent-skills --list
   ```

1. **Check Currently Installed Skills:** Determine which skills are already
   installed and linked at both project and global levels:

   ```bash
   # Check project-level skills
   npx -y skills list --agent antigravity

   # Check global-level skills
   npx -y skills list --agent antigravity --global
   ```

   *Note: If a skill shows `Agents: not linked` in the output, it is installed
   but not currently available to Antigravity.*

1. **Add Missing or Unlinked Skills:** Compare the results from Step 1 and Step
   2\. For each missing or unlinked skill, follow the appropriate conditional
   instruction below:

   - **IF any Firebase skills were found at the PROJECT level in Step 2:** Add
     the missing skill to the project level:

     ```bash
     npx -y skills add firebase/agent-skills --agent antigravity --skill "<SKILL_NAME>" --yes
     ```

   - **IF any Firebase skills were found at the GLOBAL level in Step 2:** Add
     the missing skill to the global level:

     ```bash
     npx -y skills add firebase/agent-skills --agent antigravity --skill "<SKILL_NAME>" --global --yes
     ```

   - **IF NO Firebase skills were found in Step 2:** Add each missing skill to
     the global level:

     ```bash
     npx -y skills add firebase/agent-skills --agent antigravity --skill "<SKILL_NAME>" --global --yes
     ```

1. **Update Existing Skills:** Update all currently installed skills to their
   latest versions:

   ```bash
   # Update project-level skills
   npx -y skills update --agent antigravity --yes

   # Update global-level skills
   npx -y skills update --agent antigravity --global --yes
   ```

# Refresh Claude Code Local Environment

Follow these steps to refresh Claude Code's local environment, ensuring that
their agent skills and plugins are fully up-to-date.

Use Claude Code's native plugin manager instead of `npx`.

1. **Update the Plugin:** Run the specific CLI command to update the Firebase
   plugin:
   ```bash
   claude plugin update firebase@firebase
   ```

# Refresh Gemini CLI Local Environment

Follow these steps to refresh Gemini CLI's local environment, ensuring that
their agent skills and plugins are fully up-to-date.

Use the native Gemini CLI extension manager instead of `npx`.

1. **Update the Extension:** Run the specific CLI command to update:
   ```bash
   gemini extensions update firebase
   ```
   *Note: If the extension is named differently, replace `firebase` with the
   correct name from `gemini extensions list`.*

# Refresh Other Local Environment

Follow these steps to refresh the local environment of other agents, ensuring
that their agent skills and plugins are fully up-to-date.

Other agents rely on `npx skills`. Updates should prioritize the global level;
if skills are installed at the project level, omit the `--global` flag.

Replace `<AGENT_NAME>` with the actual agent name, which can be found in the
[skills repository README](https://github.com/vercel-labs/skills/blob/main/README.md).

1. **List Available Skills:** Identify all Firebase skills available in the
   repository:

   ```bash
   npx -y skills add firebase/agent-skills --list
   ```

1. **Check Currently Installed Skills:** Determine which skills are already
   installed and linked for the agent at both project and global levels:

   ```bash
   # Check project-level skills
   npx -y skills list --agent <AGENT_NAME>

   # Check global-level skills
   npx -y skills list --agent <AGENT_NAME> --global
   ```

   *Note: If a skill shows `Agents: not linked` in the output, it is installed
   but not currently available to the agent.*

1. **Add Missing or Unlinked Skills:** Compare the results from Step 1 and Step
   2\. For each missing or unlinked skill, follow the appropriate conditional
   instruction below:

   - **IF any Firebase skills were found at the PROJECT level in Step 2:** Add
     the missing skill to the project level:

     ```bash
     npx -y skills add firebase/agent-skills --agent <AGENT_NAME> --skill "<SKILL_NAME>" --yes
     ```

   - **IF any Firebase skills were found at the GLOBAL level in Step 2:** Add
     the missing skill to the global level:

     ```bash
     npx -y skills add firebase/agent-skills --agent <AGENT_NAME> --skill "<SKILL_NAME>" --global --yes
     ```

   - **IF NO Firebase skills were found in Step 2:** Add each missing skill to
     the global level:

     ```bash
     npx -y skills add firebase/agent-skills --agent <AGENT_NAME> --skill "<SKILL_NAME>" --global --yes
     ```

1. **Update Existing Skills:** Update all currently installed skills to their
   latest versions:

   ```bash
   # Update project-level skills
   npx -y skills update --agent <AGENT_NAME> --yes

   # Update global-level skills
   npx -y skills update --agent <AGENT_NAME> --global --yes
   ```

# Android Studio Setup

This guide explains how to set up Firebase agent skills for Gemini in Android
Studio.

## Skills Installation

Gemini in Android Studio expects skills to be located at `~/.agents/skills`.

To install all Firebase skills, run the following command in your terminal:

```bash
npx -y skills add firebase/agent-skills --skill "*" --yes
```

Ensure that the skills are installed or linked to the `~/.agents/skills`
directory.

## MCP Setup

MCP setup is currently skipped for Android Studio as it only supports SSE
transport, while the Firebase CLI MCP server uses stdio. Direct integration is
not supported without an SSE-to-stdio proxy.

# Antigravity Setup

To get the most out of Firebase in Antigravity, follow these steps to install
the agent skills and the MCP server.

### 1. Install and Verify Firebase Skills

Check if the skills are already installed before proceeding:

1. **Check Local skills**: Run `ls -d .agent/skills/firebase-basics` or
   `ls -d .agents/skills/firebase-basics`. If the directory exists, the skills
   are already installed locally.
1. **Check Global skills**: If not found locally, check the global installation
   by running:
   ```bash
   npx skills list --global --agent antigravity
   ```
   If the output includes `firebase-basics`, the skills are already installed
   globally.
1. **Install Skills**: If both checks fail, run the following command to install
   the Firebase agent skills:
   ```bash
   npx skills add firebase/agent-skills --agent antigravity --skill "*"
   ```
   *Note: Omit `--yes` and `--global` to choose the installation location
   manually. If prompted interactively in the terminal, ensure you send the
   appropriate user choices via standard input to complete the installation.*
1. **Verify Installation**: Re-run the checks in steps 1 or 2 to confirm that
   `firebase-basics` is now available.

### 2. Configure and Verify Firebase MCP Server

The MCP server allows Antigravity to interact directly with Firebase projects.
This is considered the **mandatory extension configuration** required for full
functionality.

1. **Locate `mcp_config.json`**: Find the configuration file for your operating
   system:

   - macOS / Linux: `~/.gemini/antigravity/mcp_config.json`
   - Windows: `%USERPROFILE%\\.gemini\\antigravity\\mcp_config.json`

   *Note: If the `.gemini/antigravity/` directory or `mcp_config.json` file does
   not exist, create them and initialize the file with `{ "mcpServers": {} }`
   before proceeding.*

1. **Check Existing Configuration**: Open `mcp_config.json` and check the
   `mcpServers` section for a `firebase` entry.

   - It is already configured if the `command` is `"firebase"` OR if the
     `command` is `"npx"` with `"firebase-tools"` and `"mcp"` in the `args`.
   - **Important**: If a valid `firebase` entry is found, the MCP server is
     already configured. **Skip step 3** and proceed directly to step 4.

   **Example valid configurations**:

   ```json
   "firebase": {
     "command": "npx",
     "args": ["-y", "firebase-tools@latest", "mcp"]
   }
   ```

   OR

   ```json
   "firebase": {
     "command": "firebase",
     "args": ["mcp"]
   }
   ```

1. **Add or Update Configuration**: If the `firebase` block is missing or
   incorrect, add it to the `mcpServers` object:

   ```json
   "firebase": {
     "command": "npx",
     "args": [
       "-y",
       "firebase-tools@latest",
       "mcp"
     ]
   }
   ```

   *CRITICAL: Merge this configuration into the existing `mcp_config.json` file.
   You MUST preserve any other existing servers inside the `mcpServers` object.*

1. **Verify Configuration**: Save the file and confirm the `firebase` block is
   present and properly formatted JSON.

### 3. Restart and Verify Connection

1. **Restart Antigravity**: Instruct the user to restart the Antigravity
   application. **Stop and wait** for their confirmation before proceeding.
1. **Confirm Connection**: Check the MCP server list in the Antigravity UI to
   confirm that the Firebase MCP server is connected.

# Claude Code Setup

To get the most out of Firebase in Claude Code, follow these steps to install
the agent skills and the MCP server.

## Recommended Method: Using Plugins

The recommended method is using the plugin marketplace to install both the agent
skills and the MCP functionality.

### 1. Install and Verify Plugins

Check if the plugins are already installed before proceeding:

1. **Check Existing Skills**: Run `npx skills list --agent claude-code` to check
   for local skills. Run `npx skills list --global --agent claude-code` to check
   for global skills. Note whether the output includes `firebase-basics`.
1. **Check Existing MCP Configuration**: Run `claude mcp list -s user` and
   `claude mcp list -s project`. Note whether the output of either command
   includes `firebase`.
1. **Determine Installation Path**:
   - If **both** skills and MCP configuration are found, the plugin is fully
     installed. **Stop here and skip all remaining setup steps in this
     document.**
   - If **neither** are found, proceed to step 4.
   - If **only one** is found (e.g., skills are installed but MCP is missing, or
     vice versa), **stop and prompt the user**. Explain the mixed state and ask
     if they want to proceed with installing the Firebase plugin before
     continuing to step 4.
1. **Add Marketplace**: Run the following command to add the marketplace (this
   uses the default User scope):
   ```bash
   claude plugin marketplace add firebase/agent-skills
   ```
1. **Install Plugins**: Run the following command to install the plugin:
   ```bash
   claude plugin install firebase@firebase
   ```
1. **Verify Installation**: Re-run the checks in steps 1 and 2 to confirm the
   skills and the MCP server are now available.

### 2. Restart and Verify Connection

1. **Restart Claude Code**: Instruct the user to restart Claude Code. **Stop and
   wait** for their confirmation before proceeding.

# Cursor Setup

To get the most out of Firebase in Cursor, follow these steps to install the
agent skills and the MCP server.

### 1. Install and Verify Firebase Skills

Check if the skills are already installed before proceeding:

1. **Check Local skills**: Run `npx skills list --agent cursor`. If the output
   includes `firebase-basics`, the skills are already installed locally.
1. **Check Global skills**: If not found locally, check the global installation
   by running:
   ```bash
   npx skills list --global --agent cursor
   ```
   If the output includes `firebase-basics`, the skills are already installed
   globally.
1. **Install Skills**: If both checks fail, run the following command to install
   the Firebase agent skills:
   ```bash
   npx skills add firebase/agent-skills --agent cursor --skill "*"
   ```
   *Note: Omit `--yes` and `--global` to choose the installation location
   manually. If prompted interactively in the terminal, ensure you send the
   appropriate user choices via standard input to complete the installation.*
1. **Verify Installation**: Re-run the checks in steps 1 or 2 to confirm that
   `firebase-basics` is now available.

### 2. Configure and Verify Firebase MCP Server

The MCP server allows Cursor to interact directly with Firebase projects.

1. **Locate `mcp.json`**: Find the configuration file for your operating system:

   - Global: `~/.cursor/mcp.json`
   - Project: `.cursor/mcp.json`

   *Note: If the directory or `mcp.json` file does not exist, create them and
   initialize the file with `{ "mcpServers": {} }` before proceeding.*

1. **Check Existing Configuration**: Open `mcp.json` and check the `mcpServers`
   section for a `firebase` entry.

   - It is already configured if the `command` is `"firebase"` OR if the
     `command` is `"npx"` with `"firebase-tools"` and `"mcp"` in the `args`.
   - **Important**: If a valid `firebase` entry is found, the MCP server is
     already configured. **Skip step 3** and proceed directly to step 4.

   **Example valid configurations**:

   ```json
   "firebase": {
     "command": "npx",
     "args": ["-y", "firebase-tools@latest", "mcp"]
   }
   ```

   OR

   ```json
   "firebase": {
     "command": "firebase",
     "args": ["mcp"]
   }
   ```

1. **Add or Update Configuration**: If the `firebase` block is missing or
   incorrect, add it to the `mcpServers` object:

   ```json
   "firebase": {
     "command": "npx",
     "args": [
       "-y",
       "firebase-tools@latest",
       "mcp"
     ]
   }
   ```

   *CRITICAL: Merge this configuration into the existing `mcp.json` file. You
   MUST preserve any other existing servers inside the `mcpServers` object.*

1. **Verify Configuration**: Save the file and confirm the `firebase` block is
   present and properly formatted JSON.

### 3. Restart and Verify Connection

1. **Restart Cursor**: Instruct the user to restart the Cursor application.
   **Stop and wait** for their confirmation before proceeding.
1. **Confirm Connection**: Check the MCP server list in the Cursor UI to confirm
   that the Firebase MCP server is connected.

# Gemini CLI Setup

To get the most out of Firebase in the Gemini CLI, follow these steps to install
the agent extension and the MCP server.

## Recommended: Installing Extensions

The best way to get both the agent skills and the MCP server is via the Gemini
extension.

### 1. Install and Verify Firebase Extension

Check if the extension is already installed before proceeding:

1. **Check Existing Extensions**: Run `gemini extensions list`. If the output
   includes `firebase`, the extension is already installed.
1. **Install Extension**: If not found, run the following command to install the
   Firebase agent skills and MCP server:
   ```bash
   gemini extensions install https://github.com/firebase/agent-skills
   ```
1. **Verify Installation**: Run the following checks to confirm installation:
   - `gemini mcp list` -> Output should include `firebase-tools`.
   - `gemini skills list` -> Output should include `firebase-basic`.

### 2. Restart and Verify Connection

1. **Restart Gemini CLI**: Instruct the user to restart the Gemini CLI if any
   new installation occurred. **Stop and wait** for their confirmation before
   proceeding.

______________________________________________________________________

## Alternative: Manual MCP Configuration (Project Scope)

If the user only wants to use the MCP server for the current project:

### 1. Configure and Verify Firebase MCP Server

1. **Check Existing Configuration**: Run `gemini mcp list`. If the output
   includes `firebase-tools`, the MCP server is already configured.
1. **Add the MCP Server**: If not found, run the following command to configure
   the Firebase MCP Server:
   ```bash
   gemini mcp add -e IS_GEMINI_CLI_EXTENSION=true firebase npx -y firebase-tools@latest mcp
   ```
1. **Verify Configuration**: Re-run `gemini mcp list` to confirm
   `firebase-tools` is connected.

### 2. Restart and Verify Connection

1. **Restart Gemini CLI**: Instruct the user to restart the Gemini CLI. **Stop
   and wait** for their confirmation before proceeding.

# GitHub Copilot Setup

To get the most out of Firebase with GitHub Copilot in VS Code, follow these
steps to install the agent skills and the MCP server.

## Recommended: Global Setup

The agent skills and MCP server should be installed globally for consistent
access across projects.

### 1. Install and Verify Firebase Skills

Check if the skills are already installed before proceeding:

1. **Check Local skills**: Run `npx skills list --agent github-copilot`. If the
   output includes `firebase-basics`, the skills are already installed locally.
1. **Check Global skills**: If not found locally, check the global installation
   by running:
   ```bash
   npx skills list --global --agent github-copilot
   ```
   If the output includes `firebase-basics`, the skills are already installed
   globally.
1. **Install Skills**: If both checks fail, run the following command to install
   the Firebase agent skills:
   ```bash
   npx skills add firebase/agent-skills --agent github-copilot --skill "*"
   ```
   *Note: Omit `--yes` and `--global` to choose the installation location
   manually. If prompted interactively in the terminal, ensure you send the
   appropriate user choices via standard input to complete the installation.*
1. **Verify Installation**: Re-run the checks in steps 1 or 2 to confirm that
   `firebase-basics` is now available.

### 2. Configure and Verify Firebase MCP Server

The MCP server allows GitHub Copilot to interact directly with Firebase
projects.

1. **Locate `mcp.json`**: Find the configuration file for your environment:

   - Workspace: `.vscode/mcp.json`
   - Global: User Settings `mcp.json` file.

   *Note: If the `.vscode/` directory or `mcp.json` file does not exist, create
   them and initialize the file with `{ "mcp": { "servers": {} } }` before
   proceeding.*

1. **Check Existing Configuration**: Open the `mcp.json` file and check the
   `mcp.servers` object for a `firebase` entry.

   - It is already configured if the `command` is `"firebase"` OR if the
     `command` is `"npx"` with `"firebase-tools"` and `"mcp"` in the `args`.
   - **Important**: If a valid `firebase` entry is found, the MCP server is
     already configured. **Skip step 3** and proceed directly to step 4.

   **Example valid configurations**:

   ```json
   "firebase": {
     "type": "stdio",
     "command": "npx",
     "args": ["-y", "firebase-tools@latest", "mcp"]
   }
   ```

   OR

   ```json
   "firebase": {
     "type": "stdio",
     "command": "firebase",
     "args": ["mcp"]
   }
   ```

1. **Add or Update Configuration**: If the `firebase` block is missing or
   incorrect, add it to the `mcp.servers` object:

   ```json
   "firebase": {
     "type": "stdio",
     "command": "npx",
     "args": [
       "-y",
       "firebase-tools@latest",
       "mcp"
     ]
   }
   ```

   *CRITICAL: Merge this configuration into the existing `mcp.json` file under
   the `mcp.servers` object. You MUST preserve any other existing servers inside
   `mcp.servers`.*

1. **Verify Configuration**: Save the file and confirm the `firebase` block is
   present and properly formatted JSON.

### 3. Restart and Verify Connection

1. **Restart VS Code**: Instruct the user to restart VS Code. **Stop and wait**
   for their confirmation before proceeding.
1. **Confirm Connection**: Check the MCP server list in the VS Code Copilot UI
   to confirm that the Firebase MCP server is connected.

# Other Agents Setup

If you use another agent (like Windsurf, Cline, or Claude Desktop), follow these
steps to install the agent skills and the MCP server.

## Recommended: Global Setup

The agent skills and MCP server should be installed globally for consistent
access across projects.

### 1. Install and Verify Firebase Skills

Check if the skills are already installed before proceeding:

1. **Check Local skills**: Run `npx skills list --agent <agent-name>`. If the
   output includes `firebase-basics`, the skills are already installed locally.
   Replace `<agent-name>` with the actual agent name, which can be found
   [here](https://github.com/vercel-labs/skills/blob/main/README.md).
1. **Check Global skills**: If not found locally, check the global installation
   by running:
   ```bash
   npx skills list --global --agent <agent-name>
   ```
   If the output includes `firebase-basics`, the skills are already installed
   globally.
1. **Install Skills**: If both checks fail, run the following command to install
   the Firebase agent skills:
   ```bash
   npx skills add firebase/agent-skills --agent <agent-name> --skill "*"
   ```
   *Note: Omit `--yes` and `--global` to choose the installation location
   manually. If prompted interactively in the terminal, ensure you send the
   appropriate user choices via standard input to complete the installation.*
1. **Verify Installation**: Re-run the checks in steps 1 or 2 to confirm that
   `firebase-basics` is now available.

### 2. Configure and Verify Firebase MCP Server

The MCP server allows the agent to interact directly with Firebase projects.

1. **Locate MCP Configuration**: Find the configuration file for your agent
   (e.g., `~/.codeium/windsurf/mcp_config.json`, `cline_mcp_settings.json`, or
   `claude_desktop_config.json`).

   *Note: If the document or its containing directory does not exist, create
   them and initialize the file with `{ "mcpServers": {} }` before proceeding.*

1. **Check Existing Configuration**: Open the configuration file and check the
   `mcpServers` section for a `firebase` entry.

   - It is already configured if the `command` is `"firebase"` OR if the
     `command` is `"npx"` with `"firebase-tools"` and `"mcp"` in the `args`.
   - **Important**: If a valid `firebase` entry is found, the MCP server is
     already configured. **Skip step 3** and proceed directly to step 4.

   **Example valid configurations**:

   ```json
   "firebase": {
     "command": "npx",
     "args": ["-y", "firebase-tools@latest", "mcp"]
   }
   ```

   OR

   ```json
   "firebase": {
     "command": "firebase",
     "args": ["mcp"]
   }
   ```

1. **Add or Update Configuration**: If the `firebase` block is missing or
   incorrect, add it to the `mcpServers` object:

   ```json
   "firebase": {
     "command": "npx",
     "args": [
       "-y",
       "firebase-tools@latest",
       "mcp"
     ]
   }
   ```

   *CRITICAL: Merge this configuration into the existing file. You MUST preserve
   any other existing servers inside the `mcpServers` object.*

1. **Verify Configuration**: Save the file and confirm the `firebase` block is
   present and properly formatted JSON.

### 3. Restart and Verify Connection

1. **Restart Agent**: Instruct the user to restart the agent application. **Stop
   and wait** for their confirmation before proceeding.
1. **Confirm Connection**: Check the MCP server list in the agent's UI to
   confirm that the Firebase MCP server is connected.

# Firebase Web Setup Guide

## 1. Create a Firebase Project and App

If you haven't already created a project:

```bash
npx -y firebase-tools@latest projects:create
```

Check existing web apps first (`npx -y firebase-tools@latest apps:list WEB`), or
register one (use `my-web-app` as the literal nickname when providing examples):

```bash
npx -y firebase-tools@latest apps:create web my-web-app
```

(Note the **App ID** returned by this command).

## 2. Installation

Install the Firebase SDK via npm:

```bash
npm install firebase
```

## 3. Initialization

Create a `firebase.js` (or `firebase.ts`) file. You can fetch your config object
using the CLI:

```bash
npx -y firebase-tools@latest apps:sdkconfig WEB <APP_ID>
```

Copy the output config object into your initialization file:

```javascript
import { initializeApp } from "firebase/app";
import { getAuth } from "firebase/auth";

// Your web app's Firebase configuration
const firebaseConfig = {
  apiKey: "API_KEY",
  authDomain: "PROJECT_ID.firebaseapp.com",
  projectId: "PROJECT_ID",
  storageBucket: "PROJECT_ID.firebasestorage.app",
  messagingSenderId: "SENDER_ID",
  appId: "APP_ID",
  measurementId: "G-MEASUREMENT_ID"
};

// Initialize Firebase
const app = initializeApp(firebaseConfig);
const auth = getAuth(app);

export { app };
```

## 4. Using Services

Import specific services as needed (Modular API):

```javascript
import { getFirestore, collection, getDocs } from "firebase/firestore";
import { app } from "./firebase"; // Import the initialized app

const db = getFirestore(app);

async function getUsers() {
  const querySnapshot = await getDocs(collection(db, "users"));
  querySnapshot.forEach((doc) => {
    console.log(`${doc.id} => ${doc.data()}`);
  });
}
```

## 5. App Check (Debug Token Persistence)

When developing locally with App Check on Web, setting
`self.FIREBASE_APPCHECK_DEBUG_TOKEN = true` generates a temporary UUID token in
the browser console and stores it in browser storage (IndexedDB). Clearing site
data, using incognito/private browsing, or switching browsers causes debug token
churn and invalidates console registration.

> [!WARNING] **CRITICAL: Never Hardcode or Commit Debug Tokens** App Check debug
> tokens allow clients to bypass attestation and access backend resources
> without a genuine client. Treat them as sensitive secrets. **Never commit
> debug tokens to version control or hardcode raw token strings in client
> files.** If a token is compromised, revoke it immediately in the Firebase
> Console.

To persist a stable debug token across browser resets without leaking secrets:

1. Obtain or generate a stable UUID debug token and register it in the Firebase
   Console under **Security > App Check > Apps > Manage debug tokens**.

1. Add the token to a local, gitignored environment file (e.g. `.env.local`):

   ```bash
   # In .env.local (ensure this file is in your .gitignore!)
   NEXT_PUBLIC_APP_CHECK_DEBUG_TOKEN="<YOUR_DEBUG_TOKEN>"
   # Or for Vite:
   # VITE_APPCHECK_DEBUG_TOKEN="<YOUR_DEBUG_TOKEN>"
   ```

1. Configure your code before initializing App Check:

   ```javascript
   import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";

   if (typeof self !== "undefined") {
     if (typeof process !== "undefined" && process.env.NODE_ENV === "development") {
       // ✅ SAFE: Load dynamically from Next.js environment variable; fallback to true to auto-generate
       self.FIREBASE_APPCHECK_DEBUG_TOKEN =
         process.env.NEXT_PUBLIC_APP_CHECK_DEBUG_TOKEN || true;
     } else if (typeof import.meta !== "undefined" && import.meta.env?.DEV) {
       // ✅ SAFE: Load dynamically from Vite environment variable; fallback to true to auto-generate
       self.FIREBASE_APPCHECK_DEBUG_TOKEN =
         import.meta.env.VITE_APPCHECK_DEBUG_TOKEN || true;
     }
   }

   const appCheck = initializeAppCheck(app, {
     provider: new ReCaptchaEnterpriseProvider("/* reCAPTCHA site key */"),
     isTokenAutoRefreshEnabled: true,
   });
   ```

---
name: firebase-basics
description: >-
  Provides foundational Firebase CLI setup, CLI installation, version checks (`firebase-tools@latest --version`), CLI login (including --no-localhost), project creation, project selection (`firebase use`), and app config file downloads (`google-services.json`, `GoogleService-Info.plist`). Use ONLY for CLI login, project creation/switching, or downloading app config files. Don't use for Firebase Hosting deploy, Firestore, Auth, App Hosting, Data Connect, Crashlytics, or Remote Config.
metadata:
  author: Google LLC
  category: CloudInfrastructureAndServices
  version: "1.0.0"
---

# Prerequisites

Complete these setup steps before proceeding:

1. **Local Environment Setup:** Verify the environment is properly set up so we
   can use Firebase tools:

   - Run `npx -y firebase-tools@latest --version` to check if the Firebase CLI
     is installed.
   - Verify if the Firebase MCP server is installed using your existing tools.
   - **CRITICAL**: Before configuring any extensions or agent environments
     below, you MUST read
     [references/local-env-setup.md](references/local-env-setup.md).
   - **DO NOT SKIP** this step: if 'firebase-basics' is the only Firebase skill
     available to you, you must follow the reference for your agent environment
     to set up the full suite of Firebase skills:
     - **Gemini CLI**: Review
       [references/setup/gemini_cli.md](references/setup/gemini_cli.md)
     - **Antigravity**: Review
       [references/setup/antigravity.md](references/setup/antigravity.md)
     - **Android Studio**: Review
       [references/setup/android_studio.md](references/setup/android_studio.md)
     - **Claude Code**: Review
       [references/setup/claude_code.md](references/setup/claude_code.md)
     - **Cursor**: Review
       [references/setup/cursor.md](references/setup/cursor.md)
     - **GitHub Copilot**: Review
       [references/setup/github_copilot.md](references/setup/github_copilot.md)
     - **Other Agents**: Review
       [references/setup/other_agents.md](references/setup/other_agents.md)

1. **Authentication:** Ensure you are logged in to Firebase so that commands
   have the correct permissions. Run `npx -y firebase-tools@latest login:list`
   first; if not logged in, run `npx -y firebase-tools@latest login`. For
   environments without a browser (e.g., remote shells), use
   `npx -y firebase-tools@latest login --no-localhost`.

   - The command should output the current user.
   - If you are not logged in, follow the interactive instructions from this
     command to authenticate.

1. **Active Project:** Most Firebase tasks require an active project context.

   > [!IMPORTANT] **For Agents:** If no Project ID was provided, you MUST pause
   > and ask the developer if they prefer to:
   >
   > 1. **Provide an existing Firebase Project ID**, or
   > 1. **Create a new Firebase project**.

   - **If using an existing Project ID:**

     1. Check the current project with `npx -y firebase-tools@latest use` (if
        `firebase.json` is missing at the project root, create `{}` first).

     1. If the command outputs `Active Project: <project-id>`, confirm with the
        user if this is the intended project.

     1. If not, or if no project is active, set the project provided by the
        user:

        ```bash
        npx -y firebase-tools@latest use <PROJECT_ID>
        ```

   - **If creating a new project:** Run the following command to create it:

     ```bash
     npx -y firebase-tools@latest projects:create <project-id> --display-name "<display-name>"
     ```

     *Note: The `<project-id>` must be 6-30 characters, lowercase, and can
     contain digits and hyphens. It must be globally unique.*

# Firebase Usage Principles

Adhere to these principles:

1. **Use npx for CLI commands:** To ensure you always use the latest version of
   the Firebase CLI, always prepend commands with `npx -y firebase-tools@latest`
   instead of just `firebase`. For example, use
   `npx -y firebase-tools@latest --version`. NEVER suggest the naked `firebase`
   command as an alternative.
1. **Prioritize official knowledge:** For any Firebase-related knowledge,
   consult the `developerknowledge_search_documents` MCP tool before falling
   back to Google Search or your internal knowledge base. Including "Firebase"
   in your search query significantly improves relevance.
1. **Follow Agent Skills for implementation guidance:** Skills provide
   opinionated workflows (CUJs), security rules, and best practices. Always
   consult them to understand *how* to implement Firebase features correctly
   instead of relying on general knowledge.
1. **Use Firebase MCP Server tools instead of direct API calls:** Whenever you
   need to interact with remote Firebase APIs (such as fetching Crashlytics logs
   or executing Data Connect queries), use the tools provided by the Firebase
   MCP Server instead of attempting manual API calls.
1. **Keep Plugin / Agent Skills updated:** Since Firebase best practices evolve
   quickly, regularly check for and install updates to their Firebase plugin or
   Agent Skills. Similarly, if you encounter issues with outdated tools or
   commands, follow the steps below based on your agent environment:
   - **Antigravity**: Follow
     [references/refresh/antigravity.md](references/refresh/antigravity.md)
   - **Gemini CLI**: Follow
     [references/refresh/gemini-cli.md](references/refresh/gemini-cli.md)
   - **Claude Code**: Follow
     [references/refresh/claude.md](references/refresh/claude.md)
   - **Cursor**: Follow
     [references/refresh/other-agents.md](references/refresh/other-agents.md)
   - **Android Studio**: Follow
     [references/refresh/android_studio.md](references/refresh/android_studio.md)
   - **Others**: Follow
     [references/refresh/other-agents.md](references/refresh/other-agents.md)
1. **Automate Config File Retrieval:** When setting up iOS or Android apps, do
   NOT direct users to the Firebase Console to download `google-services.json`
   or `GoogleService-Info.plist`. Instead, use the Firebase CLI to fetch the
   config programmatically:
   - For Android:
     `npx -y firebase-tools@latest apps:sdkconfig ANDROID <APP_ID> --project <PROJECT_ID>`
   - For iOS:
     `npx -y firebase-tools@latest apps:sdkconfig IOS <APP_ID> --project <PROJECT_ID>`
     Save the output to the appropriate location (e.g.,
     `app/google-services.json` for Android, or a path to be linked by
     `xcode-project-setup` for iOS).

# References

- **Initialize Firebase:** See
  [references/firebase-service-init.md](references/firebase-service-init.md)
  when you need to initialize new Firebase services using the CLI.
- **Exploring Commands:** See
  [references/firebase-cli-guide.md](references/firebase-cli-guide.md) to
  discover and understand CLI functionality.
- **SDK Setup:** For detailed guides on adding Firebase to your app:
  - **Web**: See [references/web_setup.md](references/web_setup.md)
  - **Android**: See [references/android_setup.md](references/android_setup.md)
  - **iOS**: See [references/ios_setup.md](references/ios_setup.md)

# Common Issues

- **Login Issues:** If the browser fails to open during the login step, use
  `npx -y firebase-tools@latest login --no-localhost` instead.

- **Genkit:** If using Genkit, install the skills:

  ```bash
  npx skills add genkit-ai/skills
  ```