grpc-curl

grpc-curl is a command line tool for interacting with gRPC servers.

All the functionalities of grpc-curl are also accessible through the NuGet package DynamicGrpc that is part of this repository.

This tool is the .NET equivalent of the popular gRPCurl written in Golang.

NOTE: grpc-curl doesn't not support yet all the features that gRPCurl is providing.

Features

Allows to invoke method services for all gRPC calling modes (unary, client streaming, server streaming, full-duplex).
Allows to print proto reflection descriptors back to proto language (via --describe with grpc-curl, or via the API .ToProtoString() with DynamicGrpc)
Supports for plain Protocol Buffers naming conventions and JSON.
Supports for google.protobuf.Any: The type has to be encoded - and is decoded with the shadow property @type on a dictionary (e.g @type = "type.googleapis.com/YourTypeName").
Build on top of the DynamicGrpc library available as a separate NuGet package.
Build for net6.0+
Available for multiple platforms. See binaries section below.

Usage

grpc-curl currently requires that the gRPC server has activated gRPC reflection.

Copyright (C) 2022 Alexandre Mutel. All Rights Reserved
grpc-curl - Version: 1.3.6

Usage: grpc-curl [options] address service/method

  address: A http/https URL or a simple host:address.
           If only host:address is used, HTTPS is used by default
           unless the options --http is passed.

## Options

  -d, --data=VALUE           Data for string content.
      --http                 Use HTTP instead of HTTPS unless the protocol is
                               specified directly on the address.
      --json                 Use JSON naming for input and output.
      --describe             Describe the service or dump all services
                               available.
  -v, --verbosity[=VALUE]    Set verbosity.
  -h, --help                 Show this help.

Query a service

./grpc-curl --json -d "{""getStatus"":{}}" http://192.168.100.1:9200 SpaceX.API.Device.Device/Handle

Will print the following result:

{
  "apiVersion": 4,
  "dishGetStatus": {
    "deviceInfo": {
      "id": "0000000000-00000000-00000000",
      "hardwareVersion": "rev2_proto3",
      "softwareVersion": "992cafb5-61c7-46a3-9ef7-5907c8cf90fd.uterm.release",
      "countryCode": "FR",
      "utcOffsetS": 1
    },
    "deviceState": {
      "uptimeS": 667397
    },
    "obstructionStats": {
      "fractionObstructed": 2.2786187E-06,
      "wedgeFractionObstructed": [
        0.0,
        0.0,
        0.0,
        0.0,
        0.0,
        0.0,
        0.0,
        0.0,
        0.0,
        0.0,
        0.0,
        0.0
      ],
      "wedgeAbsFractionObstructed": [
        0.0,
        0.0,
        0.0,
        0.0,
        0.0,
        0.0,
        0.0,
        0.0,
        0.0,
        0.0,
        0.0,
        0.0
      ],
      "validS": 667070.0,
      "avgProlongedObstructionIntervalS": "NaN"
    },
    "alerts": {
      "roaming": true
    },
    "downlinkThroughputBps": 461012.72,
    "uplinkThroughputBps": 294406.6,
    "popPingLatencyMs": 30.35,
    "boresightAzimuthDeg": 0.7464048,
    "boresightElevationDeg": 65.841354,
    "gpsStats": {
      "gpsValid": true,
      "gpsSats": 12
    }
  }
}

Describe a service

./grpc-curl --describe http://192.168.100.1:9200 SpaceX.API.Device.Device

Will print:

// SpaceX.API.Device.Device is a service:
service Device {
  rpc Stream ( .SpaceX.API.Device.ToDevice ) returns ( .SpaceX.API.Device.FromDevice );
  rpc Handle ( .SpaceX.API.Device.Request ) returns ( .SpaceX.API.Device.Response );
}

Describe all proto files serviced via reflection

./grpc-curl --describe http://192.168.100.1:9200

Will print:

// spacex/api/common/status/status.proto is a proto file.
syntax = "proto3";

package SpaceX.API.Status;

// SpaceX.API.Status.Status is a message:
message Status {
  int32 code = 1;
  string message = 2;
}


// spacex/api/device/command.proto is a proto file.
syntax = "proto3";

package SpaceX.API.Device;

// SpaceX.API.Device.PublicKey is a message:
message PublicKey {
  string key = 1;
  repeated Capability capabilities = 2;
}

// ....... and more prints ........

Usage API

All the functionalities of grpc-curl are also accessible through the NuGet package DynamicGrpc.

var channel = GrpcChannel.ForAddress("http://192.168.100.1:9200");
// Fetch reflection data from server
var client = await DynamicGrpcClient.FromServerReflection(channel);

// Call the method `Handle` on the service `SpaceX.API.Device.Device`
var result = await client.AsyncUnaryCall("SpaceX.API.Device.Device", "Handle", new Dictionary<string, object>()
{
    { "get_status", new Dictionary<string, object>() }
});

// Print a proto descriptor
FileDescriptor descriptor = client.Files[0];
Console.WriteLine(descriptor.ToProtoString());

Binaries

grpc-curl is available on multiple platforms:

Platform	Packages
`win-x64`, `win-arm`, `win-arm64`	`zip`
`linux-x64`, `linux-arm`, `linux-arm64`	`deb`, `tar`
`rhel-x64`	`rpm`, `tar`
`osx-x64`, `osx-arm64`	`tar`

If you have dotnet 6.0 installed, you can install this tool via NuGet:

dotnet tool install --global grpc-curl

Otherwise, you can install native binaries to Windows, Linux, and macOS with the various debian/rpm/zip packages available directly from the releases.

grpc-curl is also available via homebrew for macOS and Linux:

$ brew tap xoofx/grpc-curl
$ brew install grpc-curl

License

This software is released under the BSD-Clause 2 license.

Author

Alexandre Mutel aka xoofx.

xoofx / grpc-curl