Firestore CLI

firestore-cli is a clean Node.js CLI for exploring and managing Firestore databases from the terminal.

Why

Neither gcloud firestore nor the Firebase CLI offer a good terminal experience for exploring Firestore data. gcloud supports basic document reads but uses verbose protobuf-style output, lacks field projection, can't list subcollections, and doesn't support native Firestore query operators. The Firebase CLI has no read/query commands at all — it's focused on deploy, emulators, and rules.

This CLI fills that gap with clean output, native query syntax, named profiles for switching between projects, recursive deep export of documents with their subcollections, and lightweight document write operations for the cases where you need to create, update, or remove a document without leaving the terminal.

Features

• Named profiles for cloud and emulator targets
• Root collection and subcollection listing
• Direct document reads with recursive deep export of subcollections
• Direct document writes with create, set, update, and delete commands
• Dry-run support for document writes and deletes
• Filtered, ordered, projected collection queries
• JSON exports to stdout or files
• Pretty terminal output by default, --json for machine-readable output

Install

npm install -g @csimpkins22/firestore-cli

For development:

git clone https://github.com/csimpkins22/firestore-cli.git
cd firestore-cli
npm install
npm run build
npm install -g .

Global options

--profile <name>   Profile to use (overrides the default)
--json             Emit machine-readable JSON
--verbose          Include full stack traces in error output

Profile setup

Create a cloud profile:

firestore profiles add dev \
  --project my-project \
  --credentials /absolute/path/service-account.json

Create an emulator profile:

firestore profiles add local \
  --project demo-project \
  --emulator-host 127.0.0.1:8080

Profiles also accept --database <id> for non-default Firestore databases.

Set a default profile:

firestore profiles use dev

List all profiles:

firestore profiles list

Show a single profile:

firestore profiles show dev

Remove a profile:

firestore profiles remove dev

Examples

List root collections:

firestore collections list

List subcollections under a document:

firestore collections list users/ada

Read a document:

firestore doc get users/ada

Deep export a document with all subcollections:

firestore doc get users/ada --deep

Write a document to a file:

firestore doc get users/ada --deep --out ./ada.json

The --deep flag recursively fetches all subcollections and nests them under a subcollections key. --out works with or without --deep.

Create a document:

firestore doc create users/grace '{"name":"Grace Hopper","active":true}'

Overwrite a document:

firestore doc set users/grace '{"name":"Grace Hopper","team":"compiler"}'

Merge fields into an existing document:

firestore doc set users/grace '{"lastLogin":"2026-04-02T09:30:00Z"}' --merge

Update specific fields on an existing document:

firestore doc update users/grace '{"active":false}'

Preview a write without changing Firestore:

firestore doc update users/grace '{"active":true}' --dry-run

Delete a document:

firestore doc delete users/grace

Skip the delete confirmation prompt:

firestore doc delete users/grace --yes

doc create, doc set, and doc update require a JSON object argument. Arrays and primitives are rejected. doc set --merge preserves existing fields and merges the provided object. doc create fails if the document already exists, and doc update fails if it does not. doc delete prompts for confirmation unless you pass --yes. All write commands support --dry-run, and --json returns machine-readable write and dry-run output.

Run a query:

firestore query users \
  --where status,==,"active" \
  --order-by createdAt:desc \
  --limit 10

Field projection and offset:

firestore query users --select name,email --offset 20 --limit 10

Supported --where operators: <, <=, ==, !=, >=, >, array-contains, in, not-in, array-contains-any.

Emit raw JSON:

firestore --json query users --where role,==,"engineer"

Export query results to a file:

firestore export users --where active,==,true --out ./users.json

Export to stdout:

firestore export users --out -

Configuration

The CLI stores profiles in the OS config directory resolved by env-paths("firestore-cli"), for example:

• macOS: ~/Library/Application Support/firestore-cli/config.json
• Linux: ~/.config/firestore-cli/config.json
• Windows: %APPDATA%/firestore-cli/config.json

Claude Code skill

A Claude Code skill is included in skills/firestore/. To install it, copy it to your Claude skills directory:

cp -r skills/firestore ~/.claude/skills/firestore

This lets Claude Code use the firestore CLI directly via the /firestore slash command to explore your Firestore databases.

Current limitations

• Firestore Native mode only
• No batch writes, transactions, or recursive delete helpers yet
• No collection-group queries yet
• No OAuth or interactive TUI flows