Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/.vitepress/config.mts
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,7 @@ export default withMermaid(defineConfig({
{ text: 'Editions', link: '/editions' },
{ text: 'Going Pro', link: '/pro' },
{ text: 'Install Pro', link: '/pro/install' },
{ text: 'AnyCable+ CLI', link: '/plus/cli' },
]
},
{
Expand Down
3 changes: 2 additions & 1 deletion docs/editions.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,8 @@ integrate.
- **[Pro](./pro.md)** — the same server with a denser memory model, cluster
features, and extra protocols. A drop-in replacement for the open-source binary.
- **[AnyCable+](https://plus.anycable.io)** — Pro as a managed service, so you do
not operate the server yourself. Free tier available.
not operate the server yourself. Free tier available. Provision servers from
the terminal with the [AnyCable+ CLI](./plus/cli.md).

## Which one

Expand Down
111 changes: 111 additions & 0 deletions docs/plus/cli.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,111 @@
# AnyCable+ CLI

[AnyCable+](https://plus.anycable.io) is the managed AnyCable service. The
`anycable-plus` command-line tool lets you provision and manage your _cables_
(hosted AnyCable servers) right from the terminal.

## Installation

```sh
curl -LSs https://anycable-plus.terminalwire.sh | bash
```

The script installs the CLI under `~/.terminalwire` and adds it to your PATH.
Restart your shell (or open a new terminal) and verify the installation:

```sh
anycable-plus --help
```

## Log in

```sh
anycable-plus login
```

This opens a browser window where you sign in to AnyCable+ via GitHub. The
session is stored on your machine; use `anycable-plus whoami` to check who you
are logged in as and `anycable-plus logout` to end the session.

## Create a cable

Create a hosted AnyCable server with a single command:

```sh
anycable-plus cable create my-app --public --wait
```

The `--wait` flag keeps the command running until the cable has finished
provisioning and prints its connection information:

```
Cable my-app is being provisioned
...

ID 42
Name my-app
Status created
WebSocket URL wss://<your-cable-host>/cable
Broadcast URL https://<your-cable-host>/_broadcast
Secret none (public mode)
```

Point your client at the WebSocket URL and your backend at the broadcast URL,
and you have a working realtime setup; the [quick start](../quickstart.md)
shows the full round trip.

The `--public` flag creates a cable that accepts connections and broadcasts
without authentication, which is handy for prototyping (like running a local
server with `anycable-go --public`). For production, create a cable with a
secret instead and use [JWT authentication](../anycable-go/jwt_identification.md)
and [signed streams](../anycable-go/signed_streams.md); the
[quick start](../quickstart.md#secure-it) walks through both.

Other `cable create` options:

- `--secret=SECRET`: set the AnyCable secret (for JWT, signed streams, etc.).
- `--framework=FRAMEWORK`: adjust the default configuration to your backend
framework (`rails`, `hotwire`, `js`, or `laravel`).
- `--rpc-host=RPC_HOST`: the URL of your backend for running channels
(for the [Rails setup](../rails/getting_started.md)).

## Manage cables

List your cables:

```sh
anycable-plus cables
```

Print a cable's status and connection information (URLs, secret,
configuration):

```sh
anycable-plus cable info 42
```

Change the configuration, for example, rotate the secret (pass an empty
string to switch the cable to the public mode):

```sh
anycable-plus cable update 42 --secret=new-secret
```

Terminate and delete a cable (asks for confirmation unless you pass `-y`):

```sh
anycable-plus cable destroy 42 -y
```

## How it works

The CLI is a thin client for the AnyCable+ web application (built with
[Terminalwire](https://terminalwire.com)): commands are defined on the server
and their output is streamed to your terminal. You always have the latest
command set without reinstalling anything; the flip side is that every
command, including `--help`, requires network access (and most require being
logged in).

> Curious how a CLI-over-WebSocket works under the hood? Read the
> [Any Cables #34](https://blog.anycable.io/p/any-cables-34-cli-over-websocket)
> issue covering the AnyCable+ CLI architecture.
34 changes: 31 additions & 3 deletions docs/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,8 @@ Pick your stack:
- [Node.js](#nodejs) — with the serverless SDK

If you do not want to run a server at all, start with the managed
[AnyCable+](https://plus.anycable.io) (free tier) and skip installation.
[AnyCable+](https://plus.anycable.io) (free tier) and skip installation:
the [AnyCable+ CLI](./plus/cli.md) creates a hosted server in one command.

## Install AnyCable {#install}

Expand All @@ -34,6 +35,26 @@ anycable-go --version
# AnyCable 1.6.7 ...
```

Prefer a hosted server? The [AnyCable+ CLI](./plus/cli.md) provisions a
managed one instead:

```sh
curl -LSs https://anycable-plus.terminalwire.sh | bash
```

The installer adds the CLI to your PATH; restart your shell (or open a new
terminal), then log in and create a cable:

```sh
anycable-plus login
anycable-plus cable create my-app --public --wait
```

The last command prints your cable's WebSocket URL and broadcast URL. Steps
1–3 below work the same for a hosted server: use those two URLs in place
of the `localhost` ones (and skip running `anycable-go`). Step 4 notes the
one difference: you set the secret on the cable rather than via server flags.

## Any backend (standalone pub/sub) {#any-backend}

In standalone mode AnyCable handles connections and message delivery on its own.
Expand Down Expand Up @@ -113,6 +134,10 @@ export ANYCABLE_SECRET=$(openssl rand -hex 32) # use a stable value in product
anycable-go --streams_secret=$ANYCABLE_SECRET --broadcast_adapter=http
```

> On a hosted [AnyCable+](./plus/cli.md) cable, set the secret on the cable
> itself: `anycable-plus cable update <id> --secret=$ANYCABLE_SECRET`. The
> signing and client steps below stay the same.

Generate a signed name in your backend and hand it to the client. The algorithm
is HMAC-SHA256, identical across languages. Node.js:

Expand Down Expand Up @@ -156,10 +181,13 @@ the same.

```sh
bundle add anycable-rails
bin/rails g anycable:setup
```

Follow the [Rails getting started guide](./rails/getting_started.md) for the
full setup, then run the server alongside your app:
The generator is an interactive wizard that configures AnyCable for your
application. See the [Rails getting started
guide](./rails/getting_started.md) for the details (including manual setup),
then run the server alongside your app:

```sh
anycable-go
Expand Down
4 changes: 3 additions & 1 deletion docs/ruby/cli.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# AnyCable CLI
# AnyCable Ruby CLI

> This page covers the `anycable` command that ships with the AnyCable Ruby gem. Looking for the CLI of the AnyCable+ managed service? See [AnyCable+ CLI](../plus/cli.md).

[AnyCable Ruby](https://github.com/anycable/anycable) comes with a gRPC server for AnyCable and a CLI to run this server along with your Ruby application.

Expand Down
1 change: 1 addition & 0 deletions forspell.dict
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@ Protobufs
Soketi
Stackblitz
Systemd
Terminalwire
Thruster
Twilio
Valkey
Expand Down
Loading