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

The latest Unix CLI installer is available from this Download Link

Installing the Windows CLI

The Windows CLI ships as an MSI installer. It performs a per-machine install and updates the system PATH, so it requires administrator privileges.

1. Download the .msi from the link above.
2. Run the .msi file and accept the UAC elevation prompt.
   • If a vME CLI from an older, legacy installer is already present on the machine, setup will stop with an error asking you to uninstall the legacy CLI first. This is a one-time step - later vME CLI upgrades won't require it.
3. Step through the setup wizard: accept the license agreement, then click Install.
4. Once installation completes, click Finish to close the wizard.
5. The CLI is installed to C:\Program Files\vME CLI\vme.exe, and that folder is added to the system PATH automatically.
6. If you have a terminal or command prompt window that was already open before running the installer, close it and open a new one. The installer added vme to your PATH, but windows opened before the install won't pick up that change. In the new window, confirm the install:

   vme --help
7. Continue with CLI Login below.

Installing the Unix CLI

After downloading, untar the installer and run the install script:

tar -xzf <downloaded-file>.tar.gz
sudo sh install.sh

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]
• Global help: vme help - lists all top-level resources.
• Resource help: vme <resource> or vme <resource> --help - lists subcommands for that resource, for example vme workflow --help. Each resource has its own help page; this document does not repeat the help output per command.

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
• Example:

  vme pool show

Create a pool

info

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 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.
  • --database_method, -m : optional : Database access method, can be container or network, default is container.
  • --network_info, -N : optional : JSON dictionary for network configuration when database_method is network. Required keys:
    • client_address : IP address of NFS client
    • anonuid : 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 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 -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 is False.
• 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 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 -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 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:
  • --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 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 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 -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 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
  • --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

Export a dataset as an NFS network share so a remote host can mount it.

• Command: vme db network_create <parameters>
• Parameters:
  • --full_name, -f : required : Full dataset path (pool/dataset).
  • --client_address, -a : required : Client IP or subnet allowed to mount the export.
  • --client_username, -u : optional : Client username (default admin).
  • --client_password, -P : optional : Client password (default admin).
  • --anonuid, -U : optional : Anonymous UID for the export (default 117).
  • --anongid, -g : optional : Anonymous GID for the export (default 122).
• Example:

  vme db network_create -f vme-pool/sources/mydb -a 192.168.1.100

Delete Network Database Connection

Remove the NFS network export from a dataset.

• Command: vme db network_delete <parameters>
• Parameters:
  • --full_name, -f : required : Full dataset path (pool/dataset).
• Example:

  vme db network_delete -f 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.
  • --group_id, -g : required : Group ID the user belongs to.
  • --password, -p : required : Required unless auth_type is ldap.
  • --name, -n : optional : Display name.
  • --mail, -m : optional : User email.
  • --auth_type, -a : optional : Authentication type (local, password, ldap).
• Example:

  vme user add -u john.doe -g 2 -p SecurePass123 -n "John Doe" -m john.doe@example.com

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 when auth_type is local/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 keys current, 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 --password is 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 (password or ldap).
• 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 (true or false).
• 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 (true or false).
• 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 (true or false).
• 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

Agent Commands

Agents are lightweight vME worker processes enrolled on other hosts. The agent commands cover three areas: enrollment tokens, registered agents, and agent jobs.

Create Enrollment Token

Generate a one-time token used to enroll a new agent.

• Command: vme agent token_create <parameters>
• Parameters:
  • --ttl_minutes, -t : optional : Token validity in minutes.
  • --label, -l : optional : Human-readable label for the token.
  • --environment, -e : optional : Environment tag.
  • --scope, -s : optional : Scope restriction for the token.
• Example:

  vme agent token_create -l "prod-agent-1" -t 60

List Enrollment Tokens

• Command: vme agent token_list <parameters>
• Parameters:
  • --active_only, -a : optional : Show only active (non-expired, non-revoked) tokens.
• Example:

  vme agent token_list --active_only

Revoke Enrollment Token

• Command: vme agent token_revoke <parameters>
• Parameters:
  • --token_id, -t : required : ID of the token to revoke.
• Example:

  vme agent token_revoke -t abc123

List Agents

List all enrolled agents.

• Command: vme agent list <parameters>
• Parameters:
  • --environment, -e : optional : Filter by environment tag.
  • --enabled, -E : optional : Filter by enabled state (true or false).
  • --status, -s : optional : Filter by agent status.
  • --version, -v : optional : Filter by agent version.
• Example:

  vme agent list -e production

Enable / Disable an Agent

Perform an administrative action on an enrolled agent.

• Command: vme agent patch <parameters>
• Parameters:
  • --agent_id, -a : required : ID of the agent.
  • --action, -A : required : Action to perform, for example enable, disable, or revoke.
• Example:

  vme agent patch -a agent-abc -A disable

Delete an Agent

Permanently remove an agent record.

• Command: vme agent delete <parameters>
• Parameters:
  • --agent_id, -a : required : ID of the agent to delete.
• Example:

  vme agent delete -a agent-abc

Create Agent Job

Dispatch a job to a specific agent.

• Command: vme agent job_create <parameters>
• Parameters:
  • --agent_id, -a : required : ID of the target agent.
  • --phase, -p : required : Job phase identifier.
  • --config, -c : optional : JSON configuration object for the job.
  • --secrets, -s : optional : JSON secrets object passed to the agent.
  • --workflow_id, -w : optional : Workflow this job belongs to.
  • --wizard_step, -W : optional : Wizard step this job corresponds to.
  • --job_type, -j : optional : Job type classification.
  • --role, -r : optional : Role the agent should take for this job.
  • --ingest_path, -i : optional : Path used for data ingest.
