Reference
This pageapplies toApigee andApigee hybrid.
View Apigee Edge documentation.
Theapigee-remote-service-cli Command Line Interface (CLI) helps you provision and manage Apigee Adapter for Envoy.
Binding commands
Binding associates a service deployed to the Istio mesh with an Apigee API product. The CLI lets you create, remove, list, and verify bindings.
Note:In the Apigee UI, you can add one or more remote service targets to an API. Doing so is equivalent to creating the binding using the CLI.List bindings
List all API products that are bound to the Remote Service.
Usage
For Apigee hybrid:
apigee-remote-service-cli bindings list -o [organization] -e [environment] -t [token] -r [runtime]
Parameters
| Parameters | Type | Description |
|---|---|---|
-c, --config | String | (Required) The path to the Apigee Remote Service config file. Tip: This flag allows you to omit most other command parameters, because the CLI is able to pull them directly from the config file. See Using the --config option. |
-e, --env | String | (Required) An environment in your organization. |
-h, --help | Displays help for the command parameters. | |
--insecure | Allow insecure server connections when using SSL | |
--legacy | Set this flag if you are using Apigee Cloud. It sets the management and runtime URLs for Edge Cloud. | |
--opdk | Set this flag if you are using Apigee for Private Cloud. | |
-o, --org | String | (Required) An Apigee organization. You must be an org administrator. |
-p, --password | String | (Required for basic authentication only - not available for hybrid) Your Apigee password. You can optionally specify the password in a.netrc file. If you do so, then you are not required to provide your password on the command line. See alsoUsing .netrc for credentials. |
-r, --runtime | String | A URL that includes thehostAlias for a virtual host defined in your hybrid configuration. The URL must start withhttps://. For example:https://apitest.apigee-hybrid-docs.net |
-t, --token | String | (Required) An access token. |
-u, --username | String | (Required for basic authentication only - not available for hybrid) Your Apigee username (typically an email address). You can optionally specify the username in a.netrc file. If you do so, then you are not required to provide your username on the command line. See alsoUsing .netrc for credentials. |
-v, --verbose | (Optional) Produces verbose output. |
Example
apigee-remote-service-cli bindings list -o myorg -e test -c config.yaml \-r $RUNTIME -t $TOKENPI Products============Bound-----envoy-test: Quota: 5 requests every 1 minute Target bindings: httpbin.org Paths:httpbin: Quota: 5 requests every 1 minute Target bindings: httpbin.org Paths: /httpbin /Unbound-------product-1: Quota: 100 requests every 1 hourproduct-2: Quota: 1000 requests every 1 monthproduct-3:product-4:
Verify a binding
Verify that the specified bound API product and its associated developer apps also have a remote service product associated with them. If you do not specify an API product name, then the command checks all bound products.
Usage
For Apigee hybrid:
apigee-remote-service-cli bindings verify [product_name] -o [organization] -e [environment] -r [runtime] -t [token]
Whereproduct_name is optional. If you do not specify a product name, all bound products are checked.
Parameters
| Parameters | Type | Description |
|---|---|---|
-c, --config | String | (Required) The path to the Apigee Remote Service config file. Tip: This flag allows you to omit most other command parameters, because the CLI is able to pull them directly from the config file. See Using the --config option. |
-e, --env | String | (Required) An environment in your organization. |
-h, --help | Displays help for the command parameters. | |
--insecure | Allow insecure server connections when using SSL | |
--legacy | Set this flag if you are using Apigee Cloud. It sets the management and runtime URLs for Edge Cloud. | |
--opdk | Set this flag if you are using Apigee for Private Cloud. | |
-o, --org | String | (Required) An Apigee organization. You must be an org administrator. |
-r, --runtime | String | A URL that includes thehostAlias for a virtual host defined in your hybrid configuration. The URL must start withhttps://. For example:https://apitest.apigee-hybrid-docs.net |
-t, --token | String | (Required) An access token. |
-v, --verbose | (Optional) Produces verbose output. |
Example
/apigee-remote-service-cli bindings verify my_product -o $ORG -e $ENV \-c config.yaml -r $RUNTIME -t $TOKENVerifying apps associated with product my-product: app my-app associated with product my-product is verified
Help command
Online help is provided for allapigee-remote-service-cli commands. Just type:
apigee-remote-service-cli help
For help on any command, type:
apigee-remote-service-cli [command] help
For example:
apigee-remote-service-cli provision help
Provision command
Theapigee-remote-service-cli provision command installs a proxy in your Apigee organization, sets up a certificate, and generates credentials that you'll need to configure the Apigee Adapter for Envoy.
Usage
For Apigee hybrid:
apigee-remote-service-cli provision -o$ORG -e$ENV -r$RUNTIME -t$TOKEN
Parameters
| Parameters | Type | Description |
|---|---|---|
--analytics-sa | String | Use this flag to specify the path to a Google Cloud service account key file, where the service account has theApigee Analytics Agent role. The SA is used by the adapter to directly upload analytics data to Apigee. If you are using Apigee hybrid, this option allows you to install the hybrid runtime in one cluster and the adapter in another cluster. This flag is only available for Apigee hybrid and Apigee on Google Cloud installations.Note:We recommend that you update your installation to use direct analytics upload. The non-direct method for uploading analytics that used Fluentd is deprecated. |
-c, --config | String | Path to Apigee Remote Service config file. See also Using the--config option. |
-e, --environment | String | (Required) An environment in your organization. |
-f, --force-proxy-install | (Optional) Forces theremote-service proxy to be re-installed if it is already installed in your org.UPGRADE NOTE:If you are upgrading to v1.1.0 or a later version, you must include the--force-proxy-install flag to replace the existing remote service proxy deployed on Apigee. | |
-h, --help | Displays help for the command parameters. | |
-k, --key | String | Specifies the key returned from theapigee-remote-service-cli provision command. |
--legacy | Apigee Edge (sets management and runtime URL) | |
-m, --management | String | (Required if you are on Apigee Private Cloud) Your Apigee management base URL. Default:https://api.enterprise.apigee.com |
-n, --namespace | String | Emit configuration as an Envoy ConfigMap in the specified namespace. Default: apigee |
--opdk | String | Set this flag if you are using Apigee for Private Cloud. |
-o, --organization | String | (Required) Your Apigee organization. You must be an org administrator. |
-p, --password | String | (Required for basic authentication only - not available for hybrid) Your Apigee password. You can optionally specify the password in a.netrc file. If you do so, then you are not required to provide your password on the command line. See alsoUsing .netrc for credentials. |
--rotate-int | int | Ifn > 0, generate new private key and keepn public keys (hybrid only) |
-r, --runtime | String | A URL that includes thehostAlias for a virtual host defined in your hybrid configuration. The URL must start withhttps://. For example:https://apitest.apigee-hybrid-docs.net |
-s, --secret | String | Specifies the secret returned from theapigee-remote-service-cli provision command. |
--strength | int | (Optional) Specifies the encryption strength for SSL certificates used in provisioning the adapter. Default 2048 |
-t, --token | String | Apigee OAuth or SAML token. |
-u, --username | String | (Required for basic authentication only - not available for hybrid) Your Apigee username (typically an email address). You can optionally specify the username in a.netrc file. See alsoUsing .netrc for credentials. |
-v, --verbose | (Optional) Produces verbose output. | |
--virtual-hosts | String | Overrides the default virtual hosts. |
--years | int | (Optional) The number of years before the SSL certificate used in the provisioning expires. Default: 1 |
Example
Be sure to capture the output of theprovision command in a file, which is used as input for other Apigee Adapter for Envoy operations.
Apigee hybrid example:
apigee-remote-service-cli provision --organization $ORG --environment $ENV --runtime $RUNTIME \--namespace $NAMESPACE --token $TOKEN > config.yaml
Samples command
Create a sample configuration file
Creates sample configuration files for native Envoy or Istio deployments.
Usage
apigee-remote-service-cli samples create [flags]
Description
The command requires a validconfig.yaml file generated through provisioning. By default, the sample files are output to a directory named./samples. The command creates this directory for you.
If you're using native Envoy, the command takes the target service host and the desired name forits cluster. It also sets custom SSL connection from the Envoy proxy to the remote servicecluster if a folder containingtls.key andtls.crt is provided via--tls.
If you're using Istio, where the Envoy proxy acts as a sidecar, if the target is unspecified, thehttpbin example will be generated. Otherwise, you are responsible for preparingconfiguration files related to deployment of your target services.
Parameters
| Parameters | Type | Description |
|---|---|---|
-c, --config | String | (Required) Path to Apigee Remote Service config file. Tip: This flag allows you to omit most other command parameters, because the CLI is able to pull them directly from the config file. See Using the --config option. |
-f, --force | Force the existing directory to be overwritten. | |
-h, --help | Displays help for the command parameters. | |
--host | The target service host (default "httpbin.org") | |
-n, --name | The target service name (default "httpbin") | |
--out | Th directory in which to create the sample config files. Default:./samples | |
-t, --template | The template name. If you're doing an Istio deployment (hybrid only), select one of the available Istio options. Use the native option for native Envoy deployments. Available options are:
| |
--tls | The directory in which to store the TLS key and crt files. |
Example
apigee-remote-service-cli samples create -c ./config.yaml
List available template options
Lists the options available to use with the--templates parameter.
Usage
apigee-remote-service-cli samples templates
Parameters
None.
Example
apigee-remote-service-cli samples templates
Supported templates (native is deprecated): envoy-1.14 envoy-1.15 envoy-1.16 istio-1.5 istio-1.6 istio-1.7 istio-1.8 native
Token commands
You can use a JWT token to make authenticated API proxy calls instead of using an API key.The token commands let you create, inspect, and rotate JWT tokens for this purpose.
Create a JWT token
You can use a JWT token to make authenticated API proxy calls to a remote service target. SeealsoUsing JWT based authentication.Usage
For Apigee hybrid:apigee-remote-service-cli token create -c [config_file] --id [consumer_key] --secret [consumer_secret] -r [runtime] -o [org] -e [env]
Parameters
| Parameters | Type | Description |
|---|---|---|
-c, --config | String | (Required) The path to the Apigee Remote Service config file. Tip: This flag allows you to omit most other command parameters, because the CLI is able to pull them directly from the config file. See Using the --config option. |
-e, --env | String | (Required) An environment in your organization. |
-h, --help | Displays help for the command parameters. | |
--insecure | Allow insecure server connections when using SSL. | |
-o, --org | String | (Required) An Apigee organization. You must be an org administrator. |
-r, --runtime | String | A URL that includes thehostAlias for a virtual host defined in your hybrid configuration. The URL must start withhttps://. For example:https://apitest.apigee-hybrid-docs.net |
-v, --verbose | (Optional) Produces verbose output. |
Example
./apigee-remote-service-cli token create -o $ORG -e $ENV -i YUmlZAcBKNsTAelJqPZFl3sh58ObATX9 \-s icTARgaKHqvUH1dq -c config.yaml -r $RUNTIME -t $TOKEN
Output
On success, you'll see a JST token output similar to the following:eyJraWQiOiIxIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJhY2Nlc3NfdG9rZW4iOiJ0a2tlVzVKQTY2a0pZYTB4bFV1cVBsUW1BMU43IiwiYXVkIjoiaXN0aW8iLCJuYmYiOjE1MzAxMzg1OTEsImFwaV9wcm9kdWN0X2xpc3QiOlsiaXN0aW8tcHJvZHVjdCJdLCJhcHBsaWNhdGlvbl9uYW1lIjoiaXN0aW8tYXBwIiwiZGV2ZWxvcGVyX2VtYWlsIjoicFluZ2Zsb3lkQGdvb2dsZS5jb20iLCJpc3MiOiJodHRwczovL2FwaWdlZXNlYXJjaC10ZXN0LmFwaWdlZS5uZXQvaXN0aW8tYXV0aC90b2tlbiIsImV4cCI6MTUzMDEzOTQ5MSwiaWF0IjoxNTMwMTM4NTkxLCJqdGkiOiIxODgzMzViZi0wMmE4LTRjZGUsOGFkOS0yMWJmNDZjNmRjZDkiLCJjbGllbnRfaWQiOiJZVW1sWkFjQktOc1RBZWxKcVBZRmwzc2g1OE9iQVRYOSJ9.AL7pKSTmond-NSPRNNHVbIzTdAnZjOXcjQ-BbOJ_8lsQvF7PuiOUrGIhY5XTcJusisKgbCdtIxBl8Wq1EiQ_fKnUc3JYYOqzpTB5bGoFy0Yqbfu96dneuWyzgZnoQBkqwZkbQTIg7WNTGx1TJX-UTePvBPxAefiAbaEUcigX9tTsXPoRJZOTrm7IOeKpxpB_gQYkxQtV1_NbERxjTPyMbHdMWal9_xRVzSt7mpTGudMN9OR-VtQ1uXA67GOqhZWcOzq57qImOiCMbaoKnKUADevyWjX_VscN5ZZUtzQUQhTrmv8aR69-uVhMIPKp9juMyYKaYn2IsYZEeCWfhfV45Q
Inspect a JWT token
You can inspect a JWT token with this command. See alsoInspect a token.Usage
For Apigee hybrid:apigee-remote-service-cli token inspect -o [organization] -e [environment] -f [token_file] --runtime [host_alias]
Parameters
| Parameters | Type | Description |
|---|---|---|
-c, --config | String | (Required) The path to the Apigee Remote Service config file. Tip: This flag allows you to omit most other command parameters, because the CLI is able to pull them directly from the config file. See Using the --config option. |
-e, --env | String | (Required) An environment in your organization. |
-h, --help | Displays help for the command parameters. | |
--insecure | Allow insecure server connections when using SSL. | |
-o, --org | String | (Required) An Apigee organization. You must be an org administrator. |
-r, --runtime | String | A URL that includes thehostAlias for a virtual host defined in your hybrid configuration. The URL must start withhttps://. For example:https://apitest.apigee-hybrid-docs.net |
-v, --verbose | (Optional) Produces verbose output. |
Example
apigee-remote-service-cli token inspect -c config.yaml <<< $TOKEN
Output
On success, you'll see output similar to the following:{"aud": ["remote-service-client"],"exp": 1591741549,"iat": 1591740649,"iss": "https://apigee-docs-test.apigee.net/remote-service/token","jti": "99325d2e-6440-4278-9f7f-b252a1a79e53","nbf": 1591740649,"access_token": "VfzpXzBGAQ07po0bPMKY4JgQjus","api_product_list": ["httpbin"],"application_name": "httpbin","client_id": "GYDGHy5TRpV8AejXCOlreP7dPVepA8H","developer_email": "user@example.com","scope": ""}verifying...token ok.Rotate a JWT token
At some time after you initially generate a JWT, you might need to change the public/private keypair stored by Apigee in its encrypted key-value map (KVM). This process of generatinga new key pair is called key rotation. When you rotate keys, a new private/public key pairis generated and stored in the "istio" KVM in your Apigee organization/environment.In addition, the old public key is retained along with its original key ID value.Usage
For Apigee hybrid
apigee-remote-service-cli token rotate-cert -o [organization] -e [environment] -t [token] -r [runtime] -k [provision_key] -s [provision_secret] --kid [new_key_id]
Parameters
| Parameters | Type | Description |
|---|---|---|
-c, --config | String | (Required) The path to the Apigee Remote Service config file. Tip: This flag allows you to omit most other command parameters, because the CLI is able to pull them directly from the config file. See Using the --config option. |
-e, --env | String | (Required) An environment in your organization. |
-h, --help | Displays help for the command parameters. | |
--insecure | Allow insecure server connections when using SSL | |
--truncate | int | Number of certs to keep in jwks (default 2) |
-o, --org | String | (Required) An Apigee organization. You must be an org administrator. |
-r, --runtime | String | A URL that includes thehostAlias for a virtual host defined in your hybrid configuration. The URL must start withhttps://. For example:https://apitest.apigee-hybrid-docs.net |
-v, --verbose | (Optional) Produces verbose output. |
Example
./apigee-remote-service-cli token create -o $ORG -e $ENV -i YUmlZAcBKNsTAelJqPZFl3sh58ObATX9 \-s icTARgaKHqvUH1dq -c config.yaml -r $RUNTIME -t $TOKEN
Output
certificate successfully rotated
Using .netrc for credentials
apigee-remote-service-cli automatically picks up theusername andpassword (for basic authentication where needed) from a.netrcfile in your home directory if you are on Edge Public Cloud and have an entry for themachineapi.enterprise.apigee.com. If you are on Apigee Private Cloud,the machine value is the same as yourmanagement URL (for example:http://192.162.55.100).For example on Edge Public Cloud:machine api.enterprise.apigee.comlogin jdoe@google.compassword abc123
machine http://192.162.55.100login jdoe@google.compassword abc123
Version command
Print the CLI version.
apigee-remote-service-cli version
Using the--config command option
The--config option specifies the locationof the config file generated by theprovision command. A helplful benefit of this option is that itallows you to skip most other command parameters, which the CLI pulls from the config file.These options include:- organization
- environment
- runtime
- management
- insecure
- namespace
- legacy
- opdk
For example, you could execute theprovision command like this:
apigee-remote-service-cli provision --config='old-config.yaml' > new-config.yaml
Configuration file
This section shows an example configuration file with all of the available options.
global: temp_dir: /tmp/apigee-istio keep_alive_max_connection_age: 1m api_address: :5000 metrics_address: :5001 tls: cert_file: tls.crt key_file: tls.keytenant: internal_api: https://istioservices.apigee.net/edgemicro remote_service_api: https://org-test.apigee.net/remote-service org_name: org env_name: env key: mykey secret: mysecret client_timeout: 30s allow_unverified_ssl_cert: falseproducts: refresh_rate: 2manalytics: legacy_endpoint: false file_limit: 1024 send_channel_size: 10 collection_interval: 10s fluentd_endpoint: apigee-udca-myorg-test.apigee.svc.cluster.local:20001 tls: ca_file: /opt/apigee/tls/ca.crt cert_file: /opt/apigee/tls/tls.crt key_file: /opt/apigee/tls/tls.key allow_unverified_ssl_cert: falseauth: api_key_claim: claim api_key_cache_duration: 30m api_key_header: x-api-key api_target_header: :authority reject_unauthorized: true jwks_poll_interval: 0s jwt_provider_key: https://org-test.apigee.net/remote-service/token
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-12-17 UTC.