Manual do Firescope

Instalação

1. Na página de download, baixe o.dmg da versão Mac (você pode escolher entre Apple Silicon e Intel).
2. Abra o .dmg baixado earraste o ícone do Firescope para a pasta "Aplicativos".
3. Abra o Firescope a partir da pasta Aplicativos.

Windows

1. Na página de download, baixe e execute oFirescope-Setup.exe.
2. Se aparecer o aviso do SmartScreen na primeira execução, clique em"Mais informações" → "Executar assim mesmo" para continuar.

Configuração inicial (idioma e tema)

Na primeira execução, uma tela de configuração em 4 etapas é aberta. Primeiro, escolha o idioma de exibição (com Japonês, English, 简体中文, 繁體中文, 한국어, Español, Português, Français e Deutsch — 9 idiomas embutidos). A mudança é aplicada assim que você clica, então experimente à vontade se estiver na dúvida.

Em seguida, escolha o tema visual. Há 10 opções, incluindo Light / Dark. Aqui também a prévia é exibida na hora, ao clicar.

Conectar ao Firestore

Há duas formas de conectar. A mais simples éentrar com a sua conta Google, que dispensa qualquer arquivo de chave. Você também pode continuar usando achave privada da conta de serviço (JSON), como sempre.

Forma 1: entrar com a conta Google

Autentique o Firescope com a conta Google que você já usa no dia a dia ebasta escolher na lista os projetos do Firebase aos quais você tem acesso. Não é preciso baixar nem guardar arquivos de chave.

1. Na aba "Google"do diálogo de adicionar conexão, clique em "Entrar com o Google": a tela de consentimento abre no navegador.
2. Ao voltar para o aplicativo, os projetos do Firebase aos quais você tem acesso aparecem em uma lista. Você pode filtrar pela busca e usar"Selecionar todos os N exibidos"para escolher vários de uma vez.Projetos já conectados não podem ser selecionados(aparecem como "Conectado", para evitar cadastros duplicados).
3. Para cada projeto escolhido, defina o rótulo de ambiente e se ele serásomente leitura. O rótulo de ambiente é deduzido automaticamente a partir do ID do projeto, então basta corrigir os que estiverem diferentes.
4. Confirme em "Adicionar N conexões".

Forma 2: usar a chave privada da conta de serviço (JSON)

Esta é a opção para quem quer usar uma conta de serviço de CI ou conectar sem uma conta Google. Se você ainda não tem a chave, basta seguir as instruções na tela para obtê-la em cerca de um minuto.

1. Ao clicar em "Abrir página de configuração da conta de serviço", a página correspondente do Console do Firebase é aberta no navegador (local: Configurações do projeto → Contas de serviço).
2. Clique em "Gerar nova chave privada" para baixar o JSON.
3. Volte ao Firescope e, em "Selecionar arquivo JSON e conectar", escolha o JSON baixado. Também é possívelselecionar os JSONs de vários projetos ao mesmo tempopara conectá-los todos de uma vez.
4. Escolha o ambiente da conexão (desenvolvimento / teste / staging / produção). Ele é exibido na barra lateral como um rótulo colorido, e a intensidade daproteção de segurança também é definida por esse rótulo.

Organizar as conexões (grupos e ocultação)

Quando as conexões se acumulam, fica difícil saber qual item da barra lateral corresponde a qual projeto. O Firescopeorganiza tudo automaticamente com títulos de grupo, sem que você precise reordenar nada.

Separação automática

As conexões são separadas primeiro pela credencial usada para conectar.

• Conta Google — separadas por conta autenticada. Mesmo que você use várias contas, dá para ver num relance de qual delas vem cada conexão
• Chave do AdminSDK — por chave privada de conta de serviço
• Emulador — conexões com o emulador local do Firestore

Dentro de cada separação, as conexões ainda se agrupam pelaparte comum do nome. Palavras de ambiente no final, como dev / staging / production / test / env, são removidas antes da comparação, então OCEAN-dev, ocean-pro, OCEAN-staging e OCEAN-test ficam sob um único título: OCEAN (maiúsculas e minúsculas não fazem diferença).

