Usage and commands

Overview

Relay CLI provides a variety of ways to configure request routing and also acts as an agent for request forwarding and tunneling. Main features:

automatically configure bucket, input and output for webhook forwarding with relay forward command
automatically configure tunnel with relay connect command
manage buckets, inputs and outputs for one-way request forwarding
manage tunnel subdomains, destinations and authentication details
manage access keys and secrets

Authenticate

In order to start using your CLI, you first have to authenticate. Create your key & secret pair here: https://my.webhookrelay.com/tokens. Then, there are two ways to do it:

Using login command CLI will take advantage of native secure storage:

relay login -k token-key-here -s token-secret-here

Environment variable option is very useful when automating things:

export RELAY_KEY=token-key
export RELAY_SECRET=token-secret

Forward

Forward command automatically creates configuration and starts one-way request forwarding:

relay forward --help

Usage:    relay forward [OPTIONS] [DESTINATION | COMMAND ARGS]

Create forwarding configuration (automatically creates bucket, input endpoint and output destination). If destination and bucket aren't specified - starts a relay for all endpoints

Options:
  -b, --bucket string       Bucket name (defaults to destination name if not supplied)
      --command string      Command to execute, must be used with '--relayer exec' option
      --help                Print usage
      --input-mode string   Input mode switches between raw request body passed into the exec command through STDIN and a JSON encoded full webhook event (see documentation for
                            format), must be used with '--relayer exec' option (default "body")
      --no-agent            Do not start relay agent after configuration
      --relayer string      Relayer type - 'default' HTTP (forward to HTTP servers) or 'exec' that executes commands on the current machine (default "default")
      --timeout int         Execution timeout in seconds, must be used with '--relayer exec' option. Set to 0 to never timeout (default 300)
  -t, --type string         Output type - internal or public (default "internal")
      --ws                  Use WebSocket server as a transport (might evade certain firewalls)

Here, to forward webhooks:

-b –bucket: supply bucket name to reuse existing one. Useful when invoking forward command for the same destination.
–no-agent: only configure bucket, input and output without starting an agent.
-t –type: is an output, defaults to internal.

Usage example:

$ relay forward --bucket webhook-demo http://localhost:8090/webhook
Forwarding:
https://my.webhookrelay.com/v1/webhooks/5e722a5e-f3d9-4eec-9e9f-79f1158e4b10 -> http://localhost:8090/webhook
Starting webhook relay agent...

Another forward mode is to execute commands on your machine, to do that, use:

-b –bucket: supply bucket name to reuse existing one.
–relayer: use ‘exec’ relayer type to execute commands.
–command: command to execute, for example ‘python’, ‘bash’, ‘node’ and pretty much any other executable on your computer.
–input-mode: by default only request body is passed through stdin into the executed command, use ‘json’ to retrieve body, headers, method, query and additional bucket/input metadata.

All additional arguments passed to the forward command will be passed as arguments to the executed command:

relay forward --bucket my-bucket-name --relayer exec --command python my-script.py my-first-arg my-second-arg

Connect

Connect command automatically creates tunnel configuration and starts two-way request streaming:

$ relay connect -h

Usage:    relay connect [OPTIONS] [DESTINATION]

Connects supplied destination to the public endpoint

Options:
      --auto-generate                Auto generate certificates if not supplied
      --crt string                   Certificate file for TLS termination (optional)
  -c, --crypto string                To enable HTTPS endpoints for your tunnels use 'flexible', 'full', 'full-strict', 'tls-pass-through' (default "off")
      --ddns-token string            DuckDNS token, retrieve yours at https://www.duckdns.org/  
  -d, --destination string           Destination (where the requests should be routed)
      --help                         Print usage
  -H, --host string                  Preferred host for the tunnel
      --key string                   Key file for TLS termination (optional)
  -m, --minify                       Minify content
  -n, --name string                  Tunnel name
      --no-agent                     Do not start relay agent after configuration
  -p, --password string              Password for basic auth (optional)
      --protocol string              Protocol (http, tcp) (default "http")
  -r, --region string                Region to connect tunnel daemon to
      --rewrite-host-header string   Rewrite host header
  -s, --subdomain string             Preferred subdomain for the tunnel
  -t, --token string                 Authentication token
  -u, --username string              Username for basic auth (optional)

Here:

-r, --region string : is a tunnel region. Select your region based on your location (example: eu, us-west, au)
-d, --destination: is a destination to connect to.
--no-agent: only configures tunnel without starting an agent.
-p --password: is a password for the basic authentication.
-u --username: is a username for the basic authentication.
-t --token: is a token for the token authentication.
-s --subdomain: is an optional parameter for preferred subdomain. If not supplied - random subdomain will be generated.

Usage example:

$ relay connect https://localhost:9400
Connecting:
http://f7ayb97wmq2fldenbyenxs.webrelay.io <----> https://localhost:9400
1.512048961831163e+09    info    client starting    {"version": "develop"}
1.5120489620960093e+09    info    adding HTTP tunnel f7ayb97wmq2fldenbyenxs.webrelay.io ---> https://localhost:9400
1.512048962096073e+09    info    tunnel proxy configuration updated

Buckets

