This AIP is currently a draft. This means that it is being actively debated and discussed, and it may change in non-trivial ways.

AIP-3260

Firebase CLI

Guidance

Command Naming

Commands must be named in lowercase using colons to separate namespaces. The final segment of a command should be an action verb, for example list, deploy, or clone. A "get" of a single resource may omit the action for the sake of brevity (e.g. apps:sdkconfig instead of apps:sdkconfig:get).

Project Selection

The Firebase CLI works with "project directories" that can be associated with one or more Firebase projects via the use command. This ambient project selection can be overridden by passing the -P or --project flag.

All Firebase CLI commands must determine the intended project for a command based on common project selection, except when a command involves multiple projects (e.g. a command that clones configuration from one project to another).

JSON Output

All Firebase CLI commands support machine-readable output via the --json flag. If a command correlates to a single API call, the unmodified response of that API call should be provided as the JSON response (with wrapped CLI metadata).

If a command does not directly correlate to an API call, the output should include all information a user might reasonably need for programmatic interpretation of the command. Output must be formatted in snake-case and generally conform to all standard Google API guidance (e.g. field names).

Arguments and Flags

Required inputs for a command must be represented as arguments (e.g. database:get /path) unless doing so would be confusing to the user. For instance, appdistribution:distribute requires as input both a file to distribute and an App ID, so --app <appId> as a required flag is more clear than two unrelated arguments with no clear hierarchy.

Flags must be named using kebab case (e.g. --example-flag) and may provide a single-letter alias that does not conflict with defined global flags.

Common Flags

  • --app <appId> - used to refer to a specific app within a Firebase project.
  • --force - used to indicate that a command should proceed without additional prompting regarding potentially destructive actions. For example, deploying Cloud Functions with --force will automatically delete functions, while without the user is prompted.
  • -o, --output <path> - this flag may be used to allow convenient output of a serialized response to a local file. If the output is JSON, it must output equivalent JSON to --json without wrapped CLI metadata. If the command fetches a deployable resource, it must fetch it in a deploy-compatible format. The string path may be optional if a clear default path exists. If a file already exists at the path, a confirmation prompt must be displayed unless a --force flag is also provided.

Common Command Types

List Commands

Commands that return a list of like resources must use a :list suffix (e.g. projects:list).

List commands must not require manual pagination (e.g. a --page-token flag) and will generally fetch all results (via multiple API calls if necessary). List commands may include a --limit <int> flag when a natural ordering exists, such as a reverse chronological list of releases. A --limit 0 flag indicates that all results should be fetched and returned.

The JSON output of a list command must be a concatenated array of all fetched resources in their original wire format.

Clone Commands

If a command's purpose is to copy information from one resource to another, it must be suffixed with :clone and must take a from and to argument:

  firebase example:clone <fromProject> <toProject>

To avoid confusion and accidental misuse, clone commands must explicitly require both arguments and must not rely on project selection to populate either.

If a clone operation is destructive (replaces existing state), the command should prompt the user for confirmation before proceeding. If a prompt is added, the command must allow a --force flag to bypass the prompt.

Deployment

Behavior that takes local state (e.g. a rules file) and applies it to the live operation of a Firebase project must integrate with the deploy command.

Scoped Deployments

If a service has multiple deployable resources, it may allow specifying which resources are deployed through colon namespacing, for example:

  firebase deploy --only functions:func1,functions:func2,hosting:site3

Colon namespacing may be used to identify one of many like resources (as with functions above) or to identify specific resource type (e.g. firestore:indexes vs. firestore:rules).

If the service integrates with deploy targets, the targets must be addressable via colon namespacing.