Ocultar conexões que você não usa

É possível esconder uma conexão da lista sem desconectá-la. As configurações e as chaves permanecem intactas, então dá para reverter a qualquer momento.

1. Clique com o botão direito na conexão →"Ocultar esta conexão". Pelo título do grupo, escolha "Ocultar este grupo"; com uma seleção múltipla (⌘ / Shift+ clique), escolha "Ocultar as conexões selecionadas".
2. Quando houver itens ocultos, um ícone de olho (com um selo de contagem) aparece no topo da barra lateral.
3. Ao clicar nesse ícone, as conexões ocultas são exibidas em tom mais claro. Clique com o botão direito → "Exibir novamente" para restaurá-las. Também dá para restaurar por grupo ou por seleção múltipla, de uma só vez.

Ver os dados

Abra uma conexão na barra lateral e clique em uma coleção para ver os documentos em uma tabela. Cada cabeçalho de coluna traz um selo de tipo (string / int / time etc.), então o formato dos dados fica claro à primeira vista.

• Ao clicar em uma linha, todos os campos do documento aparecem no painel à direita.
• Ordenação, quantidade de itens exibidos e busca em grupo (collection group) podem ser alteradas na barra de ferramentas.
• A contagem de leituras é sempre exibida na barra de status (uma referência para o consumo de cota).

Nomes lógicos (exibição traduzida dos campos)

Nomes de campo em inglês, como carryingOutCoffinMasterId, podem ser exibidos com um nome lógico em português (ou outro idioma). Oalternador "Nomes lógicos" na barra de ferramentas alterna a qualquer momento entre nome físico e nome lógico.

• O dicionário é editado pelo ícone 📖 na barra de ferramentas. Há dois níveis de aplicação: "comum para toda a conexão" e "apenas esta coleção (sobrescreve)".
• "Tradução automática" preenche os campos vazios de uma vez, usando o dicionário embutido e uma API de tradução gratuita.
• Ao clicar em "Abrir no Google Tradutor", a página de tradução é aberta com os nomes de campo já em inglês; basta copiar a tradução e voltar ao app para aplicá-la de uma só vez.
• Clique com o botão direito no cabeçalho de uma coluna → "Definir nome lógico…" para editar rapidamente apenas aquela coluna.
• O selo de tipo do cabeçalho (string / int etc.) pode ser mostrado ou ocultado pelo alternador "Exibir tipos".

Abas e grupos

Clique com o botão direito em uma coleção → "Abrir em nova aba" para adicionar abas, como em um navegador. As abas podem ser reunidas em grupos, no estilo do Chrome.

• Clique com o botão direito em uma aba → "Adicionar a novo grupo" para criar um grupo. É possível definir nome e cor.
• Clicar no chip do grupo recolhe ou expande as abas.
• Um duplo clique na aba permite alterar o nome e a cor de fundo.
• Arraste e solte para reordenar e mover abas entre grupos.
• O estado das abas é restaurado após reiniciar o app (é possível desativar isso nas configurações).

Visualização dividida

Clique com o botão direito em uma coleção → "Exibir dividido à direita" para colocar duas coleções lado a lado. É útil para conciliar dados mestres com transações.

• Também é possível dividir arrastando uma coleção da barra lateral até a borda esquerda ou direita da tela.
• Arrastar o chip de um painel permite trocar os lados ou extrair o painel para uma nova aba.
• O estado da divisão é mantido por aba.

Monitoramento em tempo real

Ao clicar em "Monitorar" na barra de ferramentas, as alterações da coleção exibida são refletidas ao vivo na grade. Alterações feitas por outro app ou pelo servidor entram diretamente, sem precisar recarregar.

• Na caixa de diálogo antes de iniciar, é possível restringir por condições (campo e valor), ordenação e limite de itens.
• O feed de alterações, à direita, lista "inclusão / atualização / exclusão" em ordem cronológica, mostrando também quais campos mudaram.
• O monitoramento é somente leitura. Operações de gravação feitas durante o monitoramento continuam passando normalmente pelo pipeline de segurança.
• É possível monitorar até 5 itens ao mesmo tempo.
• Após o tempo definido, o monitoramento para automaticamente (o tempo pode ser alterado nas configurações), evitando consumo excessivo de leituras.

