Home CLI guides PITR Recovery CLI

PITR Recovery CLI

Last updated on Jul 12, 2026

Current Status

PITR has a first-class CLI command group for task-backed load, diff, and guarded restore command shapes. The commands use the shared FirestorePITRService, return JSON output, and preserve the same read-only and production confirmation guardrails as the macOS module.

Current automated evidence proves command shape, request construction, task output, selected-module routing, and local guardrails with URLProtocol-backed service tests. It does not prove real Firestore PITR historical reads or live restore effects. Approved PITR-enabled Firebase evidence is still required before live PITR behavior should be claimed externally verified.

Commands

pitr load --document users/alice --read-time 2026-05-03T12:00:00Z
pitr diff --document users/alice --read-time 2026-05-03T12:00:00Z
pitr restore --document users/alice --read-time 2026-05-03T12:00:00Z --confirm
pitr restore --document users/alice --read-time 2026-05-03T12:00:00Z --confirm --production-confirm "RECOVER my-project"

pitr-recovery is accepted as a top-level alias. The commands also work through selected-module routing:

module select pitr
run diff --document users/alice --read-time 2026-05-03T12:00:00Z

Output Contract

Successful commands return machine-readable JSON with:

  • selected project metadata
  • pitr.action, documentPath, readTime, databaseID, and requiresApprovedLivePITRVerification
  • snapshot.current and snapshot.recovered document versions with decoded fields and raw JSON
  • diffRows with field path, current value, recovered value, and status
  • logs from the PITR service
  • task snapshot with status, counters, duration, attempts, and error details
  • restore raw JSON for pitr restore

Safety Boundary

Restore requires --confirm. Read-only projects reject restore before network requests. Production restore requires --production-confirm "RECOVER <project-id>" before any load or PATCH request is attempted.

For live projects, pass --authorization "Bearer <token>" or --access-token <token>. The command output still marks PITR behavior as requiring approved live verification until a PITR-enabled Firebase project run with before/after evidence and cleanup is recorded.

Verification

Covered by:

swift test --filter FirestructCLIIntegrationTests/testPITRCLIQueuesLoadDiffAndRestoreWithTaskOutput
swift test --filter FirestructCLIIntegrationTests/testPITRCLIRestoreRejectsReadOnlyAndProductionBeforeNetwork

The first test uses the real PITR service through the CLI with a URLProtocol session, verifies pitr load, selected-module run diff, and pitr restore task output, current/recovered/diff/log JSON, and recovered-field PATCH request body. The second test proves read-only and production confirmation failures happen before any network request.

Source Anchors

  • Sources/FirestructCLIKit/PITRCommand.swift
  • Sources/FirestructCore/FirestorePITRService.swift