Skip to content

SSL Teams CLI Quick Reference

Operator card: use the DevOps playbook for safety gates and the CLI command reference for every public option.

This page is deliberately compact. It collects the commands operators use most often without replacing the full explanations and safety checks in the playbook.

Safe order

configure → trust HTTPS → authenticate → ping → check CA readiness
→ setup Root/Intermediate → install public Root trust
→ issue leaf → inspect issuance → publish public material
→ rotate, retire, or revoke deliberately

One-time shell setup

set -eu
umask 077

# Optional special-case overrides; omit them for the saved/application defaults.
# export BACKEND_ORIGIN="https://service.example.test:15080"
# export SSLTEAM_CLI_HOME="$PWD/.sslteam-cli"
export PUBLIC_DIR="$PWD/public-material"
export PRIVATE_DIR="$PWD/private-material"
export LEAF_ARTIFACT_DIR="$PRIVATE_DIR/leaf-artifacts"

mkdir -p "$PUBLIC_DIR" "$PRIVATE_DIR" "$LEAF_ARTIFACT_DIR"
sslteam config show

Use sslteam config set --base-url "$BACKEND_ORIGIN" only after setting BACKEND_ORIGIN for a non-default deployment origin or when changing the saved connection.

For slow certificate generation, increase the common request timeout for that invocation:

SSLTEAM_CLIENT_REQUEST_TIMEOUT=120s sslteam cert generate ...

The default is 60s; the minimum is 10s. The environment value must be set before starting the CLI process.

Trust, login, ping

The TLS commands below require an explicit --origin. Set BACKEND_ORIGIN to the deployment origin for this shell, or replace it with that origin directly; exporting it does not change the CLI default unless you also run config set. TOFU (Trust On First Use) is appropriate only after independent fingerprint verification; reviewed PEM trust is preferred for unattended automation.

# Reviewed PEM trust for automation
sslteam tls trust-store --origin "$BACKEND_ORIGIN" --path /protected/trust/service-ca.pem

# Or first-use TOFU: discover, independently verify, then approve exactly
sslteam tls tofu --origin "$BACKEND_ORIGIN"
sslteam tls tofu --origin "$BACKEND_ORIGIN" --fingerprint <verified-sha256-fingerprint>
sslteam tls show --origin "$BACKEND_ORIGIN"

# Browser-approved operator login (change any temporary password in the browser;
# the CLI prints the account it signed in as)
sslteam auth device

# Or protected password-file login
sslteam auth password --username <username> --password-file /protected/password
sslteam me
sslteam ping

Never weaken trust or hostname verification. A changed TOFU certificate requires investigation before tls replace.

Manage users

Administrators can manage server accounts from the CLI. Review the active identity with sslteam me before privileged changes.

sslteam users list
sslteam users show <username-or-uuid>
sslteam users create --username <username> --display-name "<display name>" \
  --email <email> --role viewer
sslteam users update <username-or-uuid> --display-name "<display name>"
sslteam users role <username-or-uuid> --role operator
sslteam users credential-state <username-or-uuid>
sslteam users reset-password <username-or-uuid> --confirm <username-or-uuid>
sslteam users disable <username-or-uuid> --confirm <username-or-uuid>
sslteam users enable <username-or-uuid> --confirm <username-or-uuid>
sslteam users delete <username-or-uuid> --confirm <username-or-uuid> --reason "<reason>"

show reads one active account from the list by username or UUID. reset-password displays a one-time credential once. Deliver it through a separate approved secure channel. disable sets the account status to DISABLED, keeps it visible in the directory, revokes active sessions, and requires exact confirmation. enable sets the status back to ACTIVE; update --status active is an equivalent form. delete is a confirmed soft-delete that requires an audit reason, removes the account from normal listings, revokes active sessions, and retains audit history. Use disable when the account must remain visible and reversible. The server remains authoritative for roles, protected accounts, and concurrent version checks.

Check CA readiness

sslteam ca status
sslteam ca root list
sslteam ca intermediate status
sslteam ca trust list
sslteam ca trust list --sslteam

How --sslteam filters certificates

Every SSL Teams Root, Intermediate, and leaf certificate carries the same non-critical private X.509 extension: the UUID-derived OID 2.25.105082758692405847780781908373517615617 with the UTF-8 value SSLTeam. --sslteam checks that OID and value in local trust-store entries; it does not use the subject, issuer, filename, or alias.

