# pirc-extension

The [pi](https://github.com/earendil-works/pi) extension of
[PiRC](https://pirc.dev): it puts every interactive pi session on a PiRC
relay, so that you can follow and drive it from a phone or another
client. You need a relay of your own; PiRC's self-hosting guide covers
running one.

This repository holds releases only: the extension built into one file
(`index.js`). Its source is in PiRC's repository.

## Install

pi installs it from this repository with `git` and `npm`. Pin it to a
release:

```sh
pi install git:<this repository's host and path>@vX.Y.Z
```

To upgrade, upgrade your relay first, then install the newer tag the same
way. `pi update` keeps a pinned install where it is. Installing without a
tag follows this repository's default branch, and `pi update --extensions`
then moves it whenever a release is published, possibly ahead of your
relay.

## Enrol

In pi:

```
/pirc enrol wss://<relay-address>:<port>
```

The footer reads "pirc: awaiting approval" until the relay's operator
approves the host: on the relay, `pirc-relay pending` lists the hosts
waiting, and `pirc-relay approve <key>` admits one. Compare the key with the
one `/pirc status` shows here: the label is whatever the host claims.

Or, to skip the approval, issue a host token on the relay first
(`pirc-relay add-host --label <name>`) and give it to the command:
`/pirc enrol wss://<relay-address>:<port> <token>`.

`/pirc status` shows the connection, and `/pirc reconnect` reconnects.
The enrolment is saved in `~/.config/pirc/host.json` (or the file
`PIRC_CONFIG` names), with the host's key beside it in `host.key`; every pi
process on the host uses the same key. `PIRC_RELAY` overrides the relay
URL, and `PIRC_TOKEN` supplies a registration token, so a host can be
enrolled without the command; a relay URL without a token asks for approval.

If the relay's certificate is self-signed or from a private CA, set
`NODE_EXTRA_CA_CERTS` to the CA's PEM file in the environment pi starts in.

## Licence

MIT; see `LICENSE`. The bundle includes third-party code, listed in
`NOTICE`, under the licences in `third_party/`.