# pyngrok - a Python wrapper for ngrok

[![PyPI version](https://badge.fury.io/py/pyngrok.svg)](https://badge.fury.io/py/pyngrok)
[![Documentation Status](https://readthedocs.org/projects/pyngrok/badge/?version=latest)](https://pyngrok.readthedocs.io/en/latest/?badge=latest)
[![Build Status](https://travis-ci.org/alexdlaird/pyngrok.svg?branch=master)](https://travis-ci.org/alexdlaird/pyngrok)
[![codecov](https://codecov.io/gh/alexdlaird/pyngrok/branch/master/graph/badge.svg)](https://codecov.io/gh/alexdlaird/pyngrok)
[![image](https://img.shields.io/pypi/pyversions/pyngrok.svg)](https://pypi.org/project/pyngrok/)
[![image](https://img.shields.io/pypi/implementation/pyngrok.svg)](https://pypi.org/project/pyngrok/)
[![PyPI license](https://img.shields.io/pypi/l/pyngrok.svg)](https://pypi.org/project/pyngrok/)
[![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.me/alexdlaird)

`pyngrok` is a Python wrapper for [ngrok](https://ngrok.com/) that manages its own binary and puts
it on our path, making `ngrok` readily available from anywhere on the command line and via a
convenient Python API.

## Installation

`pyngrok` is available on [PyPI](https://pypi.org/project/pyngrok/) and can be installed
using `pip`.

```sh
pip install pyngrok
```

That's it! `pyngrok` is now available as a package to our Python projects, and `ngrok` is now available from
the command line.

## Basic Usage

To open a tunnel, use the `connect()` method, which returns the public URL generated by `ngrok`.

```python
from pyngrok import ngrok

# Open a tunnel on the default port 80
public_url = ngrok.connect()
```

The `connect()` method can also take an `options` parameter, which allows us to pass additional
options that are [supported by ngrok](https://ngrok.com/docs#tunnel-definitions).

This package also puts the default `ngrok` binary on our path, so all features of `ngrok` are also
available on the command line.

```sh
ngrok http 80
```

For details on how to fully leverage `ngrok` from the command line, see [ngrok's official documentation](https://ngrok.com/docs).

## Documentation

For more advanced usage, the full documentation is available at [http://pyngrok.readthedocs.io](http://pyngrok.readthedocs.io).

## Contributing

If you find issues, [report them on GitHub](https://github.com/alexdlaird/pyngrok/issues). Pull
requests for fixes and features are also warmly welcomed.

Be sure to review the [Contribution Guide](https://github.com/alexdlaird/pyngrok/blob/master/CONTRIBUTING.md) and
[Code of Conduct](https://github.com/alexdlaird/pyngrok/blob/master/CODE_OF_CONDUCT.md) before submitting issues
or pull requests.

Want to contribute financially? If you've found `pyngrok` useful, [a donation](https://www.paypal.me/alexdlaird) would
also be greatly appreciated!
