Skip to main content

How to use the vME CLI

Overview & Download​

The vME Command Line Interface (CLI) can be utilised to interact with the vME API from your computers command line.

The latest Windows CLI installer is available from this Download Link

CLI Login​

To login to a vME instance using the installed CLI.

Open a terminal or command prompt

  • Command: vme login -u admin -U <IP ADDRESS or DNS NAME> -t <API KEY>
  • Parameters:
    • -u : required : The vME Username.
    • -U : required : The vME Hostname or IP Address.
    • -t : required : the vME User's API key.
  • Example: 
    vme login -u admin -U https://vme.example.com -t fa3e330b-4892-df45-49f2-293a0e13048e

Pool Commands​

Show all pools​

  • Command: vme pool show
  • Parameters:
    • No parameters for vme pool show
  • Example: 
    vme pool show

Create a pool​

  • Command: vme pool create <parameters>
  • Parameters:
    • --name, -n : required : The created pool name.
    • --device, -d : optional : A path of device, default is <empty_string>. If device is empty string or not found the given device, the device will be generated with the following details:
  • Example: 
    vme pool create -n demo-pool

Destroy a pool​

  • Command: vme pool destroy <parameters>
  • Parameters:
    • --name, -n : required : The created pool name.
  • Example: 
    vme pool destroy -n demo-pool

Show pool creation logs​

  • Command: vme pool log
  • Parameters:
    • No parameters for vme pool log.
  • Example: 
    vme pool log

Show current status of a pool​

  • Command: vme pool status <parameters>
  • Parameters:
    • --name, n : required : The name of the pool to show status on.
  • Example: 
    vme pool status -n demo-pool

Show history of a pool​

  • Command: vme pool history <parameters>
  • Parameters:
    • --name, n : required : The name of the pool to run the history command on.
  • Example: 
    vme pool history -n demo-pool

Source Commands​

Show all sources​

  • Command: vme source show <parameters>
  • Parameters:
    • --pool_name, -p : optional : A name of a pool.
  • Example: 
    vme source show -p demo-pool

Create a source​

  • Command: vme source create <parameters>

  • Parameters:

    • --pool_name, -p : required : A name of a pool.
    • --name, -n : required : A name of created source.
    • --dbtype, -d : optional : A database type name, such as mysql, mariadb, mssql, mongodb etc., use to label a source, default is unknown.
    • --quota, -q : optional : A limit on the amount of disk space a dataset can consume, for example, 10G for ten GB.
    • --compression, -c : optional : Name of process where data is stored using less disk space, the name can be one of on, off, lzjb, gzip, gzip-1, gzip-2, gzip-3, gzip-4, gzip-5, gzip-6, gzip-7, gzip-8, gzip-9, zle, lz4, False, default is False.

  • Example:

    vme source create -n demo-source

Destroy a source​

  • Command: vme source destroy <parameters>
  • Parameters:
    • --pool_name, -p : optional : A name of a pool.
    • --source_name, -s : required : Name of the source to be destroyed.
  • Example: 
    vme source destroy -p vme-pool -s demo-source

Rename a source​

  • Command: vme source rename <parameters>
  • Parameters:
    • --pool_name, -p : required : A name of a pool.
    • --source_name, -s : required : Name of the source to be renamed.
    • --new_name, -n : required : New name of the source to be renamed as.
  • Example: 
    vme source rename -p demo-pool -s demo-source -n new-source-name

Snapshot Commands​

Show all snapshots​

  • Command: vme snapshot show <parameters>
  • Parameters:
    • --pool_name, -p : optional : A name of a pool.
    • --source_name, -s : optional : A name of a base source, default is POOLNAME.
  • Example: 
    vme snapshot show -p demo-pool

Create a snapshot​

  • Command: vme snapshot create <parameters>
  • Parameters:
    • --pool_name, -p : required : A name of a pool.
    • --source_name, -s : required : A name of a source.
    • --name, -n : required : A name of created snapshot.
    • --recursive, -r : optional : Recursive option, default is False.
  • Example: 
    vme snapshot create -s foo -n new-snap

