CLI Basics

Overview
Relay CLI provides a variety of ways to configure request routing and also acts as an agent for request forwarding and tunnelling. 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
Discovering other commands
To view other command in the CLI, use `--help` flag:
relay --help
Example output:
$ relay --help
Usage:	relay COMMAND
​
Webhook Relay - tunnels for the web. 
​
By using this product, you are agreeing to the terms of the the AppScension Ltd. Terms of service can be found at: https://webhookrelay.com/tos/
​
Don't have an account? Create one here: https://my.webhookrelay.com/register
or run:
​
relay register -e [email protected] -p password -u username
​
Report client related issues here: https://github.com/webrelay/client/issues.
​
If you have any questions or security related issues, please contact us via email: [email protected]
​
Options:
      --config string   Location of client config files (default "/home/karolis/.webhookrelay")
      --help            Print usage
  -v, --version         Print version information and quit
​
Management Commands:
  bucket      Manage buckets - used to group inputs and outputs together
  domain      Manage domain reservations - reserved domains can later be used for bucket inputs or tunnel hostnames
  function    Manage functions - used to transform webhooks and writing custom plugins
  ingress     Manage ingresses - reverse tunnels for Kubernetes
  input       Manage inputs - your personal endpoints to receive webhooks
  output      Manage outputs - destinations where requests are relayed
  token       Manage tokens - required for API (OAuth users) and webhook streaming connections
  tunnel      Manage tunnels - bidirectional connections that expose internal services
​
Commands:
  connect     Connects supplied destination to the public endpoint
  diagnostics Perform relay agent diagnostics
  forward     Create forwarding configuration (automatically creates bucket, input endpoint and output destination). If destination and bucket aren't specified - starts a relay for all endpoints
  login       Log in to a Webhook Relay service. Get your token key & secret pair here: https://my.webhookrelay.com/tokens. 
  logout      Log out from a Webhook Relay service
  register    Register a new Webhook Relay account
  run         Run relay agent as a service with a given config file
  service     Install and control relay as a background service, available commands (install, uninstall, start, stop, restart, status)
​
Run 'relay COMMAND --help' for more information on a command.
​
Raspberry Pi
Next - Platform
Using CLI Behind Proxy
Last modified 1yr ago
Copy link
On this page
Overview
Authenticate
Forward
Connect
Discovering other commands