pls - Project Level Shortcuts uses bashly

[codevogel]

Hi, I built a nice little CLI tool using bashly:

Project Level Shortcuts (pls) is a command-line tool designed to streamline your workflow by allowing you to create, manage, and execute custom aliases for frequently used commands.

It manages your aliases in yml files, so you can be sure they don't interfere with other commands. Aliases can also be added on a local project-based scope, where they overwriting duplicate system-wide aliases.

This makes it easy to run, for example, multiple testing frameworks across different projects by just typing pls test.

Check it out here: https://github.com/codevogel/pls

[DannyBen]

Wow - this looks super cool, and seems like it took quite a lot of effort. Just the README seems like a couple of days of work.

I am going to check it out for sure - I love aliasing commands, have built a few aliasing helpers myself.

Can I list it on https://bashly.dannyb.co/examples/#real-world-examples

Also I am curious if you had any issues or annoyances with bashly during the development, or anything that would have made the development process easier.

[codevogel]

Oh - I was creating some issues for pls and saw that I forgot to reply to this message.

You are more than welcome to list it in the real world examples. In fact, I think it'd be cool!

Regarding issues I had developing with bashly, I think I already pointed them out in the earlier question discussions I created.

The docs do feel a little overwhelming at times, hence why I missed some features that you then kindly suggested I should take a look at. But - I think that's mainly due to the nature that bashly just offers you a lot of options. The docs themselves are great: everything you need is in there, there's clear examples, and yet it doesn't feel too cluttered and you can easily find your way to what you want.
I guess the harder part is knowing what to look for.

