Applies to ReadyAPI 2.7, last modified on June 25, 2019

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.

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 ServiceV. 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 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.

Getting the command line interface utility

The command-line interface is included in VirtServer and ReadyAPI installations. You can find it in the ReadyAPI/bin or VirtServer/bin folder. The installation includes the virtserver-cli.bat/.sh file (.bat on Windows, .sh on Linux and MacOS) and the virtserver-cli-1.0.0.jar package.

Syntax

The general command line syntax is as follows:

<path>/virtserver-cli -s IP:port -u name -pw password [more-options]

Common arguments

Every command you send through the virtserver-cli utility uses the following arguments. They are always required:

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

The IP address and port of the VirtServer instance to which you are sending the command. For example, -s 192.168.1.12:9090.

-u user-name, or
--user user-name

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

The password of the user you specified in the -u argument.

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 -u name -pw password

For example:

"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 -u John -pw pswd1

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.

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 that contains your virtual service. If the name contains spaces, enclose it in quotes.

-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 ServiceV 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, -u, -pw

Required. Specifies the server address, user name and password. See above.

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 -u name -pw password

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

<path>/virtserver-cli -stop deployment-id -s IP:port -u name -pw password

For example:

"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat" -start 39 -s 192.168.1.10:9090 -u John -pw pswd1

"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat" -stop 39 -s 192.168.1.10:9090 -u John -pw pswd1

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, -u, -pw

Required. Specifies the server address, user name and password. See above.

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 -u name -pw password

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

Argument Description
-ls, or --list

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

-s, -u, -pw

Required. Specifies the server address, user name and password. See above.

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 -u name -pw password

For example:

"c:\Program Files\SmartBear\VirtServer\virtserver-cli.bat" -update 39 -p 8080 -u John -pw pswd1 -s 10.0.81.128:9090
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 ServiceV 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, -u, -pw

Required. Specifies the server address, user name and password. See above.

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.

Notes:

  • Whatever command you use, you should also specify common arguments: -s, -u and -pw.

  • 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 -u John -pw pswd1

  • 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 -u John -pw pswd1

  • Updates the tag value:

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

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 -u name -pw password

<path>/virtserver-cli -stopwt tag -s IP:port -u name -pw password

For example:

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

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, -u, -pw

Required. Specifies the server address, user name and password. See above.

Notes:

  • 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 -u name -pw password

For example:

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

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, -u, -pw

Required. Specifies the server address, user name and password. See above.

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.

See Also

Connecting to VirtServer
VirtServer Tutorial
VirtServer Command-Line Arguments

Highlight search results