Editar dados

Clique duas vezes em uma célula para editá-la diretamente.Enter confirma, Esc cancela. Tipos como int e timestamp são preservados na gravação.

Toda gravação passa pelo pipeline de segurança:

1. Confirmação — uma caixa de diálogo aparece de acordo com o rótulo de ambiente × o risco da operação. Operações destrutivas em produção exigemdigitar o ID do projeto.
2. Backup automático — os documentos afetados são capturados antes da execução.
3. Execução — a gravação é realizada.
4. Registro de operações— é registrada independentemente de sucesso ou falha (consulte em "Registro de operações", na barra inferior).

Backup e restauração

Os snapshots capturados pouco antes de operações destrutivas ficam acumulados em"Backups", na barra inferior. Ao selecionar um, aprévia de restauraçãoé aberta, permitindo conferir as diferenças de recriação / sobrescrita / sem alteração antes de restaurar.

• ⌘Z (ou o ícone ↩︎ na barra lateral) permiterestaurar instantaneamente a última gravação.
• Snapshots mais antigos são descartados ao ultrapassar o limite de gerações. Fixe com 📌 os que quiser manter.

Console

Em "Console", na barra lateral, você pode escrever consultas em JavaScript no estilo firebase-admin. Execute com ⌘Enter e o resultado aparece em uma tabela com tipos anotados.

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() }));

• Para quem prefere o mouse, há também um construtor visual(get / update / create / delete). As condições montadas podem ser convertidas em JS com "Refletir no código".
• Código que contém gravações é executado na ordemdry-run → prévia de gravação → aplicação, então os dados nunca mudam de forma repentina.
• Também há suporte para visualização com join (junção).

Importação/exportação de CSV

Exportação

Ao clicar em "Exportar CSV"na barra de ferramentas da coleção, o resultado da consulta atualmente exibido (já com filtros e ordenação aplicados) é salvo em CSV. Como o cabeçalho traz aanotação de tipo, os tipos não se perdem mesmo em uma reimportação posterior.

Importação

1. Em "Importar", na barra de ferramentas, selecione o arquivo CSV (Shift_JIS também é detectado automaticamente).
2. Confira o tipo de cada coluna e o modo (upsert / somente novos / somente atualização).
3. Em "Verificar contagem", veja a prévia de quantos itens serão criados ou sobrescritos.
4. Em "Executar importação" → após a caixa de confirmação, os dados são importados. Os itens sobrescritos recebem backup automático antes da execução.

Verificação de esquema (detecção de inconsistências)

Clique com o botão direito em uma coleção →"Verificação de esquema…"para ler a coleção inteira e detectar automaticamentecampos com tipos misturados, campos ausentes apenas em alguns documentos e campos raros que podem indicar um erro de digitação(limite de 20.000 itens).

• Campos ausentes em conjunto, no mesmo grupo de documentos, são reunidos em um único cartão. "Abrir todos" marca todas as linhas correspondentes de uma vez, permitindo seguir direto para uma exclusão em massa, por exemplo.
• Ao clicar no ID de um documento correspondente, a grade rola automaticamente até a linha e a destaca.
• Os resultados são mantidos mesmo depois de fechar o assistente, então você pode ir e voltar quantas vezes quiser enquanto confere os documentos.
• Na aba "Validação com esquema Zod", é possível colar um esquema Zod (TypeScript) para validar todos os documentos.

Comparar e copiar entre ambientes

Comparar com outro ambiente

Clique com o botão direito em uma coleção →"Comparar com outro ambiente…"para confrontar coleções de mesmo nome em dois ambientes, como desenvolvimento e produção. As diferenças (inclusão / exclusão / alteração) são listadas por documento e por campo.

• É possível especificar campos a excluir da comparação, como updatedAt.
• O conteúdo da comparação pode ser exportado como CSV.

Copiar para outro ambiente

Em "Copiar para outro ambiente…", você pode duplicar uma coleção para outra conexão (ambiente). A quantidade de itens e a existência de sobrescritas são exibidas em prévia antes da execução, e a gravação em produção passa normalmente pela proteção de confirmação rigorosa.

