CLI Examples

The CLI examples are not a complete list of all available commands but lists the most common ones.

The first command for the CLI is to specify an API-GW endpoint to use. This is saved in a CLI configuration file and does not have to be executed again unless the location of the API-GW has changed.

# Example where API-GW runs on localhost port 8002 and login with user 'test' to organization 'myorg'
vcli login http://localhost:8002 -u test -o myorg
Password: ****

# Or using environment variables
VARNISH_CONTROLLER_CLI_PASSWORD=test
VARNISH_CONTROLLER_CLI_USERNAME=test
VARNISH_CONTROLLER_CLI_ORGANIZATION=myorg
VARNISH_CONTROLLER_CLI_ENDPOINT=http://localhost:8002
vcli login

# Specify password using a password file
# The password file should contain the password in clear text on the
# first line in the file.
VARNISH_CONTROLLER_CLI_PASSWORDFILE=<path_to_file>

Agents

# List all agents
vcli agent ls

# List all agents matching name
vcli agents ls -f "name=*server*"

# Assign tag ID 2 to agents with ID 1 and 2 (tags that was created earlier) (system admin)
vcli agents tags 1,2 --tags 2

# Assign tag ID 2 to all agents matching filter (system admin)
vcli agents tags -f "name=*server*" --tags 2

# Delete all tags from an agent with ID 1 (system admin)
vcli agents tags 1 --clear

# Inspect agent with ID 1 as JSON
vcli agent i 1

Routers

# List all routers
vcli router ls

# Assign tags to router
vcli routers tags 1 --tags 2

# Debug information for router with ID 1
vcli router debug 1

# List health check status for routers
vcli router health

# Perform a routing trace for a given IP for a configured domain
vcli router trace 127.0.0.1 example.com

Routing Rules

# List routing rules
vcli rr ls

# Create a new routing rule with some specified options
vcli rr add test --lookup-order=geoip,random,external --dns --http --debug-headers=true

# Update existing routing rule
vcli rr u 1 --lookup-order=geoip,random

# Delete routing rule with ID 1 (that is not in use)
vcli rr delete 1

External Routes

# List external routes
vcli ers ls

# Create a new external route (that can be used with RoutingRules - "external")
vcli ers add cdn1 --base-url http://mycdn.tld --weight 1 --ipv4 1.2.3.4 --health-status 200 --health-interval 1s --health-method GET --health-threshold 3 --health-window-size 5 --health-path /

# Delete existing external route with ID  1
vcli ers delete 1

ASN

# List ASN routes
vcli asnroutes ls

# Create a new ASN route with ASNs connected to a tag with ID 1. Set leastutilized as subdecision.
vcli asnroutes add myASNRoute --asn-to-tag=237:1,238:1 --subdecision=leastutilized

# Update existing ASN route with another tag ID
vcli asnroutes update 1 --asn-to-tag=237:1,238:2

# Update existing ASN route with another tag and use weight(~) as decision.
vcli asnroutes update 1 --asn-to-tag=237:1~1,238:2~2 --subdecision=weight

# Delete ASN route with ID 1 (that is not in use)
vcli asnroutes delete 1

CIDR

# List CIDR routes
vcli cidrroutes ls

# Create a new CIDR route with CIDR connected to a tag with ID 1. Set leastutilized as subdecision.
vcli cidrroutes add myCIDRRoute --cidr-to-tag=127.0.0.1/24:1 --subdecision=leastutilized

# Update existing CIDR route with an other tag ID.
vcli cidrroutes update 1 --cidr-to-tag=127.0.0.1/24:2

# Update existing CIDR route with another tag and use weight(~) as decision.
vcli cidrroutes update 1 --cidr-to-tag=127.0.0.1/24:1~1,127.0.0.1/24:2~2 --subdecision=weight

# Delete CIDR route with ID 1 (that is not in use)
vcli cidrroutes delete 1

Geolocation

# List Geolocation routes
vcli geolocationroutes ls

# Find suggestions on geolocations
vcli geolocationroutes suggestions Swe

# Create a new Geolocation route with Geolocation connected to a tag with ID 1. Set leastutilized as subdecision.
vcli geolocationroutes add myGeoRoute --geolocation-to-tag=Sweden:1 --subdecision=leastutilized

