Skip to main content

ngrok Agent Command Line Interface (CLI)

ngrok

The root command of the ngrok agent.

Usage

ngrok [flags]
ngrok [command]

Commands

CommandDescription
apiuse ngrok agent as an api client
completiongenerates shell completion code for bash or zsh
configupdate or migrate ngrok's configuration file
creditsprints author and licensing information
diagnosediagnose connection issues
helpHelp about any command
httpstart an HTTP tunnel
servicerun and control an ngrok service on a target operating system
startstart tunnels by name from the configuration file
tcpstart a TCP tunnel
tlsstart a TLS tunnel
tunnelstart a tunnel for use with a tunnel-group backend
updateupdate ngrok to the latest version
versionprint the version string

Flags

FlagDescription
-h, --helpPrints the help for the ngrok command
-v, --versionPrints the version for ngrok agent

ngrok api

The ngrok api command provides access to ngrok's API. You can use the API through one of the api subcommands.

All api subcommands require an API key. You can configure it either using a flag (ngrok config add-api-key command).

You can get get the initial API key in the API section of the ngrok Dashboard. Additional keys can be created through ngrok api api-keys create subcommand.

These commands mirror our standard ngrok HTTP API. If you have shell completion enabled, these will tab complete on the terminal.

Usage

ngrok api [flags]

Commands

CommandDescription
abuse-reportsCreates a new abuse report which will be reviewed by our system and abuse response team.
agent-ingressesManage Agent Ingresses. The ngrok agent can be configured to connect to ngrok via the new set of addresses on the returned Agent Ingress.
api-keysManage API keys. These keys can be used to authenticate to the ngrok API.
backendsManage the backends that are servicing Cloud Edges.
certificate-authoritiesManage Certificate Authorities.
credentialsManage authtoken credentials. The authtoken credential can be used to authorize a new ngrok agent session.
edge-modulesManage ngrok Cloud Edge Modules.
edgesManage ngrok Cloud Edges.
endpointsList all active endpoints on the account.
event-destinationsManage Event Destinations.
event-sourcesManage types for which an event subscription will trigger.
event-subscriptionsManage Event Subscriptions.
ip-policiesManage IP policies.
ip-policy-rulesManage IP policy rules attached to IP Policies.
ip-restrictionsManage IP restrictions.
reserved-addrsManage reserved TCP addresses.
reserved-domainsManage reserved domains.
ssh-certificate-authoritiesManage SSH Certificate Authorities.
ssh-credentialsManage SSH Credentials that can be used to start new tunnels via ngrok's SSH gateway.
ssh-host-certificatesManage SSH Host Certificates.
ssh-user-certificatesManage SSH User Certificates.
tls-certificatesManage TLS certificates
tunnel-sessionsList all online tunnel sessions running on this account.
tunnelsList all online tunnels currently running on the account.

Flags

FlagDescription
--api-key stringAPI key to use
--config stringspath to config files; they are merged if multiple
-h, --helphelp for this command
--log stringpath to log file, 'stdout', 'stderr' or 'false' (default "false")
--log-format stringlog record format: 'term', 'logfmt', 'json' (default "term")
--log-level stringlogging level: 'debug', 'info', 'warn', 'error', 'crit' (default "info")

ngrok completion

The ngrok completion command generates shell tab completion code for Bash or Zsh. This requires bash-completion or zsh-completions packages to be enabled in your shell.

You can add it to your current session with the command

. <(ngrok completion)

To enable them each time you start a new session, add the following to your .bashrc or .zshrc files:

if command -v ngrok &>/dev/null; then
eval "$(ngrok completion)"
fi

Once you add this to your profile, you'll need to source ~/.bashrc or source ~/.zshrc to enable it for your current session.

Usage

ngrok completion [flags]

Flags

FlagDescription
-h, --helphelp for this command

ngrok config

The ngrok config command updates or verifies ngrok's configuration file.

Use add-authtoken, add-api-key, or add-server-addr to set the corresponding properties.

Use check to test a configuration file for validity. If you have an old configuration file, you can also use upgrade to automatically upgrade to the latest version.