Usuários do Authentication

Em "Authentication", na barra lateral, você pode listar e gerenciar os usuários do Firebase Authentication.

• Lista de e-mail, nome de exibição, provedor, data de criação e último login. O alternador de nomes lógicos também permite exibir os campos em português.
• Suporte para desativar / ativar e excluir usuários, além do envio de e-mail de redefinição de senha.
• O UID do usuário pode ser copiado para conferência cruzada com os documentos do Firestore.
• Operações destrutivas (como exclusão) passam pelo mesmo pipeline de segurança do Firestore (confirmação → registro de operações).

Log compartilhado (quem / quando / o quê)

Registra metadados das operações de escrita no Firestore do projeto, para que todos que se conectam ao mesmo projeto vejam quem fez o quê e quando.

• Ative por conexão: clique com o botão direito na conexão → "Gravar log compartilhado". O diálogo de confirmação explica tudo e permite definir seu nome de operador na hora.
• Apenas metadados são registrados (nome do operador, tipo de operação, caminho, resultado, duração). Os valores dos documentos nunca são incluídos e nada é enviado a servidores externos — os eventos ficam na coleção _firescope_audit do projeto.
• Veja em Log de operações → aba "Log compartilhado": linha do tempo agrupada por data com filtros de operador/tipo/período. Clique em uma linha para ver detalhes e abrir o documento na grade.
• Os logs são excluídos automaticamente após 30 dias.

Atualizações

• A verificação de atualizações é automática a cada 6 horas e ao iniciar (também é possível verificar manualmente em Configurações → Sobre → "Verificar atualizações").
• Quando uma atualização obrigatória é publicada, a tela de atualização exibida na inicialização executa automaticamente download → reinício → aplicação, sem necessidade de clicar em nada.
• Somente em caso de falha (por exemplo, sem conexão) o download manual pelo navegador é indicado.

Preços e licença

• Durante os 14 dias após a primeira execução, todos os recursos ficam disponíveis em modo de teste. Não é preciso se cadastrar nem informar dados de pagamento.
• Mesmo após o vencimento, a visualização dos dados continua gratuita.
• A compra é feita dentro do app: em ⚙ Configurações → Licença, no canto inferior direito, escolha o plano (Pro / TEAM, mensal / anual) e a página de pagamento do Stripe abrirá no navegador. Assim que o pagamento é concluído, o app ativa a licença automaticamente.
• Ao migrar para outro Mac, use "Desativar licença" na máquina antiga antes de ativar na nova.

Confira os detalhes dos planos na página de preços.

Perguntas frequentes

Não consigo conectar / aparece "Falha na autenticação"

Confirme se o JSON é a chave da conta de serviço do projeto correto. Se você gerou uma nova chave, o mais seguro é desconectar a conexão antiga e conectar novamente com o novo JSON.

Os dados são enviados para algum lugar?

Não. O Firescope acessa o Firestore diretamente a partir do seu Mac. Nem a chave nem os dados são enviados para nenhum servidor externo.

O que a "proteção de produção" faz exatamente?

É um mecanismo que ajusta automaticamente a intensidade da confirmação de acordo com o rótulo de ambiente da conexão e o risco da operação. Por exemplo, excluir uma coleção em produção só é possível digitando manualmente o ID do projeto. Como a verificação ocorre no núcleo do app (processo principal), e não em um simples aviso na interface, não é algo que se ultrapasse por descuido.

Existe versão para Windows?

Sim. Baixe o Firescope-Setup.exe napágina de download(se aparecer o aviso do SmartScreen, continue com "Mais informações" → "Executar assim mesmo").

É possível adicionar outros idiomas?

Sim. Em Configurações → Idioma, exporte o pacote de idioma (JSON), traduza-o e importe-o de volta para adicionar qualquer idioma.

Paleta de comandos (⌘K)

É uma busca global que pode ser aberta de qualquer lugar com ⌘K. Você pode buscar de uma vez nomes de coleções, conexões, telas, itens "vistos recentemente" e favoritos, e ao digitar uma string com 6 ou mais caracteres também aparecem sugestões de busca por ID de documento.

