Home CLI guides Seed Studio CLI

Seed Studio CLI

Last updated on Jul 12, 2026

Purpose

The Seed Studio CLI automates deterministic Firestore seed snapshots for emulator setup. It uses the same SeedStudioService as the macOS module for schema parsing, generation, apply, and drift analysis.

All successful commands print JSON. Failures return exit code 1 with a readable error on stderr.

Generate Snapshot

seed import-template --template seed.json --output normalized-seed.json
seed generate --template seed.json --output snapshot.json --seed 42
seed export-template --snapshot snapshot.json --output exported-seed.json

Options:

  • --template <path> is required and must contain a Seed Studio schema JSON document.
  • --output <path> is required.
  • --seed <uint> defaults to 1.

The generated file is a CLI snapshot envelope containing both the parsed schema and generated snapshot. Keeping both pieces together lets later seed apply and seed diff coerce values and compare fields without relying on an external template file.

Output includes the template path, destination path, random seed, collection path, document count, and snapshot digest.

seed import-template parses and validates a schema JSON file, then writes the normalized SeedSchema form to disk. seed export-template reads a generated snapshot envelope and writes its embedded schema to disk. Together they provide a real file round-trip for template import/export workflows without touching Firebase data.

Apply Snapshot

seed apply --project Local --snapshot snapshot.json --confirm
seed apply --project Local --snapshot snapshot.json --allow-overwrite --confirm
seed apply --project Local --snapshot snapshot.json --document-ids seed-1,seed-3 --confirm
seed apply --project Local --snapshot snapshot.json --reset-existing --allow-overwrite --confirm

Options:

  • --snapshot <path> is required and must be produced by seed generate.
  • --project <name|firebaseProjectID|uuid> overrides the selected project.
  • --confirm is required.
  • --allow-overwrite permits replacing existing documents.
  • --reset-existing deletes each generated document path before reapplying it.
  • --document-ids <ids> applies only the comma- or newline-separated generated document IDs. Without --allow-overwrite, existing selected documents are skipped and reported in skippedDocumentIDs; missing selected documents are recreated. With --allow-overwrite, selected existing documents are replaced.

Apply currently uses emulator-safe writes. Non-emulator writes are blocked by the core service because live seed rollout requires a separate approved verification path.

Output includes selected project JSON, source/applied document counts, partial document IDs, applied/skipped counts, applied document paths, logs, and a completed task snapshot.

Diff Snapshot

seed diff --project Local --snapshot snapshot.json
seed diff --project Local --snapshot snapshot.json --limit 1000

Options:

  • --snapshot <path> is required.
  • --project <name|firebaseProjectID|uuid> overrides the selected project.
  • --limit <count> controls the current Firestore query limit and defaults to 0, which fetches all documents in Firestruct's Firestore query service.

Diff reads current Firestore emulator data from the snapshot collection path and reports changed, unchanged, missing, and new documents.

Current Verification

FirestructCLIIntegrationTests/testCLICommandsRoundTripAgainstFirebaseEmulators imports a template to a normalized file, generates a deterministic Seed Studio snapshot from that imported template, exports the template back out of the snapshot, decodes both template artifacts, verifies apply rejects missing --confirm, applies the snapshot to a real Firestore emulator, queries the seeded collection, mutates/deletes/adds emulator documents, runs partial seed apply --document-ids without overwrite to prove existing selected docs are skipped while missing selected docs are recreated, runs partial apply with --allow-overwrite to prove selected changed docs are restored, and runs seed diff to assert the final unchanged/new counts.

Source Anchors

  • Sources/FirestructCLIKit/SeedCommand.swift
  • Sources/FirestructCore/SeedStudioService.swift
  • Sources/FirestructCore/SeedStudioService+GenerationUtilities.swift