• Example:

  vme agent job_create -a agent-abc -p discover

List Agent Jobs

• Command: vme agent job_list <parameters>
• Parameters:
  • --job_id, -j : optional : Filter by job ID.
  • --agent_id, -a : optional : Filter by agent ID.
  • --state, -s : optional : Filter by job state.
  • --workflow_id, -w : optional : Filter by workflow ID.
  • --wizard_step, -W : optional : Filter by wizard step.
  • --job_type, -t : optional : Filter by job type.
  • --role, -r : optional : Filter by role.
  • --ingest_path, -i : optional : Filter by ingest path.
  • --include_events, -e : optional : Include job event history.
  • --limit, -l : optional : Maximum number of results to return.
• Example:

  vme agent job_list -a agent-abc --include_events

Update Agent Job

Update or cancel an in-progress agent job.

• Command: vme agent job_patch <parameters>
• Parameters:
  • --job_id, -j : required : ID of the job to update.
  • --action, -a : required : Action to perform, for example cancel.
• Example:

  vme agent job_patch -j job-xyz -a cancel

Workflow Commands

Workflows orchestrate the end-to-end flow of cloning a database from one vME appliance onto another. A workflow tracks progress through a series of steps (source provisioning, snapshot, send, clone, mount) and holds the configuration and status for the whole operation.

The CLI exposes the read and teardown slice of the workflow API - enough to monitor in-flight workflows and recover from failures. Creating and stepping through a workflow is done in the vME web UI.

List Workflows

• Command: vme workflow list <parameters>
• Parameters:
  • --state, -s : optional : Filter by workflow state (draft, source_provisioning, snapshot, sending, cloning, clone_mounting, completed, failed, cancelled).
  • --created_by, -c : optional : Filter by username who created the workflow.
  • --workflow_type, -t : optional : Filter by workflow type.
  • --source_mode, -S : optional : Filter by source mode.
  • --target_mode, -T : optional : Filter by target mode.
  • --transport_mode, -m : optional : Filter by transport mode.
• Example:

  vme workflow list -s failed

Show Workflow Detail

Show a single workflow including per-step agent job history.

• Command: vme workflow show <parameters>
• Parameters:
  • --workflow_id, -i : required : Workflow ID.
• Example:

  vme workflow show -i a1b2c3d4e5f6

List Workflow Templates

List the available workflow templates (for example, SQL Server over iSCSI). Templates define the dataset roles and agent behaviour for a flow type.

• Command: vme workflow templates <parameters>
• Parameters:
  • --enabled_only, -e : optional : Show only enabled templates.
• Example:

  vme workflow templates

Preview Cleanup Candidates

List the ZFS objects (sources, snapshots, clones) that a delete --cleanup would destroy, across both the local and target vME. Use this before deleting to confirm what will be removed.

• Command: vme workflow cleanup_preview <parameters>
• Parameters:
  • --workflow_id, -i : required : Workflow ID.
• Example:

  vme workflow cleanup_preview -i a1b2c3d4e5f6

Cancel a Workflow

Soft-cancel: sets the workflow state to cancelled. The workflow record and all ZFS objects are kept. Use this to mark a workflow stopped without removing anything.

• Command: vme workflow cancel <parameters>
• Parameters:
  • --workflow_id, -i : required : Workflow ID.
• Example:

  vme workflow cancel -i a1b2c3d4e5f6

Delete a Workflow

Hard-delete: permanently removes the workflow record. Optionally also destroys the ZFS objects (sources, snapshots, clones) on both the local and target vME, in safe dependency order.

• Command: vme workflow delete <parameters>
• Parameters:
  • --workflow_id, -i : required : Workflow ID.
  • --cleanup, -c : optional : Also destroy the workflow's ZFS objects on both vMEs before deleting the record. If any object destruction fails the record is kept so you can retry.
  • --force, -f : optional : Delete the record even if --cleanup reported failures. Use when objects are already gone or you want to remove the record regardless.
  • --objects, -o : optional : Comma-separated list of specific object keys to destroy (from cleanup_preview). Omit to destroy all candidates.
• Example:

  # Delete record only
  vme workflow delete -i a1b2c3d4e5f6
  
  # Delete record and destroy all ZFS objects
  vme workflow delete -i a1b2c3d4e5f6 --cleanup
  
  # Delete record and destroy specific objects, force even on failure
  vme workflow delete -i a1b2c3d4e5f6 --cleanup --force -o clone_data,received_data

Peer Commands

Peer commands manage SSH trust between vME appliances. Two vMEs must be mutually trusted before a zfs send can stream data between them.

To pair two appliances, run vme peer identity on the source, copy the printed public key, then run vme peer trust on the target.

Get This vME's Identity

Return this appliance's managed SSH public key and fingerprint. The key is generated on first call and reused on subsequent calls. Pass this key to vme peer trust on the target appliance.

• Command: vme peer identity
• Parameters:
  • No parameters.
• Example:

  vme peer identity

Trust a Peer's Public Key

Register an SSH public key on this appliance so it will accept zfs receive connections signed by that key. The operation is idempotent - registering the same key twice returns added: false without error.

• Command: vme peer trust <parameters>
• Parameters:
  • --pubkey, -p : required : The SSH public key string to trust (output of vme peer identity on the peer).
  • --label, -l : optional : Human-readable label stored alongside the key in authorized_keys.
• Example:

  vme peer trust -p "ssh-rsa AAAA... vme-peer@source-host" -l "prod-to-dr"