Firebase alias commands aren't intuitive

I’m a newish Firebase user and I just found myself stumbling over the CLI parameters for aliases. Specifically, I was trying to move my files from one firebase project to another.

The current CLI has users entering firebase use to interact with aliases. It makes sense that firebase use <alias> would cause the command line tool to switch which alias it uses, but I found the flags --add and --unalias to be unclear and non-semantic.

I see two major problems with the current add and unalias flags. First, they don’t read well when paired with firebase use. The command “firebase use --add foo” could be rephrased as “hey firebase, add a new use called foo.” I’m not really sure what a “use” would be, which is what trips me up. Second, “add” and “unalias” aren’t complementary (rule 27); the user can’t infert that in one case they should “add” and the other they should “unalias”. A more symmetric interface would use “add/remove” or “alias/unalias”.

IMO a more ergonomic interface would use different commands for alias CRUD operations and setting modifying the Firebase runtime’s state.

• firebase alias --add [<alias> [<project>]] - Create a new alias named <alias> and map it to project <project>. Both <alias> and <project> would be optional. If either is omitted, the CLI would prompt the user to provide the name of the alias and the project it should reference (like the current flow).
• firebase alias --remove [<alias>] - Unalias the alias named <alias>. If <alias> is omitted, the CLI would prompt the user to select the alias they wish to remove and to provide final confirmation before removal.
• firebase use <alias> OR firebase alias --use <alias> - Set Firebase’s state to refernce the specified alias.
• firebase clear OR firebase alias --clear - Clear the current alias from Firebase’s state.

EDIT: Cleaning up some grammar/missing thoughts.

[odigity]

I just spent several hours trying to figure out projects, aliases, the init command and the use command, because I was still very confused even after reading the docs. Here’s a braindump of things I found confusing or frustrating:

1. During the FriendlyChat tutorial, you’re told to run the firebase use --add command and “Then select your Project ID and follow the instructions.” However, the instructions including prompting you to choose an alias for your project when nothing regarding aliases has been mentioned prior. I had no idea what an alias was or what it’s purpose is. The examples were ‘staging’ and ‘production’, so I chose ‘staging’. I later learned that firebase init will choose the alias ‘default’ for your first project, which is not consistent with prompt suggestions for firebase use --add, adding to my confusion.

2. It took me a long time to figure out the difference between “default” and “current”, which are somewhat synonymous. I would think that the “default” project you’re prompted to select during firebase init would be the one that commands would to default to using, but it turns out that’s the behavior associated with the concept of a “current” project, which is completely separate from the concept of “default”. In fact, after all my digging, it seems to me that the concept of a “default” project isn’t a concept at all — it’s just the project that firebase init will associate with the arbitrary alias “default” in .firebaserc.

3. Once I realized “current” is not the same as “default”, I spent a lot of time trying to figure out where the value of “current” is stored. As I switched back and forth between “current” projects using firebase use <proj>, I could see no changes to local files, no setting of env vars, and no changes to files in my home dir. I then realized that the long pauses when the command runs probably means it’s storing that state on Firebase’s servers, so I killed my net connection to confirm it.

   Aside from the annoyance of the delay from the remote call, it also raises more questions that I cannot answer from the existing documentation. If “current” project is stored remotely, what is it associated with? It can’t be my codebase, because my codebase has no identity. It can’t be my project, because the concept of “current project” is larger than a single project. So what, then? Is it my user account? If I’m on my desktop and run firebase use foo, and then switch to my laptop, will the firebase command start defaulting to using the foo project for commands? What if I cd to a different codebase on the same machine that has a completely distinct list of projects in it’s .firebaserc?

4. The only way I can find to tell what the “current” project is is the firebase list command, which shows you all projects you have access to while also highlighting the “current” project (current relative to what, I have no idea). The output doesn’t show you aliases, so the only way to see a list of aliases you’ve defined is to also cat .firebaserc after to get a full picture.

5. The use command is nominally about setting the “current” project, which is a remote operation, yet all of it’s options (except --clear) are about adding or removing alias records from .firebaserc, which is a local file. This is confusing.

UPDATE: Just noticed that firebase use with no args displays both (a) the “active” project and (b) a list of all aliases defined in the local .firebaserc, with the active one(s) highlighted. That’s helpful, but it introduces another problem: You’re now using yet another term (“active”) for the same concept as “current”, which just creates more confusion.

[mbleigh]

• Project: the actual Firebase project resource. Identified by “project id”
• Alias: CLI convenience feature to switch between named projects with firebase use
• Current/Active Project: The current project selected via the firebase use command (also automatically selected after running firebase init. If there is only one project alias for a given project directory, that alias is automatically made current.
• Default: A convenience alias created by firebase init. No special behavior.

Alias mappings are stored in the project directory in .firebaserc. “Active” mapping is stored in ~/.config/configstore/firebase.json along with other CLI configuration data. It is stored as a mapping of absolute directory to currently active alias.

So yes, if you move your project directory your “active” project mapping will be lost.