Rename a snapshot​

  • Command: vme snapshot rename <parameters>
  • Parameters:
    • --pool_name, -p : required : Name of the pool to rename.
    • --source_name, -s : required : Name of a source which the snapshot belongs to.
    • --currentname, -c : required : Name of snapshot/bookmark to be renamed.
    • --new_name, -n : required : Name of the snapshot to rename.
  • Example: 
    vme snapshot rename -s foo -p demo-pool -n new-snap -c snap

Destroy a snapshot​

  • Command: vme snapshot destroy <parameter>
  • Parameters:
    • --pool_name, -p : optional : A name of a pool.
    • --source_name, -s : required : A name of a source.
    • --snapshot_name, -S : required : The name of snapshot to destroy.
  • Example: 
    vme snapshot destroy -s foo -n new-snap

Rollback a snapshot​

  • Command: vme snapshot rollback <parameter>
  • Parameters:
    • --pool_name, -p : optional : A name of a pool.
    • --source_name, -s : required : A name of a source.
    • --snapshot_name, -S : required : A name of created snapshot.
    • --force, -r : optional : Force option to rollback, default is False.
  • Example: 
    vme snapshot rollback -p demo-pool -s foo -S bar -r foo

Clone Commands​

Show all clones​

  • Command: vme clone show <parameters>
  • Parameters:
    • --pool_name, -p : optional : Name of pool.
    • --source_name, -s : optional : Name of source.
    • --snapshot_name, -S : optional : Name of snapshot.
  • Example: 
    vme clone show -p demo-pool -s demo-source -s demo-snapshot

Create a clone​

  • Command: vme clone create <parameters>
  • Parameters:
    • --pool_name, -p : required : Name of pool.
    • --name, -n : required : Name of clone.
    • --snapshot_name, -s : required : Name of snapshot.
    • --source_name, -S : required : A source name with respect to a <snapshot_name>.
    • --size, -z : optional : A size of clone farm, default is 1.
    • --dbtype, -d : optional : A database type name, such as mysql, mariadb, mssql, mongodb etc., use to label a clone, default is unknown.
  • Example: 
    vme clone create -p demo-pool -s demo-clone -s demo-snapshot -S /full/path/to/demo-snapshot

Rename a clone​

  • Command: vme clone rename <parameters>
  • Parameters:
    • --pool_name, -p : required : Name of pool.
    • --newname, -n : required : New name of the clone.
    • --currentname, -c : required : Current name of the clone.
  • Example: 
    vme clone rename -p vme-pool -c foo -n bar

Destroy a clone​

  • Command: vme clone destroy <parameters>
  • Parameters:
    • --pool_name, -p : required : Name of pool.
    • --clone_name, -c : required : Name of the clone.
  • Example: 
    vme clone destroy -p vme-pool -c foo

Docker Image Commands​

Pull an image​

  • Command: vme image create <parameters>
  • Parameters:
    • --repository, -r : required : The repository to pull.
    • --tag, -t : optional : The tag to pull, default is latest.
    • --dbtype, -d : optional : A database type name, such as mysql, mariadb, mssql, mongodb etc., use to label an image, default is <repository>.
    • --credential, -c : optional : Information used to verify repository accession, default is None. Must be valid JSON.
  • Example: 
    vme image create -r mysql -t 8.0

Register an image​

  • Command: vme image register <parameters>
  • Parameters:
    • --name, -n : required : Name of image to be registered.
    • --dbtype, -d : optional : A database type name, such as mysql, mariadb, mssql, mongodb etc., use to label an image, default is <repository>.
  • Example: 
    vme image register -n mysql:latest

List all images​

  • Command: vme image list
  • Parameters:
    • No Parameters.
  • Example: 
    vme image list

Save an image​

  • Command: vme image save <parameters>
  • Parameters:
    • --image, -i : required : The image to save.
    • --filename, -f : required : Filename of saved image, the tar file will be saved at /home/vme/uploads.
  • Example: 
    vme image save -i mysql:latest -f myimage.tar

Load an image​

  • Command: vme image load <parameters>
  • Parameters:
    • --filename, -f : required : Filename of image to be loaded.
  • Example: 
    vme image load -f myimage.tar

