Home CLI guides Tasks CLI

Tasks CLI

Last updated on Jul 12, 2026

Current Status

Firestruct exposes a first-class Tasks CLI command group for current-process tasks and durable completed-task history:

tasks list
tasks show <task-id>
tasks retry <task-id>
tasks cancel <task-id>

Successful command output is JSON. Task rows include id, title, status, processedOperations, totalOperations, timestamps, durationSeconds, attemptCount, lastErrorDescription, recordedAt, source, and bounded per-task lifecycle logs.

Persistence Boundary

CLI task inspection includes two layers:

  • current-process tasks from the live TaskOrchestrator
  • durable completed-task snapshots from task-history.json

tasks list and tasks show can read persisted terminal task snapshots and their lifecycle logs in a fresh CLI context. tasks retry and tasks cancel still require the original same-process runner because Firestruct does not serialize operation closures.

Every Tasks CLI response includes:

{
  "persistence": {
    "mode": "persistent-history",
    "crossProcessPersistent": true,
    "retryCancelScope": "same-process"
  }
}

This is intentionally a history model, not a durable background job runner.

Commands

List

tasks list

Returns current-process tasks plus persisted terminal history, with summary counts for queued, running, success, failed, total, and history tasks.

Show

tasks show <task-id>
tasks show --id <task-id>

Returns a single task snapshot or a non-zero error when the task ID is unknown or malformed.

Retry

tasks retry <task-id>
tasks retry --id <task-id>

Retries failed tasks through the real TaskOrchestrator runner. Retrying a queued, running, or successful task returns a non-zero actionable error.

Cancel

tasks cancel <task-id>
tasks cancel --id <task-id>

Cancels queued or running tasks where the underlying operation can observe cancellation. Cancelling an already completed or failed task returns a non-zero actionable error.

Verification

  • FirestructCLIIntegrationTests/testTasksCLIListsShowsRetriesAndRejectsInvalidStatesInSameProcess runs a Firestore schema command through a real shared TaskOrchestrator, lists and shows the resulting success task, enqueues a real failing task, verifies failed task visibility, retries it through the Tasks CLI, and checks invalid retry/cancel states return non-zero errors. It then creates a fresh CLI context pointing at the same history file, verifies the completed and failed/retried tasks are still visible with source: history, verifies lifecycle logs include enqueue/start/progress/success/failure/retry events, and verifies retry fails with a persisted-history-only message.
  • FirestructCLIIntegrationTests/testCLICommandsRoundTripAgainstFirebaseEmulators runs Firestore, Seed, Auth, Storage, and Migrations commands against Firebase emulators, then verifies tasks list retains Seed apply, Auth disable/delete, Storage delete, and Migrations record-applied tasks in the same process.

Remaining Gaps

  • Durable retry/cancel across new CLI processes is not implemented.
  • Future long-running CLI commands such as approved-live Workspace deploy, approved-live Push real FCM delivery, and production/live migration apply workflows must route through the shared CLI context task orchestrator when they are implemented. PITR load/diff/restore command shapes already route through the task orchestrator, but approved live PITR evidence is still required before historical read or restore behavior is claimed.
  • Persisted lifecycle logs are bounded per task. They preserve task-state events, progress counters, attempt counts, and failure/cancellation messages; they do not serialize operation-specific stdout/stderr streams unless the command includes that output in its own task/result payload.

Source Anchors

  • Sources/FirestructCore/TaskOrchestrator.swift
  • Sources/FirestructCLIKit/TasksCommand.swift
  • Sources/FirestructCLIKit/CLIContext.swift
  • Sources/FirestructCLIKit/TaskHistoryStore.swift