• Use ↑↓ para navegar pelas sugestões e Enter para executar. Você troca de tela sem tirar as mãos do teclado.
• Também é possível chamar daqui operações frequentes, como alternar o tema, ativar/desativar o mascaramento de valores e abrir as configurações ou a lista de atalhos.

Busca na tabela (⌘F)

Com uma tabela aberta, pressione ⌘F (Ctrl+F no Windows) para fazer uma busca por substring em todas as células, sem diferenciar maiúsculas de minúsculas. Os resultados são destacados em âmbar, e a cada Enter o cursor desliza até o próximo resultado com uma rolagem suave.

• A busca cobre todas as colunas visíveis, incluindo a coluna de ID.
• Enter vai para o próximo resultado e Shift+Enter para o anterior — ao chegar ao fim, a busca recomeça do início.
• A célula encontrada passa a ser a célula selecionada, então dá para continuar com as setas, ⌘C ou F2 para editar.
• Enquanto nem todos os documentos foram carregados, apenas o intervalo já carregado é pesquisado (um * aparece ao lado do número de resultados).
• A busca de coleções na barra lateral passou para ⌘⇧F (em telas sem tabela, ⌘F sozinho continua focando essa busca).

Recursos avançados de consulta

As condições de consulta montadas podem ser salvas com um nome como consulta salva e chamadas a qualquer momento na lista (restaurando de uma vez condições, ordenação e limite de itens).

Ao selecionar um campo numérico (int / double), a soma e a média após os filtros atuais são exibidas na barra de ferramentas.

Em "Gráfico", a partir dos documentos já carregados, campos numéricos são exibidos como histograma e campos de texto/enum como frequência de ocorrência (top 10) — tudo desenhado na hora, sem leituras adicionais.

Em "Gerar código", você pode copiar as condições montadas como código do firebase-admin (Node.js) ou, quando a condição exigir um índice composto, como uma definição no formato firestore.indexes.json.

Proteger gravações com esquema

Na aba "Validação com esquema Zod" da Verificação de esquema, além da validação, também é possível configurar a aplicação no momento da gravação. Escolha entre três níveis — nenhum / aviso / bloqueio— e, com "bloqueio", gravações que violam o esquema são recusadas no processo principal (mesmo contornando a interface, isso é impedido). A aplicação vale apenas para documentos cujo caminho da coleção corresponde exatamente.

Com um esquema Zod registrado, o modo "Preenchimento por formulário" fica disponível ao criar um novo documento. O formulário é gerado automaticamente a partir dos tipos do esquema, permitindo criar o documento apenas preenchendo os campos obrigatórios, sem escrever JSON manualmente (em coleções sem esquema registrado, o formulário também pode ser montado a partir da inferência de tipos da verificação de esquema).

Exportar diagrama ER

Clique com o botão direito em uma conexão na barra lateral → "Exportar diagrama ER…": cada coleção é amostrada (até 100 documentos) para gerar um diagrama ER automaticamente. Além de campos reference e subcoleções, referências por ID em texto como customerId são inferidas pelo nome do campo e desenhadas como relações tracejadas.

• Alterne na hora "Mostrar campos", "Somente chaves", "Mostrar tipos" e "Incluir nomes lógicos" — todas as variantes são pré-renderizadas.
• Zoom com pinça ou Ctrl+roda, arraste para mover e um clique ajusta o diagrama inteiro.
• Copie o texto Mermaid ou salve como .mmd / .svg — cole direto no GitHub ou Notion.
• Linhas para pais com muitas subcoleções são omitidas do diagrama para melhor leitura (permanecem no texto Mermaid).

Migração de dados

Em "Atualização em massa", além de definir campos em lote, também é possível renomear campos e converter tipos. Antes de executar, sempre confira o diff de todos os itens na prévia em modo dry-run.

Clique com o botão direito em uma coleção → "Excluir coleção…" exclui de forma recursiva, incluindo as subcoleções. A contagem exibida na caixa de confirmação já inclui as subcoleções, e os documentos alvo recebem snapshot automático antes da execução.

