Common Concepts

This page documents common concepts that are used by multiple argus-cli commands.

Arguments, parameters, options and flags

Definitions

the terms “argument”, “parameter”, “option” and “flag” are used throughout the documentation. they refer to ways data is passed to a command :

example

command argument1 argument2 --option1=option1_value --option2 option2_value1 option2_value2 --option3

ARGUMENT

An input item passed to a function : arguments and options are types of arguments.

in the above example : argument1, argument2, option1, option2 and option3 are all arguments.

PARAMETER

An input item that is required and identified by its position.

in the above example : argument1 and argument2 are parameters.

OPTION

An input item that is optional, unordered and prefixed by either - (short fornm) or -- (long form).

in the above example : option1, option2 and option3 are options.

options support both the --option value and --option=value syntaxes.

FLAG

An option that does not take any value.

in the above example : --option3 is a flag.

Explicitly separating parameters from options

Normally, an argument in read as an option because it starts with a -. However, than can cause problems in some cases, like multiple-value options or argument values starting with a dash.

Consider the following example:

invalid example

# (INVALID) search events for the past month
argus-cli event search "-1 month" "now"

the intention here is to have the first parameter take a value of -1 month and the second one a value of now, but this will be interpreted as a -1 option with a value of month, a first parameter with a value of now and no second parameter ; which will fail.

In such cases, it is possible to explitly mark the separation between parameters and options using -- with the following rules :

both options and parameters can be used before --

options can only be used before --

anything after -- will be treated as a parameter value

Using this syntax, we can provide a valid version of the above example :

valid example

# (VALID) search events for the past month
argus-cli event search -- "-1 month" "now"

Remember to always use options before --, for example if we wanted to filter the search by customer :

argus-cli event search --customer mnemonic -- "-1 month" "now"

Date arguments

Several commands allow specifying a date/time using a flexible format. Here are some example values that are valid :

"2018-01-01"
"1 hour ago"
"January 1, 2020 10:00 PM EST"
"now"

Date parsing is done using the dateparser library, and more format examples can be found in the parsing function’s documentation : dateparser.parse().

Caution

negative relative dates (like "-1 month") are supported but need commands to be constructed a little differently : see Argument values starting with -