cli.nroff

Pegasus is an open-source implementationof the DMTF CIM and WBEM standards. It is designed to be por

.TH cimcli 1 LOCAL
 
.SH NAME 
cimcli \- command line WBEM Client 
.SH SYNOPSIS 
.B cimcli [operation]  [object]  [options]  [extra-parameters]
.I ...

cimcli is available for all platforms that support the Pegasus CIM Server.

.SH DESCRIPTION 

.B cimcli
is a command line test tool for executing CIM client operations. It implements
all of the DMTF CIM operations except for the modify and create class/instance operations and includes several
other operations that are useful in testing including getting all namespaces and enumerating all
instances in a namespace.

Each execution of cimcli invokes a CIM Operation with the corresponding command parameters equivalent
to the CIM Operations defined in the CIM Operations over HTTP specification.

In addition to the basic CIM Operations defined in the specification, this tool implements a number of
other specific operations that support testing and querying CIM servers including  a command to query
for namespaces and to get all instances in a namespace.

.TP
.B 1.
Enumerate namespaces (ns) - Returns a list of the namespaces available from the CIMOM.
.TP
.B 2.
Enumerate all instance names (niall) - Returns a list of all instance names in the defined namespace.
.TP
.B 2.
Turn CIMServer statistics on and off (At least for the OpenPegasus server

The format of this command is generally:
.TP
.B cimcli [Operation] [objectname] [options] [extra parameters]

.TP
.B [Operation] 
defines the  operation to be executed. cimcli executes all of the DMTF CIM Operations (ex. getclass)
and a set of compound operation (enumeratenamespaces). There
are two forms for each Operation definition, a short form typically two characters (i.e. gc)
and the long form which is the full name of the operation (i.e. getclass).
.TP
.B [objectname]
The name of the object input with the command. This parameter is operation dependent.
For example, with the getClass operation the object is a class name.
With the getinstance command the object is an object name. Note
that some of the commands do not require an object.   Thus, for example, the [object] is optional with
the enumerateClasses operation as it is with the equivalent  enumerateClassNames CIM operation. Normally
this is either a classname or an instancename (classname plus keybindings). In some operations one or the 
other is required.  In other operations, the behavior of the operation is dependent on whether classname
or instancename is supplied.
.TP
.B [options...] 
Options are identified on the command line with the - or -- notation.  There are three types of options:

.TP 8
.B 1.
A set of options that are universal and modify or define the execution of the command or the 
form of the return.  This includes options like setting the output format for object responses or
requesting only summary operation.
.TP 8
.B 2.
A set of options that represent the optional input parameters for selected operation. The
command defines the CIM Operation that will be executed and the options define the optional characteristics.
Typical context options might be -n namespace (used on most but not all operations)or -niq which
sets includequalifiers to false for operations that use the includeQualifiers optional parameter.
.TP 8
.B 3
A set of options to display help (-h, --help, --ho to get a list of all options, and
-hc to get a list of all commands. When these options are requested, no operation is
executed.
.TP
.B [extra-parameters]
Some of the operations allow or require extra parameters. these are typically keywords or keyword/value pairs
and are defined as part of the particular options that might use them.

Any extra parameters entities on the command line that occur after the [Operation] and are not preceeded by
"-" to indicate an option are considered extra paramters.  These are used in some of the operations to provide
additional information required or optionally desired by the operation.  See each operation definition to determine
if extra parameters are required or allowed.  These may be either keyname-value pairs in some cases or simply strings
depending on the operation.


NOTE: cimcli does not protect the user against inputting extra options or parameters.  Since the options are
heavily dependent on the operation to be executed, it simply ignores those options that are not used with a particular
operation.  Thus, entering the -r option (role) with a getClass operation is syntatically allowed but cimcli ignores
the parameter.

.SH UNIVERSAL OPTIONS

There is a set of options which are general to all of the CIM Operations and most of the 
compound operations and which provide parameters for the initiation or execution of the command. 
These include:
.TP
.B \-n [namespace]
Namespace name for this operation (ex. -n root). The default namespace is root/cimv2.
.TP
.B \-l [location]
Host name or IP address and optionally port for this operation. The default for this command
if the the -n option is not used is to use the Pegasus connectLocal() function to connect to the server.
Note that this means that a command like cimcli gc CIM_Door may not work when trying to connect to a 
server other than Pegasus on the same system. If cimcli is to be used to connect to a CIM Server other
than Pegasus on the same system use -l localhost or -l 127.0.0.1 or the actual name or IP address.
This will force cimcli to make the connection in the normal way, not using connectLocal()
.TP
.B \-u [user-name]
The user name to be used in in the connection to the CIM server for the command
.TP
.B \-p [password]
The password to be used in the connection to the CIM server for the command

In addition there is a set of options that modifies the manner in which the command is executed or
the display of information on response including the following:

.TP
.B \--t
Measure time for the operation to be completed and report it upon command completion. If this option
is set, the time for the operation is recorded upon completion of the operation.  In addition, the 
client infrastructure is qeieried to determine if the operation execution times optionally measured
in the infrastructure and at the server are available. If they are, they are displayed also.  This
would allow the user to see a) time spent in the server, b) round trip time for the operation, c)
application round trip time for the operation. Note that when combined with the repeat option,
the output includes maximum, minimum, and average times for the operation.  There are a specific operations
in cimcli to turn control statistics generation (See son and soff operations)
.TP
.B \--r [repeat_count]
Repeat the operation repeat_count times. This repeats the operation without disconnecting. This option is
useful for setting up tests that load the server with repeated calls and also for getting average times for
an operation by taking the average of a number of calls ( when used with the summary information option and
the measure time option). 
.TP
.B \-delay [seconds]
Delay count seconds between connect and operation.
.TP
.B \--sum
Present only summary information, not full output.  Generally it presents counts of objects returned and 
response times in place of the names or objects themselves.
.TP
.B \--count [object_count]
Defines an expected count of objects expected on the response.  An error exit is generated if this
number of objects is not received.  This test can be used in batch files to test for number of objects
returned by an operation. 
.TP
.B \--timeout [seconds]
Set the connect timeout to some time other than the default timeout.
.TP
.B \-o [ "xml" | "mof" ]
Output type for commands that output objects. Used with commands that present CIM objects in
their response.
.TP
.B \-verbose
Displays details on the options for the CIM Operation and execution.
.TP