The extension identifies the SSL Teams certificate family. It does not prove trust, hostname identity, authorization, or revocation status.

ca trust list reads the selected local trust stores and compares each certificate's exact SHA-256 fingerprint with the server inventory for the configured PKI scope. It reports the Root/Intermediate role and family relationship from the server; aliases and subjects are not identity. When the server inventory cannot be read, local entries are Unverified. Use the exact fingerprint and server inventory checks as the authority for trust and PKI-family membership.

Local Root custody

These commands operate only on the CLI's local encrypted CA store. They do not contact the backend and do not accept --base-url. Use the optional storage flags only when overriding the configured local-custody location.

sslteam ca root create --name local-root --algo ecdsa-p256
sslteam ca root import --name local-root \
  --root-cert /protected/root/root-ca.pem \
  --root-key /protected/root/root-key.pem
sslteam ca root show --name local-root

# First invocation issues a one-time confirmation token.
sslteam ca root remove --name local-root
sslteam ca root remove --name local-root --confirm <one-time-token>

Create Root and Intermediate

A certificate signing request (CSR) contains the public-key and identity details submitted for certificate signing. The commands below create or process a CSR as part of the Intermediate setup workflow.

# One-time server-managed Root + initial Intermediate ceremony
sslteam ca root setup --out-dir /protected/offline/root-backup
# Copy the passphrase separately, then type COPIED when prompted.

# Guided Intermediate workflow
sslteam ca intermediate setup \
  --name int-dev --subject-dn "CN=sslteam-int-dev" \
  --backup /protected/offline/root-backup/ssl-teams-application-ca-backup.asc

# Or reviewable create → offline sign → activate
sslteam ca intermediate create --name int-dev --subject-dn "CN=sslteam-int-dev" \
  --csr-out /protected/int-dev.csr.pem \
  --manifest-out /protected/int-dev-signing-manifest.json
sslteam ca intermediate sign --backup /protected/root-backup.asc \
  --manifest /protected/int-dev-signing-manifest.json
sslteam ca intermediate activate --name int-dev --request-id <request-id> \
  --intermediate-cert /protected/int-dev-signed.pem \
  --chain /protected/int-dev-chain.pem

sslteam ca intermediate status

Install public Root trust

sslteam ca root download certificate --out-dir "$PUBLIC_DIR"
openssl x509 -in "$PUBLIC_DIR/application-root-ca.pem" \
  -noout -subject -issuer -fingerprint -sha256

# auto = native macOS, Linux, or Windows store only
sslteam ca trust install --certificate "$PUBLIC_DIR/application-root-ca.pem" \
  --confirm-fingerprint <exact-sha256-fingerprint>
sslteam ca trust verify --certificate "$PUBLIC_DIR/application-root-ca.pem" \
  --confirm-fingerprint <exact-sha256-fingerprint>

Native macOS, Linux, and Windows trust is automatic. Use --java when Java cacerts should be updated in addition to native trust, or use --target java for Java only; set JAVA_HOME first.

Firefox requires --target firefox, an explicit profile, and Mozilla NSS certutil on PATH. The CLI does not install or remove certutil; if it is missing, install Mozilla NSS tools using the platform guidance in the DevOps playbook. On Windows use Mozilla NSS certutil, not Windows certutil.exe.

sslteam ca trust install --target firefox --profile /path/to/firefox/profile \
  --certificate "$PUBLIC_DIR/application-root-ca.pem" \
  --confirm-fingerprint <exact-sha256-fingerprint>

Issue and inspect a leaf

# DNS SAN
sslteam cert generate --name service-api \
  --common-name service.example.test --san "DNS=service.example.test" \
  --days 7 --algorithm ecdsa-p256 --output-profile PKCS12_ONLY \
  --out-dir "$LEAF_ARTIFACT_DIR"

# IP SAN
sslteam cert generate --name service-ip \
  --common-name 192.0.2.10 --san "IP=192.0.2.10" \
  --days 7 --algorithm ecdsa-p256 --output-profile PEM_ONLY \
  --out-dir "$LEAF_ARTIFACT_DIR"

