USER GUIDE
Manuel Firescope
De l'installation à l'utilisation quotidienne, ce guide se lit dans l'ordre et vous permet de démarrer immédiatement. Toutes les images sont des captures d'écran réelles de l'application.
Installation
- Depuis Téléchargement, récupérez le fichier
.dmgpour Mac (Apple Silicon ou Intel, au choix). - Ouvrez le
.dmgtéléchargé, puisglissez l'icône Firescope dans le dossier « Applications ». - Lancez Firescope depuis le dossier Applications.
Windows
- Depuis Téléchargement, récupérez
Firescope-Setup.exeet exécutez-le. - Si un avertissement SmartScreen apparaît au premier lancement, cliquez sur« Informations complémentaires » → « Exécuter quand même ».

Configuration initiale (langue et thème)
Au premier lancement, un assistant de configuration en 4 étapes s'ouvre. Commencez par choisir la langue d'affichage (9 langues intégrées : japonais, anglais, 简体中文, 繁體中文, 한국어, Español, Português, Français et Deutsch). Le changement s'applique instantanément à l'écran, alors n'hésitez pas à essayer pour voir.

Ensuite, choisissez le thème visuel. Dix thèmes sont proposés, dont Light et Dark. Là aussi, un clic affiche l'aperçu immédiatement.

Se connecter à Firestore
Deux méthodes de connexion sont possibles. La plus simple est la connexion avec votre compte Google : aucun fichier de clé à préparer. Vous pouvez aussi, comme auparavant, utiliser une clé privée de compte de service (JSON).

Méthode 1 : se connecter avec un compte Google
Authentifiez Firescope avec le compte Google dont vous vous servez au quotidien, puis choisissez simplement dans la liste des projets Firebase auxquels vous avez accès. Aucun fichier de clé à télécharger ni à conserver.
- Dans la boîte de dialogue d'ajout de connexion, ouvrez l'onglet « Google » et cliquez sur « Se connecter avec Google » : l'écran de consentement s'ouvre dans votre navigateur.
- De retour dans l'application, les projets Firebase auxquels vous avez accès s'affichent sous forme de liste. Vous pouvez filtrer par recherche, puis tout sélectionner d'un coup avec « Sélectionner les N projets affichés ». Les projets déjà connectés ne sont pas sélectionnables (ils portent la mention « Connecté » afin d'éviter les doublons).
- Pour chaque projet retenu, indiquez le libellé d'environnement et l'option lecture seule. Le libellé d'environnement est déduit automatiquement de l'ID du projet : il vous suffit de corriger ceux qui ne conviennent pas.
- Validez avec « Ajouter N connexions ».
Méthode 2 : utiliser une clé privée de compte de service (JSON)
Cette méthode convient si vous souhaitez utiliser un compte de service dédié à la CI, ou vous connecter sans passer par un compte Google. Si vous n'avez pas encore de clé, l'écran vous guide pour en obtenir une en moins d'une minute.
- Cliquez sur « Ouvrir la page de configuration du compte de service » pour ouvrir la page correspondante de la console Firebase dans votre navigateur (chemin : Paramètres du projet → Comptes de service).
- Cliquez sur « Générer une nouvelle clé privée » pour télécharger le fichier JSON.
- Revenez dans Firescope, puis choisissez le JSON téléchargé via « Sélectionner un fichier JSON pour se connecter ». Vous pouvez aussisélectionner plusieurs fichiers JSON de projets différentspour vous connecter à tous en même temps.
- Choisissez l'environnement de connexion (Développement / Test / Staging / Production). Il apparaît dans la barre latérale sous forme de libellé coloré, etle niveau des garde-fous de sécurité en dépend directement.
Organiser les connexions (groupes, masquage)
À mesure que les connexions s'accumulent, il devient difficile de savoir quel projet correspond à quoi dans la barre latérale. Firescope ajoute automatiquement des en-têtes et met de l'ordre, sans aucune manipulation de tri de votre part.

