.TH CLI 1 LOCAL
 
.SH NAME 
CLI \- command line WBEM Client 
.SH SYNOPSIS 
.B CLI [operation] [object] [option
.I ...

CLI is availabile for all platforms that support the Pegasus CIM Server.

.SH DESCRIPTION 

.B CLI
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.
.PP
Each execution of CLI invokes a CIM Operation with the corresponding command parameters equivalent
to the CIM Operations defined in the CIM Operations over HTTP specification.
.PP
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.
.PP
The format of this command is generally:

.B CLI [Operation] [object] [option] [extra parameters]

.TP
.B [Operation] 
defines the  operation to be executed. CLI executes all of the DMTF Cim Operatioons (ex. getclass)
and a set of compound operation (enumeratenamespaces). There
are two forms for each Operation, 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 [object]
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 objectname. 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.
.TP
.B [option...] 
Options are identified on the command line with the - or -- notation.  There are three types of options:

.TP 4
.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
.B 2.
A set of options that represent the optional input parameters for selected commands
and a set of options on the command line. The
command defines the CIM Operation that will be executed and the options define the optional.
.TB
.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.


.SH COMMANDS

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 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 CLI gc CIM_Door may not work when trying to connect to a 
server other than Pegasus on the same system. If CLI 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 CLI 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 connect for the command
.TP
.B \-p
Password. The password to be used in the connect 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
.TP
.B \--r [n]
Repeat the operation n times. Note that this repeats the operation without disconnecting.
.TP
.B\-delay [n]
Delay n seconds between connect and operation.
.ITP
.B \-s summary
Present only summary information, not full output.  Generally it presents counts of objects
returned in place of the names or objects themselves.
.ITP
.B \--count
Defines an expected count of objects expected on the response.  An error is generated if this
number of objects is not received.
.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
.B ni     enumerateinstanceNames
Execute the enumerateInstanceNames CIM Operation.  This operation takes as input options specific
to this command the following:

It displays the instances names that were returned by the CIM server in response to
the enumerateInstances CIM operation with the defined input parameters.

.LP Example:

CLI ni CIM_ManagedElement -p password -n name -n root/PG_Interop

.TP
.B niall enumerateallinstanceNames
Execute a enumerateinstancenames on all classes to get all instance names within the defined namespace.
This function searches the complete namespace using the CIM getClass operation to get the classes and the
enumerateInstanceNames command to enumerate all of the instances for each class. It returns
the list of instance names found.

.TP
.B ei    EnumerateInstances
Execute the CIM operation enumerateInstances.  This command takes as input options specific to the command
.Bl -bullet
.It
-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.
.it
-niq   Set  include qualifiers operation parameter to false. Note that this negative form is
used because the default for this parameter is true.
.It
-ic    Set include class origin operation parameter to true
.It
-di    Set deep inheritance operation parameter to true.
.It mof Set the output format for the instances to display the returns as mof
.El
.It
-pl [property List] optional property list for the operation.
.El
        
It returns the instances found either as MOF or XML depending on the output options parameter.

.TP
.B nc    EnumerateClassNames
Enumerate Class Names. [ <classname> ] [options] where the used options are:

        -niq - do not include qualifiers
        -nlo - not localOnly
        -pl - propertyList
        -cl - class origin

.TP
.B ec    EnumerateClasses

The format is:
	 CLI [ <classname> ] [options]
Issues the enumerateClasses CIM operation which enumerates the classes starting at the level
defined by <classname>. <classname> is 
not required.  If it is omitted, CLI inserts an empty classname which tells the CIM
operation to start at the top of the tree. 
The possible options that represent the parameters of the enumerateClasses operation are:

	include qualifiers - the -iq option. Boolean that defines whether qualifiers
	are included in the response
	includequalifiers (default true) - the -niq option turns this parameter off.
	localOnly (default so ignored) - the -lo option
	localOnly (default true) - Boolean that defines whether properties from superclasses
	are included in the response. the -nlo option turns this parameter off
	propertyList - the -pl options which allows defining an optional property list
	class origin (default false) - Boolean parameter defined by the -cl option turns this
	option on.

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

    CLI 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 mi    modifyinstance
NOTE: This command is not implemented in the current version and return a
fixed "NOT IMPLEMENTED" response.
This is the same format as the createinstance.  The difference is that the instance
must already exist to be modified.

.TP
.B gi    GetInstance
gets the instance defined by the instance name parameter and displays it
as in the format chosen for this operation (xml or mof).

This command requiers the [object] parameter.  If the parameter is an instance with
keys defined (a CIMObjectPath), the a getInstance CIM operation is executed and the
return from the CIM Server presented (in either xml or mof depending on the ouput option).
If the input is a class name, a enumerateinstanceNames CIM Operation is executed and if
any instance names are returned the result is presented to the console for the user to
select one of the instances to be deleted.

If there are no instances, the return from this command is simply an empty response.

CLI gi [instance name] [options]
which returns the specific instance named.

OR

CLI gi [class name] [options]
which presents a list of possible instances to the user from which one can be selected
for the getinstance.  In this case, the command actually executes an enumerateInstanceNames
to get the list of instances that is presented to the user.  The getInstance is executed
after the user makes a selection.

The possible options specific to this command are:

-iq  include qualifiers
-nlo  localonly
-pl  optional property list that defines which properties to return.

.B Example:

CLI gi cim_managedElement

This is an interactive request that returns a list of instances from an
enumerateinstance of CIM_ManagedElement from which the user can select one which CLI
will return as a complete instance.


.TP
.B di    deleteinstance
Delete instance executed a single deleteInstance command to the CIM Server.  

This command requires the [object] parameter.  If this parameter is a full instance
name with className and key bindings, the deleteInstance CIM Operation is executed
directly.  If it is a class name with no keybindings, the  enumerateInstances command
is executed and the list of returned instances presented to the console for the user
to select one to delete.  CLI then executes deleteInstance with the selected instance
name and returns the response,

return - there is an empty response if the instance was successfully deleted or
an exception return if there were any errors.

CLI di [object]

.B Examples:

CLI di PG_test - esecutes enumerateInstanceName on PG_test and allows the user to select the
instance to be deleted.

CLI di PG_test.name="abc" - attempts to delete that object.

.TP
.B gq    getQualifier
getQualifier displays the target qualifier

CLI gq [qualifier name]

Example:

CLI gq abstract - returns the mof or xml for the abstract qualifier.
.TP
.B sq    setQualifier
This command is not implemented.

.TP
.B eq    enumeratequalifiers
Enumerate all of the qualifiers defined in the target namespace

CLI eq

There are no options for this command.

.TP
.B dq    deletequalifier
Deletes the target qualifier.

CLI dq [qualifier name]

NOTE: This should be used with great caution.

.TP
.B a     associators
Enumerate the associators for the target object.  The syntax for this operation
is 
    CLI a [object] [options]

The options provide the various operation parameters including;

.HP
.B objectName
The object parameter
.HP
.BassociatorClass
The -ac parameter
resultClass The -rc parameter
role The -r parameter
resultRole The -rr parameter
includeClassOrigin The -ic parameter
PropertyList The -pl parameter


.TP
.B an    associatornames
Enumerate teh associator names for the target object.  The syntax for this operation
is:

    CLI an [object name] [options]

where ObjectName can be either a class name or an instance name

options can be as follows:

TBD

.TP
.B r     references
Text

.TP
.B rn    referencenames
Text

.TP
.B im    invokeMethod
This command executes an extrinsic operation to execute a method on a CIM class or instance

The form of the command is

CLI [object] [methodname] *[parameters]

Note that there is one additional required parameter to this command than to most commands,
the [methodname]

Example:

CLI PG_WBEMSLPTemplate register - n root/PG_Interop

The parameters are supplied as name=value pairs. In the current version, all parameters are
treated as strings.  

.TP
eq    executeQuery
Not Supported

.TP
ns    enumeratenamespaces
Request an Enumeration of all the namespaces in the target CIM Server.  This command uses both
the CIM_Namespace class and if that fails, the __Namespace class to determine the list of namespaces.

RETURN - It returns a list of the namespace names returned by the CIM Server.
.TP
?     Show Command Opetions


.SH OPTIONS 
There are a significant number of options to this utility, some if which provide specific information 
for one or more commands and some of which are universal across all of the commands.   In general, the
program does not check for spurious options so that if you input an option that is not used by a particular
operation, it is simply ignored.
.TP 5 
-u  
User. Allows input of a user name for authentication
.TP 
-p
password. Allows input of a password for server authentication of the command
.TP
-l
location. Allows input of the host name for the CIM server.  This includes the 
host name and optionally the port. The default is localhost:5988.  If the port component
is not input port 5988 is assumed.
.TP
-n
Namespace. Defines the namespace for the operation.
.TP
-di
deepInheritance. Specifies the deepInheritance parameter for selected commands if the option is set.
Note that this means different things to different commands and is used only with the enumerate commands.
.TP
-lo
localOnly. Specifies the localOnly operation parameter for selected commands if the option is set.
See the commands for more information. This option is Deprecated in favor of the -!lo and -nlo because the
default for local only is on so that generally the -lo is simply the default.  We recommend using
-nlo to turn off local only.
.TP
-iq
includeQualifiers. Specifies the includeQualifiers operation input paramter for selected commands. This option
is deprecated in favor of the -!iq and -niq parameters because -iq is the equivalent of the defualt for
most of the commands.

.TP
-ic
includeClassOrigin
Set the includeClassOrigin operation parameter to true. Default(false).

.TP
-u
User
Defines User Name for authentication. Default is no user name and no authentication.

Example:
-u username

.TP 
-p
Password
Defines password for authentication. Default is no password and no connection authentication.

.TP
-l
location
Specifies system and port (HostName:port). Port is optional. Default(localhost:5988).

.TP
-n
namespace. 
Specifies namespace to use for operation. Default(root/cimv2).

.TP
-di
deepInheritance. 
If set deepInheritance operation parameter set true . Default(false).

.TP 
-lo  
localOnly. 
DEPRECATED. This was used to set LocalOnly. However, default should be true and we cannot use True as default. 
See !lo . Default(true).

.TP 
-!lo  
!localOnly. 
When set, sets LocalOnly = false on operations. DEPRECATED,!confuses bash. Use -nlo . Default(false).  See also -nlo.

.TP 
-nlo  
notLocalOnly. 
When set, sets LocalOnly = false on operations . Default(false). See also -!lo. This form was implemented with the
-!lo form on some systems. It is equivalent to -!lo.

.TP 
-iq  
includeQualifiers. 
Deprecated. Sets includeQualifiers = True. However, default = true . Default(true).

.TP 
-!iq  
!includeQualifiers. 
Sets includeQualifiers = false on operations. DEPRECATED, ! confuses bash. Use -niq. Default(false).

.TP 
-niq  
notIncludeQualifiers
Sets includeQualifiers = false on operations. Default(false). See also -!iq.  This form was implemented because of
problems with the -!iq form on some systems.  It is equivalent to -!iq.

.TP 
-pl  
propertyList
Defines a propertyNameList. Format is p1,p2,p3 (without spaces). . Default(###!###)

.TP 
-ac  
assocClass
Defines a assocClass string for Associator calls. Default()

.TP 
-ar
assocRole
Defines a role string for Associatiors AssocRole parameter. Default()

.TP
-r
role
Defines a role string for reference role parameter. Default()

.TP
-rc
resultClass
Defines a resultClass string for References and Associatiors. Default()

.TP
-rr
resultRole
Defines a role string for associators operation resultRole parameter. . Default()

.TP
-ip
inputParameters
Defines an invokeMethod input parameter list. Format is p1=v1,p2=v2,..,pn=vn (without spaces) . Default()

.TP
-f
filter
Defines a filter to use for query. One String input . Default()

.TP
--s
substitute
Defines a conditional substition of input parameters. ) . Default()

.TP 
-o
outputformats
Output in xml, mof, txt. Default(mof)

.TP
-x
xmlOutput
Output objects in xml instead of mof format. Default(false)

.TP
--v
version
Displays software Version . Default(false)

.TP
-v
verbose
Verbose Display. Includes Detailed Param Input display . Default(false)

.TP
-s
summary
Displays only summary count for enumerations, associators, etc. .Default(false)

.TP
-h
help
Prints help usage message . Default(false)

.TP
--help
helpfull
Prints full help message with commands, options, examples . Default(false)

.TP
-ho
helpoptions
Prints list of options . Default(false)

.TP
-hc
helpcommands
Prints CIM Operation command list . Default(false)

.TP
--timeout
connecttimeout
Set the connection timeout in seconds. . Default(0)

.TP
-d
debug
More detailed debug messages . Default(false)

.TP
-trace
trace
Set Pegasus Common Components Trace. Sets the Trace level. 0 isoff. Default(0)

.TP
-delay
delay
Delay between connection and request . Default(0)

.TP
-count
count
Expected count of objects returned if the summary set. Tests this count and display difference. Term nonzero if test fails  . Default(29346)

.TP
--rr
repeat
Number of times to repeat the function. Zero means one time . Default(0)

.TP
--t
time
Measure time for the operation and present results. . Default(false)

.SH EXAMPLES
.PP
Execute an enumerateinstancenames CIM operation for the pg_computersystem Class
.br
CLI enumerateinstancenames pg_computersystem  -- enumerateinstances of class
.br
   or
.br
 CLI ei pg_computersystem    -- Same as above

.PP
Enumerate the class names from the default namespace "root/cimv2"
.br
 CLI enumerateclassnames -- Enumerate classnames from root/cimv2.
.PP
Enumerate class names from the namespace "root"
.br
 CLI ec /n root -- Enumerate classnames from namespace root.
.P
 CLI ec -o xml   -- Enumerate classes with XML output starting at root CLI enumerateclasses CIM_Computersystem -o xml
    -- Enumerate classes in MOF starting with CIM_Computersystem
.PP
 CLI getclass CIM_door -a -u guest -p guest
    -- Get class with authentication set and user = guest, password = guest.
.P
 CLI rn TST_Person.name=@MIKE@ -n root/sampleprovider -rc TST_Lineage.
.PP
 CLI ec -o XML -- enumerate classes and output XML rather than MOF.
.PP
 CLI getqualifiers -- Get the qualifiers in mof output format
.SH BUGS
Currently at least some platforms and shells have problems with the double-quote which
is used extensively in object names within CIM. To get around this, the
character '@' has been mapped to the double-quote so that inputting
a command line with this character in place of quotes is acceptable.
Thus, for example, 

CLI rn TST_Person.name=@MIKE@ ...

is equivalent to

CLI rn TST_Person.name-"MIKE" ...

In this version there is no way to turn this character mapping off which
means that the @ character is lost.

.SH WARNINGS

.SH "RETURN VALUE"

CLI returns the following codes TBD
.SH AUTHOR 

Karl Schopmeyer k.schopmeyer@opengroup.org