CLI Reference

---

Applies to SSHepherd 2.0

This page describes the commands and options of the two SSHepherd® command-line tools:

• shepctl, the Control CLI that users and administrators run on their own computers.
• shepagent, the Agent, which runs on each protected host.

Both tools use the form <tool> [options] <command>. Options can come before or after the command. Run shepctl --help or shepagent --help to see the options of the version you have installed.

shepctl

Usage

shepctl [-h] [--url URL] [--user USER] [--hostid HOSTID] [--hostname HOSTNAME]
        [--group GROUP] [--start START] [--end END] [--recordingid RECORDINGID]
        [--role ROLE] [--replay] [--port PORT] [--sshuser SSHUSER]
        [--sshargs SSHARGS] [--sshcmd SSHCMD] [--sshnohostkey]
        [--scpsrc SCPSRC] [--scptgt SCPTGT] [--tgtrdpport TGTRDPPORT]
        [--srcrdpport SRCRDPPORT] [--ignore-ssl-errors]
        [--sshdisableoldalgo SSHDISABLEOLDALGO] [--license LICENSE] [-q]
        [--relayport RELAYPORT] [--relaytunnel RELAYTUNNEL] [--bindip BINDIP]
        [--proxy PROXY] [--sessionfile SESSIONFILE] [--bulkfile BULKFILE]
        [--tunnelid TUNNELID] [--apikeydescription APIKEYDESCRIPTION]
        [--apikeypermission APIKEYPERMISSION]
        [--apikeyallowgroup APIKEYALLOWGROUP]
        [--apikeyforcegroup APIKEYFORCEGROUP] [--apikeyid APIKEYID]
        [command]

Options

Option	Description
-h, --help	Show the help message and exit.
--url URL	The C3 server URL, used with login.
--user USER	A user name (email address). Used with login, create-user, remove-user, group-add, group-del, list-user-role, role-add, role-del and list-recording.
--hostid HOSTID	An agent’s host ID. Used with tunnel commands, group-add, group-del, remove-host, list-host and list-recording.
--hostname HOSTNAME	An agent’s host name, for tunnel commands.
--group GROUP	A group name, for group commands and group-add-users.
--start START	Start date and time for list-recording, for example 2026-01-01T00:00:00.
--end END	End date and time for list-recording.
--recordingid RECORDINGID	A session ID, for get-recording, attach-recording and terminate-tunnel.
--role ROLE	A role name, for role-add and role-del.
--replay	Replay a finished session with attach-recording.
--port PORT	Local port for a tunnel, instead of a random port.
--sshuser SSHUSER	The user name for ssh-tunnel and scp-tunnel (ssh <sshuser>@host).
--sshargs SSHARGS	Extra arguments for the ssh client, such as -i <key file>.
--sshcmd SSHCMD	A command to run on the host with ssh-tunnel.
--sshnohostkey	Skip host key checking for ssh-tunnel and scp-tunnel.
--scpsrc SCPSRC	Source for scp-tunnel. A local path, or <user>@localhost:<path> on the host.
--scptgt SCPTGT	Target for scp-tunnel. A local path, or <user>@localhost:<path> on the host.
--tgtrdpport TGTRDPPORT	The RDP port on the host, for mstsc-tunnel. Default 3389.
--srcrdpport SRCRDPPORT	Deprecated. Use --port.
--ignore-ssl-errors	Don’t verify the C3 server’s certificate. For test environments only.
--sshdisableoldalgo SSHDISABLEOLDALGO	Turn off older SSH algorithms (diffie-hellman-group1-sha1, ecdh-sha2-nistp256).
--license LICENSE	A license key, for add-license.
-q	Ask as few questions as possible.
--relayport RELAYPORT	The port to connect to on the agent, for tunnel. Must be in the agent’s Allowed Ports.
--relaytunnel RELAYTUNNEL	An ip:port to connect to through the agent, for tunnel.
--bindip BINDIP	The local address the tunnel listens on. Default 127.0.0.1.
--proxy PROXY	A proxy to connect through, for example socks5h://localhost:9050.
--sessionfile SESSIONFILE	Use this session file instead of the default (~/.shepctl-session).
--bulkfile BULKFILE	A file with one item (such as an email address) per line, for bulk commands.
--tunnelid TUNNELID	The ID of a tunnel definition to open.
--apikeydescription APIKEYDESCRIPTION	Description of a new API key.
--apikeypermission APIKEYPERMISSION	Type of a new API key: api_agent, api_scim, api_isolate_full or api_isolate_admin. Repeat for more than one.
--apikeyallowgroup APIKEYALLOWGROUP	Group that agents registered with the key may join. Not applied in 2.0.
--apikeyforcegroup APIKEYFORCEGROUP	Group that agents registered with the key must join. Not applied in 2.0.
--apikeyid APIKEYID	An API key ID, for remove-apikey.

