# Remote commands (/docs/v0.4/cli/remote)



Command reference only. The guide is
[Remote sessions](/docs/v0.4/remote), and the step-by-step setup is the
[setup walkthrough](/docs/v0.4/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 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.
`--remote` never creates a session.

## 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 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` — 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.4/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 and secret |
| `koshi remote edit <SERVER>`               | Change one saved server's name, address 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.4/remote/servers).

## Attaching [#attaching]

```bash
koshi attach --remote laptop.local:7654 --save-as work web   # first time
koshi attach --remote work web                               # after that
```

`--save-as <NAME>` saves the address under a short name on the first
connection, which also pins the certificate that machine presents.

## 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.