Run a command on an SSH target

stable

Execute one non-interactive command on a registered SSH target with local stdin forwarded and remote output streamed straight through to your shell.

Author: Poul Kjeldager
Usage: pks ssh run <TARGET> -- <command>
Category: infrastructure

Examples

$ pks ssh run hetzner -- uname -a

Run one command and print its output

$ pks ssh run hetzner -- "cd ~/dst && tar xzf -"

Feed piped local stdin into a remote command

$ pks ssh list

See which targets are available

pks ssh run executes a single command on a registered SSH target and behaves like plain ssh host cmd: local stdin is forwarded to the remote process, remote stdout and stderr stream back untouched, and the exit code mirrors the remote command's. That makes it usable inside ordinary shell pipelines.

1. Prerequisites

  • A registered target. Create one with pks ssh register.
  • The ssh binary on PATH.
  • Key-based access that needs no prompt. run uses BatchMode=yes, so no password or passphrase prompt is possible.
  • An enrolled authenticator, if two-factor is required. The ssh.connect guard applies to run exactly as it does to connect.

2. Run a command

Put the remote command after --:

pks ssh run hetzner -- uname -a

The remote kernel line prints on stdout. -- is the preferred form; when a positional command is also present, everything after -- wins.

Quote the whole command when passing it positionally, so the local shell hands it over as one argument.

3. Pipe data through it

Because stdin is forwarded, run slots into a pipeline:

tar czf - dir | pks ssh run hetzner -- "cd ~/dst && tar xzf -"

The local archive streams into the remote tar. The pks banner is suppressed for pks ssh run, so the stream stays clean.

4. Verify

pks ssh run hetzner -- "echo ok"

ok is printed and the command exits 0. A failing remote command propagates its own exit code, so pks ssh run hetzner -- false exits non-zero.

Arguments

ArgumentRequiredDescription
TARGETyesTarget label or host from the registry.
CMDnoCommand to run. Prefer passing it after -- instead.

pks ssh run takes no flags of its own.

Troubleshooting

A usage error and exit code 1, with no connection attempt. No command was supplied — neither after -- nor as CMD. Add the command.

The remote command hangs. BatchMode=yes blocks interactive prompts, so a command expecting input on a terminal never completes. Feed it from local stdin instead, or use pks ssh connect for anything interactive.

Permission denied straight away. With BatchMode=yes there is no passphrase prompt to fall back on. Load the key into your agent, or bind the target to a pks-held key — see pks ssh key.

The command exits 1 with a guard message. The ssh.connect action guard denied the connection. Complete the second factor and retry.

Multi-part shell logic behaves oddly. Quote it as a single argument (-- "cd ~/dst && tar xzf -") so the remote shell, not your local one, interprets the &&.

Next steps