Commands

Each command below has an example. Sign in with login first; the other commands use your saved session.

Note: shepctl returns exit code 0 even when a command fails. In scripts, check the output.

Sign-in commands

login: Sign in to a C3 server. Prompts for your user name and password, or shows a URL and code for SSO.

shepctl --url https://your.sshepherd.server login

logout: Sign out and remove the saved session.

shepctl logout

whoami: Show the account you’re signed in as.

shepctl whoami

get-auth-token: Print the authentication token of your current session. Scripts can send it in the authentication-token header of requests to the C3 API. Treat it like a password.

shepctl get-auth-token

version: Show the shepctl version.

shepctl version

User commands

create-user: Create a user. Prompts for the password.

shepctl --user jane.doe@example.com create-user

remove-user: Delete a user. This also deletes the user’s sessions and recordings.

shepctl --user jane.doe@example.com remove-user

create-users: Create a user for each email address in a file. The users get random passwords and must use password reset.

shepctl --bulkfile users.txt create-users

Group commands

create-group: Create a group.

shepctl --group "Web Servers" create-group

group-add: Add a user, or an agent, to a group.

shepctl --group "Web Servers" --user jane.doe@example.com group-add
shepctl --group "Web Servers" --hostid <host id> group-add

group-del: Remove a user, or an agent, from a group.

shepctl --group "Web Servers" --user jane.doe@example.com group-del

group-add-users: Add each user listed in a file to a group.

shepctl --bulkfile users.txt --group "Web Servers" group-add-users

list-group: List all groups, or one group with its members.

shepctl --group "Web Servers" list-group

remove-group: Delete a group. This also deletes the tunnel definitions assigned to it.

shepctl --group "Web Servers" remove-group

Role commands

list-role: List roles and their permissions.

shepctl list-role

list-user-role: Show the roles a user holds.

shepctl --user jane.doe@example.com list-user-role

role-add: Give a role to a user.

shepctl --role admin --user jane.doe@example.com role-add

role-del: Take a role away from a user.

shepctl --role admin --user jane.doe@example.com role-del

Agent commands

list-host: List the agents you can reach, with their host IDs, host names and settings.

shepctl list-host

remove-host: Remove an agent from the C3 server. This also deletes its sessions, recordings and tunnel definitions. shepctl doesn’t ask for confirmation.

shepctl --hostid <host id> remove-host

Tunnel commands

tunnel: Open a Generic tunnel to a port on an agent, or open a tunnel definition.

shepctl --hostname web01 --relayport 80 --port 8080 tunnel
shepctl --tunnelid <tunnel id> tunnel

ssh-tunnel: Open an SSH session through a tunnel.

shepctl --hostname web01 --sshuser ubuntu --sshargs "-i ~/.ssh/web01.pem" ssh-tunnel

scp-tunnel: Copy files with SCP through a tunnel.

shepctl --hostname web01 --sshuser ubuntu --scpsrc ./report.txt --scptgt ubuntu@localhost:/tmp/report.txt scp-tunnel

