# shelbi remote

Connect to Shelbi on another machine over SSH, and what this machine reports to one that connects here.

```text
shelbi remote connect <HOST> [PROJECT]
shelbi remote list [--json]
```

## shelbi remote connect

`shelbi remote connect` opens a project of Shelbi on another machine in this
terminal: the same thing **Connect to Remote Session** does in the apps,
without the dialog. `HOST` is an SSH alias or `user@hostname`. `PROJECT` is the
project's id as `shelbi remote list` shows it on that machine; it can be left
out when the machine has just one project. If you leave it out and the machine
has several, or name one it doesn't have, the error lists the machine's
projects.

It signs in with your own SSH setup (asking for a password or passphrase in a
macOS dialog when SSH needs one), checks the other
machine's Shelbi, remembers the session in **Recent remote sessions**, and runs
that machine's Shelbi for the project here. If the connection drops it shows
"Reconnecting to *host*… (attempt N)" and keeps trying; press Esc to stop.
Quitting the remote Shelbi brings you back.

If Shelbi isn't running on the other machine, it asks before starting it
(`--yes` starts it without asking). When it can't ask (no terminal), it stops
and tells you to rerun with `--yes`. See
[Remote sessions](/docs/concepts/remote-sessions) for the errors it can report.

## shelbi remote list

`shelbi remote list` prints what another machine's **Connect to Remote
Session** dialog finds here: the user Shelbi runs as, its version, whether the
daemon is running, and every registered project with its `repo:` location
(usually its folder, with your home directory shown as `~`). A project whose
`repo:` is a clone URL shows the URL. It only reads. It never starts the daemon or changes a project.

A remote client runs `shelbi remote list --json` over SSH; you can run it by
hand to check what a client will see. The desktop app opens its full window for
a project here only when this version matches its own exactly (see
[Remote sessions](/docs/concepts/remote-sessions)).

```text
$ shelbi remote list
Shelbi 0.42.0 as jlong (daemon running)
  shelbi  ~/Workspaces/shelbi
  web     /srv/web
```

With no registered projects it prints `No projects.`

## Flags

| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| `-y, --yes` | bool | false | `connect`: start Shelbi on the other machine without asking when it isn't running. |
| `--json` | bool | false | `list`: print the listing as JSON: `protocol`, `version`, `user`, `daemon_running`, `projects` (each with `name`, optional `label`, and `path`), and `native`, the protocol numbers the desktop app's full window needs (absent from a Shelbi that predates it). |
| `--root <PATH>` | string | install-time default / `$SHELBI_ROOT` / `~/.shelbi` | Override the Shelbi root directory. |

## See also

- [Remote sessions](/docs/concepts/remote-sessions): connecting to Shelbi on
  another machine.