Traverse CLI (Command Line Interface)
The BVE API Command-Line Interface (bveCLI) is utility that is bundled with Traverse 5.6 and provides a convenient method for retrieving information from Traverse databases without requiring programming knowledge. The tool can be used to review configuration of device, test, container, etc. or create/update various objects or retrieving results/events from one or more DGEs. bveCLI provides numerous advantages over using a Telnet client to connect to the BVE API server - including automatic login, command history recall, inline editing of API command, filter using regular expression, choice of output format, and many others.
bveCLI uses BVE API component that is typically installed on the primary/central Traverse server. Before the tool can be used, the API server must be started:
Execute the following commands with substituting proper path of Traverse installation location
Launch Start -> Zyrion Traverse -> Traverse Service Controller and enable BVE API Server or open a command window and execute following command
bveCLI is installed under TRAVERSE_HOME/utils directory. The tool can be launched using following parameters:
<server> is specified as
and credentials are provided as
In absence of server information, bveCLI will start a basic command shell and accept limited set of commands.
Additional query parameters that provide advanced functionality are described in detail in relevant sections below
|Load this configuration file instead of looking for |
|Execute the specified query in batch mode; requires |
|Execute the queries from specified file in batch mode; requires |
|Save the result from query into specified file; if already exists, it will be overwritten|
|Result from query should be printed in specified format|
|Include only the specified fields in the output; valid only with |
|Provide diagnostic details; use multiple times to increase logging devel|
bveCLI can load the login credentials for a target BVE API server from a configuration (preferences) file located under the user's home directory. On Linux/Solaris this can be accessed as $HOME/.bveapirc while on Windows it is accessible as %HOME%\.bveapirc. bveCLI can load a configuration file located at alternate location through
--config parameter. The configuration file has following general format:
where n.n.n.n is the fully-qualified domain name or IP address of BVE server. The configuration file can support multiple sections, each represented with it's own BVE server address. The default user ID for a server is specified using _default property. If specified, upon connecting to the server, bveCLI will attempt to log in as the specified user. The password for this or other users are specified within the same section as name-value pairs. You may specify multiple credential pairs and the correct password will be looked up when logging into the API server using corresponding user.
When bveCLI is launched as
bveCLI.pl --host myServer1, the tool will attempt to log into the server as user admin using password secret1 automatically. Alternatively,
bveCLI.pl --host myServer1 --user demo1 will result in automatic login using password letmein. Finally, when launched as
bveCLI.pl --host yourServer2, the tool will establish a connection to the server but will not attempt to automatically log into it.
When launched in interactive mode, bveCLI supports the following commands
connect <n.n.n.n> [ <port> ]
Establish TCP connection to specified BVE API server. If the port number is not specified, 7661 is used by default. This step can be skipped by specifying
--port command-line parameters. If a matching entry is found in the configuration file, automatic login will be attempted. Once a connection has been established, the prompt will reflect the host name/address and port.
login <username> [ <password> ]
Log into BVE API server using specified credentials. If the password is omitted, bveCLI will attempt to lookup a matching entry form the configuration file. Until a valid credential has been supplied, it will be reflected in the prompt as
Log out of the API server and close TCP connection
Running A Query
bveCLI supports all standard BVE API commands with corresponding parameters, as outlined in Traverse Developer's Guide. A command issued on bveCLI is transparently executed on the remote server and the response from the server is parsed/analyzed. For configuration commands that only return success/failure response, no output will be presented unless the command was not successful. A command that returns configuration/performance data (eg. device.list, location.list) will be presented in a readable format.
Beyond the search criteria supported by different BVE API commands, bveCLI provides additional filtering capabilities. Commands executed on bveCLI can be piped through grep filter. The filter supports Perl5 compliant regular expressions and is applied against the raw output from remote server in case insensitive manner before parsed by bveCLI.
bveCLI can also be used in non-interactive manner for performing quick queries against BVE API server. When executed with
--exec parameter, bveCLI will execute the specified query and log out immediately. In this case,
--host parameter must be specified along with suitable login credentials provided in command line or configuration file. The search filter can be specified in batch mode, similar to interactive mode as above.
In order to execute multiple commands, use
--input parameter instead. This parameter requires the location of a text file containing one or more valid API commands on each line:
In batch mode, bveCLI allows selection of specific configuration/output fields using
--fields parameter. When used, the output will only include the specified fields
By default bveCLI uses a tabular output format that is suitable for operational use. The tool supports additional output formats - XML, JSON, CSV - that can be used for integration with in-house and third-party tools. The output format can be selected using
For JSON/XML formats, the objects are returned as an array with separate element indicating success/failure status. For CSV format, the first row is prefixed with # symbol and indicates the contents of each column.
- Interactive password input should mask user entry
- Pagination support using "| more"
- Interactive field selection using "| cut"
- Tab completion works for top level command but not parameters