# Create a new Geolocation route with a geolocation name that's not unique.
# London as a city exists in multiple countries, add Geoname ID to specify which London that's
# intended. Geoname ID can be found by the 'vcli geolocationroutes suggestions' call.
vcli geolocationroutes add myGeoRoute --geolocation-to-tag=London:2643743:1

# Update existing Geolocation route with another tag ID.
vcli geolocationroutes update 1 --geolocation-to-tag=London:2643743:2

# Update existing Geolocation route with two tag ID's and use weight as subdecision
vcli geolocationroutes update 1 --geolocation-to-tag=London:2643743:1~1,London:2643743:2~2 --subdecision=weight

# Delete Geolocation route with ID 1 (that is not in use)
vcli geolocationroutes delete 1

Domains

# Create a new domain
vcli domains add example.com

# List all domains
vcli domains ls

# List all domains matching FQDN
vcli domains ls -f "fqdn=*example*"

# Modify a domain
vcli domains update 1 --fqdn example2.com

VCL

# Create and upload a new VCL (filename here is myvcl.vcl and is a file in current directory)
vcli file add test.vcl myvcl.vcl

# List all VCLs
vcli file ls

# List all VCLs with verbose output
vcli file ls -v

# Edit an existing VCL (you will be asked to upload it after you save)
vcli file edit 1

# Remove an VCL by ID
vcli file delete 1

# Discard your draft of the VCL
vcli file discard 1

# Diff your draft and deployed source
vcli file diff 1

Files

# Create and upload a new file (filename here is index.html and is a file in current directory)
vcli files add test.html index.html

# List all files
vcli files ls

# List all files with verbose output
vcli files ls -v

# Edit an existing file (you will be asked to upload it after you save)
vcli files edit 1

# Remove an file by ID
vcli files delete 1

# Discard your draft of the file
vcli files discard 1

# Diff your draft and deployed source
vcli files diff 1

Deployment

# Create a new deployment with name myDep with max instances 2 and minimum 1
# and assign the tag with ID 2 and 3 to it.
vcli deployments add myDep --max 2 --min 1 --tags 2,3

# List all deployments
vcli deployments ls

# Delete an existing deployment
vcli deployments delete 1

Deployments with Wait

This feature is only supported from version 6.2.0.

# Deploy VCLGroup with ID 1 and wait max 60 seconds.
vcli vg deploy 1 -w 60s
# Wait max 30sec and each VG must be deployed to at least 50% of matching servers.
vcli vg deploy 1,2 -w 30s -p 50
# Same as above, but without interactive output (JSON instead)
vcli vg deploy 1,2 -w 30s -j

VCLGroup

# Create a new VCLGroup with name myName using deployment with ID 2, domain with ID 1
# and VCL with ID 2
vcli vg add myName --dep 2 --dom 1 --vcl 2

# Updating a VCLGroup and removing all included VCLs / files.
vcli vg update 1 --clear-inc

# List all VCLGroups
vcli vg ls

# Deploy a VCLGroup
vcli vg deploy 1

# Rollback a VCLGroup
vcli vg rollback 1

# Reload a VCLGroup
vcli vg reload 1

# Stage a VCLGroup on agents matching tag ID 1 and use the VCL with ID 1
# (Note that wer are using VCLGroup ID 1, the VCLGroup we want to stage.)
vcli vg stage 1 --vcl 1 --tags 1

# Delete staged VCLGroup (note that we are using VCLGroup ID 1)
vcli vg delstage 1

# Promote previously staged VCLGroup (Note that we once again refer to VCLGroup ID 1)
vcli vg promote 1

# Undeploy a VCLGroup
vcli vg undeploy 1

# Delete existing VCLGroup (must be undeployed)
vcli vg delete 1

API logs

# List all API logs
vcli apilogs ls

# Filter out a particular resource and ID
vcli apilogs ls -f "keyId=1&keyType=Agent"

Sorting

# List all tags sorted by name
vcli tags ls -fsort=name

# List all tags sorted by id in descending order
vcli tags ls -fsort=id:desc

List Subsets

# List first 3 tags
vcli tags ls -ftake=3

# List 4 tags after offset = 3
vcli tags ls -ftake=4,3

See authorization examples for examples of organization, permissions and account handling.