Répartition automatique
Les connexions sont d'abord réparties selon les identifiants utilisés pour se connecter.
- Compte Google — une section par compte connecté. Même si vous jonglez entre plusieurs comptes, vous voyez d'un coup d'œil de quel compte provient chaque connexion
- Clé AdminSDK — une section par clé privée de compte de service
- Émulateur — les connexions à l'émulateur Firestore local
Au sein de chaque section, les connexions sont ensuite regroupées par partie commune du nom de connexion. Les termes d'environnement en suffixe comme dev / staging / production / test / env sont retirés avant la comparaison : OCEAN-dev, ocean-pro, OCEAN-staging et OCEAN-test se retrouvent donc sous un seul en-tête OCEAN (la casse n'est pas prise en compte).
Masquer les connexions inutilisées
Vous pouvez retirer une connexion de la liste sans la déconnecter. Les paramètres et les clés sont conservés tels quels : le retour en arrière est possible à tout moment.
- Faites un clic droit sur une connexion →« Masquer cette connexion ». Depuis l'en-tête d'un groupe, choisissez « Masquer ce groupe » ; à partir d'une sélection multiple (clic avec ⌘ / Shift), choisissez « Masquer les connexions sélectionnées ».
- Dès qu'un élément est masqué, une icône en forme d'œil (avec un badge de comptage) apparaît en haut de la barre latérale.
- Un clic sur cette icône affiche les connexions masquées en grisé. Un clic droit → « Réafficher » les rétablit. Le rétablissement est également possible par groupe ou par sélection multiple.
Consulter les données
Ouvrez une connexion dans la barre latérale et cliquez sur une collection : les documents s'affichent dans un tableau. Chaque en-tête de colonne porte un badge de type (string / int / time, etc.), ce qui permet de voir la structure des données en un coup d'œil.

- Cliquez sur une ligne pour afficher tous les champs du document dans le panneau de droite.
- Le tri, le nombre de résultats affichés et la recherche par groupe (collection group) se règlent depuis la barre d'outils.
- Le nombre de lectures est en permanence visible dans la barre d'état (utile pour estimer la facturation).
⌘P naviguer entre les collections par nom
⌘K rechercher un document par ID, tous documents confondus
⌘F rechercher dans le tableau (recherche interne)
⌘⇧F donner le focus à la recherche de collections de la barre latérale
Palette de commandes (⌘K)
⌘K ouvre une recherche transversale accessible depuis n'importe où. Elle permet de rechercher en une fois parmi les noms de collections, les connexions, les écrans, les documents « récemment consultés » et les favoris ; à partir de 6 caractères saisis, une recherche transversale par ID de document apparaît aussi parmi les suggestions.
- ↑↓ pour naviguer parmi les suggestions, Entrée pour valider : changez d'écran sans lâcher le clavier.
- Depuis là, vous pouvez aussi basculer le thème, activer/désactiver lemasquage des valeurs, ou ouvrir les réglages et la liste des raccourcis — bref, toutes les actions fréquentes.