# Multiple DNS names only
sslteam cert generate --name service-api-dns \
  --common-name service.example.test \
  --san "DNS=service.example.test" \
  --san "DNS=service.internal.example.test" \
  --days 7 --algorithm ecdsa-p256 --output-profile PEM_ONLY \
  --out-dir "$LEAF_ARTIFACT_DIR"

# Multiple IP addresses only
sslteam cert generate --name service-ip-only \
  --common-name 192.0.2.10 \
  --san "IP=192.0.2.10" \
  --san "IP=127.0.0.1" \
  --days 7 --algorithm ecdsa-p256 --output-profile PEM_ONLY \
  --out-dir "$LEAF_ARTIFACT_DIR"

# Multiple DNS and IP identities on one leaf
sslteam cert generate --name service-api-multi \
  --common-name service.example.test \
  --san "DNS=service.example.test" \
  --san "DNS=service.internal.example.test" \
  --san "IP=192.0.2.10" \
  --san "IP=127.0.0.1" \
  --days 7 --algorithm ecdsa-p256 --output-profile PEM_ONLY \
  --out-dir "$LEAF_ARTIFACT_DIR"

sslteam cert list
sslteam cert show --issuance-id <issuance-uuid>
sslteam cert inspect --certificate "$PUBLIC_DIR/application-root-ca.pem" --sslteam

# Public-only distribution
sslteam cert download certificate --issuance-id <issuance-uuid> --out-dir "$PUBLIC_DIR"
sslteam cert download chain --issuance-id <issuance-uuid> --out-dir "$PUBLIC_DIR"

Use SANs for hostname validation

Modern TLS clients and browsers match hostnames against the certificate's Subject Alternative Name (SAN) extension, not the Common Name (CN) alone. SSL Teams still populates CN for compatibility and requires it to be consistent with the request. Use DNS=name for DNS names and IP=address for IP literals.

--algorithm accepts ecdsa-p256, ecdsa-p384, rsa-3072, or rsa-4096; the default is ecdsa-p256. BOTH is the default and includes an unencrypted PEM private key. Treat the complete artifact directory as sensitive. The public-only certificate and chain downloads below belong in PUBLIC_DIR. cert inspect reads only the selected public certificate; it makes no network request and does not change trust or certificate files. The --sslteam check is a marker check, not proof of trust or authorization.

Lifecycle actions

Always re-read current state and repeat the exact ID in --confirm.

# Planned rotation
sslteam ca root retire --root-id <root-uuid> --confirm <same-root-uuid> \
  --reason "planned Root rotation"
sslteam ca intermediate retire --intermediate-id <intermediate-uuid> \
  --confirm <same-intermediate-uuid> --reason "planned Intermediate rotation"

# Security incident
sslteam ca root revoke --root-id <root-uuid> --confirm <same-root-uuid> \
  --reason "Root private key compromise"
sslteam ca intermediate revoke --intermediate-id <intermediate-uuid> \
  --confirm <same-intermediate-uuid> --reason "Intermediate key compromise"
sslteam cert revoke --issuance-id <issuance-uuid> --confirm <same-issuance-uuid> \
  --reason "service decommissioned"

sslteam cert revocations --limit 50

There is no cert retire; leaf lifecycle uses cert revoke. Root/Intermediate retire and revoke have different impact. A 409 conflict means state changed: re-read and do not bypass it.

Platform prerequisites

Target Prerequisite
macOS Current-user login Keychain; /usr/bin/security
Linux Supported distribution trust layout, ca-certificates, and authorized sudo
Windows Current-user ROOT store and Windows certificate utility
Java Java installation, JAVA_HOME, and lib/security/cacerts; password prompt required
Firefox Mozilla NSS tools, certutil on PATH, and an explicit profile

Cleanup and diagnostics

sslteam ca trust remove --certificate <root.pem> \
  --confirm-fingerprint <exact-sha256-fingerprint>
# Add --target java for Java-only removal, or --target firefox --profile <path>
# for Firefox removal. Add --java for native-plus-Java removal.
sslteam tls forget --origin "$BACKEND_ORIGIN" --yes
sslteam auth logout
# Only when every session must be revoked:
sslteam auth logout-all

Preserve correlation IDs from failures. Never share tokens, passwords, passphrases, private keys, CSRs, PEM bodies, raw requests, or raw responses.