Skip to content

SSL Teams CLI Command Reference

Command: sslteam
Audience: operators, platform engineers, automation authors, and support engineers
Scope: command names and options registered by the installed CLI

This is the exhaustive syntax reference. Start with the DevOps playbook for the recommended sequence, or use the quick reference for a compact operator card.

Version discipline: run sslteam version and sslteam --help against the executable you will operate. Command availability and defaults can vary by installed version; use that executable's help for the final syntax check.

Manpage

Packaged installations include the rendered section-1 pages. man sslteam opens the top-level index; nested pages use hyphenated command names:

man sslteam
man sslteam-auth
man sslteam-auth-device

The .adoc files are build inputs and are not required at runtime. The installed executable and sslteam --help output show the commands and options available in that installation.

User management

The users family manages server accounts and requires an authenticated session with the corresponding server permissions:

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 <name>] [--email <email>] [--status active|disabled]
sslteam users role <username-or-uuid> --role admin|operator|viewer
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>

list, show, and credential-state are read-only. show resolves a username or UUID from the active account list. create and reset-password display a one-time credential once; deliver it through a separate approved secure channel. update, role, disable, enable, and delete use server-side authorization and current account state. disable sets the account status to DISABLED, keeps it in normal listings, revokes active sessions, and protects the bootstrap administrator. enable sets the status back to ACTIVE; update --status active is an equivalent form. delete is a confirmed soft-delete that requires a non-blank reason of at most 300 characters, removes the account from normal listings, revokes active sessions, retains audit history, and has no restore command.

Shell completion

See the dedicated shell completion guide for installation and macOS Bash, Zsh, and Oh My Zsh verification steps.

1. Global conventions

1.1 Command syntax

sslteam [COMMAND]
sslteam <group> <command> [OPTIONS]

Top-level options:

Option Meaning
-h, --help Show top-level help and exit.
-V, --version Print the CLI version and exit.

Angle-bracket values in this manual are placeholders. Do not type the brackets.

1.2 Common connection options

