Firescope User Guide

Installation

1. Get the Mac .dmg from the download page (Apple Silicon or Intel).
2. Open the downloaded .dmg and drag the Firescope icon into the Applications folder.
3. Launch Firescope from the Applications folder.

Windows

1. Get Firescope-Setup.exe from the download page and run it.
2. If SmartScreen warns you on first run, click "More info" → "Run anyway" to continue.

Initial setup (language and theme)

On first launch, a 4-step setup screen opens. Start by choosing the display language (9 languages built in: Japanese, English, Simplified Chinese, Traditional Chinese, Korean, Spanish, Portuguese, French, German). The change applies instantly as you click, so try each one if you're unsure.

Next, choose a visual theme — 10 options including Light and Dark. Clicking a theme previews it instantly.

Connecting to Firestore

Connecting requires a Firebase service account private key (JSON). If you don't have one yet, following the on-screen guide takes about a minute.

1. Click "Open service account settings page" to open the relevant page in the Firebase console in your browser (Project settings → Service accounts).
2. Click "Generate new private key" to download the JSON file.
3. Back in Firescope, choose the downloaded JSON from "Select JSON file to connect". You can also select JSON files for multiple projects at once to connect to them all simultaneously.
4. Choose the target environment (Development / Test / Staging / Production). It is shown as a colored label in the sidebar, and the strength of the safety guard is determined by this label.

Browsing data

Open a connection in the sidebar and click a collection to display its documents in a table. Each column header shows a type badge (string / int / time, etc.) so you can see the shape of the data at a glance.

• Click a row to show all of the document's fields in the right-hand panel.
• Sorting, page size, and collection group search can all be changed from the toolbar.
• The read count is always shown in the status bar, as a gauge of billing usage.

Logical names (translated field labels)

English field names like carryingOutCoffinMasterId can be displayed with logical names in Japanese or any other language. The "Logical names" toggle in the toolbar switches between physical and logical names at any time.

• Edit the dictionary from the 📖 icon in the toolbar. Scope is two-layered: "shared across the whole connection" and "this collection only (override)".
• "Auto-translate" fills in blanks in bulk using a built-in dictionary plus a free translation API.
• "Open Google Translate"opens a translation page with the field names already anglicized — copy the translated text back into the app to apply it all at once.
• Right-click a column header → "Set logical name…" to edit just that column right away.
• The type badge in the header (string / int, etc.) can be shown or hidden with the "Show types" toggle.

Tabs and groups

Right-click a collection → "Open in new tab" to add tabs like a browser. Tabs can be organized into groups, just like in Chrome.

• Right-click a tab → "Add to new group" to create a group. You can give it a name and color.
• Click a group chip to collapse or expand it.
• Double-click a tab to change its name and background color.
• Drag and drop to reorder tabs and move them in and out of groups.
• Tab state is restored after a restart (this can be turned off in settings).

Split view

Right-click a collection → "Split view to the right" to place two collections side by side. Handy for cross-checking master data against transactions.

• You can also split by dragging a collection from the sidebar to the left or right edge of the screen.
• Drag a pane's chip to swap the left and right panes or pull it out into a new tab.
• Split state is preserved per tab.

Real-time watch

Click "Watch" in the toolbar and changes to the currently displayed collection are reflected live in the grid. Writes from another app or server flow in without any reload.

• Before starting, a dialog lets you narrow things down by condition (field/value), sort order, and count.
• The change feedon the right lists "added / updated / deleted" events in chronological order, along with which fields changed.
• Watching is read-only. Any writes you make while watching still go through the normal safety pipeline.
• Up to 5 watches can run at the same time.
• Watches stop automatically after a set time (configurable in settings), to prevent excessive read usage.

Editing data

Double-click a cell to edit it in place. Press Enter to confirm or Esc to cancel. Types such as int and timestamp are preserved when written.

Every write goes through the safety pipeline:

1. Confirmation— a dialog appears whose strength depends on the environment label and the operation's risk level. Destructive operations in production require typing the project ID.
2. Automatic backup— affected documents are snapshotted before execution.
3. Execution— the write is performed.
4. Operation log— recorded regardless of success or failure (check it from "Operation log" in the bottom bar).

Backup and restore

Snapshots taken just before a destructive operation accumulate under "Backups" in the bottom bar. Selecting one opens a restore preview where you can check the diff (recreate / overwrite / unchanged) before restoring.

