Home CLI guides Workspace Link CLI

Workspace Link CLI

Last updated on Jul 12, 2026

Current Status

Workspace Link has a first-class read-only/safe CLI command group for local workspace linking, local file inspection, and deterministic rules/index diffing. It also exposes task-backed guarded deploy command shapes for Firebase CLI dry-run/real deploy routing.

Use the CLI for automation-friendly status, diff, and dry-run task evidence. Failed Firebase CLI dry-run output preserves the exact command plus stdout and stderr so project/auth/API failures are reviewable. Real successful Firebase CLI dry-run output and approved live deploy proof are still open before deploy behavior should be claimed as externally verified.

Commands

workspace link --path ./firebase-project
workspace link --path ./firebase-project --firebase-json ./firebase.custom.json --firebaserc ./firebaserc.custom
workspace status
workspace diff --rules --remote-rules-file deployed.rules
workspace diff --indexes --remote-indexes-file deployed.indexes.json
workspace diff --rules --indexes --access-token "$GOOGLE_ACCESS_TOKEN"
workspace deploy --rules --dry-run --confirm
workspace deploy --indexes --dry-run --confirm
workspace deploy --rules --confirm --production-confirm DEPLOY

workspace-link is accepted as an alias for workspace.

The commands also work through selected-module routing:

module select workspace-link
run status
run diff --rules --remote-rules-file deployed.rules
run deploy --indexes --dry-run --confirm

Implemented Coverage

  • local Firebase workspace linking
  • firebase.json and .firebaserc inspection
  • rules/index viewing
  • local rules/index diffing against explicit comparison files
  • diff reason classification for contentChanged, localMissing, remoteMissing, bothMissing, and malformed firestore.indexes parse errors with diagnostics
  • live REST rules/index diffing when an access token is supplied
  • actionable live REST credential/API failure logs for Firebase Rules and Firestore Indexes requests
  • task-backed deploy command construction for rules and indexes
  • deploy output containing selected project metadata, config path, command, logs, and task status
  • read-only real deploy rejection before command execution
  • production real deploy typed-confirmation guard before command execution

Output Contract

Successful commands return machine-readable JSON with:

  • selected project metadata, including linked workspace/config paths
  • workspaceLink.workspacePath, firebaseJSONPath, firebasercPath
  • linked files with label, path, existence, and content preview
  • diff entries with hasDifferences, reason, diagnostics, summary, and diff preview
  • deploy output with target, dryRun, configPath, command, output, liveDeployAttempted, and requiresApprovedLiveDeployVerification
  • task output with status, counters, duration, attempts, and error details for deploy commands
  • executionMode such as local-workspace-inspection, local-file-diff, live-rest-diff, firebase-cli-dry-run, or firebase-cli-deploy

When live REST comparison fails, logs include the Firebase API service name, HTTP status, backend message when present, and a credential/IAM remediation hint. This is deterministic error-surfacing coverage; it does not by itself prove live deploy support.

When a Firebase CLI deploy/dry-run command fails, errors and logs include the exact /usr/bin/env firebase deploy ... command, stdout JSON when present, and stderr text. This preserves real Firebase CLI failure output for review but does not convert a failed dry-run into external deploy proof.

Deploy Boundary

workspace deploy requires --confirm and exactly one target flag: --rules or --indexes. Real, non-dry-run deploys reject read-only projects and production real deploys require --production-confirm DEPLOY.

Current automated evidence uses a deterministic command runner to prove command shape, guardrails, task output, selected-module routing, and failed command output preservation. A local 2026-06-26 real Firebase CLI dry-run attempt against demo-firestruct reached Firebase and returned project-not-found JSON, which is failure-output evidence only. Before claiming externally verified deploy support, run a successful real Firebase CLI dry-run against a valid local workspace/project or use an approved disposable live project deploy and record the output/cleanup evidence.

Verification

Covered by:

swift build
swift test --filter FirestructCLIIntegrationTests/testWorkspaceLinkCLIInspectsAndDiffsLocalFirebaseWorkspace
swift test --filter FirestructCLIIntegrationTests/testWorkspaceDeployCLIQueuesDryRunTaskAndGuardsRealDeploy
swift test --filter WorkspaceLinkRemoteServiceTests/testFetchDeployedConfigSurfacesActionableCredentialAndAPIErrors
swift test --filter WorkspaceLinkRemoteServiceTests/testWorkspaceDeployServiceThrowsOnCommandFailureWithCommandAndOutput
swift test --filter WorkspaceDeployTaskTests/testWorkspaceDryRunDeployFailureCapturesCommandAndFirebaseOutput

The focused test writes a real temporary Firebase workspace with firebase.json, .firebaserc, rules, and indexes files; links it through the CLI; verifies status output; diffs rules/indexes against explicit remote fixture files; verifies content-changed, remote-missing, parse-error, and local-missing reason output; then verifies selected-module run diff routing.

The deploy test uses the same style of temporary Firebase workspace fixture, then verifies workspace deploy --rules --dry-run --confirm and selected-module run deploy --indexes --dry-run --confirm enqueue successful tasks, emit target project/environment/config-path JSON, and call the Firebase deploy command shape with --dry-run and --config. It also proves read-only real deploy and production missing-confirmation guards reject before command execution.

The focused failure-output tests prove failed Firebase CLI deploy/dry-run commands keep the command line, stdout JSON, stderr text, task failure status, and Workspace Link logs.

Source Anchors

  • Sources/FirestructCLIKit/WorkspaceCommand.swift
  • Sources/FirestructCore/WorkspaceLinkRemoteService.swift
  • Sources/FirestructCore/ProjectRegistry+WorkspaceServices.swift