{"id":13451917,"url":"https://github.com/njpatel/grpcc","last_synced_at":"2025-04-15T03:49:53.038Z","repository":{"id":57254535,"uuid":"51334906","full_name":"njpatel/grpcc","owner":"njpatel","description":"A gRPC cli interface for easy testing against gRPC servers","archived":false,"fork":false,"pushed_at":"2019-04-18T16:27:03.000Z","size":105,"stargazers_count":1131,"open_issues_count":28,"forks_count":75,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-04-15T03:49:48.592Z","etag":null,"topics":["developer-tools","devops","devtools","grpc","grpc-client","http2","protobuf","protobuf3"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/njpatel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-02-08T23:26:59.000Z","updated_at":"2025-01-05T06:39:55.000Z","dependencies_parsed_at":"2022-08-31T09:00:21.790Z","dependency_job_id":null,"html_url":"https://github.com/njpatel/grpcc","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njpatel%2Fgrpcc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njpatel%2Fgrpcc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njpatel%2Fgrpcc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njpatel%2Fgrpcc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/njpatel","download_url":"https://codeload.github.com/njpatel/grpcc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249003943,"owners_count":21196794,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["developer-tools","devops","devtools","grpc","grpc-client","http2","protobuf","protobuf3"],"created_at":"2024-07-31T07:01:06.880Z","updated_at":"2025-04-15T03:49:53.021Z","avatar_url":"https://github.com/njpatel.png","language":"JavaScript","readme":"# grpcc [![Circle CI](https://circleci.com/gh/njpatel/grpcc.svg?style=svg)](https://circleci.com/gh/njpatel/grpcc)\n\n`grpcc` is a flexible command-line client for any gRPC server for quick and easy testing of APIs. `grpcc` is written in nodejs but can talk to a gRPC service written in any language.\n\nThis is an example of using `grpcc` with the [Skizze](https://github.com/skizzehq/skizze) database's gPRC `.proto` file:\n\n\u003cimg src=\"https://njp.ghost.io/content/images/2017/10/grpccv1-2.png\" alt=\"grpcc cli image\" width=\"758\" height=\"841\"\u003e\n\n\n### Features\n* Easy to create flexible connections to gRPC services for testing\n* Supports auto-reconnect via the standard gRPC backoff-retries\n* Use Javascript objects to mimic protobuf `Message` objects\n* In-built, simple to use pretty-printing callbacks:\n  * `printReply` to print unary method call replies\n  * `streamReply` to print stream `call.on('data'...` replies\n  * `printMetadata` to parse and print metadata using `call.on('metadata', pm)`\n* Support for adding gRPC metadata via `createMetadata`\n* Parsing of error-metadata to json\n* Full support for streams (client, server, and bi-directional)\n* Flexibility of a full nodejs environment that can be as simple or complex as required\n* **eval** support allows using grpcc like curl, fire off a request and have JSON printed to the console\n* **exec** support allows executing pre-existing scripts with results being outputted to stdout\n* Connect with ssl, custom ssl certs, or insecurely\n* Socket connection support via `--address \"unix:/path/to/sockfile`\n\n\n### Installation\n\n`npm install -g grpcc`\n\n\n### Getting Started\n\nTo use it, you only need the service's `.proto` file, which describes the RPC service, and the address (host:port) of the service. `grpcc` can talk to local or remote services:\n\n```\n$ grpcc --proto ./service/myservice.proto --address 127.0.0.1:3466\n```\n\nBy default, `grpcc` will attempt to make a secure connection to the service. If you need an insecure connection, you can pass in the `-i` flag.\n\nOnce `grpcc` has connected, it will print out usage instructions for the configured service. It does this by reading the parsed values from the protobuf file. After printing the instructions, it will start a nodejs REPL with the following globals available:\n\n* `client` - this is the gRPC client connection to your service. The usage instructions will show the available methods, as will using tab completion by typing `client.\u003ctab\u003e`\n* `printReply` - a convenience callback for printing the response of an RPC call (nicer than `console.log`) (alias: `pr`)\n* `streamReply` - a convenience callback for printing the response of an stream's `'data'` event (nicer than `console.log`) (alias: `cr`)\n* `createMetadata` - a convenience function for converting plain javascript objects to gRPC metadata (alias: `cm`)\n* `printMetadata` - a convenience callback for printing the metadata of an RPC call (nicer than `console.log`) (alias: `pm`)\n\n\nThe REPL environment uses node's [`repl`](https://nodejs.org/api/repl.html) module, so feel free to use any of the in-built features such as save/restore history etc.\n\n#### Arguments, Callbacks, \u0026 Streaming\n\nDepending on whether your method is a simple call or a streaming call, you'll have to do different things:\n\n* All calls require an argument matching the spec, so if you have an empty message type in your proto for some calls, you'll be sending in `{}` as the first argument to those calls\n* Remember that Protobuf.js will camelCase class and property names\n* Unary calls can take a callback as the second argument which has the signature `function(err, reply)`. `reply` will be an object matching the message type as per your proto\n* For streaming calls, you'll want to use the `EventEmitter` object that is returned when the call is made and connect to the appropriate events. **Note** the grpc nodejs docs are out of date, check out the examples to see how to work with streams.\n\n\n### --eval \u0026 --exec\n\nThe `--eval` and `--exec` options allow running scripts against gRPC servers without the `grpcc` repl being activated. The output of the script is sent to stdout so it's possible to use these modes as part of your own scripts/tests/etc:\n\n**--eval**\n```\n $ grpcc -i -p foo.proto -a localhost:9090 --eval 'client.getPerson({ id: 1 }, printReply)'\n {\n   \"name\": \"Neil Jagdish Patel\",\n   \"location\": \"London\",\n   \"country\": \"United Kingdom\",\n }\n```\n\n**--exec**\n```\n$ cat myscript.js\nvar call = client.add({}, pr);\nlet i = 0;\nlet id = setInterval(() =\u003e {\n  if (i \u003e 5) {\n    clearInterval(id);\n    return call.end();\n  }\n  i++;\n  call.write({ data: i });\n}, 100);\n\n$ grpcc -i -p foo.proto -a localhost:9090 --exec myscript.js\n{\n  \"sum\": 15\n}\n\n```\n\n\n### Examples\n\nThere are some example scripts you can run in the [examples](https://github.com/njpatel/grpcc/tree/master/examples) directory. To test them out, do the following:\n\n**Start the example gRPC server**\n```\n# do this in another terminal tab/window as it has to be running in the background (and will print a lot of information)\n$ npm run example-server\n```\n\n**Run the example scripts**\n```\n$ ./bin/grpcc.js --insecure --proto ./test/test.proto --address localhost:8099 --exec ./examples/unary.js\n\u003e outputs result of TestService.sayHello()\n\n$ ./bin/grpcc.js -i -p ./test/test.proto -a localhost:8099 -x ./examples/client-stream.js\n\u003e script will send 5 'hellos' to server, then end the stream. Server will reply with all five hellos\n\n$ ./bin/grpcc.js -i -p ./test/test.proto -a localhost:8099 -x ./examples/server-stream.js\n\u003e script print streamed data from the server until server ends the stream\n\n$ ./bin/grpcc.js -i -p ./test/test.proto -a localhost:8099 -x ./examples/bidirectional-stream.js\n\u003e script streams data to server, while server streams data back to client. Either side can end the stream.\n```\n\nYou can see the server's output in the other terminal. The unary example also shows how to send and receive `metadata`.\n\n\n### Usage\n\n```\n  Usage: grpcc [options]\n\n\n  Options:\n\n    -V, --version              output the version number\n    -p, --proto \u003cpath\u003e         path to a protobuf file describing the service (required)\n    -d, --directory \u003cpath\u003e     path to a protobuf file directory\n    -a, --address \u003chost:port\u003e  the address of the service to connect to (required)\n    -s, --service \u003cname\u003e       the name of the service to connect to (optional)\n    -i, --insecure             use an insecure connection (default=false)\n    -e, --eval \u003cstring\u003e        evaluate script and print result (optional)\n    -x, --exec \u003cpath\u003e          execute a script file and print the results (optional)\n    --root_cert \u003cpath\u003e         specify root certificate path for secure connections (optional)\n    --private_key \u003cpath\u003e       specify private key path for secure connections (optional)\n    --cert_chain \u003cpath\u003e        specify certificate chain path for secure connections (optional)\n    -h, --help                 output usage information\n```\n\n\n\n### Todo\n\nCheck out the [project](https://github.com/njpatel/grpcc/projects/1)\n\n\n### License\n\nMIT\n\n\n### Contact\n\nNeil Jagdish Patel\n\n[Github](https://github.com/njpatel) [Twitter](https://twitter.com/njpatel) [Blog](https://njp.io)\n","funding_links":[],"categories":["JavaScript","JavaScript (71)","Tools"],"sub_categories":["CLI"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnjpatel%2Fgrpcc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnjpatel%2Fgrpcc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnjpatel%2Fgrpcc/lists"}