> ## Documentation Index > Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # ngrok Agent Command Line Interface (CLI) # ngrok Agent Command Line Interface (CLI) The ngrok agent CLI offers built-in commands for interfacing with the ngrok API. These API commands have been separated into the [ngrok agent CLI API page](/agent/cli-api) for convenience. For more information about the ngrok API and interfacing with it directly, see [the ngrok api page](/agent/api). ## ngrok ngrok puts network services, apps and APIs online. ngrok exposes local networked services behinds NATs and firewalls to the public internet over a secure tunnel. Share local websites, build/test webhook consumers and self-host personal services. Detailed help for each command is available by adding '--help' to any command or with the 'ngrok help' command. Open [https://dashboard.ngrok.com/obs/traffic-inspector](https://dashboard.ngrok.com/obs/traffic-inspector) to inspect traffic through your endpoints. ### Usage ```sh theme={null} ngrok [command] [flags] ``` ### Example ```sh theme={null} # forward http traffic from assigned public URL to local port 80 ngrok http 80 # choose a URL instead of random assignment ngrok http 8080 --url https://baz.ngrok.dev # manipulate traffic to your endpoint with a traffic policy file ngrok http 8080 --url https://baz.ngrok.dev --traffic-policy-file tp.yml # forward to another address on the network instead of a local port ngrok http foo.local:3000 # forward to a local https server ngrok http https://localhost:8443 # forward TCP traffic (e.g. ssh) with an assigned public address ngrok tcp 22 # load balance (in two terminals) ngrok http 80 --url https://api.example.com --pooling-enabled ngrok http 80 --url https://api.example.com --pooling-enabled # privately connect a service to the ngrok cloud. # then forward traffic from other endpoints in your account to it ngrok http 80 --url https://svc.internal ngrok tcp 5432 --url tcp://postgres.internal:5432 # make your endpoint url addressable only from k8s clusters # where you've installed the ngrok k8s operator ngrok http 80 --url https://example.namespace --binding kubernetes # start multiple endpoints defined in the config file ngrok start foo bar baz ``` ### SubCommands | Command | Description | | ------------------------------- | -------------------------------------------------------------- | | [api](#ngrok-api) | use ngrok agent as an api client | | [completion](#ngrok-completion) | generates shell completion code for bash or zsh | | [config](#ngrok-config) | update or migrate ngrok's configuration file | | [credits](#ngrok-credits) | prints author and licensing information | | [diagnose](#ngrok-diagnose) | diagnose connection issues | | [http](#ngrok-http) | start an HTTP tunnel | | [service](#ngrok-service) | run and control an ngrok service on a target operating system | | [start](#ngrok-start) | start endpoints or tunnels by name from the configuration file | | [tcp](#ngrok-tcp) | start a TCP tunnel | | [tls](#ngrok-tls) | start a TLS tunnel | | [update](#ngrok-update) | update ngrok to the latest version | | [version](#ngrok-version) | print the version string | ### Flags | Flag | Description | | ------------ | --------------------------------------------------- | | `--metadata` | opaque user-defined metadata for the tunnel session | ## 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 ```sh theme={null} ngrok completion [flags] ``` ### Example ```sh theme={null} ``` ### Flags | Flag | Description | | ---------- | ------------------------------------------------- | | `--config` | path to config files; they are merged if multiple | ## ngrok config The config command gives a quick way to create or update ngrok's configuration file. Use 'add-authtoken' or 'add-api-key' 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 migrate to the latest version. ### SubCommands | Command | Description | | ------------------------------------------------ | ---------------------------------------------------------------------------------- | | [add-api-key](#ngrok-config-add-api-key) | save api key to configuration file | | [add-authtoken](#ngrok-config-add-authtoken) | save authtoken to configuration file | | [add-connect-url](#ngrok-config-add-connect-url) | adds the connect URL (connect\_url) to configuration file for custom agent ingress | | [add-server-addr](#ngrok-config-add-server-addr) | alias of add-connect-url | | [check](#ngrok-config-check) | check configuration file | | [edit](#ngrok-config-edit) | edit configuration file | | [upgrade](#ngrok-config-upgrade) | auto-upgrade configuration file | ### Flags | Flag | Description | | ---------- | ------------------------------------------------- | | `--config` | path to config files; they are merged if multiple | ## ngrok config add-api-key The add-api-key command modifies your configuration file to include the specified api key. The API key can be generated in the [API section of the ngrok dashboard](https://dashboard.ngrok.com/api). ### Usage ```sh theme={null} ngrok config add-api-key TOKEN [flags] ``` ### Example ```sh theme={null} ngrok config add-api-key 1roPsn7AascHeO18mHcxRD3xT76_3ww7C9CDLYNgcdSYsscCB ``` ### Flags | Flag | Description | | ---------- | ------------------------ | | `--config` | save in this config file | ## ngrok config add-authtoken The add-authtoken command modifies your configuration file to include the specified authtoken. ngrok requires that you sign up for an account to use many advanced service features. In order to associate your client with an account, it must pass a secret token to ngrok 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 client always authenticates you properly. Additionally, this command saves the default config version, providing a working config file out of the box. You can find your authtoken in the [getting started section of the ngrok dashboard](https://dashboard.ngrok.com/get-started/your-authtoken). The ngrok service requires that you [sign up for an account](https://dashboard.ngrok.com/) 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 ```sh theme={null} ngrok config add-authtoken TOKEN [flags] ``` ### Example ```sh theme={null} ngrok config add-authtoken 1rlHSX3HqrqmOWZdeJ6bIv8rfuo_4cmS1QswRGyxcQD8NOukF ``` ### Flags | Flag | Description | | ---------- | ------------------------ | | `--config` | save in this config file | ## ngrok config add-connect-url The add-connect-url command modifies your configuration file to include the specified connect URL (connect\_url) used for custom agent ingress. ### Usage ```sh theme={null} ngrok config add-connect-url agent.example.com:443 [flags] ``` ### Example ```sh theme={null} ngrok config add-connect-url agent.example.com:443 ``` ### Flags | Flag | Description | | ---------- | ------------------------ | | `--config` | save in this config file | ## 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 you need to configure the server\_addr to point to your new ingress domain. *See Also*: [`server_addr`](/agent/config/#server-addr) [Custom Agent Ingress](/agent/connect-url/) ### Usage ```sh theme={null} ngrok config add-server-addr agent.example.com:443 [flags] ``` ### Example ```sh theme={null} ngrok config add-server-addr agent.example.com:443 ``` ### Flags | Flag | Description | | ---------- | ------------------------ | | `--config` | save in this config file | ## ngrok config check Checks a configuration file for validity/correctness. ### Usage ```sh theme={null} ngrok config check [flags] ``` ### Flags | Flag | Description | | ---------- | ---------------------- | | `--config` | check this config file | ## ngrok config edit Opens the configuration file in an editor defined by the EDITOR environment variable, defaulting to nano or Notepad depending on OS. ### Usage ```sh theme={null} ngrok config edit [flags] ``` ### Flags | Flag | Description | | ---------- | ---------------------- | | `--config` | check this config file | ## ngrok config upgrade Upgrade a configuration file to a version. A backup file will be created with your original configuration file in the same directory. 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 when upgrading versions. Attempting to downgrade will result in an error. By default this command will apply 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 ```sh theme={null} ngrok config upgrade [version] [flags] ``` ### Flags | Flag | Description | | ------------ | ------------------------------------------------- | | `--config` | upgrade this config file | | `--dry-run` | preview the proposed changes | | `--relocate` | relocates the config file to the default location | ## ngrok credits Displays program credits and license information. ### Usage ```sh theme={null} ngrok credits [flags] ``` ### Flags | Flag | Description | | ---------- | ------------------------------------------------- | | `--config` | path to config files; they are merged if multiple | ## ngrok diagnose Run tests to diagnose issues establishing connectivity to the ngrok cloud service. Exits 0 if connectivity is OK, otherwise 1. OPTIONS: \--config strings path to config files; they are merged if multiple -h, --help help for diagnose -6, --ipv6 Enable testing of IPV6 addresses -r, --region string ngrok server region \[auto, us, eu, au, ap, sa, jp, in, us-cal-1, eu-lon-1, all] -w, --write-report string Write a JSON report ### Usage ```sh theme={null} ngrok diagnose [flags] ``` ### Flags | Flag | Description | | ------------------------ | -------------------------------------------------------------------------------- | | `--6`, `--ipv6` | Enable testing of IPV6 addresses | | `--r`, `--region` | ngrok server region \[auto, us, eu, au, ap, sa, jp, in, us-cal-1, eu-lon-1, all] | | `--w`, `--write-report` | Write a JSON report | | `--config` | path to config files; they are merged if multiple | ## ngrok http Forward HTTP traffic from an ngrok endpoint URL to a local port, address or URL. The ngrok agent creates secure TLS connections to the ngrok cloud gateway over which it creates an endpoint with a URL and forwards traffic received on that URL over the TLS connections to the agent and then on to your local service. Specify a Traffic Policy to configure the ngrok cloud service to apply auth, routing, security or other handling of the incoming HTTP traffic. If you are not forwarding traffic to an http(s) server, use `ngrok tcp` or `ngrok tls` instead. ### Usage ```sh theme={null} ngrok http [address:port | port] [flags] ``` ### Example ```sh theme={null} # forward traffic from a randomly assigned URL to port 8080 ngrok http 8080 # forward to another host on the network with a host:port address ngrok http servername.local:9000 # forward to an https server ngrok http https://localhost:8443 # choose your endpoint URL instead of it being assigned ngrok http 8080 --url htps://bar.ngrok.dev 80 # choose an endpoint URL on your own domain (requires a DNS CNAME) ngrok http 3000 --url https://api.example.com # add Traffic Policy config for auth, security, routing + more ngrok http 80 --url https://example.ngrok.app --traffic-policy-file tp.yml # load balance between endpoints (run in two terminals) ngrok http 8081 --url https://your-api.ngrok.app --pooling-enabled ngrok http 8080 --url https://your-api.ngrok.app --pooling-enabled # forward to a file URL to serve files from a directory ngrok http file:///var/log ``` ### Flags | Flag | Description | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `--app-protocol` (deprecated) | use traffic policy instead | | `--authtoken` | ngrok.com authtoken identifying a user | | `--basic-auth` (deprecated) | use traffic policy instead | | `--binding` | ingress binding for an agent endpoint | | `--cidr-allow` (deprecated) | use traffic policy instead | | `--cidr-deny` (deprecated) | use traffic policy instead | | `--circuit-breaker` (deprecated) | use traffic policy instead | | `--compression` (deprecated) | use traffic policy instead | | `--description` | user editable description about this endpoint | | `--domain` (deprecated) | use --url instead | | `--host-header` (deprecated) | use traffic policy instead | | `--hostname` (deprecated) | use --domain instead | | `--inspect` | enable/disable http introspection (default true) | | `--metadata` | metadata about this endpoint | | `--mutual-tls-cas` (deprecated) | use traffic policy instead | | `--name` | user supplied name for this endpoint | | `--oauth` (deprecated) | use traffic policy instead | | `--oauth-allow-domain` (deprecated) | use traffic policy instead | | `--oauth-allow-email` (deprecated) | use traffic policy instead | | `--oauth-client-id` (deprecated) | use traffic policy instead | | `--oauth-client-secret` (deprecated) | use traffic policy instead | | `--oauth-scope` (deprecated) | use traffic policy instead | | `--oidc` (deprecated) | use traffic policy instead | | `--oidc-client-id` (deprecated) | use traffic policy instead | | `--oidc-client-secret` (deprecated) | use traffic policy instead | | `--oidc-scope` (deprecated) | use traffic policy instead | | `--policy-file` (deprecated) | use --traffic-policy-file instead | | `--pooling-enabled` | whether this endpoint can be pooled | | `--proxy-proto` (deprecated) | use --upstream-proxy-protocol instead | | `--region` (deprecated) | ngrok automatically chooses the region with lowest latency | | `--request-header-add` (deprecated) | use traffic policy instead | | `--request-header-remove` (deprecated) | use traffic policy instead | | `--response-header-add` (deprecated) | use traffic policy instead | | `--response-header-remove` (deprecated) | use traffic policy instead | | `--scheme` (deprecated) | use --url instead | | `--subdomain` (deprecated) | use --domain instead | | `--traffic-policy-file` | path to traffic policy configuration YAML or JSON file, e.g. './path/to/policy.yml' | | `--traffic-policy-url` | URL to traffic policy configuration YAML or JSON file, e.g. '[https://example.com/policy.yml](https://example.com/policy.yml)' | | `--ua-filter-allow` (deprecated) | use traffic policy instead | | `--ua-filter-deny` (deprecated) | use traffic policy instead | | `--upstream-protocol` (deprecated) | use traffic policy instead | | `--upstream-proxy-protocol` | version of proxy proto to use with this tunnel, empty if not unused | | `--upstream-tls-verify` | enables TLS verification of server TLS certificates | | `--upstream-tls-verify-cas` | path to CA cert to use to verify server certs | | `--url` | host endpoint on a URL | | `--verify-webhook` (deprecated) | use traffic policy instead | | `--verify-webhook-secret` (deprecated) | use traffic policy instead | | `--websocket-tcp-converter` (deprecated) | use traffic policy instead | | `--config` | path to config files; they are merged if multiple | ## ngrok service The service command manages installation and execution of ngrok as an operating system service on Windows, OS X 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". For more information about running ngrok as a service, check out the [ngrok service section in the secure tunnels documentation](/agent/#background-service) ### Usage ```sh theme={null} ngrok service [flags] ``` ### Example ```sh theme={null} ngrok service install --config=C:\ngrok.yml ngrok service start ngrok service stop ``` ### Flags | Flag | Description | | ---------- | ------------------------------------------------- | | `--config` | path to config files; they are merged if multiple | ## ngrok start start - start endpoints by name from the configuration file ### Usage ```sh theme={null} ngrok start [flags] ``` ### Example ```sh theme={null} 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 | Flag | Description | | ----------------------- | ---------------------------------------------------------- | | `--all` | start all endpoints or tunnels in the configuration file | | `--authtoken` | ngrok.com authtoken identifying a user | | `--none` | start running no endpoints or tunnels | | `--region` (deprecated) | ngrok automatically chooses the region with lowest latency | | `--config` | path to config files; they are merged if multiple | ## ngrok tcp Starts a tunnel which forwards all TCP traffic on a public port to a local address. This is extremely useful for exposing services that run non-HTTP traffic (ssh, sip, rdp, 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 \--url option. ngrok requires that you reserve a TCP tunnel address for your account before you can use it. TCP endpoints are only available on a free plan after [adding a valid payment method](https://dashboard.ngrok.com/settings#id-verification) to your account. ### Usage ```sh theme={null} ngrok tcp [address:port | port] [flags] ``` ### Example ```sh theme={null} # 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 --url=1.tcp.ngrok.io:27210 3389 ``` ### Flags | Flag | Description | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `--authtoken` | ngrok.com authtoken identifying a user | | `--binding` | ingress binding for an agent endpoint | | `--cidr-allow` | reject connections that do not match the given CIDRs | | `--cidr-deny` | reject connections that match the given CIDRs | | `--description` | user editable description about this endpoint | | `--metadata` | metadata about this endpoint | | `--name` | user supplied name for this endpoint | | `--policy-file` (deprecated) | use --traffic-policy-file instead | | `--pooling-enabled` | whether this endpoint can be pooled | | `--proxy-proto` (deprecated) | use --upstream-proxy-protocol instead | | `--region` (deprecated) | ngrok automatically chooses the region with lowest latency | | `--remote-addr` (deprecated) | use --url instead | | `--traffic-policy-file` | path to traffic policy configuration YAML or JSON file, e.g. './path/to/policy.yml' | | `--traffic-policy-url` | URL to traffic policy configuration YAML or JSON file, e.g. '[https://example.com/policy.yml](https://example.com/policy.yml)' | | `--upstream-proxy-protocol` | version of proxy proto to use with this tunnel, empty if not unused | | `--url` | host endpoint on a URL | | `--config` | path to config files; they are merged if multiple | ## ngrok tls tls - create a TLS endpoint and forward traffic from it to a local server Starts a tunnel listening for TLS traffic on port 443 with a specific hostname. The TLS SNI (Server Name Indication) 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 client-side 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 ```sh theme={null} ngrok tls [address:port | port] [flags] ``` ### Example ```sh theme={null} # forward TLS traffic for example.com to port 443 (requires CNAME) ngrok tls --url=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 | Flag | Description | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--authtoken` | ngrok.com authtoken identifying a user | | `--binding` | ingress bindings for an agent endpoint | | `--cidr-allow` | reject connections that do not match the given CIDRs | | `--cidr-deny` | reject connections that match the given CIDRs | | `--crt` | path to a TLS certificate for TLS termination | | `--description` | user editable description about this endpoint | | `--domain` (deprecated) | use --url instead | | `--hostname` (deprecated) | use --domain instead | | `--key` | path to a TLS key for TLS termination | | `--metadata` | metadata about this endpoint | | `--mutual-tls-cas` | path to TLS certificate authority to verify client certs in mutual tls | | `--name` | user supplied name for this endpoint | | `--policy-file` (deprecated) | use --traffic-policy-file instead | | `--pooling-enabled` | whether this endpoint can be pooled | | `--proxy-proto` (deprecated) | use --upstream-proxy-protocol instead | | `--region` (deprecated) | ngrok automatically chooses the region with lowest latency | | `--subdomain` (deprecated) | use --domain instead | | `--terminate-at` (deprecated) | this flag is deprecated and will be removed in a future release; use terminate-tls via Traffic Policy or agent\_tls\_termination via agent configuration instead | | `--traffic-policy-file` | path to traffic policy configuration YAML or JSON file, e.g. './path/to/policy.yml' | | `--traffic-policy-url` | URL to traffic policy configuration YAML or JSON file, e.g. '[https://example.com/policy.yml](https://example.com/policy.yml)' | | `--upstream-proxy-protocol` | version of proxy proto to use with this tunnel, empty if not unused | | `--upstream-tls-verify` | enables TLS verification of server TLS certificates | | `--upstream-tls-verify-cas` | path to CA cert to use to verify server certs | | `--url` | host endpoint on a URL | | `--config` | path to config files; they are merged if multiple | ## ngrok update This command checks the ngrok cloud service for a newer version of the ngrok agent. If a newer version is available, it will download it and replace the ngrok binary with the new version after cryptographically verifying the update is signed by ngrok. 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. Do not run this command if you installed ngrok with a package manager (i.e. homebrew, chocolatey, apt, snap, etc). Instead, update ngrok by using your package manager's update command. ### Usage ```sh theme={null} ngrok update [flags] ``` ### Example ```sh theme={null} ngrok update # update ngrok to the latest stable version ngrok update --channel=beta # update ngrok to the latest beta version ``` ### Flags | Flag | Description | | ----------- | ------------------------------------------------- | | `--channel` | update channel (stable, beta, unstable) | | `--config` | path to config files; they are merged if multiple | ## ngrok version print the version string ### Usage ```sh theme={null} ngrok version [flags] ``` ### Flags | Flag | Description | | ---------- | ------------------------------------------------- | | `--config` | path to config files; they are merged if multiple |