Usage.txt

gWhisper - A gRPC command-line client
https://github.com/IBM/gWhisper

This tool allows to call gRPC RPCs on any gRPC server with reflection enabled.
You may and should use TAB completion for all arguments (currently only
supported in BASH and FISH).

SYNOPSIS:

Unary and server-streaming RPCs:

gwhisper [OPTION ]... SERVER_URI <service> <method> [<fieldName>=FIELD_VALUE ]...


Client-streaming RPCs:

gwhisper [OPTION ]... SERVER_URI <service> <method> [:[<fieldName>=FIELD_VALUE ]...: ]...


The default TCP port used to connect to a gRPC server is 50051.

If some or all fields of the request message are omitted, they are initialized
to their default value according to the proto3 language reference. See
https://developers.google.com/protocol-buffers/docs/proto3#default
for details.

OPTION:

 General options:

   -h
   --help
       Shows this help and exits.

   --version
       Prints version information and exits.

 Behavioral options:

   --complete[=DIALECT]
       Shows possible next arguments and exits.
       DIALECT selects how suggections are formatted. Usually dialects customize
       the printed suggestions to be compatible with the completion API of a
       given shell.
       Currently two dialects are supported:
         fish: compatible putput for the fish 'complete' command
         bash: compatible output for the bash 'complete' command
       If no DIALECT is specified 'bash' is used as a default.

   --connectTimeoutMilliseconds=TIMEOUT_VALUE
       Default: 500
       Sets the timeout for the gRPC Channel to go into connected state. If the
       channel is not in connected state after the specified timeout, the gRPC
       call and reflection-based completion attempts are aborted.

    --rpcTimeoutMilliseconds=TIMEOUT_VALUE
        Default for unary RPC: 10000 (10 sec)
        Default for streaming RPCs: infinite (no deadline set)
        Defines a limit for the client to wait for the server's response to an RPC.
        If this limit is exeeded, the RPC will abort with 'deadline_exeeded'.
        To set an infinite timeout for unary RPCs, set the TIMEOUT_VALUE to 'None'.
        Example:
          gwhisper --rpcTimeoutMilliseconds=None
          gwhisper --rpcTimeoutMilliseconds=100

 SSL connection options:

   --ssl
	   Opens a secure channel with SSL/TLS for RPCs.
	   Optionally you may use --clientCert, --clientKey and --serverCert to
	   specify credentials.
	   If the server is insecure (no SSL), not setting the --ssl option opens 
	   an insecure connection without encryption and authentication.
	   Building the connection fails, when using --ssl on an insecure server.

	   Valid Examples: 
	      gwhisper <host>
	      gwhisper --ssl --serverCert=<path> --clientKey=<path> --clientCert=<path> <host>
	      gwhisper --ssl <host>
	      gwhisper --ssl --serverPath=<path> <host>

   --clientCert=<path to client certificate>
	   Set location to client certificate file.
	   The certificate should be in .pem or .crt format.
	   Use this optional parameter, if you want to specify a client certificate.
	   May be empty if client does not have a certificate chain.
	   As soon as --clientKey is set, a clientCert ist required
	   If the server requires a valid cert-key-pair and --clientCert is not set,
	   the connection will fail.
	   If this option is used without using --ssl on a secure server,
	   building the connection fails.

   --clientKey=<path to client private key>
	   Set location to client private key file.
	   The key should be in .pem or .key format.
	   Use this optional parameter, if you want to specify a client key.
	   May be empty (set with empty string) or not set at all, if server
	   does not require a valid client cert-key pair for authentication.
	   If you set --clientKey you must provide the matching clientCert
	   If the server requires a valid cert-key-pair for authentication
	   and the --clientKey is empty or not set, the connection will fail.
	   If this option is used without using --ssl on a secure server,
	   building the connection fails.

   --serverCert=<path to server certificate>
	   Set location to server certificate file.
	   The certificate should be in .pem or .crt format.
	   While clientCert and clientKey are not always needed, either the default certificate 
	   or a certificate provided by the user is mandatory for building a connection.
	   Use this optional parameter, if you want to provide an own  server certificate.
	   If this option is not set, the default-roots will be used.
	   The default location is the system cert path, which can be overridden by
	   gRPC environment GRPC_DEFAULT_SSL_ROOTS_FILE_PATH.
	   The connection will fail if no cert is found at the provided location.
	   If this option is used without using --ssl on a secure server,
	   building the connection fails.

 Output formatting options:

   --noColor
       Disables colors in the output of gRPC replies.
       NOTE: colors are automatically disabled when gwhisper is outputting
       into a pipe.

   --color
       Enables colors also in pipes.

   --noSimpleMapOutput
       Disable the map outputted as "key => value" of gRPC replies.

   --customOutput OUTPUT_FORMAT
       Instead of printing the reply message using the default human readable
       format, a custom format as specified in OUTPUT_FORMAT is used.
       See OUTPUT_FORMAT section for a description of the OUTPUT_FORMAT
       language.
       NOTE: This is an experimental feature and will be documented in detail,
       once finished.

    --jsonOutput
       Print the reply-message in JSON format, instead of using the gwhisper
       human readable format. (All output options listed above do not apply)


 Input options:

   --printParsedMessage
       Prints the parsed request message before calling the remote procedure.
   
   --jsonInput=[FILENAME ]...
       Read the request message from a file containing a JSON representation,
       instead of parsing it from commandline arguments.
       If filename is set to the reserved name "-", JSON content is read from
       stdin. Note that in this case the whole stdin is consumed until EOF.
       In case of a client-side streaming RPC, you may specify multiple JSON
       files, each containing a single message.
       Whitespaces in filenames need to be escaped using '%'.


 Debug options:

   --dot
       Prints a graphviz digraph, representing the current grammar of the
       parser.

   --debugComplete
       Prints debug information about completion (might only be useful if
       --complete is also present).

SERVER_URI:

    URI addressing the server.
    Either a TCP URI, or a Unix-Domain-Socket URI:
        host[:port]
        dns:[//authority/]host[:port]
        ipv4:address[:port][,address[:port],...]
        ipv6:address[:port][,address[:port],...]
        unix:path
        unix-abstract:abstract_path

    The URI-scheme mostly follows the gRPC Name resolution scheme, as detailed
    here: https://grpc.github.io/grpc/cpp/md_doc_naming.html
    With the following exceptions:
    1. The TCP default port (if none is specified) is 50051 instead of 443
    2. The unix://absolute_path scheme is not supported

    Examples:
        127.0.0.1
        127.0.0.1:50053
        exampleDomain.com
        exampleDomain.com:50053
        dns:exampleDomain.com
        dns:exampleDomain.com:50053
        ipv4:127.0.0.1
        ipv4:127.0.0.1:50050
        ipv6:[2607:f8b0:400e:c00::ef]:50052
        unix:/tmp/socket
        unix-abstract:socketAbstractName

FIELD_VALUE:

  Field values in the request message may be specified as follows:

  - integers:
      decimal (e.g. 46, -46, +46)
      hexadecimal (e.g. 0x45ab, -0x45Ab, +0x45ab)
        NOTE: When parsing hex numbers the case is ignored.
      octal (e.g. 078, -078, +078)
  - floats:
      decimal (e.g. 31, -67.421e-8, 83.456, 23.3e8)
      hexadecimal (e.g. -0xa7B6p-7)
        NOTE: When parsing hex numbers the case is ignored.
  - bytes:
      As a hex number or as input from a file:
      - The hex number is prefixed with '0x' (e.g. 0xab4B2F2e9d7f)
        NOTE: Only multiple of 8 bits possible
        NOTE: When parsing hex numbers the case is ignored.
      - The input filename is prefixed with 'file://' (e.g. file://myfile.bin)
  - strings:
      As a string without quotes. (e.g. ThisIsAString)
      NOTE: gWhisper control characters ' ', ',', '%' or ':' need to be escaped by
            pre-pending a '%'
      Example:
        The string "Hello World: 100% understood?" needs to be written as
        Hello% World%:% 100%%% understood?
  - enum values:
      As the enum value name
      Enum values are tab-completed
  - bools
      true, false, 1, 0
      Bool values are tab-completed
  - nested types:
      The nested type fields enclosed in colons. E.g. target=:field1=1 field2=2:
      Nested types are tab-completed
  - repeated fields:
      A list of field values enclosed in colons, separated with a comma and a
      whitespace.
      E.g. values=:2, 4, 16, 32:
      Repeated fields are tab-completed
  - map fields:
      As a repeated field with nested key, value pairs (protobuf representation
      of maps).
      E.g. my_map=::key=5 value=testval:, :key=40 value=anotherValue::
      Map fields are tab-completed

OUTPUT_FORMAT:

    This is a program written in a very simple formatting language.

    A valid program has the following form:
        @ (.<FieldName>)+ : ( <String> || /<FieldName>[%<Modifier>]/ )+ :
    The modifier is optional. Valid modifiers are: 'default', 'dec', 'hex' and
    'raw' (binary output)

    Examples:
        Filter output:
        gwhisper --customOutput @.listOfDevices:Found device /device_name%default/$'\n': 127.0.0.1 discoveryService.devices GetDevices
        Output:
            Found device Mouse
            Found device Keyboard
            Found device Screen
            ...
        This will search for any number of fields with a name "listOfDevices"
        in the RPC reply message. For each match (multiple in case of repeated
        field), The string `"Found device /device_name/\n"` is printed with
        `/device_name/` replaced by the value of the field `"device_name"`.

        Write binary data to file:
        gwhisper --customOutput @.:/data%raw/: 127.0.0.1 examples.ScalarTypeRpcs bitwiseInvertBytes data=0xabcd > file.bin
        This will redirect the data field of the reply message as raw binary
        data to stdout. Then it can be redirected into a file.


EXAMPLES:

  gwhisper exampledomain.org:50059 bakery orderCookies amount=5
      Connects to the gRPC server running at exampledomain.org on TCP port 50059
      and calls the orderCookies RPC method of the bakery service.
      A request message will be passed to the RPC call with the 'amount' field
      set to 5. Other fields, which might be present in the message type, but
      not specified here, are initialized to default values.

  gwhisper [2001:db8::2:1]:50059 bakery orderCookies config=:chocolate=true smarties=false: amount=5
      Uses IPv6 address and nested types in the request message.

  gwhisper 192.168.0.43 bakery orderCookies amount=0xa
      Uses IPv4 address, default TCP port of 50051 and field value as hex.

  gwhisper 127.0.0.1 examples.StreamingRpcs requestStreamCountMessages :: ::
      Issues a client-streaming RPC against the example server, streaming two empty messages.

  gwhisper 127.0.0.1 examples.StreamingRpcs bidirectionalStreamNegateNumbers :number=3: :number=7:
      Issues a bi-directional streaming RPC against the example server.
      Result will be:
        number = -3
        number = -7