# Koshi 0.6.0 — Remote commands (/docs/v0.6/cli/remote)



Command reference only. The guide is
[Remote sessions](/docs/v0.6/remote), and the step-by-step setup is the
[setup walkthrough](/docs/v0.6/remote/setup).

## `--remote` [#--remote]

`--remote <SERVER>` runs one invocation against the machine `SERVER` names,
either as `host:port` or as the name it was saved under.

```bash
koshi attach --remote work S-quiet-heron
koshi list-sessions --remote work
koshi new-pane --remote work --direction right
```

It takes `attach`, `list-sessions`, and the action verbs — the verbs that open,
close, resize, focus, and type into panes and tabs, and the lock verbs. It
never creates a session. Every other verb refuses it, `koshi share --remote`
and `koshi doctor --remote` included:

```text
--remote works with `attach`, `list-sessions`, and the action verbs, such as `koshi attach --remote <server>`
```

A bare `koshi --remote work` names nothing to run and is refused the same way.

`--certificate-fingerprint <FINGERPRINT>` goes with `--remote` on each of those
verbs. It is needed for a server this machine has not saved: `sha256:`
followed by 64 lowercase hex characters, as `koshi share grant` prints it on
that machine. A saved server takes the fingerprint it holds and refuses any
other.

## Tokens — run on the machine holding the sessions [#tokens--run-on-the-machine-holding-the-sessions]

| Command                                                                     | Result                                                                                       |
| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `koshi share grant <IDENTITY> [--session <SESSION>] [--expires <DURATION>]` | Grant an identity a remote access token                                                      |
| `koshi share open`                                                          | Open the port remote clients connect to, and print the commands that connect. Mints no token |
| `koshi share revoke <IDENTITY> [--session <SESSION>]`                       | Revoke the tokens an identity holds                                                          |
| `koshi share list [--session <SESSION>] [--format table\|json]`             | List the tokens granted on this machine                                                      |

`--expires` defaults to `24h` and takes a count with one unit letter — `30s`,
`15m`, `24h`, `7d`, at most `36500d` — or the word `never`.

An absent `--session` reads one way on `grant` and another on `revoke`. A grant
with no `--session` reaches every session on this machine. A revoke with no
`--session` stops every grant that identity holds.

Details, output, and the refusals: [Access tokens](/docs/v0.6/remote/tokens).

## Saved servers — run on the machine you sit at [#saved-servers--run-on-the-machine-you-sit-at]

| Command                                    | Result                                                                          |
| ------------------------------------------ | ------------------------------------------------------------------------------- |
| `koshi remote new`                         | Save a server, asking for its name, address, certificate fingerprint and secret |
| `koshi remote edit <SERVER>`               | Change one saved server's name, address, certificate fingerprint or secret      |
| `koshi remote list [--format table\|json]` | List the servers this machine has saved                                         |
| `koshi remote forget <SERVER>`             | Drop one saved server                                                           |
| `koshi remote set-secret <SERVER>`         | Replace the secret of one saved server                                          |

`koshi remote list` prints the name, address, fingerprint, and last-used time
of each saved server, and never a secret.

Details: [Saved servers](/docs/v0.6/remote/servers).

## Attaching [#attaching]

```bash
koshi attach --remote laptop.local:7654 --certificate-fingerprint sha256:3f6a0c2e9b8d4f17a5c3e1d0b9f8a7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0 --save-as work S-quiet-heron   # first time
koshi attach --remote work S-quiet-heron   # after that
```

The first connection saves the address, the fingerprint, and the secret.
`--save-as <NAME>` saves them under a short name. A saved server that has
another name refuses `--save-as`.

## Secrets [#secrets]

No koshi flag takes a secret — every argument after the program name is
readable by the other users of the machine. koshi reads the secret from
`KOSHI_REMOTE_SECRET`, and with that unset asks for it at the terminal without
printing what is typed.