Home CLI guides Project Registry CLI

Project Registry CLI

Last updated on Jul 12, 2026

Purpose

The project CLI manages local project links and the selected project used by other CLI commands.

Use it to prepare repeatable emulator, development, or production targets before running Firestore, Auth, or Storage commands. The registry keeps local metadata only; connecting a project does not create, modify, or delete Firebase resources. That separation lets teams script local setup while preserving Firestruct's production confirmation rules in the modules that actually mutate data.

Connect a Project

project connect --name Local --project-id demo-firestruct --environment emulator --host localhost --port 8080

Aliases:

project add ...
projects connect ...
projects add ...

Options:

  • --name is required.
  • --project-id is required.
  • --environment accepts emulator, development, or production; default is emulator.
  • --read-only marks the project read-only.
  • --host sets the emulator host.
  • --port sets the Firestore emulator port.
  • --auth-port sets the Auth emulator port.
  • --storage-port sets the Storage emulator port.
  • --database sets the selected Firestore database ID; default is the Firestore default database.

On success the command saves the project, selects it, and returns JSON under connected.

For emulator projects, include host and port values so downstream commands can send requests to the local Firebase Emulator Suite without extra flags. For live projects, store the project ID and environment label, then pass authorization to the individual service commands that need live Firebase access.

List Projects

project list

Returns JSON:

{
  "projects": []
}

Each project payload includes selection state.

Select Project

project select Local
project select --project demo-firestruct

The identifier can be the local name, Firebase project ID, or UUID. Selection is stored in CLI state for future commands.

The selected project is the default target, but supported commands can still override it with --project <name|firebaseProjectID|uuid>. Prefer explicit overrides in automation and CI-like scripts so a previous interactive selection does not send a command to the wrong Firebase project. For production runbooks, print or inspect the selected project before any mutation command and keep the environment label visible in the captured output.

Discover And Select Firestore Databases

project databases list
project databases list --configured
project databases add customer-data
project databases add customer-data --select
project databases select customer-data

project databases list refreshes the configured database IDs. For development and production projects it calls the Firestore database-management API and requires --access-token or --authorization "Bearer <token>". Emulator projects use their locally configured database list. Pass --configured for a read-only local view with no network request.

project databases add validates and persists a database ID without calling Firebase. --select makes it active immediately. project databases select only accepts a discovered or previously added database. The selected database is stored in the project registry and becomes the default for Firestore commands.

Database IDs must be (default) or a valid Firestore database ID using lowercase letters, numbers, and hyphens. Route-specific Auth-to-Firestore commands restore their configured database explicitly, even when a different database is selected interactively.

If a project link is no longer needed, remove it through the app or reset the local CLI state as part of a controlled cleanup. Removing local registry data does not remove remote Firebase data, service accounts, emulator data, or App Store entitlements.

Source Anchors

  • Sources/FirestructCLIKit/ProjectCommand.swift
  • Sources/FirestructCLIKit/CLIStateStore.swift
  • Sources/FirestructCLIKit/JSONOutput.swift
  • Sources/FirestructCore/FirestoreDatabaseDiscoveryService.swift