Filter option usage and help text unclear

[ataylorme]

trafficstars

Expected behavior

When using terminus help commands with the filter option available should have clear help test on its usage.

Actual behavior

The current text of Filter output based on provided expression makes me things a regular expression can be passed, which leads to the error [error] Could not parse expression.

I had to review the source code and PR #1992, where the filters were introduced, to realize the usage is `--filter="=".

I'm also not sure if regular expressions are supported or if the field value being filtered must be an exact match.

For example, terminus org:list --field=label --filter="label=Pantheon" yields no results even many organizations that have labels starting with Pantheon are available to me via terminus org:list.

Overall, the addition of the filter command is a great improvement but I'm afraid the usage being unclear will discourage users from taking advantage of it.

Steps to reproduce the behavior

1. Run terminus help org:site:list

Suggested solution

1. Update the command help text for all commands with the filter option to more clearly document the usage of the filter option.
2. Update the Terminus doc to include a section on filtering results.

terminus self:info

 ------------------------- --------------------------------------------------------------------------------------------------- 
  PHP binary                /usr/local/Cellar/php/7.3.8/bin/php                                                                
  PHP version               7.3.8                                                                                              
  php.ini used              /usr/local/etc/php/7.3/php.ini                                                                     
  Terminus project config                                                                                                      
  Terminus root dir         /Users/andrewtaylor/pantheon-cli                                                                   
  Terminus version          2.0.1                                                                                              
  Operating system          Darwin Kernel Version 18.7.0: Thu Jun 20 18:42:21 PDT 2019; root:xnu-4903.270.47~4/RELEASE_X86_64  
 ------------------------- --------------------------------------------------------------------------------------------------- 

[greg-1-anderson]

There are some examples of contains and regex filters on the project page: https://github.com/consolidation/filter-via-dot-access-data

[ataylorme]

@greg-1-anderson I was thinking more specifically better help text in Terminus itself and perhaps some practical examples, like filtering org:site:list, on the Terminus docs page. Both of those are much more discoverable than the repository of a dependency.

[greg-1-anderson]

I was merely providing a resource for drafting that information.

[ataylorme]

I was merely providing a resource for drafting that information.

👍 in that context, it is very useful, thanks for the link!

[twopercent]

Is there a way to use --filter multiple times? Like terminus site:list --filter plan_name!="Sandbox" --filter framework=wordpress Currently, only the last --filter is used.

[greg-1-anderson]

Only one --filter is supported, but simple boolean logic may be used, e.g. color=red&&shape=round

[twopercent]

That worked Greg! Thank you. (You will need to double quote the entire filter or escape the boolean so bash doesn't interpret it) terminus site:list --filter "plan_name!=sandbox&&framework=wordpress" terminus site:list --filter plan_name!=sandbox\&\&framework=wordpress

[danflies]

Can this be added to the help test for filters. I sucks so much trying to guess my way through it.

[aaronbauman]

Noting for posterity: for boolean values like frozen, you can't use the value true or false that are returned bysites.

You have to use --filter="frozen=1" or --filter="frozen!=1.

This does not work: --filter="frozen=0"

Lots of trial and error to figure out how these filters work.