Buckets are used to group inputs and outputs for webhook relaying. Any request that hits an input in a bucket will be relayed to all outputs inside the same bucket.

List

To list all buckets:

relay bucket list

Create

relay bucket create <new bucket name>

Usage example:

$ relay bucket create github
github

Update

To update an existing bucket:

relay bucket update <bucket name or ID>

Usage example:

$ relay bucket update github -d "github webhooks"
github

Delete

To delete existing bucket:

$ relay bucket rm <bucket name or ID>

Note that this command will only delete buckets that have no Inputs or Outputs inside, but you can force
delete a bucket:

$ relay bucket rm -f <bucket name or ID>

Usage example:

$ relay bucket rm -f github
github

Inputs

Inputs are your personal endpoints to receive webhooks.

List

To list all inputs:

relay input ls

Create

To create an input:

$ relay input create -b <bucket> <name>

Here:

-b –bucket: is a bucket name to use. Defaults to input name if not supplied.
-d –description: is a description for the input.

Delete

To remove an input

$ relay input rm -b <bucket> <name or ID>

Outputs

Outputs are destination where requests should be routed

List

To list all outputs:

relay output ls

Create

To create an output:

$ relay output create -b <bucket> -d <destination> -t <type> <name>

Here:

-b --bucket: is a bucket name to use. Defaults to output name if not supplied.
-d --destination: is destination where request should be relayed.
-t --type: is output type. Available options: internal (default), public.
--header list: Set request override headers (key=value pairs) (default [])
--description: is a description for the output.

Update

To update an output:

$ relay output update <name> --bucket <bucket> --header <header key>=<header value> --destination <destination>

Here:

-b, --bucket: is a buucket name (required)
-d, --destination: is output destination - where request should be relayed
--header: allows to set request headers (key=value pairs) (default [])
--id string: is an output ID
-t, --type string: is output type (available options: internal (default), public) (default ‘internal’) (default “internal”)

Delete

To remove an output:

$ relay output rm -b <bucket> <name or ID>

Tokens

Tokens are used for API, CLI or webhookrelayd authentication.

List

To list all tokens:

relay token ls

Create

To create a new token:

relay token create

Once token is generated - secret is already encrypted. Save it somewhere as we don’t store decrypted credentials.
If you lost your token’s secret - just remove it and create a new one.

Delete

To remove a token:

relay token rm <name or ID>

Tunnel

Tunnels are used to create bidirectional connections between public endpoint (ie: yourtunnel.webrelay.io) and local endpoint on your computer, private network or even remote website.

List

To list all tunnels:

relay tunnel ls

Create

relay tunnel create [OPTIONS] [TUNNEL]

Usage example:

$ relay tunnel create --group webrelay-ingress hellonode
rei1dsfuw06rnk6noobvsn.webrelay.io<---->http://127.0.0.1

Update

To update an existing tunnel:

relay tunnel update <tunnel name or ID> --crypto flexible

Usage example to enable public endpoint encryption:

$ relay tunnel update b8c5290a-3683-4774-a5d1-60028167d245 --crypto flexible

Delete

To delete existing tunnel:

$ relay tunnel rm <tunnel name or ID>

Ingress

Ingresses are tunnels but with additional configuration to enable path based routing, tailored for Kubernetes ingresses. Tunnels that are of type ingress can be created using special group:

relay tunnel create --group webrelay-ingress hellonode
rei1dsfuw06rnk6noobvsn.webrelay.io<---->http://127.0.0.1

Then, these tunnels will be used by the ingress controller.

List

To view existing ingress type tunnels that already have path based routing rules:

$ relay ingress ls

Example:

$ relay ingress ls
ID                                     NAME                                                  HOST                                 BACKENDS                  CRYPTO              AUTH                AGE
cfe4c30a-a140-444b-aa5c-31653ff59ce4   webrelay-ingress-pis9izc72c1wd9i21gxqxm.webrelay.io   pis9izc72c1wd9i21gxqxm.webrelay.io   default/hello-node/8080   off                 -                   5 days
3d2b613b-8e16-4fec-ae47-06caa5c0f3cd   hellonode

Init

Init command initializes ingress controller in your Kubernetes cluster. It prepares namespace, configures RBAC, provisions credentials for your account and creates a secret:

$ relay ingress init

There are additional options for this command (ie: if you don’t have RBAC enabled in your cluster, use --no-rbac flag):

relay ing init -h
Flag shorthand -h has been deprecated, please use --help

Usage:    relay ingress init [OPTIONS]

Install Web Relay ingress controller onto your Kubernetes cluster and sets up authentication for it (creates and uses 'webrelay-ingress' namespace)

Options:
      --help              Print usage
  -k, --key string        Access key to use (creates new if none supplied)
      --kubectl string    Which kubectl to use for the installation (defaults to the one available in your PATH (default "kubectl")
  -m, --manifest string   Manifest to use for the installation
      --no-rbac           Install without RBAC
  -s, --secret string     Access secret to use (creates new if none supplied)

Reset command removes ingress controller from your cluster. Use this when you don’t want to use ingress controller anymore. However, dormant ingress controller barely uses any resources so it’s recommended to just remove your ingress.yaml resources to disconnect tunnels.