A CLI tool to export Google Cloud Firestore collections to CSV files.

• Go 1.21+
• Google Cloud credentials configured via Application Default Credentials:

  gcloud auth application-default login

Install and run:

go install github.com/serpro69/firestore2csv
firestore2csv -p <project-id> [flags]

Or build and run:

go build -o firestore2csv .
./firestore2csv -p <project-id> [flags]

Or run directly without installing/building a binary:

go run . -p <project-id> [flags]

* At least one of --project or --emulator must be provided. Both can be used together to specify the project ID when connecting to an emulator running in single-project mode (e.g. -e localhost:8686 -p my-project). When only --emulator is given, the project defaults to emulator-project.

Export all collections:

go run . -p my-project

Export specific collections with a row limit:

go run . -p my-project -c users,orders -l 100

Export from a named database to a custom directory:

go run . -p my-project -d my-db -o ./export

Export only top-level collections (no sub-collections):

go run . -p my-project --depth 0

Export with one level of sub-collections, limiting sub-collection docs:

go run . -p my-project --depth 1 --child-limit 50

Export from a local emulator:

go run . -e localhost:8686

Export from an emulator with a specific project ID (for single-project mode):

go run . -e localhost:8686 -p my-project

• One CSV file per collection, named {collection}.csv
• Sub-collections are exported into subdirectories mirroring the Firestore hierarchy
• First column is __document_id__ (Firestore document ID)
• Remaining columns are sorted alphabetically
• Columns are the union of all fields across documents in the collection

Sub-collections are automatically discovered and exported recursively. Documents from the same sub-collection across different parent documents are aggregated into a single CSV file. Virtual documents (documents that exist only as containers for sub-collections, with no fields of their own) are also traversed.

For example, if users/alice and users/bob both have an orders sub-collection, all orders are written to users/orders.csv.

output/
  users.csv
  users/
    orders.csv
    orders/
      items.csv
  products.csv

Use --depth to control how deep to recurse (0 = top-level only, 1 = one level of sub-collections, -1 = unlimited).

Unit tests cover pure functions (value formatting, CSV writing, etc.) and require no external services:

go test -v ./...

Integration tests run against a local Firebase Firestore Emulator and exercise the full export pipeline — collection resolution, recursive sub-collection export, depth/limit controls, and CSV output.

Prerequisites: Firebase CLI (npm install -g firebase-tools)

Run with Make (starts and stops the emulator automatically):

make test-integration

Or run all tests (unit + integration):

make test-all

To run manually:

firebase emulators:start --only firestore --project test-project &
FIRESTORE_EMULATOR_HOST=localhost:8686 go test -v -tags integration -count=1 ./...