Remove an image​

  • Command: vme image remove <parameters>
  • Parameters:
    • --image, -i : required : The image to remove.
  • Example: 
    vme image remove -i mysql:latest

Docker Container Commands​

Create a Container​

Create a container via /docker/container/create. Similar to the docker run command.

  • Command: vme container create <parameters>

  • Parameters:

    • --image, -i : required : An image name.
    • --name, -n : required : A container name.
    • --detach, -d : optional : Boolean for running container in the background, default is True.
    • --command, -c : optional : The command to run in the container.
    • --environment, -e : optional : Environment variables to set inside the container, as a dictionary or a list of strings in the format ["SOMEVARIABLE=xxx"].
    • --volumes, -v : optional : A list or dictionary to configure volumes mounted inside the container.
    • --ports, -p : optional : Ports to bind inside the container. It can be integer or list of integers.
    • --dbtype, D : optional : A database type name, such as mysql, mariadb, mssql, mongodb etc., use to label a container, default is <dbtype_of_image>.
    • --ports, p : optional : Ports to bind inside the container in the format "a:b,c:d,...", for example 8080:80 means map port 8080 on the host to TCP port 80 in the container, default is None.

  • Example:

    vme container create -i mysql:latest -n foo

List all containers​

  • Command: vme container list
  • Parameters:
    • No parameters.
  • Example: 
      vme container list

Start a container​

  • Command: vme container start <parameters>
  • Parameters:
    • name : required : A container name.
  • Example: 
    vme container start -n foo

Stop a container​

  • Command: vme container stop <parameters>
  • Parameters:
    • name : required : A container name.
  • Example: 
    vme container stop -n foo

Execute a command inside the container​

  • Command: vme container exec <parameters>
  • Parameters:
    • name : required : A container name.
    • command : required : A string or list of commands to be executed.
  • Example: 
    vme container exec -n foo -c "ls -l"

Remove a container​

  • Command: vme container remove <parameters>
  • Parameters:
    • name : required : A container name.
  • Example: 
    vme container remove -n foo

Get container log​

  • Command: vme container log <parameters>
  • Parameters:
    • name : required : Container name.
  • Example: 
    vme container log -n foo

Database commands​

Connect Database​

Testing connection to database.

  • Command: vme db connect <parameters>
  • Parameters:
    • --dbtype, -d : required : Type of database to connect to.
    • --host, -h : required : Host IP of the database server to connect to.
    • --user, -u : required : Username for the database.
    • --password, -p : required : Password for the user of the database.
    • --port, -P : required : Port to connect to on the database.
  • Example: 
    vme db connect -d mariadb -h localhost -u foo -p bar -P 3306

Receive Database​

Receive backup and restore dataset.

  • Command: vme db receive <parameters>
  • Parameters:
    • --pool_name, -p : required : Name of pool.
    • --dataset_name, -d : required : Name of dataset to be restored.
    • --dbtype, -D : optional : Database type, such as mysql, mariadb, mssql, mongodb etc., used to label a source, default is unknown.
    • --src, -s : required : Path name of received backup file in .vmebk format, the default absolute path is /enov8/vme/data/<filename> when only the filename is provided.
  • Example: 
    vme db receive -p vme-pool -d mydata -D mariadb -s dataset.vmebk

Send Database​

Send dataset.

  • Command: vme db send <parameters>

  • Parameters:

    • --type, -t : required : Sending type, pool2pool or sys2sys.
    • --dataset, -d : required : Name of dataset to be send.
    • --receiver, -r : required : Information of receiver contains pool_name, dataset_name, and other verification info for receiver. Must be valid JSON dictionary. JSON fields for sys2sys are:
      • address
      • username
      • identity_file
      • api-key
      • pool_name
      • dataset_name
    • For pool2pool
      • pool_name
      • dataset_name

  • Example:

    vme db send -t pool2pool -d demo-pool/sources/sender@now -r "{"pool_name": "vme-pool", "dataset_name": "receiver-snap"}"

Backup Database​

Get all backup filenames.

  • Command: vme db receive <parameters>
  • Parameters:
    • --dataset, -d : required : Name of dataset to be backup.
  • Example: 
    vme db receive -p vme-pool -d mydata -D mariadb -s dataset.vmebk