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>
# 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
# 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
# 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
# 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
# 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 22.214.171.124 --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
# 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
# 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
# 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
# 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
# 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
# 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
# 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
# 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
# List all API logs vcli apilogs ls # Filter out a particular resource and ID vcli apilogs ls -f "keyId=1&keyType=Agent"
# 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 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.