Skip to end of metadata
Go to start of metadata

Traverse CLI (Command Line Interface)

 

Overview

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.

Prerequisites

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:

Linux/Solaris

Execute the following commands with substituting proper path of Traverse installation location

Windows

Launch Start -> Zyrion Traverse -> Traverse Service Controller and enable BVE API Server or open a command window and execute following command

General Syntax

bveCLI is installed under TRAVERSE_HOME/utils directory. The tool can be launched using following parameters:

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

Sample Session

Additional query parameters that provide advanced functionality are described in detail in relevant sections below

ParameterShortDescription
--config-cLoad this configuration file instead of looking for .bveapirc under user's home directory
--exec-xExecute the specified query in batch mode; requires --host parameter
--input-iExecute the queries from specified file in batch mode; requires --host parameter
--output-oSave the result from query into specified file; if already exists, it will be overwritten
--format-tResult from query should be printed in specified format
--fields-fInclude only the specified fields in the output; valid only with --exec or --input parameters
--debug-dProvide diagnostic details; use multiple times to increase logging devel

Configuration File

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.

Example: $HOME/.bveapirc

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.

Session Management

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 --host and --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 unauth

exit

Log out of the API server and close TCP connection

Sample Session

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.

Sample Session

Search Filter

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.

Sample Session

Batch Processing

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.

Sample Session

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:

Sample Session

Field Selection

In batch mode, bveCLI allows selection of specific configuration/output fields using --fields parameter. When used, the output will only include the specified fields

Sample Session

Output Format

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 --format parameter

Sample Session

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.

Future Enhancements

  • 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