Connect Firetool to Firestore

Add an account

Firetool connects only to Google, over HTTPS to *.googleapis.com (port 443), directly or through a proxy. Nothing connects until you choose a way in. You only do this once: Firetool remembers it and connects that way every time it starts.

1. Choose the + button at the top of the sidebar (Add a project or account), then Add account…. While you have no accounts, the start page shows the same choices, and the sidebar has an Add account button.
2. Pick one of the four cards: Continue with Google, Google Cloud CLI (gcloud), Service account key (JSON) or Firestore emulator.

The File menu has the same ways in: Sign in with Google…, Add service account… (Ctrl+Shift+A, ⌘ Shift A on a Mac) and Connect to emulator…. You can add several accounts. Each appears at the top level of the sidebar with its projects under it.

Continue with Google

Best for your own work: Firetool lists every Firebase project your Google account can open. You don't need the Google Cloud CLI.

1. Choose Continue with Google. Google's sign-in page opens in your browser.
2. Choose your account and allow access, then come back to Firetool.
3. Your account appears in the sidebar with its projects. Expand a project, then click a collection to open it in a tab.

The browser sends Google's answer back to a one-time address on your own computer (127.0.0.1) that only Firetool is listening on. A random check (PKCE) makes sure that answer is for this sign-in only. Firetool keeps the sign-in encrypted on this computer.

If the browser doesn't open, the Sign in with Google dialog shows Open Google's sign-in page and copy the link. Choose Cancel to stop.

Firetool uses one Google account at a time. To use another one, sign out first (see Sign out or remove), then sign in with the other account.

Google Cloud CLI (gcloud)

If you've already signed in with gcloud auth application-default login, Firetool can use that sign-in. It's used only after you agree:

• On first start, Firetool asks Use your Google sign-in? and shows the account. Choose Use this account, Other ways to connect… or Not now. After Not now it doesn't ask again.
• Later, open Add account…. The Google Cloud CLI (gcloud) card shows the sign-in found on this computer. Choose Use this sign-in.

Until you choose it, Firetool sends nothing to Google with that sign-in.

Service account key (JSON)

A key is for one project, without a Google sign-in.

1. In the Firebase console, open Project settings, then Service accounts, and choose Generate new private key.
2. In Firetool, choose Service account key (JSON) → Import service account JSON, or File → Add service account….
3. In Add a service account, drop the .json file on the box, click the box to choose it, or paste the key's text.
4. Choose Add account. The service account's email appears in the sidebar, with its project under it.

Give the service account the Cloud Datastore User role to read and write, or Cloud Datastore Viewer for read-only. You can add several keys, one per project. Firetool keeps a copy of each key in ~/.firetool/service-accounts, encrypted (see Where keys are kept). You can delete the downloaded file afterwards.

Firestore and Authentication emulators

1. Start the emulators with firebase emulators:start.
2. Choose File → Connect to emulator…, or the Firestore emulator card.
3. Fill in Address (for example 127.0.0.1:8080) and Project IDs (comma separated).
4. To manage test users too, fill in Auth emulator address (optional, for users), for example 127.0.0.1:9099.
5. Choose Connect. The sidebar shows Emulator followed by its address.

If Firetool starts with FIRESTORE_EMULATOR_HOST set, it adds that emulator by itself. It also picks up FIREBASE_AUTH_EMULATOR_HOST, and takes the project ID from GCLOUD_PROJECT (otherwise demo-project). An emulator added this way can't be removed in the app. The emulator doesn't use composite indexes, so every query works there without one.

Projects and named databases

Right-click a Google or emulator account:

• Add project… adds a project by its ID, for one your account can open that isn't listed. Find the ID in the Firebase console under Project settings.
• Refresh reloads the project list.

To hide a project, right-click it and choose Remove from sidebar…. Nothing changes in Firebase. To bring it back, choose Add project… and then Show again. A service account key always shows its one project.

If a project has more than one Firestore database, each one is listed under the project, the (default) database and named databases alike. Projects with only the (default) database show their collections straight away. Authentication appears under each project, and under emulator projects when you gave an Auth emulator address.

Office networks and proxies

Firetool follows your system's proxy settings, including automatic configuration (PAC) scripts, and the HTTPS_PROXY environment variable. If your network needs a proxy that your system doesn't already use:

1. Choose Settings → Network proxy….
2. Enter the Proxy address as host:port, or http://user:password@host:port if it needs a sign-in.
3. Choose Save. Firetool checks that it can reach Firestore and tells you the result.

Leave the address empty to follow the system settings again. Proxies that sign in with your Windows account (NTLM or Kerberos) aren't supported. Connections go through the proxy as an encrypted tunnel, so the proxy sees host names only. Local addresses such as the emulators never use a proxy.

Where sign-ins and keys are kept

Your Google sign-in and service account keys stay in ~/.firetool (on Windows %USERPROFILE%\.firetool). They're encrypted so that only your user account on this computer can read them:

On Linux without a keyring, the files aren't really protected. Tools → Diagnostics shows how your keys are stored, and says "NOT encrypted" with what to install when there's no keyring.

Sign out or remove an account

• Google account: choose File → Sign out of Google…, or right-click the account and choose Sign out…, then Sign out. Firetool stops using the account and closes its tabs. For a sign-in made with Continue with Google, Firetool's access is removed at Google too. Saved queries, schedules and the audit log are kept.
• gcloud sign-in: signing out only stops Firetool using it. Tick Also sign out of Google on this PC (gcloud) to revoke it for other tools as well.
• Service account: right-click it and choose Remove service account…. This deletes the key file from this computer.
• Emulator: right-click it and choose Remove emulator….

Troubleshooting

• "No projects found." The account can't list any projects. Right-click the account, choose Add project… and enter the project ID.
• "… can't open <project>" when adding a project. The account has no access to it. Ask the project's owner for a role, or use a service account key for that project.
• "Firestore isn't enabled in this project." Set up Firestore for the project in the Firebase console, then right-click the project and choose Refresh.
• "That isn't a service account key." Use the file from Generate new private key, not a google-services.json or other config file.
• "Your Google sign-in has expired or was revoked." Choose Continue with Google and sign in again.
• A query needs an index, or indexes don't load. Listing indexes needs the Cloud Datastore Index Viewer or Index Admin role (or Owner); creating them needs Index Admin.
• Nothing loads on an office network. Open Tools → Diagnostics. It shows the proxy in use and whether firestore.googleapis.com, oauth2.googleapis.com and identitytoolkit.googleapis.com are reachable. Then set Settings → Network proxy… if needed.
• Still stuck? Help → Report a problem… sends us a message, with the diagnostics if you choose.

Questions

Related

• Firestore desktop client: what Firetool does once you're connected.
• Install Firetool: Windows, macOS and Linux.
• Query Firestore: filters, sorting and totals.
• Roles and production safety: read-only and production projects.
• Security: where your data goes and how keys are protected.
• Download Firetool