Recherche dans le tableau (⌘F)
Avec un tableau ouvert, appuyez sur ⌘F (Ctrl+F sous Windows) pour lancer une recherche par sous-chaîne, insensible à la casse, sur toutes les cellules. Les correspondances sont surlignées en ambre, et chaque appui sur Entrée fait glisser le curseur vers la correspondance suivante avec un défilement fluide.
- La recherche porte sur toutes les colonnes visibles, y compris la colonne ID.
- Entrée pour la correspondance suivante, Maj+Entrée pour la précédente — la recherche reboucle une fois la fin atteinte.
- La cellule trouvée devient la cellule sélectionnée : vous pouvez enchaîner directement avec les flèches, ⌘C ou F2 pour modifier.
- Tant que tous les documents ne sont pas chargés, seule la plage déjà chargée est parcourue (un * s'affiche à côté du nombre de correspondances).
- La recherche de collections de la barre latérale passe à ⌘⇧F (sur les écrans sans tableau, ⌘F seul lui donne toujours le focus).

La puissance des requêtes
Les conditions de requête composées peuvent être enregistrées sous un nom en tant querequête sauvegardée, et rappelées à tout moment depuis une liste (conditions, tri et nombre de résultats sont restaurés ensemble).

En sélectionnant un champ numérique (int / double), la barre d'outils affiche instantanément la somme et la moyenne après application des filtres en cours.

« Graphique » dessine immédiatement, à partir des documents déjà chargés, un histogramme pour les champs numériques et la fréquence d'apparition (top 10) pour les champs texte/enum, sans lecture supplémentaire.

« Génération de code » permet de copier les conditions composées sous forme de code firebase-admin (Node.js), ou, si un index composite est nécessaire, sous forme de définition au formatfirestore.indexes.json.

Noms logiques (affichage traduit des champs)
Un nom de champ en anglais comme carryingOutCoffinMasterId peut être affiché sous unnom logique, par exemple en français. Lebascule « Noms logiques » de la barre d'outils permet à tout moment de passer du nom physique au nom logique, et inversement.
- Le dictionnaire se modifie depuis l'icône 📖 de la barre d'outils. Deux niveaux de portée sont disponibles : « commun à toute la connexion » et « propre à cette collection uniquement » (surcharge).
- « Traduction automatique » remplit d'un coup les champs vides à l'aide du dictionnaire intégré et d'une API de traduction gratuite.
- « Ouvrir Google Traduction » ouvre la page de traduction avec les noms de champs déjà mis en forme en anglais : il ne reste qu'à copier la traduction et revenir dans l'application pour l'appliquer en une fois.
- Un clic droit sur un en-tête de colonne → « Définir le nom logique… » permet de modifier immédiatement cette seule colonne.
- Le badge de type dans l'en-tête (string / int, etc.) peut être affiché ou masqué via le bascule « Afficher les types ».

Onglets et groupes
Un clic droit sur une collection → « Afficher dans un nouvel onglet » permet de multiplier les onglets, comme dans un navigateur. Les onglets peuvent être regroupés en groupes, à la façon de Chrome.

- Clic droit sur un onglet → « Ajouter à un nouveau groupe » pour créer un groupe. Vous pouvez lui donner un nom et une couleur.
- Cliquer sur la puce d'un groupe le replie ou le déplie.
- Double-cliquer sur un onglet permet de changer son nom et sa couleur de fond.
- Le glisser-déposer permet de réordonner les onglets et de les déplacer entre groupes.
- L'état des onglets est restauré après redémarrage (cette option peut être désactivée dans les réglages).
Vue scindée
Un clic droit sur une collection → « Afficher scindé à droite » permet d'aligner deux collections côte à côte. Pratique pour rapprocher des données maîtres et des transactions.

- Vous pouvez aussi scinder la vue en glissant une collection depuis la barre latérale vers le bord gauche ou droit de l'écran.
- Glisser la puce d'un volet permet d'échanger les côtés ou de l'extraire dans un nouvel onglet.
- L'état de la scission est conservé pour chaque onglet.
Suivi en temps réel
En cliquant sur « Surveiller » dans la barre d'outils, les changements de la collection affichée sont répercutés en direct dans la grille. Ce qu'écrit une autre application ou votre serveur apparaît directement, sans recharger la page.
- Une boîte de dialogue, avant le démarrage, permet de restreindre par condition (champ, valeur), tri et nombre de résultats.
- Le flux de changements à droite liste dans l'ordre chronologique les ajouts, mises à jour et suppressions, en indiquant même quels champs ont changé.
- Le suivi est en lecture seule. Les écritures effectuées pendant la surveillance passent normalement par le pipeline de sécurité.
- Cinq suivis au maximum peuvent tourner simultanément.
- Le suivi s'arrête automatiquement au bout d'une durée définie (modifiable dans les réglages), afin d'éviter une consommation excessive de lectures.

Modifier les données
Double-cliquez sur une cellule pour l'éditer sur place.Entrée valide, Échap annule. Les types (int, timestamp, etc.) sont préservés lors de l'écriture.

Toute écriture passe par le pipeline de sécurité :
- Confirmation — une boîte de dialogue apparaît selon le libellé d'environnement × le risque de l'opération. Les opérations destructrices en production exigentde saisir l'ID du projet.
- Sauvegarde automatique — les documents concernés sont mis en instantané avant l'exécution.
- Exécution — l'écriture est effectuée.
- Journal d'audit — enregistré qu'il y ait succès ou échec (consultable depuis « Journal d'audit » dans la barre inférieure).
Sauvegarde et restauration
Les instantanés pris juste avant une opération destructrice s'accumulent dans« Sauvegardes », dans la barre inférieure. En sélectionner un ouvre unaperçu de restaurationoù vous pouvez vérifier les différences (recréer / écraser / inchangé) avant de restaurer.

- ⌘Z (ou l'icône ↩︎ de la barre latérale) permet derestaurer immédiatement la dernière écriture.
- Au-delà du nombre maximal de générations, les instantanés les plus anciens sont supprimés. Épinglez 📌 ceux que vous souhaitez conserver.
Console
Dans « Console », dans la barre latérale, écrivez vos requêtes en JavaScript, dans le style firebase-admin. ⌘Entrée exécute la requête, dont le résultat s'affiche dans un tableau avec types annotés.

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() }));- Pour ceux qui préfèrent la souris, un constructeur visuel (récupérer / mettre à jour / créer / supprimer) est aussi disponible. Les conditions ainsi composées peuvent être converties en JS via « Reporter dans le code ».
- Le code contenant des écritures s'exécute dans l'ordresimulation (dry-run) → aperçu des écritures → application, ce qui évite toute modification imprévue des données.
- La vue de jointure (join) entre collections est également prise en charge.
Import/export CSV
Export
En cliquant sur « Export CSV » dans la barre d'outils d'une collection, le résultat de la requête actuellement affichée (filtres et tri inclus) peut être enregistré en CSV. L'en-tête porte une annotation de type, ce qui garantit que les types ne se perdent pas lors d'une réimportation ultérieure.
Import

