CLI

The CLI talks with Varnish Controller via the REST API but presents the output in a human readable fashion. Most resources can be output as JSON from the CLI using the inspect flag (supported by most resource types).

Resource IDs

When working with the CLI the ID of different resources is used to identify which resources to combine and use. Most CLI commands also support a -v flag to show a verbose output. Most commands also support filtering with the --filter flag.

Filtering

Note that when using filter to commands, it will require the filter to specify the attribute such as --filter "name=*tag*" for tags that have the attribute name. But for Domains that have the attribute FQDN the filter would be --filter "FQDN=*example*". Filtering supports wildcard annotated with a *. Filters can be used as a way of specifying resources without an ID and also perform actions toward multiple resources at the same time.

Sorting output is possible using filter (-f/--filter) with sort keyword, e.g -f sort=timestamp:desc using desc or asc or descending for ascending sorting.

Pagination is also possible using filtering keyword take=<offset>,<entries>. E.g. -f take=2,10 will take 10 entries, skipping first 2.

It is also possible to filter using [gte] (greater or equal) and [lte] (lower or equal) to filter out results. E.g. to filter all agents running on Varnish port lower or equal to 8082: -f varnish_port[lte]=8082.

JSON Output

The VCLI supports JSON output instead of ASCII table. Specifying -j to a command will print the result as JSON output. The JSON output will be the table in JSON format. Hence, the keys in the JSON objects will be the header names with stripped spaces.

CSV Output

Comma separated values (CSV) are also supported by the CLI by specifying --csv to the command. This will print the table in a CSV format. Note that this is the CLI presented table in CSV format, not an actual API response in CSV format.

Self-Signed Certificates

If the API-GW is run with self-signed certificates, the CLI will complain about the certificates if the root CA certificate is missing on the system. In order to login to such configured API-GW there are two options. The preferred option is to specify the root CA certificate for the self-signed certificate. This can be done using the flag --ca <root_ca.pem> to the login command. The other alternative is to not validate the certificate at all, using the --insecure flag to the login command. The latter is not preferred as this is not secure.

Both these options can be specified using environment variables, VARNISH_CONTROLLER_CLI_INSECURE and VARNISH_CONTROLLER_CLI_CA.

System Debug

To collect debug information for the whole Varnish Controller system the CLI can be used.

# Upload a system wide JSON dump to filebin.varnish-software.com
# Link is output once uploaded
vcli debug -u ZD1234

# Output the debug information to a file
vcli debug --file debug.json

The call takes about 5 seconds to complete. This is in order to gather information about all components in the system. The debug information contains last API logs, information about database, memory, CPU, network information, average API call time from API-GW and license information.

Colored Output

The CLI supports ANSI color configuration. This is a manual setup which requires edit of the configuration file.

The configuration file is typically found at ~/.vcli.yml. To enable colors, add the following to the end of the configuration file:

color:
  enabled: true
  header: 36 #cyan
  even: 34 #blue
  odd: 32 #green

Color definitions can be found here (using the FG color codes).

Aliases

Many of the CLI commands have aliases to shorten the command lengths. Each command has a help page that can be viewed by running vcli [command] -h.

Since the CLI is implemented using the REST API all commands that the CLI supports can be created using the API directly.