Usage

ngrok config [flags]

Commands

CommandDescription
add-api-keysave an API key to configuration file. The API key can be generated in the API section of the ngrok dashboard.
add-authtokensave authtoken to configuration file
add-server-addradds the server address (server_addr) to configuration file for custom agent ingress
checkcheck configuration file
editopens the config file in your system's default editor. It looks specifically for the SHELL and EDITOR environment variables.
upgradeauto-upgrade configuration file

Flags

FlagDescription
-h, --helphelp for this command

ngrok config add-api-key

The ngrok config add-api-key command saves the ngrok API key to the configuration file. The API key can be generated in the API section of the ngrok dashboard.

Usage

ngrok config add-api-key TOKEN [flags]

Examples

ngrok config add-api-key 1roPsn7AascHeO18mHcxRD3xT76_3ww7C9CDLYNgcdSYsscCB

Flags

FlagDescription
--config stringsave in this config file
-h, --helphelp for this command
--log stringpath to log file, stdout, stderr or false (default false)
--log-format stringlog record format: term, logfmt, json (default term)
--log-level stringdebug, info, warn, error, crit (default info)

ngrok config add-authtoken

The ngrok config add-authtoken command saves the ngrok authtoken to the configuration file. You can find your authtoken in the getting started section of the ngrok dashboard.

The ngrok service requires that you sign up for an account to connect with an agent. Some advanced service features require a paid account. In order to associate your agent with an account, it must pass a secret token to the ngrok service when it starts up. Instead of passing this authtoken on every invocation, you may use this command to save it into your configuration file so that your agent always authenticates you properly.

Usage

ngrok config add-authtoken TOKEN [flags]

Examples

ngrok config add-authtoken 1rlHSX3HqrqmOWZdeJ6bIv8rfuo_4cmS1QswRGyxcQD8NOukF

Flags

FlagDescription
--config stringsave in this config file
-h, --helphelp for this command
--log stringpath to log file, stdout, stderr or false (default false)
--log-format stringlog record format: term, logfmt, json (default term)
--log-level stringdebug, info, warn, error, crit (default info)

ngrok config add-server-addr

The ngrok config add-server-addr command updates the server address (server_addr) in the configuration file. This is useful when your account is using Custom Agent Ingress and need to configure the server_addr to point to your new ingress domain.

Usage

ngrok config add-server-addr agent.example.com:443 [flags]

Examples

ngrok config add-server-addr agent.example.com:443

Flags

FlagDescription
--config stringsave in this config file
-h, --helphelp for this command
--log stringpath to log file, stdout, stderr or false (default false)
--log-format stringlog record format: term, logfmt, json (default term)
--log-level stringdebug, info, warn, error, crit (default info)

ngrok config check

The ngrok config check command checks a configuration file for validity/correctness.

Usage

ngrok config check [flags]

Flags

FlagDescription
--config stringcheck this config file
-h, --helphelp for this command
--log stringpath to log file, stdout, stderr or false (default false)
--log-format stringlog record format: term, logfmt, json (default term)
--log-level stringdebug, info, warn, error, crit (default info)

ngrok config edit

The ngrok config edit command opens the configuration file in an editor defined by the EDITOR environment variable, defaulting to nano or Notepad depending on OS.

Usage

ngrok config edit [flags]

Flags

FlagDescription
--config stringopen this config file to edit
-h, --helphelp for this command
--log stringpath to log file, stdout, stderr or false (default false)
--log-format stringlog record format: term, logfmt, json (default term)
--log-level stringdebug, info, warn, error, crit (default info)

ngrok config upgrade

The ngrok config upgrade command upgrades a configuration file to a specific version.

You can optionally pass a version to upgrade to. If the configuration file version is missing, the upgrade command will add it. It also applies all automatic transformations between versions.

By default this command applies the transformations and display the final file. Use --dry-run to preview changes before applying.

By default this command will not move any configuration files to their new default location. Use --relocate to move the config file to the default location.

Usage

ngrok config upgrade [version] [flags]

Flags

