How to use the vME CLI
Overview & Download
The vME Command Line Interface (CLI) can be used to interact with the vME API from your computer's 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,--username: required : The vME Username.-U,--url: required : The vME Hostname or IP Address.-t,--token: required : The vME User's API key.
- Example:
vme login -u admin -U https://vme.example.com -t fa3e330b-4892-df45-49f2-293a0e13048e
Command Format
- General format:
vme <resource> <command> [options] - Help:
vme help
Run commands from a YAML file
You can provide options from a YAML file using -f / --from-file.
- Command:
vme <resource> -f <file.yaml> - YAML Example:
create:
pool_name: demo-pool
name: demo-source
dbtype: mysql
quota: 10G - CLI Example:
vme source -f source-create.yaml
Pool Commands
Show all pools
- Command:
vme pool show - Parameters:
- No parameters for
vme pool show
- No parameters for
- Example:
vme pool show
Create a pool
Run vme system disks to list available partitions and disks.
- Command:
vme pool create <parameters> - Parameters:
--name,-n: required : The created pool name.--device,-d: required : Path of the device to use for the pool (for example,/dev/nvme1n1).
- Example:
vme pool create -n demo-pool -d /dev/nvme1n1
Destroy a pool
- Command:
vme pool destroy <parameters> - Parameters:
--name,-n: required : The created pool name.
- Example:
vme pool destroy -n demo-pool
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
Register a pool
Register a pool for creation of sources and other operations.
- Command:
vme pool register <parameters> - Parameters:
--name,-n: required : Name of pool to be registered.
- Example:
vme pool register -n vme-pool
Check pool creation status
- Command:
vme pool create_status - Parameters:
- No parameters.
- Example:
vme pool create_status
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 isunknown.--quota,-q: optional : A limit on the amount of disk space a dataset can consume, for example,10Gfor ten GB.--compression,-c: optional : Name of process where data is stored using less disk space, the name can be one ofon,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 isFalse.--database_method,-m: optional : Database access method, can becontainerornetwork, default iscontainer.--network_info,-N: optional : JSON dictionary for network configuration when database_method isnetwork. Required keys:client_address: IP address of NFS clientanonuid: Anonymous user ID (integer)anongid: Anonymous group ID (integer)
-
Example:
vme source create -n demo-source -p demo-pool
Modify a source
Modify source properties including quota, compression, dbtype, and network settings.
- Command:
vme source modify <parameters> - Parameters:
--pool_name,-p: required : Name of pool containing the source.--name,-n: required : Name of source to be modified.--property,-P: required : JSON dictionary of properties to modify. Valid keys:quota: Disk space limit (e.g., "10G")compression: Compression type (on, off, lzjb, gzip, gzip-[1-9], zle, lz4)dbtype: Database type label (mysql, mariadb, mssql, mongodb, etc.)database_method: Database access method (container, network)client_address: NFS client address(es) for network method
- Example:
vme source modify -p vme-pool -n foo -P '{"quota": "5G", "compression": "gzip", "dbtype": "mysql"}'
Rename a source
- Command:
vme source rename <parameters> - Parameters:
--pool_name,-p: required : A name of a pool.--currentname,-c: required : Name of the source to be renamed.--newname,-n: required : New name of the source to be renamed as.
- Example:
vme source rename -p demo-pool -c demo-source -n new-source-name
Destroy a source
- Command:
vme source destroy <parameters> - Parameters:
--pool_name,-p: required : 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
Check source status
- Command:
vme source status - Parameters:
- No parameters.
- Example:
vme source status
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 isPOOLNAME.
- 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 isFalse.
- Example:
vme snapshot create -p demo-pool -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.--newname,-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: required : 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 -p demo-pool -s foo -S new-snap
Rollback a snapshot
- Command:
vme snapshot rollback <parameter> - Parameters:
--pool_name,-p: required : A name of a pool.--source_name,-s: required : A name of a source.--snapshot_name,-S: required : A name of created snapshot.--force,-f: optional : Force option to rollback, default isFalse.
- Example:
vme snapshot rollback -p demo-pool -s foo -S bar -f true
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: optional : Name of pool.--source_name,-s: required : A source name with respect to a<snapshot_name>.--snapshot_name,-S: required : Name of snapshot.--name,-n: required : Name of clone.--size,-z: optional : A size of clone farm, default is1.--dbtype,-d: optional : A database type name, such as mysql, mariadb, mssql, mongodb etc., use to label a clone, default isunknown.
- Example:
vme clone create -s demo-source -S demo-snapshot -n demo-clone
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
Modify a clone
Modify clone properties including quota, compression, dbtype, and network settings.
- Command:
vme clone modify <parameters> - Parameters:
--pool_name,-p: required : Name of pool containing the clone.--name,-n: required : Name of clone to be modified.--property,-P: required : JSON dictionary of properties to modify. Valid keys:quota: Disk space limit (e.g., "10G")compression: Compression type (on, off, lzjb, gzip, gzip-[1-9], zle, lz4)dbtype: Database type label (mysql, mariadb, mssql, mongodb, etc.)database_method: Database access method (container, network)client_address: NFS client address(es) for network method
- Example:
vme clone modify -p vme-pool -n foo-clone -P '{"quota": "10G", "dbtype": "postgres"}'
Destroy a clone
- Command:
vme clone destroy <parameters> - Parameters:
--pool_name,-p: required : Name of pool.--clone_name,-c: required : Name of the clone.--recursive,-r: optional : Recursive delete flag.
- Example:
vme clone destroy -p vme-pool -c foo
Check clone status
Check the status of clone creation operations.
- Command:
vme clone status - Parameters:
- No parameters.
- Example:
vme clone status
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 islatest.--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 isNone. 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:
--image,-i: required : Image name to tag the loaded image.--filename,-f: required : Filename of image to be loaded.
- Example:
vme image load -i mysql:latest -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
Check image status
Check the status of image pull/load operations.
- Command:
vme image status - Parameters:
- No parameters.
- Example:
vme image status
Get image details
Get detailed information about a specific image.
- Command:
vme image detail <parameters> - Parameters:
--name,-n: required : Name of the image.
- Example:
vme image detail -n postgres:latest
Get Docker information
Get Docker version and system information.
- Command:
vme image info - Parameters:
- No parameters.
- Example:
vme image info
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: optional : A container name.--detach,-d: optional : Boolean for running container in the background, default isTrue.--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 in the format"a:b,c:d,...", for example 8080:80 means map port8080on the host to TCP port80in the container, default isNone.
-
Example:
vme container create -i mysql:latest -n foo -p 3307:3306
List all containers
- Command:
vme container list - Parameters:
- No parameters.
- Example:
vme container list
Start a container
- Command:
vme container start <parameters> - Parameters:
--name,-n: required : A container name.
- Example:
vme container start -n foo
Stop a container
- Command:
vme container stop <parameters> - Parameters:
--name,-n: required : A container name.
- Example:
vme container stop -n foo
Execute a command inside the container
- Command:
vme container exec <parameters> - Parameters:
--name,-n: required : A container name.--command,-c: 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,-n: required : A container name.--volume,-v: optional : Remove associated volumes.
- Example:
vme container remove -n foo
Get container log
- Command:
vme container log <parameters> - Parameters:
--name,-n: required : Container name.
- Example:
vme container log -n foo
Get details from container
- Command:
vme container detail <parameters> - Parameters:
--name,-n: required : Container name.
- Example:
vme container detail -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 isunknown.--src,-s: required : Path name of received backup file in.vmebkformat, 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,pool2poolorsys2sys.--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
--keep_snapshot,-k: optional : Keep the temporary snapshot created for send operation. Default is false (snapshot deleted after send).
-
Example:
vme db send -t pool2pool -d demo-pool/sources/sender@now -r '{"pool_name": "vme-pool", "dataset_name": "receiver-snap"}'
Check Send Status
Check the status of a database send operation or view transfer history.
- Command:
vme db send_status <parameters> - Parameters (mutually exclusive - use one):
--task_id,-t: optional : Task ID returned from db send command. Returns status for specific transfer.--dataset,-d: optional : Dataset name (e.g., vme-pool/sources/foo). Returns all transfer history.
- Example:
# Check specific transfer by task ID
vme db send_status -t xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
# View all transfers for a dataset
vme db send_status -d vme-pool/sources/foo
Backup Database
Create a backup of a dataset.
- Command:
vme db backup <parameters> - Parameters:
--dataset,-d: required : Name of dataset to be backup.
- Example:
vme db backup -d vme-pool/sources/foo
List Database Backups
List all available backup files.
- Command:
vme db backup_list - Parameters:
- No parameters.
- Example:
vme db backup_list
Create Network Database Connection
Create a network-based database connection (NFS or iSCSI).
- Command:
vme db network_create <parameters> - Parameters:
--pool_name,-p: required : Name of the pool.--dataset_name,-d: required : Name of the dataset.--dbtype,-D: required : Database type (mysql, postgres, oracle, etc.).--network_type,-n: required : Network type (nfsoriscsi).--target_host,-t: required : Target host IP or hostname.--target_user,-u: required : Target host username.
- Example:
vme db network_create -p vme-pool -d sources/mydb -D postgres -n nfs -t 192.168.1.100 -u dbuser
Delete Network Database Connection
Delete a network-based database connection.
- Command:
vme db network_delete <parameters> - Parameters:
--dataset,-d: required : Full dataset path (pool/dataset).
- Example:
vme db network_delete -d vme-pool/sources/mydb
Log Commands
List Log Files
List all available log files.
- Command:
vme log list - Parameters:
- No parameters.
- Example:
vme log list
Show Log Content by ID
Display log content by log ID.
- Command:
vme log show <parameters> - Parameters:
--logid,-l: required : Log ID to retrieve.
- Example:
vme log show -l 123
Get Log Content by ID
Alias for vme log show.
- Command:
vme log get <parameters> - Parameters:
--logid,-l: required : Log ID to retrieve.
- Example:
vme log get -l 123
User Management Commands
Add User
Create a new user account.
- Command:
vme user add <parameters> - Parameters:
--username,-u: required : Username for the new user.--name,-n: required : Display name.--mail,-m: required : User email.--auth_type,-a: optional : Authentication type (local,password,ldap).--password,-p: conditionally required : Required whenauth_typeislocal/password(or omitted).
- Example:
vme user add -u john.doe -n "John Doe" -m john.doe@example.com -p SecurePass123
Get Current User Info
Get information for the currently authenticated user.
- Command:
vme user info - Parameters:
- No parameters.
- Example:
vme user info
List Users
List all users (admin endpoint).
- Command:
vme user list - Parameters:
- No parameters.
- Example:
vme user list
Admin Add User
Create a user using the admin endpoint.
- Command:
vme user admin_add <parameters> - Parameters:
--username,-u: required : Username for the new user.--name,-n: required : Display name.--mail,-m: required : User email.--group_id,-g: optional : Group ID (default backend behavior applies).--auth_type,-a: optional : Authentication type (local,password,ldap).--password,-p: conditionally required : Required whenauth_typeislocal/password(or omitted).
- Example:
vme user admin_add -u jane.doe -n "Jane Doe" -m jane.doe@example.com -g 2 -p SecurePass123
Admin List Users
List users using admin endpoint.
- Command:
vme user admin_list - Parameters:
- No parameters.
- Example:
vme user admin_list
Modify User
Modify an existing user account.
- Command:
vme user modify <parameters> - Parameters:
--username,-u: required : Username to modify.--current_password,-c: required : Current password for verification.--name,-n: optional : New display name.--mail,-m: optional : New email.--rotate_api_key,-r: optional : Rotate API key (true/false).--password,-p: optional : Password update object with keyscurrent,new,confirm.
- Example:
vme user modify -u john.doe -c CurrentPass123 -n "John D."
Admin Modify User
Modify a user using admin endpoint.
- Command:
vme user admin_modify <parameters> - Parameters:
--username,-u: required : Username to modify.- At least one of the following is required:
--name,--mail,--group_id,--rotate_api_key,--auth_type,--password. --password,-p: optional : New password.--auth_type,-a: required when--passwordis provided.
- Example:
vme user admin_modify -u john.doe -g 2
Delete User
Delete a user account.
- Command:
vme user delete <parameters> - Parameters:
--username,-u: required : Username to delete.--password,-p: required : Password for verification.--confirm_text,-c: required : Confirmation text (for example:DELETE john.doe).--method,-m: optional : Auth method (passwordorldap).
- Example:
vme user delete -u john.doe -p SecurePass123 -c "DELETE john.doe"
Admin Delete User
Delete a user using admin endpoint.
- Command:
vme user admin_delete <parameters> - Parameters:
--username,-u: required : Username to delete.
- Example:
vme user admin_delete -u john.doe
Set User Group
Assign a user to a specific group.
- Command:
vme user setgroup <parameters> - Parameters:
--username,-u: required : Username to update.--password,-p: required : Password for verification.--group_id,-g: required : Group ID to assign.
- Example:
vme user setgroup -u john.doe -p SecurePass123 -g 3
List Groups
List all user groups.
- Command:
vme user group_list - Parameters:
- No parameters.
- Example:
vme user group_list
Add Group
Create a new user group.
- Command:
vme user group_add <parameters> - Parameters:
--group_id,-g: required : Group ID for the new group.--group_name,-n: required : Name of the new group.
- Example:
vme user group_add -g 5 -n developers
Delete Group
Delete a user group.
- Command:
vme user group_delete <parameters> - Parameters:
--group_id,-g: required : Group ID to delete.
- Example:
vme user group_delete -g 5
Get LDAP Settings
Retrieve current LDAP configuration.
- Command:
vme user ldap_get - Parameters:
- No parameters.
- Example:
vme user ldap_get
Create LDAP Settings
Create LDAP authentication settings.
- Command:
vme user ldap_create <parameters> - Parameters:
--host,-h: required : LDAP server hostname or IP.--port,-p: required : LDAP server port.--base_dn,-b: required : Base DN for LDAP searches.--bind_dn,-d: required : Bind DN for LDAP authentication.--bind_password,-P: required : Password for bind DN.--user_filter,-u: required : LDAP user filter (e.g.,(uid=%s)).--enabled,-e: required : Enable or disable LDAP (trueorfalse).
- Example:
vme user ldap_create -h ldap.example.com -p 389 -b "dc=example,dc=com" -d "cn=admin,dc=example,dc=com" -P AdminPass123 -u "(uid=%s)" -e true
Update LDAP Settings
Update LDAP authentication settings.
- Command:
vme user ldap_update <parameters> - Parameters:
--host,-h: required : LDAP server hostname or IP.--port,-p: required : LDAP server port.--base_dn,-b: required : Base DN for LDAP searches.--bind_dn,-d: required : Bind DN for LDAP authentication.--bind_password,-P: required : Password for bind DN.--user_filter,-u: required : LDAP user filter (e.g.,(uid=%s)).--enabled,-e: required : Enable or disable LDAP (trueorfalse).
- Example:
vme user ldap_update -h ldap.example.com -p 636 -b "dc=example,dc=com" -d "cn=admin,dc=example,dc=com" -P AdminPass123 -u "(uid=%s)" -e true
Delete LDAP Settings
Delete LDAP configuration.
- Command:
vme user ldap_delete - Parameters:
- No parameters.
- Example:
vme user ldap_delete
Test LDAP Settings
Test LDAP connection without saving.
- Command:
vme user ldap_test <parameters> - Parameters:
--host,-h: required : LDAP server hostname or IP.--port,-p: required : LDAP server port.--base_dn,-b: required : Base DN for LDAP searches.--bind_dn,-d: required : Bind DN for LDAP authentication.--bind_password,-P: required : Password for bind DN.--user_filter,-u: required : LDAP user filter (e.g.,(uid=%s)).--enabled,-e: required : Enable or disable LDAP (trueorfalse).
- Example:
vme user ldap_test -h ldap.example.com -p 389 -b "dc=example,dc=com" -d "cn=admin,dc=example,dc=com" -P AdminPass123 -u "(uid=%s)" -e true
Backward-Compatible LDAP Alias
vme user ldap_setting is kept as an alias of vme user ldap_create.
System Commands
System Info
- Command:
vme system info - Parameters:
- No parameters.
- Example:
vme system info
System Version
- Command:
vme system version - Parameters:
- No parameters.
- Example:
vme system version
Upload License Key
- Command:
vme system key_drop <parameters> - Parameters:
--secret,-s: required : License key secret.--renew,-r: optional : Renew flag.
- Example:
vme system key_drop -s YOUR_LICENSE_KEY
Get License Key Status
- Command:
vme system key_get - Parameters:
- No parameters.
- Example:
vme system key_get
List ZFS Disks
- Command:
vme system disks - Parameters:
- No parameters.
- Example:
vme system disks
Set iSCSI CHAP
Configure CHAP / mutual CHAP for a target and initiator pair.
- Command:
vme system iscsi_chap_set <parameters> - Parameters:
--target_iqn,-t: required : iSCSI target IQN.--initiator_iqn,-i: required : iSCSI initiator IQN.--chap_user,-u: optional : CHAP username.--chap_password,-p: optional : CHAP password.--mutual_chap_password,-m: optional : Mutual CHAP password.
- Example:
vme system iscsi_chap_set -t iqn.2025-01.local:target1 -i iqn.2025-01.local:init1 -u admin -m mutualSecret123
Remove iSCSI CHAP
Remove CHAP / mutual CHAP settings for a target and initiator pair.
- Command:
vme system iscsi_chap_remove <parameters> - Parameters:
--target_iqn,-t: required : iSCSI target IQN.--initiator_iqn,-i: required : iSCSI initiator IQN.
- Example:
vme system iscsi_chap_remove -t iqn.2025-01.local:target1 -i iqn.2025-01.local:init1
Task Commands
Check Task Status
- Command:
vme task status <parameters> - Parameters:
--task_id,-t: required : Task ID to query.
- Example:
vme task status -t 6c9d1f3b-6c0b-4b8e-9f64-1b1c0f8d24a2