Open an interactive shell on a registered SSH target, with stale pks VM entries pruned and a stopped Azure VM started before the session begins.
pks ssh connect [TARGET]$ pks ssh connect pks-vm-2e93Open a shell on a named target
$ pks ssh connectPick a target from an interactive list
$ pks ssh listSee which targets are available
pks ssh connect opens an interactive SSH session on a registered target. It resolves the target by label or host, prunes stale pks-provisioned VM entries, starts the backing Azure VM when one is tracked and stopped, passes the connection through the action guard, and hands your terminal to the system ssh process.
pks vm init register it for you.ssh binary on PATH. The session is the real ssh process with your terminal attached.ssh.connect action guard denies the connection when the factor is required and not satisfied.connect skips the VM status check and attempts SSH directly.pks ssh connect pks-vm-2e93
Omit the target and pks shows an interactive picker built from the registry. Before the picker appears, any target labeled pks-* whose backing VM is no longer present in local VM metadata is pruned from the registry.
The action guard runs under the id ssh.connect. With an authenticator enrolled, supply the second factor at the prompt. A denial ends the command with exit code 1 and the guard's own message — no SSH process is started.
If the target maps to an Azure VM that pks vm tracks and that VM is stopped or deallocated, connect offers to start it. The start is gated separately under the vm.start action. Starting the VM resumes billing.
After a start, pks polls for SSH readiness for up to three minutes. A timeout prints a yellow warning rather than failing outright, so you can retry once the machine finishes booting.
You land on the remote shell prompt. Confirm the machine:
hostname
Leaving the session returns the remote ssh process's exit code as the exit code of pks ssh connect, so a non-zero result from the remote side is preserved.
| Argument | Required | Description |
|---|---|---|
TARGET | no | Target label or host. An interactive picker is shown when omitted. |
pks ssh connect takes no flags. Connection details come from the registry entry created at registration time.
The target disappeared from the picker. Its label started with pks- and the backing VM is gone from local VM metadata, so the entry was pruned. Register it again with pks ssh register if the host still exists.
The command exits 1 with a guard message. Two-factor is required for ssh.connect and was not satisfied. Enroll or complete the factor, then retry.
Could not access pks-held key. The target references a key id that is no longer in the store — most often because pks ssh key remove deleted it. Import the key again and re-register the target. See pks ssh key.
SSH still refuses after the VM starts. The three-minute readiness poll expired and warned instead of failing. Wait for the boot to finish and run pks ssh connect again.
No host-key prompt appeared. connect passes -o StrictHostKeyChecking=no, so host-key verification is bypassed by design. Trust rests on the explicit local registration step.