FlagDescription
--config stringsave in this config file
--dry-runpreview the proposed changes
-h, --helphelp for this command
--log stringpath to log file, stdout, stderr or false (default false)
--log-format stringlog record format: term, logfmt, json (default term)
--log-level stringdebug, info, warn, error, crit (default info)
--relocaterelocates the config file to the default location

ngrok credits

The ngrok credits command displays the software credits and license information.

Usage

ngrok credits [flags]

Flags

FlagDescription
-h, --helphelp for this command

ngrok diagnose

The ngrok diagnose command runs a series of tests to diagnose potential connectivity issues between the ngrok agent and the remote ngrok service.

Usage

ngrok diagnose [flags]

Flags

FlagDescription
--config stringspath to config files; they are merged if multiple
-h, --helphelp for this command
-6, --ipv6Enable testing of IPV6 addresses
-w, --write-report stringWrite a JSON report

ngrok help

The ngrok help command provides help for any command in the application. Simply type ngrok help [path to command] for full details.

Usage

ngrok help [command] [flags]

Flags

FlagDescription
-h, --helphelp for this command

ngrok http

The ngrok http command is used to start a tunnel listening for HTTP/HTTPS traffic with a specific hostname. The HTTP Host header on incoming public requests is inspected to determine which tunnel it matches.

Usage

ngrok http [address:port | port] [flags]

Examples

ngrok http 8080                             # forwards provided ngrok URL to port 80
ngrok http example.com:9000 # forward traffic to example.com:9000
ngrok http --url=bar.ngrok.dev 80 # request subdomain name: 'bar.ngrok.dev'
ngrok http --url=www.ex.com 1234 # request tunnel 'www.ex.com' (DNS CNAME)
ngrok http --basic-auth='falken:joshua' 80 # enforce basic auth on tunnel endpoint
ngrok http --host-header=ex.com 80 # rewrite the Host header to 'ex.com'
ngrok http file:///var/log # serve local files in /var/log
ngrok http https://localhost:8443 # forward to a local https server

Flags

FlagDescription
--authtoken stringngrok authtoken
--app-protocol string (Deprecated)use '--upstream-protocol' instead
--basic-auth stringsenforce basic auth on tunnel endpoint, user:password
--cidr-allow stringsreject connections that do not match the given CIDRs
--cidr-deny stringsreject connections that match the given CIDRs
--circuit-breaker floatreject requests when 5XX responses exceed this ratio
--compressiongzip compress http responses from your web service
--config stringspath to config files; they are merged if multiple
--url stringhost tunnel on a custom domain
-h, --helphelp for this command
--host-header stringset Host header; if rewrite use local address hostname
--inspectenable/disable http introspection (default true)
--log stringpath to log file, stdout, stderr or false (default false)
--log-format stringlog record format: term, logfmt, json (default term)
--log-level stringlogging level: debug, info, warn, error, crit (default info)
--mutual-tls-cas stringpath to TLS certificate authority to verify client certs in mutual TLS.
--oauth stringenforce authentication OAuth2 provider on tunnel endpoint, e.g. google
--oauth-allow-domain stringsallow only OAuth2 users with these email domains
--oauth-allow-email stringsallow only OAuth2 users with these emails
--oauth-client-id stringoauth app client id, optional
--oauth-client-secret stringoauth app client id, optional
--oauth-scope stringsrequest these OAuth2 scopes when users authenticate
--policy-file string (Deprecated)use --traffic-policy-file instead
--proxy-proto stringversion of PROXY protocol to use with this tunnel, empty if not using. Example values are 1 or 2.
--region string (Deprecated)ngrok server region us, us-cal-1, eu, au, ap, sa, jp, in (defaults to closest)
--request-header-add stringsheader key:value to add to request
--request-header-remove stringsheader field to remove from request if present
--response-header-add stringsheader key:value to add to response
--response-header-remove stringsheader field to remove from response if present
--traffic-policy-file stringpath to traffic policy configuration YAML or JSON file (See Traffic Policy)
--ua-filter-allow stringsa list of regular expressions for user-agents to allow
--ua-filter-deny stringsa list of regular expressions for user-agents to deny
--upstream-protocol stringspecify the upstream protocol to be used: http1, http2 (default http1)
--verify-webhook stringvalidate webhooks are signed by this provider, e.g. slack
--verify-webhook-secret stringsecret used by provider to sign webhooks, if any
--websocket-tcp-converterconvert ingress websocket connections to TCP upstream

