Using the Vamp CLI

Vamp’s command line interface (CLI) can be used to perform most actions against the Vamp API. The CLI was primarily developed to work with continuous delivery (CD) pipelines. In these setups, the CLI can be used to release new deployments from your pipeline.

Npm distribution is at


Vamp CLI EE is a Node.js package. Install it globally and export the host address of your Vamp installation via VAMP_HOST.

npm install -g vamp-cli-ee
export VAMP_HOST=http://vamp-host
vamp --help

You will need to authenticate and provide the correct namespace to further use the CLI

Tokens & Namespaces

To use the CLI, you need have an API token and set the correct namespace. - API token: can be set by export VAMP_TOKEN=<token uuid> or as an CLI argument –token - Namespace: can be set by export VAMP_NAMESPACE=<namespace uuid> or as an CLI argument –namespace

Logging in as a non admin

If you do not have the access rights to create a token, your Vamp admin should provide you with one. Also, you should be provided with the correct namespace UUID.

# Logging in will prompt you to request an API token from your admin
vamp login -u tim -p password
You do not have enough rights to create an API token, please request a token from your Vamp admin. Then add the token
to your request using the "--token [token]" syntax or export as VAMP_TOKEN

# Once you have the token and namespace, you can proceed
export VAMP_TOKEN=3366ca4397f87f5de6bc9b5863f37efb46f4bc6f4d9626e
export VAMP_NAMESPACE=6d1339c7c7a1ac54246a57320bb1dd15176ce29

# You can now use the CLI
vamp list deployments
NAME   CLUSTERS                   PORTS                                                                STATUS
sava   sava, backend1, backend2   sava.webport:40000, backend1.webport:40002, backend2.webport:40001   Deployed

Logging in as an admin

Admins are a bit different from other users: - They can generate their own API access tokens - They can query the organisation namespace for users, roles, tokens, environments etc.

# Logging in when you are an admin sets the admin namespace as default
vamp login -u admin -p password
Login successful

# You can now query the organisation namespace
vamp list users
Bob     qa
Admin   admin
Tim     developer
Jason   developer

# Querying a specific environment artifacts requires setting the namespace. First get a list of the available namespaces
vamp list namespaces
NAME          UUID
test          6d1339c7c7a1ac54246a57320bb1dd15176ce29
prod          51b1a5465f4ea62adf537b4f72bb23dc096ce6ca

# Then set the namespace as cli parameters, or export it as an environment variable, `export VAMP_NAMESPACE=<uuid>`. Bot methods are equivalent.
export VAMP_NAMESPACE=6d1339c7c7a1ac54246a57320bb1dd15176ce29
vamp list deployments
NAME   CLUSTERS                   PORTS                                                                STATUS
sava   sava, backend1, backend2   sava.webport:40000, backend1.webport:40002, backend2.webport:40001   Deployed

Note for Windows users

On Windows, the ‘%’ sign is reserved. The Vamp CLI uses this character when updating the weight on gateways. You need to surround the `--weights command argument with double quotes ", i.e.

vamp update-gateway myDeployment/myService/web --weights "[email protected]%,[email protected]%"


# deploy a blueprint
vamp deploy myService:1.0.0 myDeployment

# get the details of a deployment
vamp describe deployment myDeployment

# merge a blueprint to a running deployment
vamp merge myService:1.1.0 myDeployment

# get the details of a gateway
vamp describe gateway myDeployment/myService/web

# set a condition on specific route in a gateway
vamp update-gateway myDeployment/myService/web --route  myDeployment/myCluster/myService:1.1.0/web --condition "User-Agent == Safari" --strength 100%

# set the weight distribution on set of routes in a gateway
vamp update-gateway myDeployment/myService/web --weights myDeployment/myCluster/myService:1.0.0/[email protected]%,myDeployment/myCluster/myService:1.1.0/[email protected]%

# undeploy a specific service of a deployment
vamp undeploy myDeployment --service myService:1.0.0

# list all the roles
vamp list roles

# using environment variable for token and namespace
export VAMP_TOKEN=14b8a1e541edc87839d288368f0f0b7639509594cd934d61
export VAMP_NAMESPACE=851ff948633b26de75ffea856b1bb10d414df47d
vamp list roles

# see details of a role
vamp describe role admin

# create a role
vamp create role -f createRole.json

# delete a role
vamp delete role myrole2

# list all users
vamp list users

# see details of an user
vamp describe user admin

# create a user
vamp create user -f createUser.json

# delete an user
vamp delete user abc

# list all tokens
vamp list tokens

# see details of a token
vamp describe token mytoken

# create a token
vamp create token -f createToken.json

# delete an user
vamp delete token mytoken

# login
vamp login -u user -p passw0rd

# show stored token
vamp credentials

Using the CLI programmatically

You can include the vamp-cli-ee package in your code. It will expose the api object which you can use to interact with Vamp in your Node.js code. Configure the host by either setting the VAMP_HOST environment variable or pass in a config object with a host entry

const vamp = require('vamp-cli-ee')({ host: 'http://localhost:8080', token: <token>, namespace: <namespace> })

  .then(res =>

.then(res =>

Last updated on September 7, 2018