.SH OPERATIONS
This section defines the individual operations supported by cimcli. 
Note that the either the names (ex EnumerateInstances) or the shortcut (ei) may
be used in inputting an operation defintion and they they are case independent.

.TP
.B ci    CreateInstance
NOTE: This command is not implemented in the current version and return a
fixed "NOT IMPLEMENTED" response.
This command issues the CIM operation create instance with the parameters provided.
It requires the [object] parameter defining the class for which the instance is to
be created and also allows for an optional set of parameters that defined properties
to be provided in the following format

  [propertyName]=value

If the propertyName parameter is provided with no value, the default is inserted.
Note that the CIM operation is issued even if the property name is illegal since this 
is considered to be a test program.

The command actually reads the CIM_Class, inserts the properties that have been defined
on the command line using the value type from the class.

The command will be rejected if the class does not exist in the namespace.

.B Example:

	cimcli ci CIM_door name=abc size=zyx

Returns the object path of the created instance if the call to the cim server was executed.
Otherwise it returns the exception received.

.TP
.B ec    EnumerateClasses
Issues the enumerateClasses CIM operation which enumerates the class hiearchy starting at the level
defined by <classname>.

The format is:
.B	 cimcli ec [classname] [options]

where classname is not required.  If it is omitted, cimcli inserts an empty classname into the CIM operation
which tells the CIM Server to start at the top of the class inheritance tree. 
The possible options that represent the parameters of the enumerateClasses operation are:


.B \-niq
Boolean (not_include_Qualifiers) that sets the operation parameter for include_quailifers to false.

.B \-nlo 
Boolean that defines whether properties from superclasses
are included in the response. the -nlo option turns this parameter off

.B \-cl 
Boolean parameter sets the operation parameter classOrigin in the operation request. the CIMServer
is expected to return classOrigin information as part of the response.

.B \-pl [propertyList]
Optional property list for the operation.

.B Examples
	TBD

.TP
.B nc    EnumerateClassNames
Enumerate Class Names. 
The format is:

	cimcli[ <classname> ] [options] where the used options are:

The options specific to this operation include;

.B \-niq
do not include qualifiers

.B \-nlo
not localOnly

.B \-cl
class origin

.B \-pl [propertyList]
optional property list for the operation.

On this operation the classname parameter is optional similar to the way the CIM operation
is defined.

.B Examples
	TBD

.TP
.B ni     EnumerateInstanceNames
Execute the enumerateInstanceNames CIM Operation. The syntax for this operation is:

.B	cimcli ni [classname] [options]

This operation takes as input options specific
to this command the following:

    object - classname for which instancenames are to be enumerated.

It displays the instances names that were returned by the CIM server in response to
the enumerateInstances CIM operation with the defined input parameters. if the -s option is set
it returns only the count of names returned.

In order to provide all of the options allowed for the CIM operation EnumerateInstances it uses the following
options specific to the command:

-B \-nlo
not local only operation parameter to false. Note that this negative form for the
option is used becaused the default for local only parameter is true. Thus, not including this
parameter means that the parameter is not set.

.B Example:

        cimcli ni CIM_ManagedElement -p password -n name -n root/PG_Interop
	Execute the enumerateInstanceNames operation on CIM_ManagedElement class in the root/PG_Interop
	namespace.

.TP
.B ei    EnumerateInstances
Execute the CIM operation enumerateInstances. The format of this operation is:

.B	cimcli ei <className> [options]

In order to provide all of the options allowed for the CIM operation EnumerateInstances it uses the following
options specific to the command

.B \-nlo
not local only operation parameter to false. Note that this negative form for the
option is used becaused the default for local only parameter is true. Thus, not including this
parameter means that the parameter is not set.

.B \-niq
Boolean (not_include_Qualifiers) that sets the operation parameter for include_quailifers to false,
Note that this negative form is used because the default for this parameter is true.

.B \-ic
Boolean to set include class origin operation parameter to true.

.B \-di
Set deep inheritance operation parameter to true.
 
.B \-o [xml|mof]
Set the output format for the instances to display the returns as mof