ngrok service

The ngrok service command allows you to run and control an ngrok service on the operating system. For more information about running ngrok as a service, check out the ngrok service section in the secure tunnels documentation.

This command manages installation and execution of ngrok as an operating system service on Windows, MacOS and Linux systems. The service command takes a single argument which must be start, stop, restart, install, or uninstall.

When you choose install, you must specify the config flag which will define where the installed ngrok service looks for its configuration file.

When the ngrok service runs, it has the same behavior as if it were invoked from the command line with the command: ngrok start --all.

Usage

ngrok service [flags]

Examples

ngrok service install --config=C:\ngrok.yml
ngrok service start
ngrok service stop

Flags

FlagDescription
--config stringspath to config files; they are merged if multiple
-h, --helphelp for this command

ngrok start

The ngrok start command starts tunnels by name from the configuration file. You may specify any number of tunnel names. You may start all tunnels in the configuration file with the --all switch.

Usage

ngrok start [flags]

Examples

ngrok start dev        # start tunnel named 'dev' in the configuration file
ngrok start web blog # start tunnels named 'web' and 'blog'
ngrok start --all # start all tunnels defined in the config file

Flags

FlagDescription
--allstart all tunnels in the configuration file
--authtoken stringngrok authtoken identifying a user
--config stringspath to config files; they are merged if multiple
-h, --helphelp for this command
--log stringpath to log file, stdout, stderr or false (default false)
--log-format stringlog record format: term, logfmt, json (default term)
--log-level stringdebug, info, warn, error, crit (default info)
--nonestart running no tunnels
--region stringngrok server region us, us-cal-1, eu, au, ap, sa, jp, in (defaults to closest)

ngrok tcp

Use ngrok tcp to start a TCP tunnel which forwards all traffic on a public port to a local address. This is extremely useful for exposing services that run non-HTTP traffic (SSH, SIP, RDP, RTSP, GRPC, game servers, etc).

A TCP tunnel binds a public address on the remote ngrok server. Any services which require a stable public address should use the --remote-addr option. ngrok requires that you reserve a TCP tunnel address for your account before you can use it.

warning

TCP endpoints are only available on a free plan after adding a valid payment method to your account.

Usage

ngrok tcp [address:port | port] [flags]

Examples

# forward a port to your local ssh server
ngrok tcp 22
# expose an RDP server on a specific public address that you reserved
ngrok tcp --remote-addr=1.tcp.ngrok.io:27210 3389

Flags

FlagDescription
--authtoken stringngrok authtoken
--cidr-allow stringsreject connections that do not match the given CIDRs
--cidr-deny stringsreject connections that match the given CIDRs
--config stringspath to config files; they are merged if multiple
-h, --helphelp for this command
--log stringpath to log file, stdout, stderr or false (default false)
--log-format stringlog record format: term, logfmt, json (default term)
--log-level stringdebug, info, warn, error, crit (default info)
--traffic-policy-file stringpath to traffic policy configuration YAML or JSON file (See Traffic Policy)
--proxy-proto stringversion of proxy proto to use with this tunnel, empty if not using
--policy-file string (Deprecated)use --traffic-policy-file instead
--region stringngrok server region us, us-cal-1, eu, au, ap, sa, jp, in (default to closest)
--remote-addr stringbind remote address (requires you reserve a TCP Address)

ngrok tls

The ngrok tls command starts a TLS tunnel listening for traffic on port 443 with a specific hostname. The TLS Server Name Indication (SNI) extension field in the TLS connection is inspected to determine which tunnel it matches.

The ngrok server does not terminate TLS connections forwarded with this command. Any underlying protocol may be used. You may optionally specify a TLS key/cert pair which will be used to terminate the traffic at the ngrok agent before it is forwarded. If not specified, the traffic will be forwarded still encrypted.

