Use WebSocket for the Jenkins CLI unless you have a reason not to. It is the more standard transport and avoids many reverse proxy problems. Authenticate with an API token loaded from a file rather than a password, and give the user only the permissions the commands need.
The three transports
| Transport | Flag | Notes |
|---|---|---|
| WebSocket | -webSocket | Default. Needs Jenkins and client 2.217 or newer |
| HTTP | -http | Must be chosen explicitly. Known to be unreliable behind some reverse proxies, which must not buffer bodies |
| SSH | -ssh -user <id> | Uses an SSH keypair. The SSH service is disabled by default and set up on the Security page |
Behind a reverse proxy, SSH needs the org.jenkinsci.main.modules.sshd.SSHD.hostName system property set.
Authentication
The user needs Overall/Read to reach the CLI, and individual commands may need more. In HTTP mode, -auth username:apitoken takes the token from the user's configure page. The docs recommend loading credentials from a file using @. You can also set JENKINS_USER_ID and JENKINS_API_TOKEN, and -auth overrides them. Passwords work but are discouraged.
Clients older than Jenkins 2.54 are considered insecure and should not be used. The who-am-i command shows what permissions the current user has when a command seems missing.
Why this deserves attention
The CLI is a powerful remote interface, and powerful interfaces are easy to forget about. Treat it as an API that needs an owner.
Steps to review your setup
- Decide whether anyone really uses the CLI. If not, check that the SSH service is off and that automation is not relying on it.
- Move scripts to API tokens kept in files with strict permissions.
- Use a dedicated user with narrow permissions for each automation.
- Prefer WebSocket, and update clients to a current version.
- Behind a proxy, test the transport you plan to use, and confirm the proxy does not buffer.
- If SSH is on, manage keys per user and remove keys when people leave.
A warning such as "Server key did not validate" can mean the server key changed. In production, check with the administrator before editing known_hosts.
Try it yourself
The demo scans an API surface, which is a useful way to think about any remote control interface.
Click through it at your own pace, or open it full screen.
Where Safeguard fits
Safeguard scans dependencies and enforces policies and gates on pipelines. Try the free scan.
Quick check
Is the Jenkins SSH service on by default?
No. It is disabled by default and configured on the Security page.
Should scripts use my password with the CLI?
Avoid it. Use an API token loaded from a file instead.
Sources
Last reviewed: 19 October 2026.