Commands that communicate with the backend expose --base-url <url> as an optional per-command override. The CLI first uses a saved origin-scoped preference and then the configured application default (SSLTEAM_BACKEND_URL, otherwise https://localhost:15080). Scope is resolved from the configured CLI defaults.

All CLI HTTP requests use a 60-second timeout by default. Set SSLTEAM_CLIENT_REQUEST_TIMEOUT to another duration, for example 120s or 2m, before starting the command. Values below 10s are rejected. The setting is read at process startup and applies to the application request; it does not replace the separate TLS discovery or connection-handshake limits.

The local-only commands ca root create, ca root import, ca root show, and ca root remove do not contact the backend and therefore do not expose --base-url. ca status and ca root list are mixed commands: they read local custody and contact the backend, so they retain the backend URL override.

1.3 Local CA storage options

ca status, ca root list, ca root create, ca root import, ca root show, and ca root remove expose optional local-custody storage overrides:

Option Default Meaning
--storage-implementation <id> fs Storage implementation identifier.
--storage-location <path> Configured CLI home/ca for fs Implementation-specific storage location.
--storage-param <key=value> None Repeated implementation-specific storage parameter.

The CLI documents fs as the supported storage implementation. A local Root is custody material and is not automatically the server-managed Root.

Command help separates required inputs from optional command controls and optional storage overrides. Omit optional overrides to use the configured scope and local storage defaults.

1.4 Safety conventions

  • Fingerprints must be complete SHA-256 values in the format accepted by the installed build.
  • Server-managed Root, Intermediate, and leaf lifecycle operations require the resource identifier and an exact repeated --confirm value. Local Root removal instead requires the local --name and a one-time confirmation token issued by the CLI.
  • A server-side conflict means state changed; re-read inventory and do not bypass validation.
  • users delete requires exact --confirm matching and a non-blank --reason of at most 300 characters; use users disable for a reversible lifecycle change.
  • Public certificate downloads do not contain private keys. Complete artifact downloads may contain private keys and PKCS#12 files.
  • --force is a deliberate overwrite permission for public output files; review the existing file before using it.
  • Do not put passwords, tokens, private keys, passphrases, certificate signing requests (CSRs), certificate bodies, or raw responses in shell history, logs, URLs, or ordinary artifacts.

2. Command tree

sslteam
├── auth
│   ├── device
│   ├── password
│   ├── logout
│   └── logout-all
├── me
├── ping
├── users
│   ├── list
│   ├── show
│   ├── create
│   ├── update
│   ├── role
│   ├── credential-state
│   ├── reset-password
│   ├── disable
│   ├── enable
│   └── delete
├── version
├── config
│   ├── set
│   └── show
├── tls
│   ├── tofu
│   ├── trust-store
│   ├── show
│   ├── replace
│   └── forget
├── ca
│   ├── status
│   ├── root
│   │   ├── list
│   │   ├── create
│   │   ├── import
│   │   ├── show
│   │   ├── remove
│   │   ├── setup
│   │   ├── download certificate
│   │   ├── retire
│   │   └── revoke
│   ├── intermediate
│   │   ├── status
│   │   ├── download certificate
│   │   ├── download chain
│   │   ├── create
│   │   ├── setup
│   │   ├── sign
│   │   ├── activate
│   │   ├── retire
│   │   └── revoke
│   └── trust
│       ├── list
│       ├── install
│       ├── verify
│       └── remove
└── cert
    ├── generate
    ├── inspect
    ├── list
    ├── show
    ├── download certificate
    ├── download chain
    ├── artifact
    ├── revoke
    └── revocations

3. Configuration and session commands

sslteam version

Prints the version embedded in the build. It performs no network, filesystem, or credential operation.

sslteam version

sslteam config set

Save an explicit backend preference. This is only needed for a non-default origin or when changing the saved connection; it is not required for ordinary use.

sslteam config set \
  --base-url https://service.example.test:15080
Option Required Meaning
--base-url <url> Optional Backend base URL to save.

sslteam config show

Display stored connections, effective origin, scope values, source precedence, TLS mode, and bounded public fingerprint/path metadata.

sslteam config show

This command has no command-specific options. It does not display tokens or private material.

sslteam me

Display the server-authoritative identity for the active authenticated CLI session.

sslteam me

The output includes the display name, username, email, account UUID, effective roles, account status, protected-account flag, and backend origin. The command uses the stored session and refreshes it when required; it never prints access or refresh tokens.

Use this before privileged or destructive operations when the active account must be explicit. It requires a valid authenticated session; run sslteam auth device or sslteam auth password first when no session is available.

sslteam ping

Call the authenticated ping endpoint using the locally stored token session.

sslteam ping
sslteam ping --diag
Option Meaning
--base-url <url> Use another backend origin for this command.
--diag Enable bounded JWT diagnostics for this command run.

A successful response proves authenticated reachability only. It does not prove CA readiness or permission for a particular PKI mutation.

--diag JWT diagnostics

Use --diag only while investigating authentication or token-validation problems. It is available for sslteam auth device, sslteam auth password, and sslteam ping:

sslteam auth device --diag
sslteam auth password --username <username> --password-file /protected/password --diag
sslteam ping --diag

The option enables bounded JWT parser and claim diagnostics for that command run. The CLI logs validation details such as issuer, subject, audience, and time-claim failures when they are relevant. It does not print access tokens, authorization headers, passwords, private keys, certificate bodies, or raw HTTP responses. Diagnostics are disabled by default; remove --diag after the investigation.

sslteam auth device

Start OAuth device authorization, print browser approval instructions, poll until completion, synchronize the JWT verifier key, and save the local session.

sslteam auth device
sslteam auth device --base-url https://service.example.test:15080
Option Meaning
--base-url <url> Backend origin for the device flow.
--diag Enable bounded JWT diagnostics for this command run.

Approve the exact user code in the dashboard and leave the process running. If the dashboard asks you to replace a temporary password, finish that step in the browser: the terminal continues by itself and never saves a session that still requires a password change. After success the CLI prints the account it signed in as; if that is not your account, run sslteam auth logout and start again. Approving a second request for the same account replaces the first: the first terminal stops with "replaced by a newer authentication" and saves no session. Denial, expiry, timeout, and unexpected exchange errors fail without weakening transport trust.

sslteam auth password

Authenticate with a username/password and save a local session.

sslteam auth password --username <username>
sslteam auth password --username <username> --password-file /protected/password
Option Meaning
--base-url <url> Backend origin for this login.
--username <username> Direct-login username. If omitted, prompt interactively.
--password <password> Direct-login password. Supported but unsafe for shell history and process inspection; prefer a prompt or file.
--password-file <path> Protected file containing the current password. Mutually exclusive with --password.
--new-password-file <path> Protected replacement password used only when the server requires an initial password change.
--diag Enable bounded JWT diagnostics for this command run.

The CLI clears password characters after use and prints the account it signed in as. A rejected login does not save a session. If the initial password change succeeds but the following sign-in fails, the password has already changed: run sslteam auth password again with the new password. An expired temporary password is reported separately; ask an administrator to reset it.

sslteam auth logout

Revoke the current server session and clear local credentials.

sslteam auth logout
Option Meaning
--base-url <url> Backend origin for the current session.

sslteam auth logout-all

Revoke every server session for the current authenticated account and clear local credentials.

sslteam auth logout-all
Option Meaning
--base-url <url> Backend origin for session cleanup.

Use this only when revoking all sessions is intended.

4. Transport TLS commands

Transport trust is origin-scoped. The normalized origin includes scheme, hostname, and effective port. These commands do not issue certificates and do not change server CA state.

sslteam tls tofu

Discover the peer certificate and optionally approve the exact fingerprint.

sslteam tls tofu --origin https://service.example.test:15080
sslteam tls tofu \
  --origin https://service.example.test:15080 \
  --fingerprint <verified-sha256-fingerprint>
Option Required Meaning
--origin <https-origin> Yes HTTPS origin, including an optional port.
--fingerprint <sha256> No Complete fingerprint to approve. Without it, discovery does not save a profile.

Discovery sends no HTTP request or credentials. Approve only after independent verification. The second invocation performs fresh discovery and saves a TOFU profile only on an exact fingerprint match.

sslteam tls trust-store

Validate a public PEM trust store against the service and persist it for one origin.

sslteam tls trust-store \
  --origin https://service.example.test:15080 \
  --path /protected/trust/service-ca.pem
Option Required Meaning
--origin <https-origin> Yes HTTPS origin, including an optional port.
--path <path> Yes Public X.509 PEM trust-store path.

The profile is saved only after trust and hostname validation succeeds. Secret-bearing or malformed PEM input is rejected.

sslteam tls show

Show persisted TLS profiles without certificate bodies.

sslteam tls show
sslteam tls show --origin https://service.example.test:15080
Option Meaning
--origin <https-origin> Show only one normalized origin.

sslteam tls replace

Freshly discover and explicitly replace an existing TOFU fingerprint.

sslteam tls replace \
  --origin https://service.example.test:15080 \
  --fingerprint <new-verified-sha256-fingerprint>
Option Required Meaning
--origin <https-origin> Yes Existing HTTPS origin.
--fingerprint <sha256> Yes Freshly discovered fingerprint to approve.

Use only after investigating a changed certificate. It does not weaken trust or hostname verification.

sslteam tls forget

Remove one persisted origin trust profile.

sslteam tls forget --origin https://service.example.test:15080 --yes
Option Required Meaning
--origin <https-origin> Yes Exact origin to forget.
--yes Yes Required confirmation flag.

This removes local transport trust only. It does not revoke a certificate or remove platform trust.

5. CA status and Root commands

sslteam ca status

Show application-CA readiness, server family state, local Root custody, active Intermediate state, pending requests, and validity warnings.

sslteam ca status --base-url https://service.example.test:15080

This is a read-only CA status check. It does not mutate local custody or server state.

sslteam ca root list

List the server-managed Root authority and local Root custody for a scope.

sslteam ca root list

sslteam ca root setup

Run the server-managed application-CA setup or replacement ceremony. It creates a new Root and initial Intermediate, creates an encrypted Root backup, and requires explicit passphrase-copy confirmation. Run the same command after planned Root retirement or Root revocation; the server creates a new PKI family instead of reactivating the old one.

sslteam ca root setup \
  --common-name "SSL Teams Root CA" \
  --organization "SSL Teams" \
  --organizational-unit "Certificate Authority" \
  --out-dir /protected/offline/root-backup
Option Default Meaning
--base-url <url> Effective origin Backend origin.
--common-name <name> SSL Teams Root CA Root certificate common name.
--organization <name> SSL Teams Root certificate organization.
--organizational-unit <name> Certificate Authority Root certificate organizational unit.
--out-dir <path> . Directory for encrypted backup and temporary passphrase file.

The command refuses to overwrite an existing backup. The temporary passphrase file is deleted on exit; copy it separately before typing COPIED. The server does not replay Root private-key material after an interrupted ceremony.

sslteam ca root create

Create a local offline Root in encrypted CLI custody. This is not server-managed Root setup.

sslteam ca root create --name local-root --algo ecdsa-p256
Option Default Meaning
--name <name> — Required local Root name; current description requires lowercase, 3–64 characters.
--algo <algorithm> ecdsa-p256 ecdsa-p256 or rsa-3072.
--passphrase <value> Prompt/configured resolver Passphrase protecting the local private key. Prefer protected interactive input.
Storage options See Section 1.3 Select local custody storage.

sslteam ca root import

Import an existing Root certificate and private key into local encrypted custody.

sslteam ca root import --name local-root \
  --root-cert /protected/root/root-ca.pem \
  --root-key /protected/root/root-key.pem
Option Required/default Meaning
--name <name> Required Local alias.
--root-cert <path> Required Root certificate PEM.
--root-key <path> Required Root private-key PEM.
--passphrase <value> Prompt/configured resolver Decrypt and re-encrypt the imported key.
Storage options See Section 1.3 Select local custody storage.

sslteam ca root show

Show local Root metadata and certificate/key-match status. Private-key contents remain hidden.

sslteam ca root show --name <local-root-name>
Option Required/default Meaning
--name <name> Required Local Root name to inspect.
--passphrase <value> Not checked unless supplied Verify that the private key matches the certificate.
Storage options See Section 1.3 Select local custody storage.

sslteam ca root remove

Destructively remove local Root certificate and private-key material. It does not revoke a server Root.

sslteam ca root remove --name <local-root-name>
# Re-run with the one-time token printed by the first command.
sslteam ca root remove --name <local-root-name> --confirm <one-time-token>

Options: required --name, optional --confirm <one-time-token>, and optional local CA scope/storage overrides. This command is local-only and does not accept --base-url. Run once without --confirm to receive the token, then re-run with that exact token. The action cannot be undone.

sslteam ca root download certificate

Download only the public server-managed Root certificate.

sslteam ca root download certificate --out-dir /public-material
Option Default Meaning
common connection options Effective values Backend URL; PKI scope comes from configured CLI defaults.
--out-dir <path> . Public output directory.
--force Off Replace an existing public certificate after validation.

The private key is never downloaded by this command.

sslteam ca root retire

Planned retirement of the server-managed Root.

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

Options: common connection options, required --root-id <uuid>, required exact --confirm <uuid>, and optional bounded --reason (planned-retirement default). PKI scope comes from configured CLI defaults.

The CLI warns that the family status becomes RETIRED, issuance stops, and the Root retirement time and reason are retained. Existing Intermediate and leaf certificates remain unchanged and are not revoked. Use for planned rotation, not compromise response. The Root detail and audit history expose retiredAt; do not infer revocation from the family status alone.

For planned replacement, run the same sslteam ca root setup ceremony after retirement. Install the new public Root, issue replacement leaves, deploy and verify them, then remove the old Root from trust stores when migration is complete.

sslteam ca root revoke

Revoke the server-managed Root for a Root-level security event. Options are the same as ca root retire, with a revocation default reason.

sslteam ca root revoke --root-id <root-uuid> \
  --confirm <same-root-uuid> --reason "Root private key compromise"

The CLI warns that the family status is RETIRED, new issuance stops, and the Root revokedAt time and reason are retained. The issuing Intermediate and every non-deleted descendant leaf are revoked and audited. The shared family status is also used for planned Root retirement, so use Root lifecycle metadata or audit history to distinguish these actions.

For emergency replacement, run the same sslteam ca root setup ceremony after revocation. Install the new public Root and issue replacement leaves; the old Intermediate and leaves must be treated as revoked.

6. Intermediate commands

sslteam ca intermediate status

Show the active Intermediate, pending requests, expiry, and lifecycle history.

sslteam ca intermediate status

sslteam ca intermediate download certificate

Download the public active Intermediate certificate.

sslteam ca intermediate download certificate --out-dir /public-material

Options: common connection options, --out-dir <path> defaulting to ., and --force to replace an existing public file after validation. PKI scope comes from configured CLI defaults.

sslteam ca intermediate download chain

Download the public active Intermediate chain. Options are the same as intermediate download certificate; the output is the public chain.

sslteam ca intermediate download chain --out-dir /public-material

sslteam ca intermediate create

Create a server-side Intermediate request and certificate signing request (CSR), then write a versioned signing manifest.

sslteam ca intermediate create \
  --name int-dev --algorithm ecdsa-p256 \
  --subject-dn "CN=sslteam-int-dev" \
  --csr-out /protected/int-dev.csr.pem \
  --manifest-out /protected/int-dev-signing-manifest.json
Option Required/default Meaning
common connection options Effective values Backend URL; PKI scope comes from configured CLI defaults.
--name <name> Required Intermediate name.
--algorithm <algorithm> ecdsa-p256 ecdsa-p256 or rsa-3072.
--subject-dn <DN> Required CSR subject DN.
--replace-active Off Explicitly permit replacing the active Intermediate.
--csr-out <path> Not written unless supplied Persist returned CSR PEM.
--manifest-out <path> Request-specific file in current directory Persist signing manifest JSON.

Do not manually edit the CSR or manifest. The response includes request ID, expiry, request version, and family version.

sslteam ca intermediate sign

Sign one server-generated Intermediate CSR from an encrypted Root backup.

sslteam ca intermediate sign \
  --backup /protected/root-backup/ssl-teams-application-ca-backup.asc \
  --manifest /protected/int-dev-signing-manifest.json
Option Required/default Meaning
--base-url <url> Effective origin Connection/profile context.
--backup <path> Required Encrypted OpenPGP Root backup.
--manifest <path> Required Exact versioned signing manifest JSON.
--upload Off Upload and activate after signing.
--replace-active Off Explicitly permit active replacement during upload.

The Root backup passphrase is prompted interactively. The Intermediate private key is not returned to the operator.

sslteam ca intermediate activate

Activate signed public Intermediate material on the server.

sslteam ca intermediate activate \
  --name int-dev --request-id <request-id> \
  --intermediate-cert /protected/int-dev-signed.pem \
  --chain /protected/int-dev-chain.pem
Option Required/default Meaning
common connection options Effective values Backend URL; PKI scope comes from configured CLI defaults.
--name <name> Required Intermediate name.
--request-id <id> Optional advanced override Request to activate when not selected by name.
--intermediate-cert <path> Required Signed Intermediate certificate PEM.
--chain <path> Required Issuer chain PEM from offline signing.
--replace-active Off Explicitly permit active replacement.

The command verifies that the chain identifies the current server Root before activation.

sslteam ca intermediate setup

Run create, offline sign, and activate as one guided workflow.

sslteam ca intermediate setup \
  --name int-dev --subject-dn "CN=sslteam-int-dev" \
  --algorithm ecdsa-p256 \
  --backup /protected/root-backup/ssl-teams-application-ca-backup.asc
Option Required/default Meaning
common connection options Effective values Backend URL; PKI scope comes from configured CLI defaults.
--name <name> Required 3–64 lowercase letters, digits, ., _, or -.
--subject-dn <DN> Required CSR subject DN.
--algorithm <algorithm> ecdsa-p256 ecdsa-p256 or rsa-3072.
--backup <path> Required Encrypted OpenPGP Root backup.
--replace-active Off Explicitly permit active replacement.
--csr-out <path> CLI home/intermediate default CSR output path.
--cert-out <path> CLI home/intermediate default Signed certificate output path.
--chain-out <path> CLI home/intermediate default Chain output path.

sslteam ca intermediate retire

Plannedly remove an Intermediate from the active signing path.

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

Options: common connection options, required --intermediate-id, required exact --confirm, and bounded --reason with a planned-retirement default. PKI scope comes from configured CLI defaults. The CLI warns that the Intermediate becomes RETIRED, the family becomes DEGRADED, issuance is unavailable until replacement activation, and existing leaf certificates remain unchanged and historical.

sslteam ca intermediate revoke

Revoke an Intermediate for a security event.

sslteam ca intermediate revoke \
  --intermediate-id <intermediate-uuid> \
  --confirm <same-intermediate-uuid> \
  --reason "Intermediate private key compromise"

Options are the same as Intermediate retirement, with a revocation default reason. The CLI warns that the Intermediate and every non-deleted descendant leaf become REVOKED, the family becomes DEGRADED, and new leaf issuance stops until replacement activation. Each descendant revocation is retained in history and audit evidence.

7. Platform trust commands

All three commands use the same options:

Option Required/default Meaning
--target <target> auto auto for automatic native trust, java for Java-only trust, or firefox for an explicit Firefox profile. Native OS names are not accepted because native selection is automatic.
--java Off Also operate on Java cacerts after the automatically detected native store. Use this instead of --target java when both stores are required.
--certificate <path> Required CA certificate PEM.
--confirm-fingerprint <sha256> Required Exact fingerprint confirmation for that certificate.
--profile <path> Required with --target firefox Firefox profile directory; the operation does not modify the native or Java store.

Without --target or --java, the CLI detects the current macOS, Linux, or Windows native trust store. Java-only operations use --target java; native-plus-Java operations use --java. Firefox operations use --target firefox --profile <path> and require Mozilla NSS certutil on PATH.

sslteam ca trust install

Install the confirmed CA certificate into one or more trust stores.

sslteam ca trust install \
  --certificate /public-material/application-root-ca.pem \
  --confirm-fingerprint <exact-sha256-fingerprint>

Examples:

sslteam ca trust install \
  --certificate /public-material/application-root-ca.pem \
  --confirm-fingerprint <fingerprint>
sslteam ca trust install --java \
  --certificate /public-material/application-root-ca.pem \
  --confirm-fingerprint <fingerprint>
sslteam ca trust install --target java \
  --certificate /public-material/application-root-ca.pem \
  --confirm-fingerprint <fingerprint>
sslteam ca trust install --target firefox --profile /path/to/profile \
  --certificate /public-material/application-root-ca.pem \
  --confirm-fingerprint <fingerprint>

sslteam ca trust verify

Verify that the exact certificate is present in the selected trust store. Use the same options as trust install.

sslteam ca trust verify --target java \
  --certificate /public-material/application-root-ca.pem \
  --confirm-fingerprint <exact-sha256-fingerprint>

sslteam ca trust remove

Remove the exact certificate from the selected trust store and verify removal. Use the same options as trust install.

sslteam ca trust remove --target java \
  --certificate /public-material/application-root-ca.pem \
  --confirm-fingerprint <exact-sha256-fingerprint>

Removal of local trust does not revoke the server-managed Root.

sslteam ca trust list

List certificates discovered in the selected local trust stores and compare their exact SHA-256 fingerprints with the server-authoritative Root and Intermediate inventory for the configured PKI scope.

sslteam ca trust list
sslteam ca trust list --java
sslteam ca trust list --target firefox --profile /path/to/profile
sslteam ca trust list --sslteam
sslteam ca trust list --target firefox --profile /path/to/profile --sslteam

The command never treats an alias, filename, subject, or nickname as certificate identity. If the server inventory cannot be read, local entries are shown as Unverified; do not treat them as application-CA trust until the command succeeds against the intended scope.

--sslteam filters the local results by the non-critical private X.509 extension that SSL Teams adds to every Root, Intermediate, and leaf certificate: UUID-derived OID 2.25.105082758692405847780781908373517615617 with the UTF-8 value SSLTeam. The filter is available for automatic native discovery, Java cacerts, and Firefox NSS. It checks the extension rather than the subject, issuer, filename, or alias.

This extension identifies the SSL Teams certificate family; it does not make a certificate trusted and does not replace exact SHA-256 fingerprint, certificate chain, hostname, authorization, revocation, or server-inventory checks.

Platform prerequisites

Target Implementation/prerequisite
native automatic selection Current-user macOS Keychain, supported Linux distribution trust layout, or Windows current-user ROOT store.
java JAVA_HOME points to a Java installation containing lib/security/cacerts; the CLI reads it through the Java KeyStore API and prompts for the store password.
firefox Mozilla NSS certutil on PATH; profile contains cert9.db or cert8.db; close Firefox first.

Firefox operations require --target firefox, --profile <path>, and Mozilla NSS certutil on PATH; the CLI does not install or remove that prerequisite. If it is missing, install Mozilla NSS tools according to the platform: macOS brew install nss; Debian/Ubuntu sudo apt-get install libnss3-tools; Fedora/RHEL sudo dnf install nss-tools; Arch sudo pacman -S nss. On Windows use Mozilla NSS tools, not Windows system certutil.exe. The CLI invokes only the NSS add (-A), delete (-D), and list (-L) operations for the selected profile.

8. Leaf certificate commands

sslteam cert inspect

Read one PEM or DER X.509 certificate without contacting the backend or changing any trust store. The command prints subject, issuer, SHA-256 fingerprint, validity metadata, and whether the exact SSL Teams certificate extension is present.

sslteam cert inspect --certificate /public-material/certificate.pem
sslteam cert inspect --certificate /public-material/certificate.pem --sslteam
Option Required Meaning
--certificate <path> Yes One PEM or DER X.509 certificate.
--sslteam No Require the exact SSL Teams certificate extension; a certificate without the OID and SSLTeam value fails the check.

This command does not establish trust, verify a hostname, authenticate to the server, or modify the certificate. It is suitable for checking downloaded public certificates and files exported from a local trust store.

sslteam cert generate

Issue a leaf and download its complete artifact ZIP.

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 /protected/leaf-material

For multiple DNS names only, repeat --san with DNS= values:

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 /protected/leaf-material

For multiple IP addresses only, repeat --san with IP= values:

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 /protected/leaf-material

For a certificate containing both DNS and IP identities, repeat --san for each value:

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 /protected/leaf-material
Option Required/default Meaning
common connection options Effective values Backend URL; PKI scope comes from configured CLI defaults.
--name <text> Local development certificate Human-readable certificate name.
--common-name <value> localhost Subject common name; it does not replace SAN validation.
--san <TYPE=value> DNS=localhost Repeat for each DNS or IP identity.
--days <n> 90 Leaf validity in days, subject to backend policy.
--output-profile <profile> BOTH BOTH, PKCS12_ONLY, or PEM_ONLY.
--algorithm <algorithm> ecdsa-p256 ecdsa-p256, ecdsa-p384, rsa-3072, or rsa-4096.
--out-dir <path> . Protected artifact destination; a bundle may contain private key material.
--generate-password Off Generate a PKCS#12 password locally. Valid for profiles containing PKCS#12.
--show-generated-password Off Display a generated password once; requires --generate-password.

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.

Use DNS=name for DNS names and IP=literal for IP addresses. The server returns one ZIP; the CLI extracts its members and also keeps the downloaded archive as leaf-artifacts.zip beside them. This is an intentional local duplicate for convenient use and recovery, not multiple server responses. The ZIP may contain leaf-key.pem, leaf-cert.pem, chain/root material, and localhost.p12. The CLI validates archive paths and refuses unsafe or duplicate entries. Use cert download certificate or cert download chain for public-only files; do not use a generated artifact directory as a public distribution directory.

sslteam cert list

List scoped leaf inventory, status, SANs, issuer Intermediate, fingerprints, validity, versions, and expiry warnings.

sslteam cert list

Options: common connection options only. PKI scope comes from configured CLI defaults. An active certificate past notAfter is displayed as expired.

sslteam cert show

Show one leaf by issuance ID.

sslteam cert show --issuance-id <issuance-uuid>

Options: common connection options and required --issuance-id <uuid>. PKI scope comes from configured CLI defaults.

sslteam cert download certificate

Download only a public leaf certificate.

sslteam cert download certificate --issuance-id <issuance-uuid>

Options: common connection options, required --issuance-id <uuid>, --out-dir <path> defaulting to ., and --force to replace an existing public file after validation. PKI scope comes from configured CLI defaults.

sslteam cert download chain

Download only a public leaf certificate chain. Options are the same as cert download certificate; the output is the chain.

sslteam cert download chain --issuance-id <issuance-uuid>

sslteam cert artifact

Rebuild and download a complete artifact ZIP for an existing active issuance. Use this when the original bundle was lost or must be downloaded again; it is not renewal, replacement, revocation, or password recovery for the old ZIP. First run sslteam cert list and sslteam cert show --issuance-id <uuid> to verify the correct active issuance.

sslteam cert artifact --issuance-id <issuance-uuid> \
  --output-profile PKCS12_ONLY --generate-password
Option Required/default Meaning
common connection options Effective values Backend URL; PKI scope comes from configured CLI defaults.
--issuance-id <uuid> Required Existing leaf issuance.
--output-profile <profile> BOTH BOTH, PKCS12_ONLY, or PEM_ONLY.
--out-dir <path> . Protected artifact destination.
--generate-password Off Generate a new local PKCS#12 password.
--show-generated-password Off Display it once; requires generation.

The original password is not replayed. With --generate-password, the CLI writes the new password to localhost.p12.password beside the extracted keystore. Without it, the CLI prompts for a password and writes no sidecar password file. The server never returns this sidecar file. The password is never placed in the ZIP or manifest.json. The CLI validates the ZIP, refuses unsafe paths and an existing output directory, and protects private files where supported. If a prompted password is forgotten, run the command again with a new password.

sslteam cert revoke

Revoke one leaf by issuance ID. The CLI does not provide a cert retire command.

sslteam cert revoke --issuance-id <issuance-uuid> \
  --confirm <same-issuance-uuid> --reason "service decommissioned"
Option Required/default Meaning
common connection options Effective values Backend URL; PKI scope comes from configured CLI defaults.
--issuance-id <uuid> Required Leaf issuance identifier.
--confirm <uuid> Required Must exactly equal --issuance-id.
--reason <text> operator requested revocation Bounded audit reason.
--purge-local Off After server revocation, remove matching local artifact directory.
--out-dir <path> . Parent directory for local artifact directories.

Server revocation occurs before local purge. A purge failure does not undo a successful server revocation.

sslteam cert revocations

List certificate revocation audit events for a scope.

sslteam cert revocations

Options: common connection options and --limit <n> defaulting to 50. PKI scope comes from configured CLI defaults; the limit must be 1–100.

sslteam completion

Generate a static completion script. The command accepts exactly one shell name and writes only the script to standard output. It does not contact the backend, read trust state, or access credentials.

sslteam completion bash > ~/.local/share/bash-completion/completions/sslteam
sslteam completion zsh > ~/.zsh/completions/_sslteam

See the shell completion guide for shell startup setup and verification.

Package installations place the generated files in the package manager's completion directory. Package installation does not modify shell startup files; source the installed file from the shell configuration used by the operator. Completion values are static command names and options only. The generator never reveals credentials, certificates, private keys, fingerprints, or persisted trust state.

First operator session

sslteam tls tofu --origin "$BACKEND_ORIGIN"
sslteam tls tofu --origin "$BACKEND_ORIGIN" --fingerprint <verified-sha256-fingerprint>
sslteam auth device
sslteam ping

Root/Intermediate readiness

sslteam ca status
sslteam ca root list
sslteam ca intermediate status

Leaf issuance and public publication

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 /protected/leaf-material
sslteam cert show --issuance-id <issuance-uuid>
sslteam cert download certificate --issuance-id <issuance-uuid> --out-dir /public-material
sslteam cert download chain --issuance-id <issuance-uuid> --out-dir /public-material

10. Exit, logs, and support evidence

Use sslteam auth logout when work is complete. Use auth logout-all only when every session must be revoked. For unexpected failures, preserve the correlation ID and command classification. CLI logs are written under the configured CLI home; redact sensitive material before sharing diagnostics.

Do not report a certificate as trusted merely because it downloaded. Verify the correct trust store, verify hostname identity separately, and keep the Root/Intermediate family distinct from startup transport TLS.