Using this command is only recommended with the --url option. Other uses will work, but will always result in certificate mismatch warnings.

Usage

ngrok tls [address:port | port] [flags]

Examples

# forward TLS traffic for www.example.com to port 443 (requires CNAME)
ngrok tls --url=www.example.com 443
# forward TLS traffic on subdomain (mismatch certificate warning)
ngrok tls 1234
# terminate TLS traffic for t.co before forwarding
ngrok tls --url=t.co --crt=/path/to/t.co.crt --key=/path/to/t.co.key 443

Flags

FlagDescription
--authtoken stringngrok authtoken
--cidr-allow stringsreject connections that do not match the given CIDRs
--cidr-deny stringsreject connections that match the given CIDRs
--config stringspath to config files; they are merged if multiple
--crt stringpath to a TLS certificate for TLS termination
--url stringhost tunnel on a custom domain
-h, --helphelp for this command
--key stringpath to a TLS key for TLS termination
--log stringpath to log file, stdout, stderr or false (default false)
--log-format stringlog record format: term, logfmt, json (default term)
--log-level stringdebug, info, warn, error, crit (default info)
--mutual-tls-cas stringpath to TLS certificate authority to verify client certs in mutual TLS
--traffic-policy-file stringpath to traffic policy configuration YAML or JSON file (See Traffic Policy)
--proxy-proto stringversion of proxy proto to use with this tunnel, empty if not using
--policy-file string (Deprecated)use --traffic-policy-file instead
--region stringngrok server region us, us-cal-1, eu, au, ap, sa, jp, in (defaults to closest)
--terminate-at stringterminate at ngrok "edge", "agent" or "upstream. Defaults to no termination or "edge" if --crt or --key are present

ngrok tunnel

The ngrok tunnel command is used to start labeled tunnels for use with Tunnel Group backends as part of Edges.

Starts a tunnel with labels so that it can be part of a tunnel group. The tunnel group consists of all the tunnels matching all the labels of a tunnel group backend.

Examples

# tunnel-group traffic for app=foo may be forwarded to port 80
ngrok tunnel --label app=foo 80
# match tunnel-group with multiple labels
ngrok tunnel --label app=foo --label dc=bar 80

Usage

ngrok tunnel [--label key:value] ... [address:port | port] [flags]

Flags

FlagDescription
--authtoken stringngrok authtoken identifying a user
--config stringspath to config files; they are merged if multiple
--crt stringpath to a TLS certificate for TLS termination
-h, --helphelp for this command
--inspectenable/disable http introspection (default true)
--key stringpath to a TLS key for TLS termination
--label stringslabels to associate with the tunnel in key=value format
--log stringpath to log file, stdout, stderr or false (default false)
--log-format stringlog record format: term, logfmt, json (default term)
--log-level stringdebug, info, warn, error, crit (default info)
--proxy-proto stringversion of proxy proto to use with this tunnel, empty if not using
--region stringngrok server region us, us-cal-1, eu, au, ap, sa, jp, in (defaults to closest)

ngrok update

The ngrok update command updates ngrok to the latest version.

This command checks the ngrok web service for a newer versions of the ngrok agent. If a newer version is available, it will download it an replace the ngrok binary with the new version after cryptographically verifying the update is safe to apply.

In order to update successfully, the ngrok binary must be in a directory that is writable by your current user. If you placed ngrok in a system path, you may need to run this with root or Administrator privileges.

Examples

ngrok update                     - update ngrok to the latest stable version
ngrok update --channel=beta - update ngrok to the latest beta version

Usage

ngrok update [flags]

Flags

FlagDescription
--channel stringupdate channel (stable, unstable, beta) (default "stable")
-h, --helphelp for this command
--log stringpath to log file, 'stdout', 'stderr' or 'false' (default "false")
--log-format stringlog record format: 'term', 'logfmt', 'json' (default "term")
--log-level stringlogging level: 'debug', 'info', 'warn', 'error', 'crit' (default "info")

ngrok version

Usage

ngrok version [flags]

Flags

FlagDescription
-h, --helphelp for this command