# cloudflared

Cloudflared in Node.

- Easily install `cloudflared` on macOS, Linux, and Windows.
- Typed API for creating tunnel.

> This tool will automatically install the [latest version of `cloudflared`](https://github.com/cloudflare/cloudflared/releases/latest) at the first time.
> Then, it just passes down the command to `cloudflared`.

## Installation

### PNPM

```sh
pnpm i -g cloudflared
```

### NPM

```sh
npm i -g cloudflared
```

### Yarn

```sh
yarn global add cloudflared
```

## Usage

You can find the usage of `cloudflared` here: <https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/tunnel-useful-commands/>

Or just try:

```sh
cloudflared --help
```

### Extra Things

There is an extra command: `cloudflared remove-bin`, which will remove the `cloudflared` binary that is installed by this package.

## Library Usage

### Binary Path & Install

```js
import { bin, install } from "cloudflared";
import fs from "node:fs";
import { spawn } from "node:child_process";

if (!fs.existsSync(bin)) {
    // install cloudflared binary
    await install(bin);
}

// run cloudflared
spawn(bin, ["--version"], { stdio: "inherit" });
```

- `bin`: The path of the binary.
- `install`: A function that installs the binary to the given path.

### Tunnel

Checkout [`examples/tunnel.js`](examples/tunnel.js).

```js
import { tunnel } from "cloudflared";

console.log("Cloudflared Tunnel Example.");
main();

async function main() {
    // run: cloudflared tunnel --hello-world
    const { url, connections, child, stop } = tunnel({ "hello-world": null });

    // show the url
    console.log("LINK:", await url);

    // wait for the all 4 connections to be established
    const conns = await Promise.all(connections);

    // show the connections
    console.log("Connections Ready!", conns);

    // stop the tunnel after 15 seconds
    setTimeout(stop, 15_000);

    child.on("exit", (code) => {
        console.log("tunnel process exited with code", code);
    });
}
```

```sh
❯ node examples/tunnel.js
Cloudflared Tunnel Example.
LINK: https://aimed-our-bite-brought.trycloudflare.com
Connections Ready! [
  {
    id: 'd4681cd9-217d-40e2-9e15-427f9fb77856',
    ip: '198.41.200.23',
    location: 'MIA'
  },
  {
    id: 'b40d2cdd-0b99-4838-b1eb-9a58a6999123',
    ip: '198.41.192.107',
    location: 'LAX'
  },
  {
    id: '55545211-3f63-4722-99f1-d5fea688dabf',
    ip: '198.41.200.53',
    location: 'MIA'
  },
  {
    id: 'f3d5938a-d48c-463c-a4f7-a158782a0ddb',
    ip: '198.41.192.77',
    location: 'LAX'
  }
]
tunnel process exited with code 0
```