- Dans la barre d'outils, « Importer » → sélectionnez un fichier CSV (le Shift_JIS est détecté automatiquement).
- Vérifiez le type de chaque colonne, ainsi que le mode (upsert / création seule / mise à jour seule).
- « Vérifier le nombre » affiche un aperçu des documents créés et écrasés.
- « Lancer l'import » → après une boîte de dialogue de confirmation, les données sont importées. Les documents écrasés sont sauvegardés automatiquement avant l'exécution.
Vérification de schéma (détection des écarts de schéma)
Un clic droit sur une collection →« Vérification de schéma… »lit l'ensemble de la collection et détecte automatiquementles champs aux types mélangés, les champs absents seulement sur certains documents, ainsi que les champs rares potentiellement liés à une faute de frappe(limite de 20 000 documents).
- Les champs manquants regroupés sur les mêmes documents sont réunis en une seule carte. « Tout ouvrir » coche toutes les lignes concernées, ce qui permet d'enchaîner directement sur une suppression groupée, par exemple.
- Cliquer sur l'ID d'un document concerné fait défiler automatiquement la grille jusqu'à la ligne correspondante, qui est mise en surbrillance.
- Les résultats persistent même après fermeture de l'assistant, ce qui permet d'aller-retour aussi souvent que nécessaire tout en vérifiant les documents.
- L'onglet Validation de schéma Zod permet de coller un schéma Zod (TypeScript) et de valider tous les documents avec.

Protéger les écritures avec un schéma
Dans l'onglet « Validation de schéma Zod » de Vérification de schéma, vous pouvez aussi configurer, au-delà de la simple validation, l'application au moment de l'écriture. Choisissez parmi trois niveaux — aucun / avertissement / blocage— et en mode blocage, les écritures qui violent le schéma sont rejetées dans le processus principal (impossible de contourner via l'interface). L'application ne concerne que les documents dont le chemin de collection correspond exactement.

Une fois un schéma Zod enregistré, le mode « Saisie via formulaire » devient disponible à la création d'un nouveau document. Le formulaire est généré automatiquement à partir des types du schéma : il suffit de remplir les champs obligatoires, sans écrire de JSON à la main (pour les collections sans schéma enregistré, un formulaire peut aussi être construit à partir des types déduits par la vérification de schéma).

Export du diagramme ER
Clic droit sur une connexion dans la barre latérale → "Exporter le diagramme ER…" : chaque collection est échantillonnée (jusqu’à 100 documents) pour générer automatiquement un diagramme ER. Outre les champs reference et les sous-collections, les références par ID en chaîne comme customerId sont déduites des noms de champs et dessinées en pointillés.
- Basculez instantanément "Afficher les champs", "Clés seulement", "Afficher les types" et "Inclure les noms logiques" — toutes les variantes sont pré-rendues.
- Zoom au pincement ou Ctrl+molette, déplacement par glisser, un clic pour ajuster le diagramme entier.
- Copiez le texte Mermaid ou enregistrez en .mmd / .svg — collez-le tel quel dans GitHub ou Notion.
- Les liens vers les parents comptant de nombreuses sous-collections sont omis du diagramme pour la lisibilité (ils restent dans le texte Mermaid).