• Press ⌘Z (or the ↩︎ icon in the sidebar) to instantly restore the most recent write.
• Snapshots beyond the generation limit are removed oldest-first. Pin 📌 any you want to keep.

Console

The "Console" in the sidebar lets you write queries in firebase-admin-style JavaScript. Press ⌘Enter to run it, and the result is shown in a type-annotated table.

const snap = await db.collection('orders')
  .where('status', '==', 'paid')
  .orderBy('amount', 'desc')
  .limit(20)
  .get();
return snap.docs.map((d) => ({ id: d.id, ...d.data() }));

• For mouse-driven workflows there's also a visual builder (get / update / create / delete). Any conditions you build can be converted to JS with "Reflect in code".
• Code that includes writes runs as dry run → write preview → apply, so data never changes unexpectedly.
• Join views are also supported.

CSV import/export

Export

Click "Export CSV" in the collection toolbar to save the current query result (with filters and sorting applied) as CSV. Headers include type annotations, so re-importing later preserves types correctly.

Import

1. Click "Import" in the toolbar and select a CSV file (Shift_JIS is auto-detected).
2. Review each column's type and the mode (upsert / new only / update only).
3. Click "Check counts" to preview how many rows will be new vs. overwritten.
4. Click "Run import" → confirm in the dialog to import. Overwritten rows are automatically backed up before the import runs.

Schema check (detecting schema drift)

Right-click a collection → "Schema check…" to scan the whole collection and automatically detect fields with mixed types, fields missing from only some documents, and rare fields that may be typos (up to 20,000 documents).

• Fields missing together across the same set of documents are grouped into a single card. "Open all" checks every matching row, ready for a bulk action like deletion.
• Clicking a matching document's ID auto-scrolls the grid to that row and highlights it.
• Results persist even after closing the wizard, so you can go back and forth while reviewing documents as many times as needed.
• The Zod schema validation tab lets you paste a Zod schema (TypeScript) to validate every document against it.

Comparing and copying environments

Compare with another environment

Right-click a collection → "Compare with another environment…" to match up the same-named collection across two environments (e.g. development vs. production). Differences (added / removed / changed) are listed per document and per field.

• You can exclude fields such as updatedAt from the comparison.
• The diff results can be exported as CSV.

Copy to another environment

"Copy to another environment…" duplicates a collection into another connection (environment). It previews the count and whether anything will be overwritten before running, and writes to production still go through the usual strict confirmation guard.

Authentication users

"Authentication" in the sidebar lists and manages Firebase Authentication users.

• Lists email, display name, provider, creation date, and last sign-in. The logical names toggle can show Japanese labels for these fields too.
• Supports disabling / enabling / deleting users and sending password reset emails.
• Copy a user's UID to cross-reference it with documents on the Firestore side.
• Destructive operations (such as deletion) go through the same safety pipeline as Firestore (confirmation → operation log).

Updates

• Updates are checked automatically every 6 hours and at startup (you can also check manually via Settings → About → "Check for updates").
• If a required update is published, the startup update screen handles download → restart → applyautomatically — no button presses needed.
• A manual browser download is only suggested if this fails (e.g. while offline).

Pricing and licensing

• All features are available for a 14-day trial from first launch. No sign-up or payment info required.
• After the trial ends, you can still view data for free indefinitely.
• Purchase from within the app: go to ⚙ Settings → License in the bottom right, choose a plan (Pro / TEAM, monthly / annual), and a Stripe checkout page opens in your browser. Once payment completes, the app activates the license automatically.
• Moving to another Mac? "Deactivate license" on the old machine first, then activate on the new one.

See the pricing page for plan details.

FAQ

I can't connect / it says "Authentication failed"

Check that the JSON is a service account key for the target project. If you regenerated the key, disconnect the old connection and reconnect with the new JSON.

Is any data sent anywhere?

No. Firescope accesses Firestore directly from your Mac. Neither keys nor data are sent to any external server.

What does the "production guard" actually do?

It automatically adjusts confirmation strength based on the connection's environment label and the operation's risk level. For example, deleting a collection in production can't be run without manually typing the project ID. Because this is enforced in the app's core (the main process) rather than as a UI warning, it can't be bypassed by accident.

Is there a Windows version?

Yes. Get Firescope-Setup.exe from the download page(if SmartScreen warns you, click "More info" → "Run anyway").

Can I add another language?

Yes. From Settings → Language, export a language pack (JSON), translate it, and import it back to add any language you like.