Search
Varnish Controller

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>

Tags

# Create two new tags (system admin)
vcli tags add myTag1 myTag2 

# List all tags 
vcli tags ls

# List all tags with matching name (using filter)
vcli tags ls -f "name=*my*"

# Modify tag name for tag with ID 1 (system admin)
vcli tags update 1 --name myNewName

# Delete a tag by id (cannot be assigned to agent/deployments or it will fail) (system admin)
vcli tags delete 1

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

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

# 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

External Routes

# List external routes
vcli ers ls

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

# 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 /

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 vcl add test.vcl myvcl.vcl

# List all VCLs
vcli vcl ls

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

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

# Remove an VCL by ID 
vcli vcl delete 1

# Discard your draft of the VCL
vcli vcl discard 1

# Diff your draft and deployed source
vcli vcl 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

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.