"Gerar dados de exemplo (seed)" estima a estrutura de campos a partir da distribuição de tipos dos documentos existentes (verificação de esquema) e cria de uma vez a quantidade indicada de documentos fictícios. É um recurso para testes em desenvolvimento e no emulador.

Comparação e diferenças

A comparação entre ambientes também suporta a sincronização de diferenças, que permite selecionar as diferenças (documentos com conteúdo divergente ou presentes em apenas um lado) e aplicá-las diretamente ao destino. A direção da sincronização é sugerida com base nos rótulos de ambiente das conexões, e a aplicação passa normalmente pelo pipeline de segurança (confirmação e backup automático).

O botão "Comparar" no painel direito do documento permite comparar campo a campo o documento aberto com qualquer outro documento (inclusive de outra coleção ou outra conexão).

No "Histórico de alterações" do documento, os backups automáticos são listados cronologicamente como versões, e você pode escolher quaisquer duas versões (incluindo a atual) para comparar as diferenças.

Buscar e compartilhar

A "Busca de valor" procura um valor — mesmo sem saber em qual campo ele está — em todos os documentos e campos da coleção. Antes de executar, uma estimativa da quantidade de leituras é exibida, então você pode usá-la com tranquilidade mesmo em coleções grandes.

Marcar um documento com ★ favoritopermite chamá-lo a qualquer momento, entre conexões, pelo ícone ★ na barra lateral. A aba "Vistos recentemente" mantém o histórico dos documentos abertos automaticamente.

• Em "Link", no painel direito do documento, é possível copiar um link direto (firescope://); ao compartilhar pelo Slack, por exemplo, a outra pessoa consegue abrir o documento diretamente no Firescope dela.
• Pelo ícone de link externo na trilha de navegação (breadcrumb), você pode ir direto para o caminho correspondente no Console do Firebase (Web) (oculto em conexões de emulador).

Operação

O monitoramento em tempo real pode ter alertas por condiçãoconfigurados. Ao registrar "quando for adicionado", "quando for excluído" ou "quando um campo específico mudar", uma notificação de desktop é enviada ao ocorrer a alteração correspondente.

Ao clicar na contagem de leituras no rodapé, um popover mostra a quantidade estimada de leituras da sessão, o custo estimado e a evolução ao longo do tempo.

Na aba "Compartilhar/transferir" das configurações, é possível exportar e importar em um único arquivo JSON algumas configurações de interface, como nomes lógicos de campos, consultas salvas e favoritos. Como nunca inclui a chave privada da conexão, informações de licença ou rótulos de ambiente, é útil para compartilhar com a equipe ou trocar de máquina.

Ao ativar "Ocultar valores" na barra de ferramentas, apenas os dados reais são exibidos como asteriscos (••••), mantendo nomes de campo, tipos e estrutura visíveis. É útil ao compartilhar a tela ou tirar capturas de tela (é apenas uma questão de exibição; os dados reais não são alterados).

Servidor MCP (integração com agentes de IA)

O Firescope vem com um servidor MCP (Model Context Protocol) embutido. Ao conectar a partir de um agente de IA, como o Claude Code, é possível listar coleções do Firestore, obter documentos e executar consultas diretamente durante a conversa.

Para iniciar (na raiz do repositório):

# Para conectar ao emulador
FIRESCOPE_MCP_PROJECT_ID=your-project \
FIRESCOPE_MCP_EMULATOR_HOST=127.0.0.1:8080 \
npm run mcp

# Para conectar a um projeto real via JSON de conta de serviço
FIRESCOPE_MCP_SERVICE_ACCOUNT_PATH=/path/to/service-account.json \
npm run mcp

Exemplo de configuração no lado do cliente 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"
      }
    }
  }
}

• São 3 as ferramentas oferecidas: listagem de coleções (firestore_list_collections), obtenção de documento (firestore_get_document) e execução de consulta (firestore_query_collection, com suporte a filtro/ordenação/limite de itens).
• Como reutiliza a mesma lógica interna do construtor de consultas da interface gráfica, o formato do resultado corresponde exatamente ao que é exibido no app.