Managing Virts with the CLI

This section details how to manage virtual services using the VirtServer command-line interface (CLI). It includes instructions for deploying services, starting and stopping them, updating properties, handling tags, and undeploying services. Additionally, it covers user management tasks such as adding, removing, and editing users. Use these commands to efficiently administer virtual services and user accounts on VirtServer.

Deploy a virtual service to VirtServer

The following command deploys a virtual service (virtual API) to VirtServer:

<path>/virtserver-cli -d project -n virt-name [-p virt-port] [-a true/false] [-r] [-ppw project-password] -s IP:port
Example

For a non-composite project:

"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat" -d "c:\my projects\sample-soap-project.xml" -n "My Service1" -p 8088 -s 10.0.81.128:9090

For a composite project:

"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat" -d "c:\my projects\sample-composite-project" -n "My Service1" -p 8088 -s 10.0.81.128:9090

Important

Before running any commands on VirtServer, you must log in using the -login command.

Important

Result value: The command returns the deployment id for your virtual service. This id is used by other operations that work with virtual services on VirtServer.

Tip

To deploy all virtual services from a project file, use the -deployall command.

The command uses the following arguments:

Argument

Description

-d project-file-name, or

--deploy project-file-name

Required. The fully-qualified name of the ReadyAPI project file or the path to the composite project folder that contains your virtual service. If the name contains spaces, enclose it in quotes.

Note: You can deploy virtual services from composite projects only in ReadyAPI 3.1 or later.

-n virt-name, or

--name virt-name

Required. The name of the virtual service to deploy. If the name contains spaces, enclose it in quotes.

-p port-number, or

--port port-number

Optional. Specifies the port the virtual service will use on VirtServer. This port must be free in order for the virtual service to be able to run. If you skip this parameter, VirtServer will try to use the port specified by the service settings.

You can reassign the port number from the VirtServer UI or ReadyAPI UI, or from the command line.

-a true, or

--autostart true

Optional. true or false, default – false. If this parameter is true, VirtServer starts the virtual service automatically after the deployment, and every time VirtServer starts. If the parameter is false, you will have to start the service yourself.

-r, or

--replace

If this parameter is used, the virtual service will replace an existing service with the same name that was deployed to your VirtServer earlier.

-ppw password, or--projectpassword password

Must be used for encrypted projects. Specifies the project password to decrypt the project.

-s IP:port, or

‑‑server IP:port

Optional. Specifies the IP address and port of the VirtServer instance.

If you omit this argument, the utility uses the address specified in the previous command.

Deploy all virtual services from a project

The following command deploys all virtual services (virtual APIs) from a project to VirtServer:

<path>/virtserver-cli -deployall project [-p virt-port] [-a true/false] [-r] [-ppw project-password] -s IP:port
Example

For a non-composite project:

"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat" -deployall "c:\my projects\sample-soap-project.xml" -p 8088 -s 10.0.81.128:9090

For a composite project:

"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat" -d "c:\my projects\sample-composite-project" -p 8088 -s 10.0.81.128:9090

Important

Before running any commands on VirtServer, you must log in using the -login command.

Important

Result value: The command returns the deployment ids for your virtual services. These ids are used by other operations that work with virtual services on VirtServer.

Tip

To deploy one virtual service from a project file, use the -deploy command.

The command uses the following arguments:

Argument

Description

-deployall project-file-name, or

--deployall project-file-name

Required. The fully-qualified name of the ReadyAPI project file or the path to the composite project folder that contains your virtual services. If the name contains spaces, enclose it in quotes.

Note: You can deploy virtual services from composite projects only in ReadyAPI 3.1 or later. We added support for zipped project in VirtServer 3.13.

-p port-number, or

--port port-number

Optional. Specifies ports the virtual services will use on VirtServer. If you skip this parameter, VirtServer will try to use the port specified by the service settings.

Important

All the deployed virtual services will have the same port number. Make sure the Path properties of the virtual services have different values. Otherwise, you cannot run them concurrently (for example, by using the -a true argument).

You can reassign the port number from the VirtServer UI or ReadyAPI UI, or from the command line.

-a true, or

--autostart true

Optional. true or false, default – false. If this parameter is true, VirtServer starts virtual services automatically after the deployment, and every time VirtServer starts. If the parameter is false, you will have to start the service yourself.

-r, or

--replace

Use this parameter to replace existing virtual services that have the same names as virtual services you are deploying.

-ppw password, or--projectpassword password

Must be used for encrypted projects. Specifies the project password to decrypt the project.

-s IP:port, or

‑‑server IP:port

Optional. Specifies the IP address and port of the VirtServer instance.

If you omit this argument, the utility uses the address specified in the previous command.

Deploy several virtual services with the same name but different ports

You can deploy several virtual services with the same name but different ports on one VirtServer. This is managed through the CLI.

Argument

Description

--clone or short -c virt-name

You can add it to the deploy command. A new deployment will be created based on the same virt. All old deployments will stay the same. This option is not allowed to be combined with --replace or short -r. That will cause an error.

--replace or short -r virt-name

All deployments based on that virt will be replaced. The meta data for these virts (e.g. port) will stay the same.

When deploying, if there already is a deployment from this virt on the server, it will do one of three things:

  • If neither --replace or --clone is present, an error will occur saying to use --replace is needed to replace.

    (I see now that this message could be updated to mention --clone). No changes will be performed at all.

  • If --replace is present, all deployments based on that virt will be replace. The meta data for these (like port) will stay the same.

  • If --clone is present, a new deployment will be created based on the same virt. All old deployments will stay the same.

To deploy to your VirtServer, use the following command format:

<path>/virtserver-cli -c virt-name IP:port

Start and stop virtual services on VirtServer

To start a virtual service that you deployed to VirtServer, use the following command:

<path>/virtserver-cli -start deployment-id -s IP:port

To stop a working virtual service, use the following command:

<path>/virtserver-cli -stop deployment-id -s IP:port

To stop a working virtual service, use the following command:

<path>/virtserver-cli -stopall -s IP:port
Example
"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat" -start 39 -s 192.168.1.10:9090
"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat" -stop 39 -s 192.168.1.10:9090

Important

Before running any commands on VirtServer, you must log in using the -login command.

Argument

Description

-start deployment-id, or--start deployment-id,-stop deployment-id, or--stop deployment-id

Commands VirtServer to start or stop a virtual service. The deployment-id value is the identifier that VirtServer assigned to your virtual service when you deployed it to VirtServer. If you forget it, you can get it later by using the -ls parameter.

-s IP:port, or

‑‑server IP:port

Optional. Specifies the IP address and port of the VirtServer instance.

If you omit this argument, the utility uses the address specified in the previous command.

Notes:

  • Before starting a virtual service on VirtServer, you need to deploy this virtual service to VirtServer.

  • The commands above start and stop individual virtual services. You can start and stop multiple services by their tag values.

  • You can command VirtServer to start a virtual service automatically by using the -a true parameter when deploying the service to VirtServer.

Get a list of virtual services

To obtain information on virtual services deployed to your VirtServer, use the following command:

<path>/virtserver-cli -ls -s IP:port

The command returns a list of virtual services and their deployment identifiers – unique values used to work with services on VirtServer.

Important

Before running any commands on VirtServer, you must log in using the -login command.

Argument

Description

-ls, or --list

Commands VirtServer to output information on the virtual services that were deployed to this VirtServer.

-s IP:port, or

‑‑server IP:port

Optional. Specifies the IP address and port of the VirtServer instance.

If you omit this argument, the utility uses the address specified in the previous command.

Change the virtual service properties

To change a virtual service port on VirtServer, or to change the Autostart property of a service, use a command line like this:

<path>/virtserver-cli -update deployment-id [-p new-port] [-a true/false] -s IP:port

For example:

"c:\Program Files\SmartBear\VirtServer\virtserver-cli.bat" -update 39 -p 8080 -u John -pw pswd1 -s 10.0.81.128:9090

Important

Before running any commands on VirtServer, you must log in using the -login command.

Argument

Description

-update deployment-id, or--update deployment-id

Commands VirtServer to change the parameters of a virtual service that the deployment id specifies. deployment-id is the identifier that VirtServer assigned to your virtual service when you deployed it to VirtServer. You can get it by using the -ls parameter.

-p port-number, or

--port port-number

Optional. Specifies the new port number that the virtual service will use on VirtServer. The port must be free in order for the virtual service to be able to run.

You can also reassign the port number in the VirtServer UI or ReadyAPI UI.

-a true, or

--autostart true

Optional. Specifies the Autostart property of the virtual service, can be true or false. If true, VirtServer will start the service automatically when VirtServer starts.

-s IP:port, or

‑‑server IP:port

Optional. Specifies the IP address and port of the VirtServer instance.

If you omit this argument, the utility uses the address specified in the previous command.

Assign and unassign tags

The virtserver-cli utility supports a number of arguments to help you assign tags to virtual services and remove tags from them:

Argument

Description

-at deployment-id tag, or--assignTag deployment-id tag

Assigns a tag to the virtual service specified by its deployment id. If the tag does not exist on the VirtServer side, it is created.

-ct tag, or--createTag tag

Creates a tag on VirtServer, but does not assign it to any virtual service.

-dt tag, or--deleteTag tag

Deletes the specified tag from VirtServer. If a tag is assigned to some virtual service, it is removed from this service.

-uat deployment-id tag, or--unAssignTag deployment-id tag

Removes a tag from the specified virtual service.

-ut old-tag new-tag, or--updateTag old-tag new-tag

Replaces an existing tag with a new one on VirtServer. If the existing tag is assigned to some virtual services, this command will replace it with a new tag on all these services.

-s IP:port, or

‑‑server IP:port

Optional. Specifies the IP address and port of the VirtServer instance.

If you omit this argument, the utility uses the address specified in the previous command.

Notes:

  • Before running any commands on VirtServer, you must log in using the -login command.

  • If a tag name includes spaces, enclose it in quotes.

  • Deployment id is the identifier that VirtServer assigns to your virtual service when you deploy it to VirtServer. If you forget it, you can check it at any time later.

Examples:

  • Assigns the new tag “My tag” to a virtual service with the ID 39:

    "c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat" -at 39 "My tag" -s 192.168.1.56:9090

  • Removes a tag from all the virtual services, to which it is assigned, and from VirtServer:

    "c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat" -dt "My tag" -s 192.168.1.56:9090

  • Updates the tag value:

    "c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat" -ut "My tag" "New tag" -s 192.168.1.56:9090

Start and stop virtual services by tags

To start and stop multiple services by their tags, use the following commands:

<path>/virtserver-cli -startwt tag -s IP:port
<path>/virtserver-cli -stopwt tag -s IP:port

For example:

"c:\Program Files\SmartBear\VirtServer\bin\virtserver.bat -startwt "My tag" -s 192.168.1.10:9090

Argument

Description

-startwt tag, or --startWithTag tag,-stopwt tag, or--stopWithTag tag

Commands VirtServer to start or stop all virtual services to which the specified tag is assigned.

Note: If the tag name includes spaces, enclose it in quotes.

-s IP:port, or

‑‑server IP:port

Optional. Specifies the IP address and port of the VirtServer instance.

If you omit this argument, the utility uses the address specified in the previous command.

Notes:

  • Before running any commands on VirtServer, you must log in using the -login command.

  • Before starting a virtual service on VirtServer, you need to deploy this virtual service to your instance of VirtServer.

  • The commands work with one tag only. If you want to start or stop virtual services that have different tags assigned, call the commands several times – once per each tag.

  • To start and stop individual services, you can also use the -start and -stop commands. See above.

Undeploy all virtual services from VirtServer

To remove all virtual services from VirtServer, use the following command line:

<path>/virtserver-cli -deleteall -s IP:port
Example

Hide example

"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat" -deleteall -s 10.0.81.128:9090

Important

Before running any commands on VirtServer, you must log in using the -login command.

Tip

To undeploy one virtual service, use the -delete command.

Argument

Description

-deleteall, or--deleteall

Commands VirtServer to remove all virtual services from your VirtServer instance.

-s IP:port, or

--server IP:port

Optional. Specifies the IP address and port of the VirtServer instance.

If you omit this argument, the utility uses the address specified in the previous command.

--deleteall /path/to/projectfile

To revert deployment of virtual services in a specific project, add the project identifier to --deleteall in CLI so that only virtual services in that project are removed.

Undeploy a virtual service from VirtServer

To remove a virtual service from VirtServer, use the following command line:

<path>/virtserver-cli -delete deployment-id -s IP:port
Example
"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat" -delete 39 -s 10.0.81.128:9090

Important

Before running any commands on VirtServer, you must log in using the -login command.

Tip

To undeploy all virtual services from VirtServer, use the -deleteall command.

Argument

Description

-delete deployment-id, or--delete deployment-id

Commands VirtServer to remove a virtual service from your VirtServer instance. The deployment-id value is the identifier that VirtServer assigned to your service when you deployed it to VirtServer. If you forget it, you can get it at any time later.

-s IP:port, or

--server IP:port

Optional. Specifies the IP address and port of the VirtServer instance.

If you omit this argument, the utility uses the address specified in the previous command.

Undeploy all virtual services from VirtServer

To remove all virtual services from VirtServer, use the following command line:

<path>/virtserver-cli -deleteall -s IP:port
Example

Hide example

"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat" -deleteall -s 10.0.81.128:9090

Important

Before running any commands on VirtServer, you must log in using the -login command.

Tip

To undeploy one virtual service, use the -delete command.

Argument

Description

-deleteall, or--deleteall

Commands VirtServer to remove all virtual services from your VirtServer instance.

-s IP:port, or

--server IP:port

Optional. Specifies the IP address and port of the VirtServer instance.

If you omit this argument, the utility uses the address specified in the previous command.

--deleteall /path/to/projectfile

To revert deployment of virtual services in a specific project, add the project identifier to --deleteall in CLI so that only virtual services in that project are removed.

Add user

To add a user to VirtServer, use the following command line:

<path>/virtserver-cli --adduser -nu username -npw password -s IP:port
Example
"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat" --adduser -nu "john.smith" -npw "p@ssw0rd" -s 10.0.81.128:9090

Important

To manage VirtServer users, you must log in as an administrator by using the -login command.

Argument

Description

--adduser

Adds a new user to VirtServer.

The new user will not have administrator permissions. To give them, edit the user in the web interface.

-nu username

Required. Specifies the username of the new user.

-npw password

Required. Specifies the password of the new user.

-s IP:port, or--server IP:port

Optional. Specifies the IP address and port of the VirtServer instance.

If you omit this argument, the utility uses the address specified in the previous command.

Note

If your VirtServer is configured for OIDC, user management is only possible through your OIDC environment. Contact your administrator for assistance and refer to the OIDC page for details.

Remove user

To remove a user from VirtServer, use the following command line:

<path>/virtserver-cli --deleteuser -du username -s IP:port
Example
"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat" --deleteuser -du "john.smith" -s 10.0.81.128:9090

Important

To manage VirtServer users, you must log in as an administrator by using the -login command.

Argument

Description

--deleteuser

Removes the specified user from VirtServer.

-du username

Required. Specifies the username to delete.

-s IP:port, or--server IP:port

Optional. Specifies the IP address and port of the VirtServer instance.

If you omit this argument, the utility uses the address specified in the previous command.

Note

If your VirtServer is configured for OIDC, user management is only possible through your OIDC environment. Contact your administrator for assistance and refer to the OIDC page for details.

Edit user

To modify a user’s password or role, use the following command line:

<path>/virtserver-cli --edituser -eu username -epw new-password -er user-role -s IP:port
Example
"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat" --edituser -eu "john.smith" -epw "NewP@ssw0rd" -er admin -s 10.0.81.128:9090

Important

To manage VirtServer users, you must log in as an administrator by using the -login command.

Argument

Description

--edituser

Updates the password or role of a VirtServer user.

-eu username

Required. Specifies the user whose password or role you want to change.

-epw new-password

Optional. Specifies the new password for the user.

-er user-role

Optional. Specifies the new role for the user. Possible values: user, admin.

-s IP:port, or--server IP:port

Optional. Specifies the IP address and port of the VirtServer instance.

If you omit this argument, the utility uses the address specified in the previous command.

Note

If your VirtServer is configured for OIDC, user management is only possible through your OIDC environment. Contact your administrator for assistance and refer to the OIDC page for details.

Get list of VirtServer users

To get a list of users added to VirtServer, use the following command line:

<path>/virtserver-cli --enumerateusers -s IP:port
Example
"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat" --enumerateusers -s 10.0.81.128:9090

Important

To manage VirtServer users, you must log in as an administrator by using the -login command.

Argument

Description

--enumerateusers

Shows a list of all users added to VirtServer.

-s IP:port, or--server IP:port

Optional. Specifies the IP address and port of the VirtServer instance.

If you omit this argument, the utility uses the address specified in the previous command.

Note

If your VirtServer is configured for OIDC, user management is only possible through your OIDC environment. Contact your administrator for assistance and refer to the OIDC page for details.

More commands

The virtserver-cli utility also has the following arguments:

Argument

Description

-audit, or --audit

Outputs the contents of the VirtServer Audit Log page to the console. Supported for VirtServer 1.2 and later.

-legacy, or --legacy

Indicates that you are sending commands to VirtServer version 1.1 or earlier.

-h, or --help

Displays quick help on the command-line arguments.

-v, or --version

Displays the version of the command-line utility.

See Also

In this section:
© 2025
Publication date: