Remote commands

Command reference only. The guide is Remote sessions, and the step-by-step setup is the setup walkthrough.

`--remote`

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

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:

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

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.

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.

Attaching

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

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.