Migration de données
« Mise à jour groupée » permet, en plus de définir des champs en masse, derenommer des champs et de convertir leur type. Avant l'exécution, vérifiez toujours l'aperçu en dry-run montrant le diff pour l'ensemble des documents.

Un clic droit sur une collection → « Supprimer la collection… » la supprimede façon récursive, sous-collections comprises. Le nombre affiché dans la boîte de dialogue de confirmation inclut les sous-collections, et les documents concernés sont automatiquement mis en instantané avant l'exécution.

« Génération de données de test » déduit la structure des champs à partir de la distribution des types (vérification de schéma) des documents existants, et crée en une fois le nombre indiqué de documents fictifs. Utile pour tester en développement ou sur émulateur.

Comparaison et copie entre environnements
Comparer avec un autre environnement
Un clic droit sur une collection →« Comparer avec un autre environnement… »permet de rapprocher la même collection entre deux environnements, par exemple développement et production. Les différences (ajouts / suppressions / modifications) sont listées par document et par champ.
- Vous pouvez exclure certains champs de la comparaison, comme updatedAt.
- Le contenu des différences peut être exporté en CSV.
Copier vers un autre environnement
« Copier vers un autre environnement… » permet de dupliquer une collection vers une autre connexion (environnement). Un aperçu du nombre de documents et des éventuels écrasements est affiché avant l'exécution, et l'écriture vers la production passe, comme d'habitude, par le garde-fou de confirmation strict.

