argus-cli Caveats

There are some aspects of argus-cli than can be confusing or error-prone. The goal of this page is offer clarification for some know cases.

Multiple-Value options

Multiple-value options are those that can receive several values.

An example of such an argument is the --exclude-flag option for the argus-cli events search command, that allows filtering out events that have a certain flag set.

Multiple-Value options should be passed once with several values

The correct way to pass several values to a multiple-value option is to specify the option once and only once, follow by its values.

Example: If you want to search events belonging to CUSTOMER from START_DATE to END_DATE and exclude events that have neither FLAG1 or FLAG2 set, the correct expression is :

valid
argus-cli events search \
    --include-customer $CUSTOMER \
    $START_DATE $END_DATE \
    --exclude-flag $FLAG1 $FLAG2

While technically valid, repeating the option several time will ignore all its values except the last one :

Warning

do NOT do this

invalid
argus-cli events search \
    --include-customer $CUSTOMER \
    $START_DATE $END_DATE \
    --exclude-flag $FLAG1 \
    --exclude-flag $FLAG2 # incorrect

Caution

With this second example, only FLAG2 would be excluded

Multiple-value options “swallow” arguments

Because of the way arguments are parsed, argus-cli will consider everything between a multiple-value option and the next -- to be a value for the option.

This means that if a multiple-value option is passed before a short (single -) option or arguments, the option/arguments will be ignored.

Example: If you want to search events belonging to CUSTOMER from START_DATE to END_DATE and exclude events that have neither FLAG1 or FLAG2 set, this expression is valid :

valid
argus-cli events search \
    --include-customer $CUSTOMER \
    $START_DATE $END_DATE \
    --exclude-flag $FLAG1 $FLAG2

This works because the multiple-value option --exclude-flag is used last.

The following is also valid:

valid
argus-cli events search \
    --exclude-flag $FLAG1 $FLAG2 \
    --include-customer $CUSTOMER \
    $START_DATE $END_DATE

This works because the multiple-value option --exclude-flag is followed by a long (double -) option.

Finally, it is possible to explicitly mark the separation between options and arguments with -- :

valid
argus-cli events search \
    --include-customer $CUSTOMER \
    --exclude-flag $FLAG1 $FLAG2 \
    -- \
    $START_DATE $END_DATE

This works because the end of options is marked by -- (note that no option can be used after --, only arguments).

The following will not work as expected:

Warning

do NOT do this

invalid
argus-cli events search \
    --include-customer $CUSTOMER \
    --exclude-flag $FLAG1 $FLAG2 \
    $`START_DATE $END_DATE`

Caution

Here, the command will never receive the arguments START_DATE and END_DATE because they will be considered values of the --exclude-flag option.

Boolean/flag options

Flag options are those that expect a boolean value (True/False).

Example: a number if commands accept a --dry option to perform a dry run without making any change.

The correct way to set such a option to true is to pass it without any value:

--dry

And to prefix them with not to set them to false:

Note

the prefix is not - it isn’t no

--not-dry

The following expression will not work as intended :

Warning

do Not do this

--dry 0
--dry false
--dry False

Caution

using any of these will result in dry being set to True

Argument values starting with -

Because - is used to prefix options, arguments whose value start with a literal - can cause the command to be misinterpreted. This can be prevented :

For options whose value start with a -, use the --option=value syntax :

# do not do this:
--startTimestamp "-1 month"
# do this instead:
--startTimestamp="-1 month"

For parameters whose value start with a -, explicitly separate parameters from options :

# do not do this:
argus-cli events search "-2 month" "-1 month"
# do this instead:
argus-cli events search -- "-2 month" "-1 month"