Maybe a way to improve this could be to add a couple of tutorial/sample projects, in which you can write a simple CLI tool from start to finish (e.g. a tool that adds numbers from one file to numbers from another file) - including adding some simple code (the examples mostly contain bashly .yml examples and the output of those commands - I don't mean 'write a bash scripting tutorial', but just show how you could implement a feat, making use of the arguments/env vars etc.). You could start pretty bare-bones (just run and it adds the numbers of file a and b), then slowly work up to adding arguments (specify path for a and b, flags (--subtract instead), etc.

Though to be fair, I'd consider the work/reward ratio there, because as I said, the docs are already very clear. With a little more patience I would've found my way around.

[DannyBen]

list it in the real world examples

I was optimistic and already did.

As for the tutorials / example projects, thanks for the feedback. I thought that having an extensive index of examples, each being minimal to only a single topic would serve as a "choose your path" tutorial.

You are right in identifying the fact that the examples are mostly about the bashly configuration itself and less about the needed bash code - however this was one of bashly's goals; to not force you to learn anything in bash itself - you just get that $args dictionary and that is it. The rest is up to you. If this particular message is not conveyed clearly, then we need to improve the docs.

Perhaps the Getting Started page could get some love.

[DannyBen]

So I have tested this a little deeper, using the very useful docker environment.

What I like

• Love the name. I am sure it is not a coincidence that it is also a shortcut to "please", so typing "pls deploy" makes it fun to use.
• Love the detailed README and --help - makes it very easy to grasp what it does and how it does it, quickly.
• Love the "first run" confirmation - makes it feel safe to run.
• Love the fzf menu.
• Love the cascading nature of the .pls.yml files.
• Love the thorough test/spec suit.

Some personal observations

• I am usually not a huge fan of commands that have underscores in them. I am guessing this naming convention was picked to distinguish these commands from user aliases.
• I wonder if to mitigate the above, it is worth considering having all of the "internal" commands be converted to flags instead: pls -l, pls -p etc. This frees the "command namespace" completely for the user aliases.
• I wonder - especially since fzf is a dependency - if it would be possible to allow the user to type just the first few letters of an alias, and if they resolve to a single command, run this command: pls dup => pls duplicate.
• There is a hefty number of environment variables. I wonder if it would make sense to use a configuration file (~/.plsrc) for configuring all at once. Then, there could be only one environment variable pointing to the path of the configuration file.
• I see that when you have an option (like --destination) that requires the value to be one of a whitelist, you are not using flag.allowed` and instead do a custom validation.

[DannyBen]

Excellent. I will evaluate the options for flag.needs.

[DannyBen]

I think flag.needs (aka Needy Flags) is going to happen 👉 #543

[codevogel]

I've implemented pls without any commands now, it's all through flags now.

Before I push this to my main branch, I would like to check in with you, because I think I'm running into something that I don't like all too much here:
https://github.com/codevogel/pls/blob/b1e3ce0bd75c3cf3e34962e1bfe44b2ea135da8a/src/bashly.yml

The issue is that the conflicts and needs are quite cluttered in my bashly.yml.
It would be nice if needs could support OR actions.

e.g.
I have a --scope flag that I want to use with --add OR --delete OR --list. But it should not be used in conjunction with any other flags. I could add conflicts to each and every other option that is not one of the three above, but that clutters the --help. Besides, it is easy to miss a few combinations once the amount of flags start growing.

It is easier to just add needs: [ --add, --delete, --list ] to --scope and then have the --scope argument throw an error when used without --need, but right now this is not possible, as it is currently expecting you need all three.

Since I'm not sure if yaml supports an OR-like syntax, maybe you could add multiple options to needs by combining the shorthands, like needs: -adl. But maybe that's a silly idea.

Or would you say this is more of a custom validation job? I'm not sure how to approach this.

[DannyBen]

Yes. I see the issues, and agree that this bashly.yml is not fun to read or write.

Some initial thoghts:

1. I thought about OR in needs, but quickly dismissed this thought. The main reason was that this (as well as conflicts) is meant for simple cases with one or two conflicts/needs. I do not want the YAML configuration file to become a programming language.
2. I do not think you should set any of your flags to private (e.g. --command) - let the users see its help.
3. I saw you used --List with capital L - I would avoid it (then your conflicts does not have to mention both --list and --List.
4. I would consider limiting the needs to one. For example, I feel like --scope should be optional - if you agree, then you are left with --add that needs --command. and that's it.
5. I am not sure there is a need to state ALL conflicts - after all, if someone provides --list and --clear-cache - your code can either accept it (and do both) or just perform whichever of the functions you have first in your if statement.

Now - I would consider one of three ways forward - and this is not a bashly problem in particular, but rather a CLI design problem.

Option 1 - simplified flags

Find a way to simplify the "operations" interface, with less / minimal flags. Note that this also means that you acknowledge that adding more operations in the future might be unscalable and convoluted, so you in essence "cap" your future expamsion.

Option 2 - custom filter

Completely avoid using bashly's needs and conflicts.

Instead, write a custom logic filter. Normally I would not recommend this, but in this case it fits because you would need to do the same in almost any other CLI framework (in any language) - the logic you need is custom, therefore you need to write the code for it yourself.

Option 3 - rethink interface

Rethink the "flag only" interface.

If "flags only" interface is a problem and "too many commands" was a problem - perhaps there is a third way?
Going back to the "add / deleete" etc. commands does not see right to me - since it suffers from the same issues it suffered before (mainly namespace contamination). Perhaps there is a different way to approach this (interface wise).

Just as an example, consider an interface that has two commands: "run" for running alias (default), and "configure" for ALL configuration commands (listing, clearing cache, deleting etc).

Imagine a "manage" command ("m" for short) which can have its own natural subcommands:

$ pls m purge
$ pls manage add ALIAS COMMAND....
$ pls manage add ALIAS --scope local COMMAND....
$ pls manage del ALIAS [--scope local]
$ pls ALIAS
$ pls run ALIAS
$ pls r ALIAS

and so on.

I guess my point is - first decide on an interface that makes sense both from the user perspective and from development perspective, and then it should be more straight forward to implement.

[codevogel]

Thanks for the suggestions.

I realized that -p is already used to print commands, so I decided to just use that as an additional argument for the --list command instead of using --List.

I've also done away with the conflicts, I now just use needs where applicable, and then made a custom validation function is_only_operation for the --add , --delete, --list flags.

Although still not perfect, I think this reads a lot better than before.

In conjunction with a new table in the README, this should be fine for now.