Comparaison et différences
La comparaison entre environnements prend aussi en charge lasynchronisation des différences : sélectionnez les différences (contenu différent ou document présent d'un seul côté) et appliquez-les directement vers la destination. Le sens de la synchronisation est suggéré à partir des libellés d'environnement des connexions, et l'application passe, comme d'habitude, par le pipeline de sécurité (confirmation, sauvegarde automatique).
Le bouton « Comparer » du panneau de droite d'un document permet de comparer champ par champ le document ouvert avec un document quelconque (même dans une autre collection ou une autre connexion).

Dans « Historique des modifications » d'un document, les sauvegardes automatiques sont listées chronologiquement comme des versions : choisissez deux versions quelconques (y compris la version actuelle) pour comparer les différences.

Utilisateurs Authentication
Depuis « Authentication » dans la barre latérale, vous pouvez lister et gérer les utilisateurs Firebase Authentication.
- Liste des e-mails, noms affichés, fournisseurs, dates de création et dernières connexions. Le bascule « Noms logiques » permet aussi d'afficher les intitulés en français.
- Prend en charge la désactivation / réactivation et la suppression d'utilisateurs, ainsi que l'envoi d'e-mails de réinitialisation de mot de passe.
- Vous pouvez copier l'UID d'un utilisateur pour le rapprocher des documents correspondants côté Firestore.
- Les opérations destructrices (suppression, etc.) passent par le même pipeline de sécurité que Firestore (confirmation → journal d'audit).

Exploitation
Le suivi en temps réel peut recevoir des alertes conditionnelles. Enregistrez « en cas d'ajout », « en cas de suppression » ou « si un champ donné change » : une notification de bureau arrive dès qu'un changement correspondant se produit.

Cliquer sur le nombre de lectures dans le pied de page affiche, dans une fenêtre contextuelle, le nombre estimé de lectures pour la session en cours, le coût estimé et son évolution.

L'onglet « Partage et transfert » des réglages permet d'exporter/importer, dans un seul fichier JSON, certains réglages d'interface — noms logiques des champs, requêtes sauvegardées, favoris. Les clés privées de connexion, les informations de licence et les libellés d'environnement n'y figurent jamais, ce qui le rend adapté au partage en équipe ou à un changement de machine.

Activer « Masquer les valeurs » dans la barre d'outils affiche les données réelles sous forme de points (••••), en conservant les noms de champs, les types et la structure. Pratique pour le partage d'écran ou les captures d'écran (fonctionnalité d'affichage uniquement, les données réelles ne sont pas modifiées).

Serveur MCP (intégration avec les agents IA)
Firescope inclut un serveur MCP (Model Context Protocol) . En vous y connectant depuis un agent IA tel que Claude Code, vous pouvez, au fil de la conversation, lister les collections Firestore, récupérer des documents et exécuter des requêtes directement.
Démarrage (depuis la racine du dépôt) :
# Pour se connecter à un émulateur FIRESCOPE_MCP_PROJECT_ID=your-project \ FIRESCOPE_MCP_EMULATOR_HOST=127.0.0.1:8080 \ npm run mcp # Pour se connecter à un projet réel via un JSON de compte de service FIRESCOPE_MCP_SERVICE_ACCOUNT_PATH=/path/to/service-account.json \ npm run mcp
Exemple de configuration côté client MCP (.mcp.json) :
{
"mcpServers": {
"firescope": {
"command": "npm",
"args": ["run", "mcp"],
"cwd": "/path/to/firescope",
"env": {
"FIRESCOPE_MCP_SERVICE_ACCOUNT_PATH": "/path/to/service-account.json"
}
}
}
}- Trois outils sont proposés : liste des collections (
firestore_list_collections), récupération d'un document (firestore_get_document) et exécution d'une requête (firestore_query_collection, avec filtres/tri/limite). - La même logique interne que le constructeur de requêtes de l'interface graphique est réutilisée, si bien que la forme des résultats correspond à ce qui est affiché dans l'application.
Mises à jour
- Les mises à jour sont vérifiées automatiquement toutes les 6 heures et au démarrage(vérification manuelle possible depuis Réglages → À propos → « Vérifier les mises à jour »).
- Lorsqu'une mise à jour obligatoire est publiée, l'écran de mise à jour au démarrage se charge automatiquement du téléchargement → redémarrage → application, sans aucune action de votre part.
- Ce n'est qu'en cas d'échec (hors ligne, par exemple) qu'un téléchargement manuel depuis le navigateur est proposé.

Tarifs et licence
- Dès le premier lancement, vous bénéficiez de 14 jours d'essaiavec toutes les fonctionnalités. Aucune inscription ni information de paiement n'est nécessaire.
- Même après expiration, la consultation des données reste gratuite.
- L'achat se fait directement dans l'application : depuis ⚙ Réglages → Licenceen bas à droite, choisissez un plan (Pro / TEAM, mensuel / annuel) pour ouvrir la page de paiement sécurisée Stripe dans votre navigateur. Une fois le paiement effectué, l'application active automatiquement la licence.
- Pour changer de Mac, pensez à « Désactiver la licence » sur l'ancienne machine avant de l'activer sur la nouvelle.
Pour le détail des plans, consultez la page des tarifs.

Questions fréquentes
- Impossible de se connecter / message « Échec de l'authentification »
- Vérifiez que le JSON correspond bien à la clé de compte de service du projet visé. Si vous avez régénéré la clé, le plus sûr est de déconnecter l'ancienne connexion et de se reconnecter avec le nouveau JSON.
- Les données sont-elles envoyées quelque part ?
- Non. Firescope accède directement à Firestore depuis votre Mac. Ni les clés ni les données ne sont envoyées à un serveur externe.
- À quoi sert le « garde-fou production » ?
- C'est un mécanisme qui ajuste automatiquement le niveau de confirmation selon le libellé d'environnement de la connexion et le risque de l'opération. Par exemple, supprimer une collection en production ne peut s'exécuter que si l'ID du projet est saisi manuellement. Cette validation se fait au cœur de l'application (processus principal), et non via de simples avertissements d'interface — impossible donc de la contourner par inadvertance.
- Existe-t-il une version Windows ?
- Oui. Récupérez
Firescope-Setup.exedepuis lapage de téléchargement (en cas d'avertissement SmartScreen, cliquez sur « Informations complémentaires » → « Exécuter quand même »). - Peut-on ajouter d'autres langues ?
- Oui. Depuis Réglages → Langue, exportez un pack de langue (JSON), traduisez-le puis réimportez-le pour ajouter la langue de votre choix.



