Firebase-tools: Firebase alias commands aren't intuitive

Created on 23 May 2016 · 8Comments · Source: firebase/firebase-tools

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 and map it to project . Both and 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 . If 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.

feature request

Source

dotproto

👍25

All 8 comments

Hey Simeon,

Thanks for the detailed feedback! We had quite a bit of discussion about use and the best way to expose all of this functionality. I tried to avoid adding multiple top-level commands, but I agree with your assessments about the weaknesses of the current approach.

I think we're going to spend some time with this in production to keep gathering feedback, but I'll definitely mark this as a vote for an improved UX and if anyone sees this and agrees, feel free to :+1: with an emoji reaction on the issue above.

mbleigh on 23 May 2016

152 starts to address the intuitiveness of aliasing by automatically activating an alias if only one is available.

mbleigh on 25 May 2016

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:

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.
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.
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?

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.
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.

odigity on 5 Nov 2016

👍1

Is this true?

When this is run, it creates a mapping between the directory it was run in and which project / alias you selected, so if you moved the directory the firebase.json file is situated in the previous link may have been severed.

http://stackoverflow.com/a/37402821/210867

UPDATE: It's seems like the Firebase servers are storing whatever string you pass to firebase use <thing>, whether it's an alias or project ID.

When I use an alias, then edit .firebaserc to change or remove the alias, then run firebase use, "Active Project" reports the alias string I originally used, but no project ID, since it can no longer translate from that alias to a project ID using the mapping in .firebaserc.
When I use a project ID, then add an alias for that project ID, then run firebase use, "Active Project" reports the project ID I originally used, but no alias.

Would really like to see a concise and accurate explanation of:

Firebase's Domain Model (projects, aliases, default, current, active, etc)
The relevant implementation details (what info is stored where and in what format/structure).

odigity on 5 Nov 2016

👍1

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.

mbleigh on 5 Nov 2016

🎉1

People on this thread: do you have suggestions as to how you'd like to see firebase use and project aliasing work instead? To give some background on why some things work how they do:

We want to be able to store aliases in the project directory, so that team members working on the same project can use the same aliases without manual configuration.
We do not want to store the "current" mapping in the project directory, because if it were committed into version control you could accidentally switch someone from "staging" to "production" instantly.
We want to make sure that people who are only working with one project don't have to jump through unnecessary hoops, which is why we automatically activate an alias if only one is present.
We wanted to bundle all of the functionality into a single command to keep the surface area small -- however, we may have put too much focus on this at the expense of discoverability.

I'm very much open to taking a new approach especially to the command structure, and I'd be very happy to hear about either how you think it should work or other tools that you think do a good job with this.

mbleigh on 5 Nov 2016

That's pretty much exactly the summary I ended up with in my notes after my experimentation session, with one exception - I didn't know about ~/.config/configstore/firebase.json. I concluded (based on the network dependency) that it was storing those mappings remotely, which was shocking. I'm glad to learn it's stored locally, though the choice of location is odd to me.

I'm too brain dead at the moment to make useful suggestions, but if some come to me, I'll post them here.

odigity on 6 Nov 2016

I'm still a bit unsure if I understand aliases correctly. I was thinking it was for separating parallel phases of development. For example: