You can deploy and modify virtual services (virtual APIs) on VirtServer from the command line. For this purpose, you use the command-line interface utility provided with VirtServer and ReadyAPI installation.
![]() |
Starting from the 1.12.0 version (shipped with VirtServer 3.10.0), the utility returns only two exit codes: 0 (success) and 1 (error). If your automation relies on them, you may need to modify it when you move to the new version of the utility. |
About the VirtServer command-line interface utility
The VirtServer command-line utility is typically used to work with virtual services on VirtServer from client machines that do not have access to ReadyAPI. You can deploy and update services from it without stopping VirtServer, or integrate a command into your development environment. You can also start virtual services during your builds by using Maven integration or the Jenkins plugin.
Tip: | If you do not automate your virtual service startup, you can also use the VirtServer Web UI to work with virtual services from your browser. |
Requirements and limitations
-
To interact with VirtServer, you need a user on it. Use the VirtServer web interface or the VirtServer application command line to add a user.
-
The VirtServer command-line interface does not support working with JMS virtual services that use HermesJMS. Use the direct connection from ReadyAPI to deploy the services from the command line.
Get the command line interface utility
The command-line interface is included in VirtServer and ReadyAPI installations. It includes:
-
Executable file:
virtserver-cli.bat/.sh
file (.bat
on Windows,.sh
on Linux and MacOS). You can find it in the ReadyAPI/bin or VirtServer/bin folder. -
Library:
virtserver-cli-<library-version>.jar
. You can find it in the ReadyAPI/tools or VirtServer/tools folder.Tip: The library is also available in the ReadyAPI Download Center.
Syntax
The general command line syntax is as follows:
<path>/virtserver-cli -s IP:port [more-options]
Argument | Description |
---|---|
-s IP:port , or ‑‑server IP:port |
Required at least once. The IP address and port of the VirtServer instance to which you are sending the command. For example, Once you specify the VirtServer address, you can omit the argument. In this case, the command-line utility will use the address specified in the previous command. When you need to change the address, specify the |
Log in to VirtServer
To perform any tasks using the command line interface, you must first log in. To do that, use the following command:
<path>/virtserver-cli -login -s IP:port -u name -pw password
For example:
"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat" -login -s 10.0.81.128:9090 -u John -pw pswd1
The command uses the following arguments:
Argument | Description | ||
---|---|---|---|
-login , or --login |
Commands VirtServer to send a token that will be stored on the computer and used for authenticating other commands. The expiration time of the token is controlled by the timeout settings of VirtServer. |
||
-s IP:port , or ‑‑server IP:port |
Optional. The IP address and port of the VirtServer instance to which you are logging in. For example, If you omit this argument, the utility uses the address specified in the previous command. |
||
-u user-name , or ‑‑user user-name |
Required. The user account for interacting with VirtServer. This can be the user account you created when running VirtServer for the first time or an account you added later. |
||
-pw password , or ‑‑password password |
Optional. The password of the user you specified in the
|
![]() |
Important: In VirtServer 3.2.0, the use of the -u and -pw arguments with commands other than -login has been deprecated. |
Managing SmartBear ID Based Licenses via CLI
We are updating support for managing VirtServer via the command line. We have added activation and deactivation of a SmartBear ID Based license to the CLI. This is a separate utility to the previous behaviour which managed license activation and deactivation upon startup.
Activating and Deactivating a SmartBear ID-Based License
To activate a SmartBear-hosted ID Based license via CLI (where SmartBear hosts the license on its online license server), please use the following format:
<path>/virtserver-cli -activatelicense -licenseaccesskey
-licenseissuer SLM
For example:
"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat"
-activatelicense -licenseaccesskey 3881e8c2-7898-4d5c-aa6e-2e47fc5e2538
-licenseissuer SLM
To activate a SmartBear ID Based license hosted on customer premise via CLI, please use the following format:
<path>/virtserver-cli -activatelicense -licenseserver -licenseaccesskey
-licenseissuer SLM
For example:
"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat"
-activatelicense -licenseserver http://181.72.180.195:40892
-licenseaccesskey 3881e8c2-7898-4d5c-aa6e-2e47fc5e2538 -licenseissuer SLM
To deactivate a SmartBear-hosted ID Based license via CLI (where SmartBear hosts the license on its online license server), please use the following format:
<path>/virtserver-cli -deactivatelicense -licenseaccesskey
-licenseissuer SLM
For example:
"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat"
-deactivatelicense -licenseaccesskey 3881e8c2-7898-4d5c-aa6e-2e47fc5e2538
-licenseissuer SLM
To deactivate a SmartBear ID Based license hosted on customer Premise via CLI, please use the following format:
<path>/virtserver-cli -deactivatelicense -licenseserver
-licenseaccesskey -licenseissuer SLM
For example:
"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat"
-deactivatelicense -licenseserver http://181.72.180.195:40892
-licenseaccesskey 3881e8c2-7898-4d5c-aa6e-2e47fc5e2538 -licenseissuer SLM
Argument | Description |
---|---|
-activatelicense , or --activatelicense |
Required: Activate a SmartBear ID-Based License. |
-deactivatelicense , or --deactivatelicense |
Required: Deactivate a SmartBear ID-Based License. |
-licenseserver , or --licenseserver |
Not required if your license is SmartBear-hosted: This argument can be fullly removed as the CLI will point to the SmartBear license Server by default. Required only if you host an on-premise SLM license server: Specify the address of the on-premise SLM License Server (hosted on your environment). You will probably need to request this from your license administrator. |
-licensekey , or --licenseaccesskey |
Always required if your license is SmartBear-hosted: The access key is mandatory if your license is hosted with SmartBear. This is the access key generated for the VirtServer Admin after license is assigned and the admin has logged into manage.smartbear.com. Required only if you use on-premise license server with authentication configured: You must specify the access key if authentication is set on your SLM on-premise License portal. You will need to request information to access the on-premise license portal from your license administrator. Not required if your onpremise SLM license server is enabled for access for everyone: Your SLM onpremise License portal does not require users to be authenticated and it is enough to point VirtServer at the onpremise SLM license server for a license to be acquired. |
-licenseissuer , or --licenseissuer |
Specify that this is an SLM license (this is a different license type to our legacy file based license which has a licenseissuer=JPROD). |
-getlicense , or --getlicense |
Get information about installed license. |
Activating and Deactivating a File Based License
While we are asking customers to switch to ID-based licensing due to the upcoming retirement of legacy file-based (ProtectionLS) licensing model, we have extended CLI support for this licensing model. This replaces activation and deactivation of license during VirtServer upstart.
To activate a file-based floating license via CLI, please use the following format:
<path>/virtserver-cli -activatelicense -licenseserver
-licenseaccesskey -licenseissuer JPROD
For example:
"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat"
-activatelicense -licenseserver http://181.72.180.195:443
-licenseissuer JPROD
To activate a file-based fixed license via CLI, please use the following format:
<path>/virtserver-cli -activatelicense --licensefile (file)-licenseissuer JPROD
For example:
"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat"
-activatelicense --licensefile (file)-licenseissuer JPROD
To deactivate a file-based license via CLI, please use the following format:
<path>/virtserver-cli -deactivatelicense
For example:
"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat"
-deactivatelicense
Argument | Description |
---|---|
-activatelicense , or --activatelicense |
Required: Activate a file-based License. |
-deactivatelicense , or --deactivatelicense |
Required: Deactivate a file-based License. |
-licensefile , or --licensefile or (file) |
Required for file-based fixed license: Specify path to the legacy fixed license file. |
-licenseserver , or --licenseserver |
Required for file-based floating license: Specify the onpremise ProtectionLS License Server. You may need to request this from your license administrator. |
-licenseissuer , or --licenseissuer |
Required should be licenseissuer JPROD to specify that this is an JPROD license (this is a different license type to our ID-based license which has a licenseissuer SLM). |
-getlicense , or --getlicense |
Get information about installed license. |
Log out of VirtServer
When you have finished working with VirtServer, log out by using the following command:
<path>/virtserver-cli -logout -s IP:port
For example:
"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat" -logout -s 10.0.81.128:9090
The command uses the following arguments:
Argument | Description |
---|---|
-logout , or --logout |
Commands VirtServer to delete the stored session token that is used for authenticating commands. |
-s IP:port , or ‑‑server IP:port |
Optional. The IP address and port of the VirtServer instance to which you are logging in. For example, If you omit this argument, the utility uses the address specified in the previous command. |
Tasks
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
![]() |
Before running any commands on VirtServer, you must log in using the -login command. |
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. |
-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
![]() |
Before running any commands on VirtServer, you must log in using the -login command. |
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.
You can reassign the port number from the VirtServer UI or ReadyAPI UI, or from the command line. |
||
-a true , or--autostart true |
Optional. |
||
-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
![]() |
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. See below.
-
You can command VirtServer to start a virtual service automatically by using the
-a true
parameter when deploying the service to VirtServer. See above.
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.
![]() |
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:
![]() |
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 |
-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
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 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
![]() |
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
![]() |
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 |
Add user
To add a user to VirtServer, use the following command line:
<path>/virtserver-cli --adduser -nu username -npw password -s IP:port
![]() |
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. |
Remove user
To remove a user from VirtServer, use the following command line:
<path>/virtserver-cli --deleteuser -du username -s IP:port
![]() |
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. |
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
![]() |
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: |
-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. |
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
![]() |
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. |
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
Connect With ReadyAPI
VirtServer Tutorial
VirtServer Command-Line Arguments