{"id":13739827,"url":"https://github.com/grpc-ecosystem/polyglot","last_synced_at":"2025-04-04T22:07:58.134Z","repository":{"id":43444799,"uuid":"54324354","full_name":"grpc-ecosystem/polyglot","owner":"grpc-ecosystem","description":"A universal grpc command line client","archived":false,"fork":false,"pushed_at":"2022-09-05T17:33:32.000Z","size":1074,"stargazers_count":530,"open_issues_count":18,"forks_count":60,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-03-28T21:07:42.434Z","etag":null,"topics":["client","command-line","grpc","java","protobuf","universal"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grpc-ecosystem.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-03-20T15:14:14.000Z","updated_at":"2024-12-31T15:44:58.000Z","dependencies_parsed_at":"2023-01-17T21:02:22.935Z","dependency_job_id":null,"html_url":"https://github.com/grpc-ecosystem/polyglot","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grpc-ecosystem%2Fpolyglot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grpc-ecosystem%2Fpolyglot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grpc-ecosystem%2Fpolyglot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grpc-ecosystem%2Fpolyglot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grpc-ecosystem","download_url":"https://codeload.github.com/grpc-ecosystem/polyglot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247256112,"owners_count":20909240,"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":["client","command-line","grpc","java","protobuf","universal"],"created_at":"2024-08-03T04:00:38.077Z","updated_at":"2025-04-04T22:07:58.118Z","avatar_url":"https://github.com/grpc-ecosystem.png","language":"Java","readme":"# Polyglot - a universal grpc command line client\n\n![Build Status](https://github.com/grpc-ecosystem/polyglot/actions/workflows/bazel_test.yaml/badge.svg)\n\nPolyglot is a grpc client which can talk to any grpc server. In order to make a call, the following are required:\n* A compiled Polyglot binary,\n* the .proto files for the service *or* grpc reflection enabled on the remote server,\n* and a request proto instance in text format.\n\nIn particular, it is not necessary to generate grpc classes for the service or to compile the protos into the Polyglot binary.\n\n## Features\n\n* Supports unary, client streaming, server streaming, and bidi streaming rpcs.\n* Runs on Windows, Mac and Linux.\n* Parses proto files at runtime to discover services. Supports pretty-printing discovered services.\n* Can discover services by reflection if the remote server has reflection enabled\n* Supports authentication via oauth.\n* Accepts request protos through stdin and can output responses to stdout to allow chaining.\n* Supports plain text connections as well as TLS.\n* Supports passing custom grpc metadata over the command line.\n* Supports all protobuf well-known-types, including fields of type \"Any\".\n\n## Usage\n\n### Requirements\n\nAll you need to run Polyglot is a Java runtime. Binaries for Mac, Linux, and Windows are available from the [releases page](https://github.com/dinowernli/polyglot/releases).\n\n### Making a grpc request\n\nThe \"Hello World\" of using Polyglot is to make an rpc call. This can be done using `call` command as follows:\n\n```\n$ echo \u003cjson-request\u003e | java -jar polyglot.jar \\\n    --proto_discovery_root=\u003cpath\u003e \\\n    call \\\n    --endpoint=\u003chost\u003e:\u003cport\u003e \\\n    --full_method=\u003csome.package.Service/doSomething\u003e\n```\n\nFor stream requests double newlines `\\n\\n` are used to separate your json requests as follows:\n\n```\n$ echo '\u003cjson-request-1\u003e \\n\\n \u003cjson-request-2\u003e ... \\n\\n \u003cjson-request-n\u003e' | java -jar polyglot.jar \\\n    --proto_discovery_root=\u003cpath\u003e \\\n    call \\\n    --endpoint=\u003chost\u003e:\u003cport\u003e \\\n    --full_method=\u003csome.package.Service/doSomething\u003e  \n```\n\nFor more invocation examples, see the [examples](https://github.com/grpc-ecosystem/polyglot/tree/master/src/tools/example) directory.\n\n### Server reflection\n\nIf the remote server has reflection enabled, there is no need to pass the proto files to Polyglot. The example invocation above then becomes:\n\n```\n$ echo \u003cjson-request\u003e | java -jar polyglot.jar \\\n    call \\\n    --endpoint=\u003chost\u003e:\u003cport\u003e \\\n    --full_method=\u003csome.package.Service/doSomething\u003e\n```\n\nBy default, Polyglot always tries to use reflection before compiling local protos. Reflection can be turned off explicitly by setting the flag `--use_reflection=false`.\n\n### Configuration (optional)\n\nSome of the features of Polyglot (such as Oauth, see below) require some configuration. Moreover, that sort of configuration tends to remain identical across multiple Polyglot runs. In order to improve usability, Polyglot supports loading a configuration set from a file at runtime. This configuration set can contain multiple named `Configuration` objects (schema defined [here](https://github.com/dinowernli/polyglot/blob/master/src/main/proto/config.proto#L14)). An example configuration could look like this:\n\n```json\n{\n  \"configurations\": [\n    {\n      \"name\": \"production\",\n      \"call_config\": {\n        \"use_tls\": \"true\",\n        \"oauth_config\": {\n          \"refresh_token_credentials\": {\n            \"token_endpoint_url\": \"https://auth.example.com/token\",\n            \"client\": {\n                \"id\": \"example_id\",\n                \"secret\": \"example_secret\"\n            },\n            \"refresh_token_path\": \"/path/to/refresh/token\"\n          }\n        }\n      },\n      \"proto_config\": {\n        \"proto_discovery_root\": \"/home/dave/protos\",\n        \"include_paths\": [\n          \"/home/dave/lib\"\n        ]\n      }\n    },\n    {\n      \"name\": \"staging\",\n      \"call_config\": {\n        \"oauth_config\": {\n          \"refresh_token_credentials\": {\n            \"token_endpoint_url\": \"https://auth-staging.example.com/token\"\n          }\n        }\n      },\n      \"proto_config\": {\n        \"proto_discovery_root\": \"/home/dave/staging/protos\",\n        \"include_paths\": [\n          \"/home/dave/staging/lib\"\n        ]\n      }\n    }\n  ]\n}\n```\n\nBy default, Polyglot tries to find a config file at `$HOME/.polyglot/config.pb.json`, but this can be overridden with the `--config_set_path` flag. By default, Polyglot uses the first configuration in the set, but this can be overridden with the `--config_name` flag.\n\nThe general philosophy is for the configuration to drive Polyglot's behavior and for command line flags to allow selectively overriding parts of the configuration. For a full list of what can be configured, please see [`config.proto`](https://github.com/dinowernli/polyglot/blob/master/src/main/proto/config.proto#L14).\n\n### Using TLS\n\nPolyglot uses statically linked [boringssl](https://boringssl.googlesource.com/boringssl/) libraries under the hood and doesn't require the host machine to have any specific libraries. Whether or not the client uses TLS to talk to the server can be controlled using the `--use_tls` flag or the corresponding configuration entry.\n\nPolyglot can also do client certificate authentication with the `--tls_client_cert_path` and `--tls_client_key_path` flags. If the hostname on the server does not match the endpoint (e.g. connecting\nto `localhost`, but the server thinks it's `foo.example.com`), `--tls_client_override_authority=foo.example.com` can be used.\n\n### Authenticating requests using OAuth\n\nPolyglot has built-in support for authentication of requests using OAuth tokens in two ways:\n* Loading an access token from disk and attaching it to the request.\n* Loading a refresh token from disk, exchanging it for an access token, and attaching the access token to the request.\n\nIn order to use this feature, Polyglot needs an `OauthConfiguration` inside its `Configuration`. For details on how to populate the `OauthConfiguration`, please see the documentation of the fields in [`config.proto`](https://github.com/dinowernli/polyglot/blob/master/src/main/proto/config.proto#L14).\n\n### Listing services\n\nPolyglot supports printing a list of all the discovered services using the `list_services` command. This command can be invoked as follows:\n\n```\n$ java -jar polyglot.jar \\\n    --proto_discovery_root=\u003cpath\u003e \\\n    list_services\n```\n\nThe printed services can be filtered using `--service_filter=\u003cservice_name\u003e` or `--method_filter=\u003cmethod_name\u003e`, and the `--with_message` flag can be used to also print the exact format of the requests.\n\n### Custom metadata\n\nIt is possible to add custom grpc metadata to calls made using Polyglot by setting the `--metadata=key1:value1,key2:value2` flag.\n\n### Configuring logs\n\nPolyglot uses the `slf4j` logging framework with the `org.slf4j.impl.SimpleLogger` implementation. It also redirects grpc's JUL logs to `slf4j`. To change the default log level, specify the `org.slf4j.simpleLogger.defaultLogLevel` JVM argument, e.g., by passing the argument `-Dorg.slf4j.simpleLogger.defaultLogLevel=debug`.\n\n## Build requirements\n\nIn order to build Polyglot from source, you will need:\n\n* [Java 8](https://www.oracle.com/downloads/index.html)\n* [Bazel](http://bazel.io)\n\n## Building a binary\n\n`$ bazel build src/main/java/me/dinowernli/grpc/polyglot`\n\nAfter calling this, you should have a fresh binary at:\n\n`./bazel-bin/src/main/java/me/dinowernli/grpc/polyglot`\n\nIf you would like to build a deployable (fat) jar, run:\n\n`$ bazel build src/main/java/me/dinowernli/grpc/polyglot:polyglot_deploy.jar`\n\n## Running the examples\n\nExample invocations can be found in the [examples](https://github.com/grpc-ecosystem/polyglot/tree/master/src/tools/example) directory. In order to run a simple rpc call, invoke [`run-server.sh`](https://github.com/grpc-ecosystem/polyglot/tree/master/src/tools/example/run-server.sh) followed by (in a different terminal) [`call-command-example.sh`](https://github.com/grpc-ecosystem/polyglot/tree/master/src/tools/example/call-command-example.sh).\n\n## Building and running tests\n\n`$ bazel test //src/...`\n\n## Main contributors\n\n* [Dino Wernli](https://github.com/dinowernli)\n","funding_links":[],"categories":["Tools","Java"],"sub_categories":["CLI"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrpc-ecosystem%2Fpolyglot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrpc-ecosystem%2Fpolyglot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrpc-ecosystem%2Fpolyglot/lists"}