CLI Reference
This page describes the sshteam command-line tool for requesting short-lived SSH certificates from an SSH Teams server.
SYNOPSIS
sshteam init <server-url> [OPTIONS]
sshteam sign <user@host[:port]> [OPTIONS]
sshteam issue <user@host[:port]> [OPTIONS]
sshteam agent <user@host[:port]> [OPTIONS]
sshteam devices list [OPTIONS]
sshteam devices revoke <device-id> [OPTIONS]
sshteam help [command]
DESCRIPTION
sshteam is a command-line tool for requesting short-lived SSH certificates from an SSH Teams server. Authentication uses the OAuth2 device authorization flow (RFC 8628) with mandatory DPoP proof-of-possession tokens (RFC 9449).
Credentials and per-server state are stored under ~/.sshteam/.
When a default server is configured (typically after the first successful sshteam init),
commands that support --server can omit it. This commonly applies when the device is
registered against a single SSH Teams CA/server.
--server and init accept either a full URL (https://sshteam.com, https://sshteam.com:8443)
or hostname form (sshteam.com, sshteam.com:443). When no scheme is supplied,
the CLI assumes https://.
COMMANDS
init — Authenticate this device
sshteam init <server-url> [--default] [--poll-interval <seconds>] [-I|--ignore-ssl-trust]
Registers this machine with an SSH Teams server. The command:
- Generates a fresh DPoP EC P-256 key pair.
- Starts an OAuth2 device authorization request (
/oauth2/device_authorization). - Prints a verification URL and user code — open the URL in a browser and enter the code to approve the device.
- Polls the token endpoint until the authorization is approved or expires.
- Saves the DPoP private key and access/refresh tokens under
~/.sshteam/<server-key>/. - Records the server as the default when
--defaultis given, or when no default has been configured yet.
Arguments
| Argument | Description |
|---|---|
<server-url> |
Base URL of the SSH Teams server, e.g. https://sshteam.example.com |
Options
| Option | Description |
|---|---|
--default |
Set this server as the default for all subsequent commands |
--poll-interval <seconds> |
Token-poll interval while waiting for browser approval (default: 5) |
-I, --ignore-ssl-trust |
Disable TLS certificate validation — for self-signed certs in dev/test only |
-h, --help |
Show help and exit |
Example
# Production server
sshteam init https://sshteam.example.com --default
# Local dev server with self-signed certificate
sshteam init https://localhost:8443 -I
sign — Certify an existing SSH public key
sshteam sign <user@host[:port]> -k <public-key> [OPTIONS]
Sends an existing SSH public key to the server and receives back a signed SSH
certificate. The certificate is written to stdout or to the file specified by
--output.
The server resolves the target host's SSH fingerprint and evaluates the team's certificate issuance policies before issuing the certificate.
Arguments
| Argument | Description |
|---|---|
<user@host[:port]> |
SSH connection target — the principal and server fingerprint are derived from this |
Options
| Option | Description |
|---|---|
-k, --public-key <file> |
Path to the SSH public key file to certify |
-o, --output <file> |
Write the certificate to this file (default: stdout) |
--type <ED25519\|RSA> |
Certificate type (default: ED25519) |
--timezone <tz> |
IANA timezone override for time-restriction policy evaluation (default: local system timezone) |
-s, --server <url\|host[:port]> |
SSH Teams server (e.g. https://teams.example.com, teams.example.com, teams.example.com:443; uses configured default when omitted) |
-I, --ignore-ssl-trust |
Disable TLS certificate validation — for self-signed certs in dev/test only |
-h, --help |
Show help and exit |
Example
sshteam sign alice@prod-db.example.com -k ~/.ssh/id_ed25519.pub
sshteam sign alice@prod-db.example.com -k ~/.ssh/id_rsa.pub --type RSA -o ~/.ssh/id_rsa-cert.pub
issue — Generate an ephemeral key pair and receive a certificate
sshteam issue <user@host[:port]> [OPTIONS]
Generates a fresh ephemeral key pair locally, sends the public key to the
server for signing, and writes both the private key and certificate to
~/.ssh/sshteam/. Use this when you want a temporary, use-once identity
without creating a permanent key file.
Arguments
| Argument | Description |
|---|---|
<user@host[:port]> |
SSH connection target |
Options
| Option | Description |
|---|---|
-t, --type <ED25519\|RSA> |
Key type (default: ED25519) |
-b, --bits <n> |
Bit count for RSA keys, e.g. 2048, 3072, 4096 |
--timezone <tz> |
IANA timezone override for policy evaluation (default: local system timezone) |
-s, --server <url\|host[:port]> |
SSH Teams server (e.g. https://teams.example.com, teams.example.com, teams.example.com:443; uses configured default when omitted) |
-I, --ignore-ssl-trust |
Disable TLS certificate validation — for self-signed certs in dev/test only |
-h, --help |
Show help and exit |
Example
sshteam issue alice@prod-db.example.com
sshteam issue alice@prod-db.example.com --type RSA --bits 4096
agent — Issue a certificate and load it into ssh-agent
sshteam agent <user@host[:port]> [OPTIONS]
Combines issue with automatic loading into the running ssh-agent.
Generates an ephemeral key pair, requests a certificate from the server, then
calls ssh-add to load both the private key and certificate into the agent.
The key files are removed from disk after loading.
Requires a running ssh-agent (the SSH_AUTH_SOCK environment variable must
be set).
Arguments
| Argument | Description |
|---|---|
<user@host[:port]> |
SSH connection target |
Options
| Option | Description |
|---|---|
-t, --type <ED25519\|RSA> |
Key type (default: ED25519) |
-b, --bits <n> |
Bit count for RSA keys, e.g. 2048, 3072, 4096 |
--timezone <tz> |
IANA timezone override for policy evaluation (default: local system timezone) |
-s, --server <url\|host[:port]> |
SSH Teams server (e.g. https://teams.example.com, teams.example.com, teams.example.com:443; uses configured default when omitted) |
-I, --ignore-ssl-trust |
Disable TLS certificate validation — for self-signed certs in dev/test only |
-h, --help |
Show help and exit |
Example
# Issue cert and load into agent, then SSH normally
sshteam agent alice@prod-db.example.com
ssh alice@prod-db.example.com
devices list — Show registered device info
sshteam devices list [-s <url>]
Displays the stored credentials for the configured server: server URL, DPoP key ID, and current token status (valid / expired / time remaining).
Options
| Option | Description |
|---|---|
-s, --server <url\|host[:port]> |
SSH Teams server (e.g. https://teams.example.com, teams.example.com, teams.example.com:443; uses configured default when omitted) |
-I, --ignore-ssl-trust |
Disable TLS certificate validation — for self-signed certs in dev/test only |
-h, --help |
Show help and exit |
devices revoke — Revoke a registered device
sshteam devices revoke <device-id> [-s <url>]
Calls the server API to revoke a registered device by its ID. After revocation the device can no longer obtain certificates.
Arguments
| Argument | Description |
|---|---|
<device-id> |
ID of the device to revoke (obtain from the web console at <server>/devices) |
Options
| Option | Description |
|---|---|
-s, --server <url\|host[:port]> |
SSH Teams server (e.g. https://teams.example.com, teams.example.com, teams.example.com:443; uses configured default when omitted) |
-I, --ignore-ssl-trust |
Disable TLS certificate validation — for self-signed certs in dev/test only |
-h, --help |
Show help and exit |
GLOBAL OPTIONS
The following options are accepted by the root sshteam command:
| Option | Description |
|---|---|
-h, --help |
Show help and exit |
-V, --version |
Print version information and exit |
FILES
| Path | Description |
|---|---|
~/.sshteam/defaults.json |
Default server URL |
~/.sshteam/<server-key>/config.json |
Per-server credentials (DPoP key + tokens) |
~/.sshteam/<server-key>/dpop.key |
Encrypted DPoP private key |
~/.sshteam/errors.log |
Full stack traces from failed commands |
~/.ssh/sshteam/ |
Ephemeral key pairs written by issue and agent |
<server-key> is a URL-safe slug derived from the server's base URL.
AUTHENTICATION FLOW
SSH Teams uses the OAuth2 device authorization grant (RFC 8628) combined with DPoP (RFC 9449) to bind access tokens to the device's key pair:
sshteam initgenerates a device-local EC P-256 DPoP key pair.- The server issues an access token that is cryptographically bound to the public half of that key.
- Every subsequent API call includes a fresh DPoP proof JWT — a short-lived signed assertion proving the caller holds the private key.
- The server validates the DPoP proof before accepting the certificate request.
This means a stolen access token is useless without the corresponding private key.
CERTIFICATE POLICIES
Certificate issuance is controlled by per-team policies configured on the server. Policies can restrict:
- Which server fingerprints (target hosts) are allowed.
- The principal (UNIX username) permitted in the certificate.
- Time windows during which certificates may be issued (evaluated against
the timezone passed in
--timezone, defaulting to the local system timezone).
If a request violates a policy the server returns an error and no certificate is issued.
EXIT STATUS
| Code | Meaning |
|---|---|
0 |
Success |
1 |
Runtime error (server error, network failure, authorization denied) |
2 |
Usage error (bad arguments or options) |
ENVIRONMENT
| Variable | Description |
|---|---|
SSH_AUTH_SOCK |
Unix socket for the running ssh-agent — required by sshteam agent |
EXAMPLES
# Register this machine with a production server
sshteam init https://sshteam.example.com --default
# Sign an existing key for a one-off connection
sshteam sign alice@db1.example.com -k ~/.ssh/id_ed25519.pub
# Issue an ephemeral key and load it into the agent, then connect
sshteam agent alice@db1.example.com && ssh alice@db1.example.com
# Development: register against a local server with a self-signed certificate
sshteam init https://localhost:8443 -I
sshteam agent alice@localhost -I
# List device credential status for the default server
sshteam devices list
# Revoke a device (device ID visible in the web console)
sshteam devices revoke 7f3a1c2d-…
SEE ALSO
ssh(1), ssh-agent(1), ssh-add(1), ssh-keygen(1)
RFC 8628 — OAuth 2.0 Device Authorization Grant
RFC 9449 — OAuth 2.0 Demonstrating Proof of Possession (DPoP)