# Hyperbeam



Hyperbeam creates a one-to-one encrypted pipe between two peers. This page documents the public CLI installed by [`hyperbeam`](https://github.com/holepunchto/hyperbeam).

## System support [#system-support]

Desktop only: macOS, Linux, and Windows are supported. Hyperbeam is not available on Android or iOS.

## Install [#install]

```sh
npm i -g hyperbeam
```

## `hyperbeam` [#hyperbeam]

[Command source on GitHub](https://github.com/holepunchto/hyperbeam/blob/v3.1.0/bin.js)

Create a new encrypted pipe, or connect to an existing one by passphrase.

```sh
hyperbeam [passphrase] [options]
```

Flags:

* `-r`: restart the listening side with an existing passphrase instead of joining as the second peer.
  Default: off
* `-h, --help`: show help.

Defaults and behavior:

* If you omit `passphrase`, Hyperbeam generates a new passphrase, starts listening, and prints the connect command for the second peer.
* If you provide `passphrase`, Hyperbeam connects to the existing pipe for that passphrase.
* If you provide `passphrase` together with `-r`, Hyperbeam starts listening again with that same passphrase.
* Status messages are written to standard error, while piped data flows through standard input and standard output.

Example:

```sh
hyperbeam
```

## Common workflows [#common-workflows]

### Create a fresh pipe and connect from a second terminal [#create-a-fresh-pipe-and-connect-from-a-second-terminal]

In the first terminal, start a new Hyperbeam session:

```sh
hyperbeam
```

The command prints a generated passphrase. In the second terminal, join that same pipe:

```sh
hyperbeam <passphrase>
```

Anything written to one side is now available on the other.

### Pipe standard input and output through the encrypted tunnel [#pipe-standard-input-and-output-through-the-encrypted-tunnel]

Send data into a new pipe:

```sh
echo "hello world" | hyperbeam
```

Connect from another terminal or machine and read the data:

```sh
hyperbeam <passphrase>
```

### Restart the original listening side with the same passphrase [#restart-the-original-listening-side-with-the-same-passphrase]

If the announcing side stops and you want to resume it with the same passphrase, start it again with `-r`:

```sh
hyperbeam <passphrase> -r
```

### Use Hyperbeam as a temporary one-to-one transport [#use-hyperbeam-as-a-temporary-one-to-one-transport]

Because the CLI uses a single passphrase per connection pair, Hyperbeam is well suited to short-lived point-to-point transfers where one side creates the session and the other joins it with the printed passphrase.

## See also [#see-also]

* [HyperDHT](/p2p/reference/building-blocks/hyperdht)
* [Hypershell—`hypershell`](/p2p/reference/tools/hypershell#hypershell)
* [Hypertele—persistent TCP proxy](/p2p/reference/tools/hypertele#expose-a-local-tcp-service-to-a-client-side-local-port)
* [Hyperssh—`hyperssh`](/p2p/reference/tools/hyperssh#hyperssh)
* [Pear CLI](/pear/reference/pear/cli)