mstsc-tunnel: Open a Remote Desktop session through a tunnel.

shepctl --hostname WinSvr2022 mstsc-tunnel

list-tunnel: List the SSH, RDP and Generic tunnel definitions you created or that are assigned to you, with their IDs. This applies to administrators too; use the Tunnels page in the Administrator Console to see every definition.

shepctl list-tunnel

terminate-tunnel: End a live session. Needs the terminate-tunnel and list-recording permissions.

shepctl --recordingid <session id> terminate-tunnel

Session commands

list-recording: List sessions, optionally by time, agent or user.

shepctl --start 2026-01-01T00:00:00 --end 2026-01-31T23:59:59 list-recording

get-recording: Export an SSH session’s recording as text. RDP recordings can’t be exported.

shepctl --recordingid <session id> get-recording > session.txt

attach-recording: Watch a live session, or replay a finished one with --replay.

shepctl --recordingid <session id> attach-recording
shepctl --recordingid <session id> --replay attach-recording

Note: In 2.0, attach-recording fails with “Execution failed”. Watch and replay sessions on the Sessions page of the Administrator Console instead.

License commands

add-license: Apply a license key.

shepctl --license "<license key>" add-license

list-license: Show the current license.

shepctl list-license

API key commands

create-apikey: Create an API key. The key is printed once.

shepctl --apikeypermission api_agent --apikeydescription "Web server rollout" create-apikey

list-apikey: List API keys, without the key values.

shepctl list-apikey

remove-apikey: Delete an API key.

shepctl --apikeyid <key id> remove-apikey

shepagent

Run shepagent commands as administrator on Windows, or with sudo on Linux.

Usage

shepagent [-h] [--url URL] [--key KEY] [--script SCRIPT]
          [--scriptargs SCRIPTARGS] [--socat SOCAT] [--sshd SSHD]
          [--rec REC] [--mkdir MKDIR] [--port PORT] [--token TOKEN]
          [--apikey APIKEY] [--group GROUP] [--ignore-ssl-errors]
          [--nowinssh] [--proxy PROXY] [--tunnel TUNNEL]
          [command]

Options

Option	Description
-h, --help	Show the help message and exit.
--url URL	The C3 server URL, for register.
--apikey APIKEY	An Agent Registration API key, for register.
--group GROUP	A group to add the agent to when it registers. Repeat for more than one: --group A --group B.
--nowinssh	Don’t install OpenSSH Server during registration on Windows.
--ignore-ssl-errors	Don’t verify the C3 server’s certificate. For test environments only.
--proxy PROXY	A proxy to connect through, for example socks5h://localhost:9050.
--token TOKEN	Deprecated. Use --apikey.
--port PORT, --tunnel TUNNEL	Listed in the help for adding and removing allowed ports and relay targets. 2.0 has no commands that use them; manage Allowed Ports in the console.
--key, --script, --scriptargs, --socat, --sshd, --rec, --mkdir	Paths to an SSH key and helper programs (tty recorder, socat, sshd, recording FIFO, mkdir) that the Agent uses. You don’t normally need these.

Commands

register: Register the host with a C3 server.

sudo shepagent --url https://your.sshepherd.server --apikey <api key> --group "Web Servers" register

The API key is visible in the process list while the command runs. See Installing the Agent.

info: Show the host ID, the C3 server URL and whether the Agent is registered.

sudo shepagent info

version: Show the Agent version.

shepagent version

list-whitelist: Show the agent’s Allowed Ports.

sudo shepagent list-whitelist

list-tunnel: Show the tunnel definitions the agent knows about.

sudo shepagent list-tunnel

run: Run the Agent. The Agent service runs this for you; you don’t normally run it yourself.

sudo shepagent run

Removed in 2.0

shepagent add-whitelist and shepagent remove-whitelist no longer exist. Use Allowed Ports on the agent’s Settings tab in the Administrator Console. See Managing Agents.